Bonjour (DNS-SD)

• General information about Bonjour (DNS-SD)
• User experience in Radiccio as a player
• DNS-SD Record

General information about Bonjour (DNS-SD)

Radiccio Server can broadcast its availability on the LAN via Bonjour (also known as DNS Service Discovery or DNS-SD). Bonjour is enabled by default on the server side (if the server is running), but the server owner can disable it. When enabled, this allows servers to automatically appear in Radiccio players.

If you are a server developer, you can broadcast availability via Bonjour, to make it easier for users to connect when using Radiccio and other OpenSubsonic clients.

If you are a client developer, you can discover nearby Bonjour servers, to make it easier for users to connect to Radiccio Server and other OpenSubsonic servers.

Typically, Bonjour only works on the same LAN. It is technically possible to extend Bonjour over wide-area networks and VPNs, but this is an advanced networking technique which is not commonly found in the wild. Tailscale does not currently support Bonjour, although other VPN providers might.

User experience in Radiccio as a player

This section describes how Bonjour servers work with Radiccio as a player, so that server developers can know what to expect. If you are a player developer, you are free to implement a different user experience however you wish.

Before Radiccio players can detect Bonjour servers, the user must allow two permission prompts: (a) “Show Bonjour Servers?” and (b) the macOS local network privacy prompt. The first prompt automatically appears the first time Radiccio is launched, and the second prompt appears if the user accepts the first prompt.

Servers which can appear automatically in the source list (sidebar)

Radiccio players display a Bonjour-advertised server automatically in the source list if at least one of the following is true:

• The server offers anonymous authentication†
• The server offers iCloud authentication‡, and the server and player are both signed into the same iCloud account

Usually, a paid subscription is required for Radiccio to connect to a server as an OpenSubsonic client. However, the free version of Radiccio may connect to Bonjour-advertised OpenSubsonic servers using anonymous† authentication. The free version is not able to save OpenSubsonic sources permanently, nor can it sign in with an API Key, password, or token. Paid subscribers can do all of these things.

When the user selects a Bonjour server in the source list, they can start using it immediately; there is no need for the UX to include a sign-in step, because both anonymous and iCloud authentication can occur automatically without any user input.

† Note

Anonymous authentication is disabled by default in Radiccio Server, so the server owner needs to enable it before it becomes available.

‡ Note

iCloud authentication is not possible with servers and players other than Radiccio, because iCloud data syncing is scoped to a specific developer.

Servers which can appear automatically when adding a new source

Radiccio players display Bonjour-advertised servers automatically in the “new source” UI.

Unlike the source list (sidebar), the “new source” UI shows servers regardless of authentication method, which includes API Key, password, and token authentication, as well as anonymous and iCloud. The user will be able to select from your server’s supported authentication methods, based on your server’s response to getOpenSubsonicExtensions.

After the user completes the “new source” workflow, the server’s selected music folders are added as permanent sources in the source list, and Bonjour is no longer needed in order to connect to the server after that. Note, however, that if the server is advertising a .local hostname, the user will not be able to connect from outside the LAN, even though Bonjour is no longer a factor. The user may manually edit the hostname if needed.

Users must have a paid Radiccio Plus! subscription to add an OpenSubsonic source permanently. There are no exceptions for authentication type.

DNS-SD Record

• The service type† for the DNS-SD record is: _radiccio._tcp
• The service name should be a human-readable name which helps the user identify which server instance they are connecting to. For example: David's Mac mini
  • The service name should not be the name of the server software product (e.g. Navidrome) as this does not help the user choose between different instances running the same software.
  • Ideally, consider adding a configuration value to your server which allows the user to provide a name that they can recognize later.
  • As a last resort, if no other useful name is available, you can use the machine’s hostname as the service name (e.g. raspberry-pi-3)
• The port number should correspond to one of the ports that clients can connect to either via HTTP or HTTPS. However, clients should not rely on the port number specified here; instead, they should use the port number in the TXT record to disambiguate whether HTTP or HTTPS should be used.
• The TXT record is as follows:

Name	Type	Req.	Notes
httpPort	integer	Either httpPort or httpsPort is required (acceptable to have both)	The port number on which the server accepts HTTP connections. If the server does not accept HTTP, this may be omitted, however in that case httpsPort must be specified instead. Clients should use this port number for HTTP, not the port number specified with the hostname in the DNS record.
httpsPort	integer	Either httpPort or httpsPort is required (acceptable to have both)	The port number on which the server accepts HTTPS connections. If the server does not accept HTTPS, this may be omitted, however in that case httpPort must be specified instead. Clients should use this port number for HTTPS, not the port number specified with the hostname in the DNS record.
httpsHost	string	Yes if httpsPort is specified; no otherwise	HTTPS requires the hostname the client uses to connect to match the hostname specified in the HTTPS certificate. To ensure that the client uses the correct hostname (instead of an IP address, etc.) the server must specify the hostname that matches the certificate. The certificate must be valid and signed by a Certificate Authority recognized by all major operating systems; self-signed certificates are not acceptable and will likely result in clients being unable to connect to your server. Clients must use this hostname for HTTPS connections. Clients must not use this hostname for HTTP connections, instead they should use a hostname or IP address from the base DNS-SD record, as there is no guarantee that the same hostname works for both HTTP and HTTPS.
auth	string	Yes	A comma-separated list of supported authentication methods. This allows clients to know how to authenticate without needing to request getOpenSubsonicExtensions first. Valid values include: password token apiKey anonymous radiccio.keyPair (a.k.a. iCloud) Non-Radiccio servers should not advertise radiccio.keyPair.
configHash	string	No	An opaque hash that represents the current state of the server configuration, such as the contents of getOpenSubsonicExtensions and getMusicFolders (the exact inputs are left as an implementation detail). When there are significant changes to the server configuration, changing the value of this hash is a hint that it would be appropriate for the client to repeat such requests to get updated data. Clients must not attempt to parse this string, other than to compare it to a previous hash for the purpose of detecting a change. Servers should avoid changing the value of this too frequently or unnecessarily. Note that this is optional and servers may or may not implement it. Also keep in mind the overall size limitations (noted below).
radiccio.keyID	string	No	For Radiccio internal use.

DNS-SD records are limited in size. Per RFC 6763 section 6.2, try to keep it brief. Under no circumstance should the TXT record exceed 1300 bytes, or clients may be unable to discover your server.

† Note

If this document becomes a part of the OpenSubsonic specification in the future, the service type would likely change so that it no longer refers to Radiccio specifically.