1. Top
  2. libsood
  3. Files
  4. man
  5. sood.7
libsood

Zig library for Roon Core discovery message, with C-compatible API and WebAssembly.

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28
  29. 29
  30. 30
  31. 31
  32. 32
  33. 33
  34. 34
  35. 35
  36. 36
  37. 37
  38. 38
  39. 39
  40. 40
  41. 41
  42. 42
  43. 43
  44. 44
  45. 45
  46. 46
  47. 47
  48. 48
  49. 49
  50. 50
  51. 51
  52. 52
  53. 53
  54. 54
  55. 55
  56. 56
  57. 57
  58. 58
  59. 59
  60. 60
  61. 61
  62. 62
  63. 63
  64. 64
  65. 65
  66. 66
  67. 67
  68. 68
  69. 69
  70. 70
  71. 71
  72. 72
  73. 73
  74. 74
  75. 75
  76. 76
  77. 77
  78. 78
  79. 79
  80. 80
  81. 81
  82. 82
  83. 83
  84. 84
  85. 85
  86. 86
  87. 87
  88. 88
  89. 89
  90. 90
  91. 91
  92. 92
  93. 93
  94. 94
  95. 95
  96. 96
  97. 97
  98. 98
  99. 99
  100. 100
  101. 101
  102. 102
  103. 103
  104. 104
  105. 105
  106. 106
  107. 107
  108. 108 
.\" Copyright 2025 Shota FUJI
.\"
.\" Licensed under the Zero-Clause BSD License or the Apache License, Version 2.0, at your option.
.\" You may not use, copy, modify, or distribute this file except according to those terms. You can
.\" find a copy of the Zero-Clause BSD License at LICENSES/0BSD.txt, and a copy of the Apache License,
.\" Version 2.0 at LICENSES/Apache-2.0.txt. You may also obtain a copy of the Zero-Clause BSD License
.\" at <https://opensource.org/license/0bsd> and a copy of the Apache License, Version 2.0 at
.\" <https://www.apache.org/licenses/LICENSE-2.0>
.\"
.\" SPDX-License-Identifier: 0BSD OR Apache-2.0
.TH sood 7


.SH NAME
libsood \- Library for parsing and building SOOD message, binary format
for Roon service discovery


.SH DESCRIPTION
.B libsood
provides parser and builder functions for SOOD message, which is binary
message format sent over UDP, to perform Roon Server discovery. Code is
written in Zig and available as Zig library, static/dynamic library
(for C and languages supporting C API), and WebAssembly module.
.PP
Currently, only Zig library expose a function to build SOOD message.
.PP
To perform Roon Server discovery, send a prebuilt discovery query message
via IP multicast.
You can send the query at every IPv4 network interfaces too,
like the official Roon Node.js API[0].
You can also send the query via UDP broadcast, for a single interface or
multiple interfaces, like the Roon Node.js API and Pyroon[1].
.B libsood
exports the IPv4 multicast address and target UDP port number for this
process.
.nf
[0] https://github.com/RoonLabs/node-roon-api
[1] https://github.com/pavoni/pyroon
.fi
.PP
When a Roon Server receives the discovery query message, it may then send
back a discovery response message to the sender.
Parse the discovery response message using a function from
.B libsood
and you'll get necessary information to communicate with the Roon Server.
Note that the response message does NOT contain IP address of the Roon
Server; read that from a UDP packet.
.PP
Due to the nature of UDP and probably Roon Server's throttle mechanism,
sending of the discovery query message does not gurantee a discovery
response message.
You should set an appropriate timeout and resend the query until you
receive a discovery response message.


.SH DOCUMENTATION

.SS Zig library
Not available yet. However, API is simple and source code has okay\-ish
amount of doc comments and unit tests.
Consulting for the source code would be the best way to learn the API.


.SS C API
See
.BR sood (3).


.SS WebAssembly module
Not available yet.


.SH LIBRARY DESIGN

.SS Zig library
Zig API is designed to be simple and ease\-to\-use, rather than
performance focused.
Functions return a struct in general, hoping Zig compiler deciding good
memory location (copy or pointer).
.PP
I/O is not included in the Zig API.
Users are responsible for performing UDP send/recv operations.

.SS C API
Like Zig API,
.BR sood (3)
avoids any I/O including memory allocation, for portability.
It runs everywhere Zig compiler supports and C99 is available.
.PP
Users are responsible for allocating struct and passing pointer for
functions.


.SS WebAssembly module
WebAssembly module is designed to be bare\-minimum:
only high\-level response parsing.
.PP
Considering various language can access the module through WebAssembly
runtime, WebAssembly module API is designed to minimize the need for raw
memory handling.
Every struct fields has corresponding getter function that returns a field
value, and every slice has functions to get an address and length of the
slice.


.SH SEE ALSO
.BR sood (3)