Extensions

OpenSubsonic extensions
- apiKeyAuthentication
- formPost
Radiccio extensions

OpenSubsonic extensions

We implement the following extensions as defined in the OpenSubsonic specification.

apiKeyAuthentication

Radiccio Server supports API Key Authentication as defined by the OpenSubsonic specification. The server owner can find their API Key in App Settings > Server. Radiccio Server is a single-user system, and only has a single API Key. The API Key is randomly generated. The server owner can generate a new API Key at any time, which invalidates the previous API Key.

Radiccio Server does not use usernames or passwords. In order to support players that are not aware of API Keys, Radiccio Server will also accept the API Key in the password field (with any value in the username field). This is not in the specification; it is a Radiccio-specific behavior. This behavior may change in the future, and you should not rely on it.

Player app developers are strongly encouraged to develop proper UI support for API Keys, in order to avoid user confusion. The authors of the OpenSubsonic specification are encouraging everyone to move to API Keys instead of passwords, which has security benefits for users.

formPost

Radiccio Server supports Form POST requests as defined by the OpenSubsonic specification. This is optional; you may use GET query requests as well, or freely switch between them. If you choose Form POST, make sure to send the correct header Content-Type: application/x-www-form-urlencoded and the correct HTTP Method (POST), otherwise the HTTP body will be ignored.

Do not mix URL query and body parameters in the same request; this not supported and the behavior is undefined.

Radiccio extensions

In addition to OpenSubsonic extensions, Radiccio Server implements a number of our own extensions, which are not (yet) part of the community specification. You are welcome to implement Radiccio extensions in your servers or players if you wish, and we are documenting them here to help you do so.

Please note the following:

To avoid potential overlap with future OpenSubsonic extensions, our extensions always have the vendor prefix computer.crispycrunchy.radiccio
We use the same version numbering strategy for extensions as the OpenSubsonic spec does. This means, if you see a version number you were not expecting, you should expect that there may have been breaking changes to the API. If the changes are non-breaking (i.e., purely additive), we will send both the old and new version numbers.
In the future, if the community decides to adopt our extensions as part of the OpenSubsonic spec, the vendor prefix would be removed and this would be considered a new version with breaking changes. There would be a transition period where Radiccio Server would support both the prefixed and un-prefixed versions; eventually, the Radiccio-specific version would be removed. Please do not assume that a hypothetical future un-prefixed version would work the same; it is likely to undergo changes as part of the standardization process.

computer.crispycrunchy.radiccio.pins

Adds the attribute radiccio/pinned (Bool) to artists and albums. Adds the endpoints radiccio/getPinned and radiccio/setPinned.

When an item is pinned, it appears at the top of the list.

computer.crispycrunchy.radiccio.autoSkip

Adds the attribute radiccio/autoSkip (Bool) to albums and songs. Adds the endpoint radiccio/setAutoSkip.

When an item is set to auto skip, it does not get added to the playback queue when the user plays a group of songs (like an album, or an entire artist discography, or when shuffling a music folder). The user can still play the item individually.

Usage examples:

User plays an album — The album is played (even if the album is marked as auto skip), except for any songs marked as auto skip.
User plays an artist discography — All artist albums are played, except albums marked as auto skip and songs marked as auto skip.
User plays favorite songs by an artist — Favorite songs by the artist are played, except songs marked as auto skip. Favorite status does not override auto skip. (Radiccio’s favorite status maps to OpenSubsonic starred status.)
User plays a song marked as auto skip — The song plays, but no other songs play. Songs marked as auto skip are isolated from the rest of the collection.

computer.crispycrunchy.radiccio.journal

Adds the attribute radiccio/lastJournalEntry (RadiccioJournalEntry) to albums and songs. Adds the endpoints: radiccio/getJournalEntries, radiccio/createJournalEntry, radiccio/deleteJournalEntry

For more about how Journal works, see the Radiccio User Guide. For details about Journal data, see the Entities page.

computer.crispycrunchy.radiccio.nested

Adds the attribute radiccio/nested (Bool) to playlists.

Radiccio stores and retrieves playlists as M3U files in the filesystem. If a playlist is stored in the root of the music folder, or in a subfolder of the root, this value will be false. If the playlist is in a subfolder of a subfolder (or any deeper level), the value will be true. This allows Radiccio to provide a feature that helps the user hide certain kinds of bundled or automatically-generated playlist files which may not be useful to them.

computer.crispycrunchy.radiccio.noLimits

Allows you to specify all in endpoints that require a specified size or count, such as getAlbums2 and search3. When you do so, all results will be returned, so there is no longer a need to paginate.

For the search3 endpoint, all can only be used when retrieving one type of item at a time (albums, artists, or songs). When using all for one of them, the other counts must be set to 0 .

computer.crispycrunchy.radiccio.prefersSeparateMusicFolders

Unlike other servers, Radiccio is designed with each “music folder” (in our terminology, an “On My Mac” source) as a separate and independent entity. Therefore, Radiccio keeps data about each music folder in a completely separate database.

As a result, when you don’t specify a musicFolderId, Radiccio queries each database separately, and then concatenates the results together. Out of concern for likely performance issues, we intentionally do not apply any additional sorting to the concatenated result set prior to returning it.

This may result in somewhat strange results in your player app. For example, if the user has 3 music folders, and requests a list of albums in alphabetical order, the resulting list will be: the first folder A-Z, followed by the second folder A-Z, followed by the third folder A-Z. This is probably not what the user is expecting. Furthermore, the concatenations are ordered by the folders’ original creation date, which may seem arbitrary to the user, but is necessary to ensure consistency of API responses.

You can apply your own sorting on the client side. However, a better solution would be if your player UI prompts the user to select only one music folder a time for browsing. Then you can pass the musicFolderId in each request, and Radiccio Server will provide responses that are ordered correctly as requested. The responses should also be faster since only one database at a time will be queried, instead of all of them every time.

When Radiccio is acting as a player-client, and it finds the presence of this extension, it suppresses the option to view combined music folders. It would be ideal if your player did the same.

computer.crispycrunchy.radiccio.filterByMusicFolder

Allows you to pass musicFolderId to additional endpoints: getArtist, getPlaylists, createPlaylist

When you pass this parameter, only results from that music folder are returned. We recommend doing so whenever possible (see above explanation for prefersSeparateMusicFolders).

There is a similar proposed extension in the OpenSubsonic spec.

computer.crispycrunchy.radiccio.getRecentlyPlayedArtists

Provides a list of recently played artists, since there is not an existing endpoint that does this. Adds the endpoint radiccio/getRecentlyPlayedArtists

computer.crispycrunchy.radiccio.search3AlbumSort

Allows you to sort album search results by providing parameters type, fromYear and toYear in the search3 endpoint. These parameters work the same as with getAlbumList2.

This only works for album results. Artists and songs cannot be sorted this way, and the parameters are ignored for those results.

computer.crispycrunchy.radiccio.searchPlaylists

Allows you to search playlists. Adds the endpoint radiccio/searchPlaylists

There is a similar proposed extension in the OpenSubsonic spec.

computer.crispycrunchy.radiccio.unavailable.userRatings

This indicates that Radiccio does not support numeric user ratings functionality. When you see the presence of this extension, it would be appropriate to disable or remove this functionality from your player app. When this extension is present, endpoints related to this functionality will always return an error, so it would be best if you do not attempt to call these endpoints.

computer.crispycrunchy.radiccio.unavailable.transcoding

This indicates that Radiccio does not support transcoding functionality. When you see the presence of this extension, it would be appropriate to disable or remove this functionality from your player app. When this extension is present, related endpoints may return an error, or may return original audio data that disregards the attempted transcoding. It would be best if you do not attempt to play content that your player is incapable of playing in its original format.

computer.crispycrunchy.radiccio.anonymousAuthentication

This allows users to connect without a user account or API Key. In order to do this, follow the API Key specification, and use the API Key anonymous. Note that anonymous users are not allowed to create or modify data of any kind. Endpoints that require creating or modifying data will return an error. User-specific metadata, such as play counts and last played dates, will not be updated for anonymous users, and will return null values.

Server owners can enable or disable this feature, and in Radiccio it is off by default. When the server owner has disabled the feature, it does not appear in the list of extensions. The server owner may enable or disable it at any time.

computer.crispycrunchy.radiccio.keyPairAuthentication

This is the implementation that Radiccio players and servers use to authenticate with each other, referred to in the app UI as “iCloud”, since Apple’s iCloud service is used for automatic key exchange. This is not possible with third-party players because iCloud data syncing is scoped to a specific developer. Non-Radiccio players should use API Key Authentication instead, as defined in the OpenSubsonic specification.