Skip to content
Synara
Synara
On this page

Synara RPC Services Documentation

Models: MODELS.md · REST routes: REST_API.md · Permissions: PERMISSIONS.md · Guides: README.md

Table of Contents

RPC Services

IIndexer

Local file system media scanning.

Function Parameters Returns Permissions Errors Description
start - Flow<String> Admin Start indexing files in the media library and stream progress updates.

IAlbumService

Manages albums and their metadata.

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The album unique identifier. Album? - Get album by ID.
byMusicBrainzId mbId (PlatformUUID): The MusicBrainz release (or release-group) UUID. List<Album> - Get album by MusicBrainz ID.
byMusicBrainzIds mbIds (List<PlatformUUID>): Collection of MusicBrainz release (or release-group) UUIDs. List<Album?> - Get multiple albums by their MusicBrainz IDs.
byIds ids (List<PlatformUUID>): Collection of album IDs. List<Album> - Get multiple albums by their IDs.
byOriginalIds ids (Collection<PrefixedId>): Collection of original platform-specific album identifiers. List<Album> - Find albums by their original platform-specific unique identifiers.
byOriginalUrls urls (Collection<String>): Collection of original platform URLs. Map<String, Album?> - Find albums by their original platform URLs, returning a mapping.
versions id (PlatformUUID): The album unique identifier. List<Album> - List the other editions of an album, main edition first.
byVersionGroup versionGroupId (PlatformUUID): The version group unique identifier, as carried by versionGroupId on an album.
explicit (Boolean): True prefers the explicit edition as the main one when an album exists in an explicit and a clean edition. False prefers the clean one.		 List<Album> - List all albums of a version group, main edition first. The albums come back as a flat list and their versions lists are empty.
byName page (Int): Page index (starting from 0).
pageSize (Int): Number of items per page.
name (String): The album name to search for.		 PaginatedResponse<Album> - Search albums by name.
rankedSearch page (Int): Page index.
pageSize (Int): Number of items per page.
query (String): The search query.		 PaginatedResponse<Album> - Ranked album search.
allAlbums page (Int): Page index.
pageSize (Int): Number of items per page.
explicit (Boolean?): True prefers the explicit edition as the main one when an album exists in an explicit and a clean edition. False prefers the clean one. When it is not given, the explicit edition is preferred.		 PaginatedResponse<Album> - Get all albums in the library, grouped into editions. Each entry is the main edition of an album and carries the other editions in versions.
byColor page (Int): Page index.
pageSize (Int): Number of items per page.
color (Int): The target color in ARGB format.
range (Int): The allowed range (0-255).		 PaginatedResponse<Album> - Search for albums by color.
updateAlbum album (Album): The album object with updated fields. Album? EDIT Update album metadata.
deleteAlbums ids (List<PlatformUUID>): Collection of album IDs to delete. Boolean DELETE Delete multiple albums from the library.
fetchMusicBrainzId id (PlatformUUID): The album unique identifier. Album? EDIT Fetch and link MusicBrainz ID for an album.
setMusicBrainzId id (PlatformUUID): The album unique identifier.
musicBrainzId (PlatformUUID?): The MusicBrainz Release UUID.		 Album? EDIT Manually set MusicBrainz ID for an album.
byArtist page (Int): Page index.
pageSize (Int): Number of items per page.
artistId (PlatformUUID): The artist unique identifier.
singles (Boolean): Whether to include singles.
explicit (Boolean?): True prefers the explicit edition as the main one when an album exists in an explicit and a clean edition. False prefers the clean one. When it is not given, the explicit edition is preferred.		 PaginatedResponse<Album> - List albums by artist, grouped into editions. Each entry is the main edition of an album and carries the other editions in versions.
extendedMetadata id (PlatformUUID): The album unique identifier. AlbumExtendedMetadata? - Get extended metadata for an album.

IAnimatedImageService

Management of animated cover files (short looping videos).

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The animated image unique identifier. AnimatedImage? - Get animated image metadata by its unique ID.
byHash hash (String): The unique hash of the animated image. AnimatedImage? - Find animated image metadata by its content hash.
getCoverHashes hashes (List<String>): Collection of animated image hashes. Map<String, PlatformUUID> - Map a list of animated image hashes to their existing internal UUIDs.
getAnimatedImageData id (PlatformUUID): The animated image unique identifier. ByteArray? - Retrieve the raw binary data of an animated image.
createAnimatedImage bytes (ByteArray): The raw binary data of the animated image.
origin (String): The source or category of the animated image.		 PlatformUUID - Store a new animated image on the server.
createBatch images (List<InsertableAnimatedImage>): Collection of animated images to store. Map<String, PlatformUUID> - Store multiple animated images on the server in a single operation.

IApiKeyService

Manages long-lived API keys for authenticating non-interactive clients (e.g. media players).

Function Parameters Returns Permissions Errors Description
createApiKey label (String): Human-readable label describing where the key will be used.
scopes (List<String>): Identifiers of the scopes to grant to the key. Must be registered scopes.		 String - Create a new API key and return the raw secret.
getApiKeyString id (PlatformUUID): The API key unique identifier. String? - Get the raw secret of one of the current user's API keys. Returns null for keys created before secrets were stored.
listAvailableScopes - List<ApiKeyScopeInfo> - List all scopes that can be granted to API keys.
listApiKeys - List<ApiKeyInfo> - List metadata for all API keys belonging to the current user. Never returns the secrets.
revokeApiKey id (PlatformUUID): The API key unique identifier. Boolean - Revoke an API key by its identifier. Returns true if a key was revoked.

IArtistService

Manages artist data and complex library maintenance.

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The artist unique identifier. Artist? - Get artist by ID.
byMusicBrainzId mbId (PlatformUUID): The MusicBrainz artist UUID. List<Artist> - Get artist by MusicBrainz ID.
byIds ids (List<PlatformUUID>): Collection of artist IDs. List<Artist> - Get multiple artists by their IDs.
rankedSearch page (Int): Page index.
pageSize (Int): Number of items per page.
query (String): The search query.		 PaginatedResponse<Artist> - Ranked artist search.
setGroup id (PlatformUUID): The group artist unique identifier.
artistIds (List<PlatformUUID>?): Optional collection of sub-artist IDs.		 Artist? EDIT Set sub-artists for a group.
byGroup page (Int): Page index.
pageSize (Int): Number of items per page.
groupId (PlatformUUID): The group artist unique identifier.		 PaginatedResponse<Artist> - List artists in a group, ordered by name without regard to case, artists with the same name by ID.
mergeArtists mergeArtists (MergeArtists): Configuration for merging artists. Artist? EDIT Merge multiple artist records into one.
splitArtist splitArtist (SplitArtist): Configuration for splitting an artist. List<Artist> EDIT Split an artist record into multiple artists.
allArtists page (Int): Page index.
pageSize (Int): Number of items per page.		 PaginatedResponse<Artist> - Get all artists in the library, ordered by name without regard to case, artists with the same name by ID.
byColor page (Int): Page index.
pageSize (Int): Number of items per page.
color (Int): The target color in ARGB format.
range (Int): The allowed range (0-255).		 PaginatedResponse<Artist> - Search for artists by color.
createArtist name (String): Name of the artist.
isGroup (Boolean): Whether the artist is a group.
about (String): Optional biography or description.
musicBrainzId (PlatformUUID?): Optional MusicBrainz ID.		 Artist EDIT Manually create an artist record.
searchArtistOnMusicBrainz query (String): The search query.
page (Int): Page index.
pageSize (Int): Number of items per page.		 PaginatedResponse<MusicBrainzArtist> - Search for an artist directly on MusicBrainz.
fetchMusicBrainzId id (PlatformUUID): The artist unique identifier. Artist? EDIT Fetch and link MusicBrainz ID for an artist.
setMusicBrainzId id (PlatformUUID): The artist unique identifier.
musicBrainzId (PlatformUUID?): The MusicBrainz ID to link.		 Artist? EDIT Link an artist record to a MusicBrainz ID.
searchArtistImages type (MetadataType): The metadata provider to use.
query (String): The artist name to search for.
limit (Int): Maximum number of images to return.		 List<Image> - Search for artist images using a metadata provider.
setArtistImageByUrl id (PlatformUUID): The artist unique identifier.
url (String): The direct image URL.		 Artist? EDIT Set an artist's image from a direct URL.
artistsWithoutMusicBrainzId - Flow<Artist> - Stream all artists that are missing a MusicBrainz ID.
artistIdsWithoutMusicBrainzId - Flow<PlatformUUID> - Stream IDs of all artists that are missing a MusicBrainz ID.
topSongs artistId (PlatformUUID): The artist unique identifier.
limit (Int): Maximum number of songs. Clamped to 1..100.
order (ArtistTopSongOrder): How the songs are ranked.		 List<ArtistTopSong> - List the artist's library songs ranked by popularity. The list holds the artist's most listened songs across all listeners and the artist's songs the current user has listened to.
aliases id (PlatformUUID): The artist unique identifier. List<ArtistAlias> - List aliases for an artist.
addAlias artistId (PlatformUUID): The artist unique identifier.
name (String): The alternative name.		 Boolean EDIT Add an alias to an artist.
removeAlias artistId (PlatformUUID): The artist unique identifier.
name (String): The alternative name.		 Boolean EDIT Remove an alias from an artist.

IAudioAnalysisService

Service for audio analysis and related data management.

Function Parameters Returns Permissions Errors Description
getAudioData songId (PlatformUUID): The song unique identifier. SongAudioData? - Get audio analysis data for a song.
getAudioTimeline songId (PlatformUUID): The song unique identifier. SongAudioTimeline? - Get the beat grid and loudness envelope of a song, or null when not extracted yet. Call analyzeSong to extract it.
analyzeSong songId (PlatformUUID): The song unique identifier. Unit - Trigger analysis for a song.

IAuthService

Handles user login and session security.

Function Parameters Returns Permissions Errors Description
authenticate username (String): The username of the user.
password (String): The password of the user.		 AuthenticationResponse - IllegalArgumentException, IllegalStateException Logs in a user and returns JWT token.
refreshToken refreshToken (String): The refresh token. AuthenticationResponse - IllegalArgumentException, IllegalStateException Refreshes an expired access token.
createDeviceSession userAgent (String): The user agent of the device the session is created for. AuthenticationResponse - IllegalStateException Creates a new session for another device (e.g. Apple TV) on behalf of the authenticated user.

IBackupService

System-wide data persistence and disaster recovery.

Function Parameters Returns Permissions Errors Description
listBackups - List<BackupInfo> Admin SecurityException List all available system backup files.
loadBackup fileName (String): The name of the backup file. Unit Admin SecurityException, IllegalArgumentException Restore the entire server state from a backup file.
deleteBackup fileName (String): The name of the backup file. Unit Admin SecurityException Delete a system backup file from the server.
createBackup - BackupResult Admin SecurityException Trigger the creation of a full system backup.

IChangeService

Tells a client which parts of the user's state changed, so it reads them again with the regular getters instead of polling or keeping one stream open per screen.

Function Parameters Returns Permissions Errors Description
observeChanges - Flow<Change> - Watch the state of the user for changes. The stream stays silent until something changes and then emits the ChangeTopic that changed, which names the getter to call again. Bursts of changes to the same topic within a short window arrive as a single change. Nothing is replayed, so a client reads the current state after every (re)subscribe.

IChartService

Charts of popular music.

Function Parameters Returns Permissions Errors Description
appleChart country (String): Two-letter country code, for example us or de.
kind (AppleChartKind): Whether to get the song chart or the album chart.
limit (Int): Maximum number of entries. Clamped to 1..100.		 AppleChart - IllegalArgumentException Get the current Apple Music chart of the most played songs or albums in a country. Every chart entry is returned, entries that are in the library carry the library song or album.

IClientRequestService

The connection a client keeps open to the server for the lifetime of the app. It carries the tasks the server asks the calling client to perform, which the client performs through the regular RPC services and reports back so the device that asked for it is unblocked, and it doubles as the presence of the client: a session that connects with a description is listed as an online device of the user, with the cross-device features it offers, for exactly as long as it keeps the stream open.

Function Parameters Returns Permissions Errors Description
observeRequests - Flow<ClientRequest> - Watch for requests addressed to the calling session without announcing the device. A session that is not subscribed is reported as unreachable to the requester.
connect description (ClientDescription): How this client is listed on the other devices of the user and what it can do. Flow<ClientRequest> - Watch for requests addressed to the calling session and be listed as an online device of the user while the stream is open. The description is kept only for the duration of the stream, so a client that changes its name or its capabilities subscribes again. Requests that need a capability are only delivered to sessions that connected offering it.
complete requestId (PlatformUUID): The identifier of the request that was handled.
status (ClientRequestStatus): Whether the request was performed or declined.		 Unit - Report the outcome of a request to the waiting requester. Only COMPLETED and REJECTED are accepted. The timed out and unreachable outcomes are determined by the server.
getOnlineDevices - List<OnlineDevice> - List the devices of the user that are connected right now, newest connection first. Sessions that only observe requests without a description are not listed.

IClientSettingsService

Stores the settings of the clients of a user as opaque key/value entries, where the value is an arbitrary JSON document in text form and the server never interprets what a setting means. Entries live either in the synced scope, which is shared by all devices of the user, or in the device scope of a single device, and the client decides per key which one it uses. Each scope carries a monotonically increasing version that every accepted write advances by one, and every entry remembers the version it was written at, so clients detect concurrent changes and can catch up incrementally instead of reading everything again.

Function Parameters Returns Permissions Errors Description
getSettings scope (ClientSettingScope): The scope to read.
device (String?): The device to read in the device scope. Required for the device scope and ignored in the synced scope.
includeDeleted (Boolean): Whether the tombstones of deleted keys are returned as well.		 List<ClientSetting> - Read the entries of a scope. Tombstones of deleted keys are left out unless they are asked for explicitly. Reading the device scope registers the device or refreshes its last seen time.
getSnapshot deviceId (String): The stable identifier the client chose for this device. ClientSettingsSnapshot - Read the complete settings of a device in one call: the live entries of the synced scope and of the device scope with the current version of each. Reading a snapshot registers the device or refreshes its last seen time, so this is what a client calls right after it starts.
getChanges scope (ClientSettingScope): The scope to read.
sinceVersion (Long): The version the client is already up to date with. Entries written at a later version are returned.
device (String?): The device to read in the device scope. Required for the device scope and ignored in the synced scope.
limit (Int): Maximum number of entries to return.		 ClientSettingsChanges - Read the entries a scope changed after a version the client already knows, tombstones included and ordered by the version they were written at. When more entries are available than the page holds, the client asks again with the version of the last entry it received. If tombstones the client never saw were already purged, the result asks for a full resync and the client re-reads the whole scope instead.
setSettings entries (List<ClientSettingWrite>): The entries to write, each with the version the client based its change on.
scope (ClientSettingScope): The scope to write to.
device (String?): The writing device. Required for the device scope, and in the synced scope only recorded as the writer of the entries.
force (Boolean): Whether to apply the entries even if the server moved past the base versions supplied.		 ClientSettingsWriteResult - IllegalArgumentException Write a batch of entries into a scope. The batch is all-or-nothing: an entry is accepted only if its base version matches the version the stored entry was last written at, or is 0 for a key that does not exist or is only a tombstone, and as soon as one key conflicts nothing is written at all. Forcing the write skips that check. An entry with a null value deletes its key and leaves a tombstone behind so other devices learn about the deletion. Writing the device scope registers the device or refreshes its last seen time, while the device of a synced write is optional and only recorded as the writer.
getHistory scope (ClientSettingScope): The scope the key belongs to.
key (String): The key to read the previous values of.
device (String?): The device to read in the device scope. Required for the device scope and ignored in the synced scope.
limit (Int): Maximum number of previous values to return.		 List<ClientSetting> - Read the previous values of a single key, newest first. The server keeps a bounded number of superseded values per key, so older values are dropped as new ones are written.
restore scope (ClientSettingScope): The scope the key belongs to.
key (String): The key to restore.
version (Long): The version of the historic value to write back.
device (String?): The device to write in the device scope. Required for the device scope and in the synced scope only recorded as the writer.
force (Boolean): Whether to apply the value even if the server moved past the version the entry currently has.		 ClientSettingsWriteResult - IllegalArgumentException Write a previous value of a key back as a new version. The value is taken from the history of the key and stored through the normal write path, so the scope advances by one and the value that was replaced moves into the history itself. The call fails if the requested version is not kept in the history any more.
observeSettings - Flow<ClientSettingsChange> - Watch the settings of the user for changes. Every accepted write emits the scope it changed, the version it advanced to and the keys it touched, including writes made by other devices, so a client pulls only what it needs.
getDevices - List<ClientDevice> - List the devices of the user that stored settings on the server, each with the current version of its device scope.
registerDevice deviceId (String): The stable identifier the client chose for this device.
name (String): Human readable name of this device.
platform (String): Platform of this device, for example the operating system it runs on.		 ClientDevice - IllegalArgumentException Register a device or refresh the name and platform it is listed under. Calling this is optional, since reading or writing the device scope registers the device on its own, but it lets a client give its device a readable name before it stores anything.
deleteDevice deviceId (String): The identifier of the device to forget. Unit - Forget a device together with its device-scoped settings and their history. The synced scope is not touched, so the other devices of the user keep their shared settings.

ICollectionService

Management of user-owned downloadable collections.

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The collection unique identifier. MediaCollection? - Get a collection by ID.
allCollections - List<MediaCollection> - Get all collections owned by the current user.
createCollection collection (InsertableCollection): The initial collection data. PlatformUUID - Create a new collection owned by the current user.
updateCollection id (PlatformUUID): The collection unique identifier.
collection (InsertableCollection): The new metadata.		 Boolean - UnauthorizedException Update a collection's metadata (name, description, image).
addItem id (PlatformUUID): The collection unique identifier.
itemType (CollectionItemType): The kind of referenced entity.
itemId (PlatformUUID): The referenced entity unique identifier.		 Boolean - UnauthorizedException Add an item (song, album, artist or playlist) to a collection.
removeItem id (PlatformUUID): The collection unique identifier.
itemType (CollectionItemType): The kind of referenced entity.
itemId (PlatformUUID): The referenced entity unique identifier.		 Boolean - UnauthorizedException Remove an item from a collection.
setCollectionImage id (PlatformUUID): The collection unique identifier.
imageId (PlatformUUID?): The image unique identifier.		 Boolean - UnauthorizedException Set the cover image of a collection.
delete id (PlatformUUID): The collection unique identifier. Boolean - UnauthorizedException Delete a collection.
rankedSearch collectionId (PlatformUUID): The collection unique identifier.
query (String): The search query.
explicit (Boolean): Whether to include explicit-content songs.
page (Int): The page index (starting from 0).
pageSize (Int): Items per page, applied per result type.		 CollectionSearchResults - Ranked search within a single collection across songs, artists, albums and playlists.
songIds collectionId (PlatformUUID): The collection unique identifier. Flow<PlatformUUID> - Stream the IDs of songs explicitly added to a collection.
albumIds collectionId (PlatformUUID): The collection unique identifier. Flow<PlatformUUID> - Stream the IDs of albums explicitly added to a collection.
artistIds collectionId (PlatformUUID): The collection unique identifier. Flow<PlatformUUID> - Stream the IDs of artists explicitly added to a collection.
playlistIds collectionId (PlatformUUID): The collection unique identifier. Flow<PlatformUUID> - Stream the IDs of playlists explicitly added to a collection.

ICoverGenerationService

Generates cover images for user playlists and collections from their content, asset packs and palette.

Function Parameters Returns Permissions Errors Description
options - CoverGenerationOptions - Styles and asset packs available to the current user.
coverInfo target (CoverTarget): The playlist or collection. CoverInfo - IllegalArgumentException The current cover state of a playlist or collection.
previewCoverImage target (CoverTarget): The playlist or collection.
params (CoverGenerationParams): Generation parameters.		 ByteArray - IllegalArgumentException, UnauthorizedException Render a 1024x1024 JPEG preview without persisting it. Only the owner or an admin may call this.
applyCover target (CoverTarget): The playlist or collection.
params (CoverGenerationParams): Generation parameters.		 PlatformUUID - IllegalArgumentException, UnauthorizedException Render, persist and set the cover, marking it as generated. Returns the new image id. Only the owner or an admin may call this.
resetCover target (CoverTarget): The playlist or collection. Boolean - UnauthorizedException Clear a user-set cover so automatic generation may replace it. Returns false when there was nothing to reset.
generateMissing params (CoverGenerationParams): Generation parameters applied to every item. PlatformUUID - Queue generation for every playlist and collection of the current user without a cover. Returns the job id.

ICustomAudioService

Handles manual audio uploads.

Function Parameters Returns Permissions Errors Description
uploadCustomAudio fileData (ByteArray): The raw bytes of the audio file.
fileName (String): The original name of the file.
metadata (CustomMetadata?): Optional metadata associated with the audio.		 PlatformUUID? EDIT Upload a custom audio file and its metadata.

IDbManagementService

Direct database management and data migration.

Function Parameters Returns Permissions Errors Description
exportData - ByteArray Admin Export the entire system database as a binary blob.
importData data (ByteArray): The raw database blob. Unit Admin Import a previously exported database blob to overwrite the current state.

IDiscoveryService

Service for content discovery and song recommendations.

Function Parameters Returns Permissions Errors Description
createSongMosaic image (ByteArray): The source image data.
width (Int): Target grid width.
height (Int): Target grid height.
page (Int): Page index.
pageSize (Int): Number of items per page.
range (Int): Search range for colors (0-255).		 PaginatedResponse<UserSong> - Create a mosaic of songs matching the colors of an image.
createAlbumMosaic image (ByteArray): The source image data.
width (Int): Target grid width.
height (Int): Target grid height.
page (Int): Page index.
pageSize (Int): Number of items per page.
range (Int): Search range for colors (0-255).		 PaginatedResponse<Album> - Create a mosaic of albums matching the colors of an image.
getSimilarSongs seedSongIds (List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs similar to the provided seed tracks.
getSimilarSongsByPlaylist playlistId (PlatformUUID): The user playlist unique identifier to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs similar to the songs in the provided user playlist.
getSimilarSongsByBpm seedSongIds (List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs with similar BPM to the provided seed tracks.
getSimilarSongsByEnergy seedSongIds (List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs with similar energy to the provided seed tracks.
getSimilarSongsByMood seedSongIds (List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs with similar mood (valence) to the provided seed tracks.
getSongsBySameComposers seedSongIds (List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs by the same composers as the provided seed tracks.
getSongsBySameLyricists seedSongIds (List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs by the same lyricists as the provided seed tracks.
getSongsBySameProducers seedSongIds (List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (Int): The maximum number of results to return.		 List<UserSong> - Get songs by the same producers as the provided seed tracks.

IEntityChangeService

Answers which library entities changed since a time the client names, so a client that keeps library data reads only those again instead of everything. It is a pull the client starts and not a subscription. Every returned stream delivers the changes recorded so far and then completes, nothing is emitted afterwards. The live notifications are IChangeService.observeChanges. A result contains library changes plus the caller's own LIKE and TIMECODES changes, ordered by time. A filtered pull returns the changes of every object a client gets when it loads that artist, album, playlist or collection, including objects nested in others, such as the artists and the album of a song, the artists of an album and the member artists of an artist that is a group. A change is recorded once for the entity it happened to, so an object nested in several others is reported once as itself, and a client updates the copies it holds by id. A client calls IEntityChangeService.getWindow first, pulls with the time it kept from its last pull and keeps the new one for the next.

Function Parameters Returns Permissions Errors Description
getWindow - EntityChangeWindow - Read the time frame around a pull. The client keeps serverTime as the since of its next pull and compares the since it is about to use with availableSince. If that since lies before availableSince the recorded changes no longer reach back far enough and the client reads everything again.
allChanges since (Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned. Flow<EntityChange> - Stream every recorded change since a time, ordered by time. The stream completes after the last entry.
byArtist artistId (PlatformUUID): The artist unique identifier.
since (Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 Flow<EntityChange> - Stream the recorded changes of everything a client gets when it loads an artist since a time, ordered by time. These are the changes of the artist itself, of its member artists when it is a group, of its albums and songs, deleted ones included, of the albums of those songs, of every artist credited on those albums and songs, and of the member artists of credited groups. The caller's LIKE changes of these songs, albums and artists and its TIMECODES changes of these songs are part of it. The stream completes after the last entry.
byAlbum albumId (PlatformUUID): The album unique identifier.
since (Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 Flow<EntityChange> - Stream the recorded changes of everything a client gets when it loads an album since a time, ordered by time. These are the changes of the album itself, of its artists, of its songs, deleted ones included, of every artist credited on those songs, and of the member artists of credited groups. The caller's LIKE changes of the album, these songs and these artists and its TIMECODES changes of these songs are part of it. The stream completes after the last entry.
byPlaylist playlistId (PlatformUUID): The unique identifier of the user playlist or global playlist.
since (Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 Flow<EntityChange> - Stream the recorded changes of everything a client gets when it loads a playlist since a time, ordered by time. These are the changes of the playlist itself, its contents changing included, of the songs it contains now, of the albums of those songs, of every artist credited on those songs and albums, and of the member artists of credited groups. The caller's LIKE changes of these songs, albums and artists and its TIMECODES changes of these songs are part of it. It works for user playlists and global playlists alike. The stream completes after the last entry.
byCollection collectionId (PlatformUUID): The collection unique identifier.
since (Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 Flow<EntityChange> - Stream the recorded changes of everything a client gets when it loads a collection since a time, ordered by time. These are the changes of the collection itself and of its direct members, which are songs, albums, artists and user playlists. The members are expanded to what they contain. A member album brings its songs, a member artist brings its albums, its songs and the songs of those albums, and a member playlist brings the songs it contains now. For every song reached that way the changes of its album and of its credited artists are returned as well, for every album those of its artists, and for every such artist that is a group those of its member artists. The caller's LIKE changes of these songs, albums and artists and its TIMECODES changes of these songs are part of it. The stream completes after the last entry.

IFavSyncService

Tracks the history of favorite synchronization tasks.

Function Parameters Returns Permissions Errors Description
getLatestFavSync service (SyncServiceType): The service type (e.g., TIDAL). FavSync? - Get the timestamp of the last successful synchronization for a specific service.
insertFavSync service (SyncServiceType): The service type.
syncedAt (PlatformDate): The timestamp of synchronization.		 Int - Record a new successful synchronization timestamp.

IHandshakeService

Service for server reachability and handshake testing.

Function Parameters Returns Permissions Errors Description
handshake - HandshakeResponse - Perform a handshake test to check server reachability and protocol support.

IHueService

Philips Hue bridges paired by the current user and their light links, driven by now-playing changes.

Function Parameters Returns Permissions Errors Description
discoverBridges - List<HueBridgeCandidate> - Discover Hue bridges on the local network via mDNS and the Hue cloud discovery endpoint. Paired is relative to the current user.
listBridges - List<HueBridgeInfo> - Bridges paired by the current user.
startPairing ip (String): IP address of the bridge. Flow<HuePairingStatus> - Pair with a bridge. Press the link button on the bridge while this flow polls for up to 30 seconds. The bridge is stored for the current user. Other users pair it separately.
removeBridge bridgeId (PlatformUUID): Server-side bridge unique identifier. Boolean - Remove one of the current user's bridges together with the user's link to it.
listTargets bridgeId (PlatformUUID): Server-side bridge unique identifier. List<HueTarget> - IllegalArgumentException Lights, rooms and zones exposed by a bridge.
listScenes bridgeId (PlatformUUID): Server-side bridge unique identifier. List<HueScene> - IllegalArgumentException Scenes exposed by a bridge, each scoped to a room or zone that the bridge reports.
getLinks - List<HueUserLink> - The current user's light links.
setLink link (HueUserLink): Link settings. bridgeId selects the bridge. HueUserLink - IllegalArgumentException Create or update the current user's link to a bridge.
removeLink bridgeId (PlatformUUID): Server-side bridge unique identifier. Boolean - Remove the current user's link to a bridge.
test bridgeId (PlatformUUID): Server-side bridge unique identifier.
targets (List<HueTarget>): Targets to test.		 Boolean - IllegalArgumentException Flash the given targets with a test palette.
status - HueStatus - Last command time, last error and current colors for the current user's links.

IImageService

Management of image files for covers and profiles.

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The image unique identifier. Image? - Get image metadata by its unique ID.
byHash hash (String): The unique hash of the image. Image? - Find image metadata by its content hash.
getCoverHashes hashes (List<String>): Collection of image hashes. Map<String, PlatformUUID> - Map a list of image hashes to their existing internal UUIDs.
getImageData id (PlatformUUID): The image unique identifier.
size (Int): Requested image size (width/height). 0 for original size.		 ByteArray? - Retrieve the raw binary data of an image.
createImage bytes (ByteArray): The raw binary data of the image.
origin (String): The source or category of the image.		 PlatformUUID - Store a new image on the server.
createBatch images (List<InsertableImage>): Collection of images to store. Map<String, PlatformUUID> - Store multiple images on the server in a single operation.
moveImages oldPath (String): Path prefix to match.
newPath (String): New base path.		 Int Admin Batch update image file paths.
generateMosaicImage image (ByteArray): The source image data.
width (Int): Grid width (max width * height = 65,536).
height (Int): Grid height (max width * height = 65,536).
resultSize (Int): The resolution of the resulting square image.		 Flow<MosaicGenerationResponse> - IllegalArgumentException Generate a mosaic image from a source image where each pixel is replaced by a matching cover.

IListenBackupService

Configure and control the backup of server-side listens to a remote listen-backup receiver.

Function Parameters Returns Permissions Errors Description
getState - ListenBackupState Admin SecurityException Get the current backup configuration and sync state.
observeState - Flow<ListenBackupState> Admin SecurityException Stream the backup state, re-emitting whenever the configuration or sync progress changes.
updateConfig config (ListenBackupConfig): The new configuration. A null key keeps the stored key. ListenBackupState Admin SecurityException, IllegalArgumentException Update the backup configuration.
testConnection config (ListenBackupConfig?): Configuration to probe. Null uses the stored configuration. ListenBackupConnectionTest Admin SecurityException Probe a receiver. Uses the stored configuration when no config is given.
syncNow - ListenBackupState Admin SecurityException, IllegalStateException Run a backup sync now and return the resulting state.
resetCursor - ListenBackupState Admin SecurityException Reset the sync cursor so the next run re-pushes every local listen.

IListenBrainzService

Manage the current user's ListenBrainz connection and listen-history sync.

Function Parameters Returns Permissions Errors Description
link username (String): The ListenBrainz username.
token (String?): Optional ListenBrainz user token, required for private listens.		 ListenBrainzStatus - Link the current user to a ListenBrainz account and trigger an initial sync.
unlink - Unit - Remove the current user's ListenBrainz link.
getStatus - ListenBrainzStatus? - Get the current user's ListenBrainz connection status, or null if not linked.
syncNow - ListenBrainzStatus - Trigger an incremental sync of the current user's ListenBrainz listens now.
recentListens limit (Int): Maximum number of listens to return. Clamped to 1..1000. List<ListenedSong> - Return the current user's most recent listened songs (newest first), capped at 1000.

IListeningStatsService

Listening statistics over the current user's unified listen history (local scrobbles and ListenBrainz imports), deduplicated across sources.

Function Parameters Returns Permissions Errors Description
getStats range (StatsRange): The time range to aggregate.
timezone (String): IANA timezone for range boundaries, e.g. Europe/Berlin. Invalid or blank falls back to UTC.
topLimit (Int): Maximum entries per top list. Clamped to 1..100.
topOrder (TopOrder): Metric used to rank the top and discovery lists.		 ListeningStats - Compute listen count, previous-range comparison, top songs/artists/albums, listen clock, streaks, unique counts and new discoveries for a time range.
getTopSongs range (StatsRange): The time range to aggregate.
timezone (String): IANA timezone for range boundaries, e.g. Europe/Berlin. Invalid or blank falls back to UTC.
limit (Int): Maximum number of songs. Clamped to 1..500.
order (TopOrder): Metric used to rank the songs.		 List<UserSong> - Return the current user's most played songs in a time range as a playable list, ranked by the given metric. Songs that are not in the library are left out.
linkUnmatchedTrack request (LinkUnmatchedTrackRequest): The unmatched track identity and the target library song. LinkUnmatchedTrackResult - Link the current user's unmatched listens of a track to a library song, identified by recording MSID and/or MBID. The link persists, applies to future synced listens, and is submitted to ListenBrainz as a manual mapping when the song has a recording MBID.
getLinkedListenGroups songId (PlatformUUID): The library song. List<LinkedListenGroup> - List the groups of the current user's listens that are linked to a library song. Each group can be moved to another song with relinkSong.
relinkSong fromSongId (PlatformUUID): The library song the listens are linked to now.
toSongId (PlatformUUID): The library song to link the listens to.
groups (List<LinkedListenGroupKey>?): The groups to move, as returned by getLinkedListenGroups. Null moves every group.		 LinkUnmatchedTrackResult - Move the current user's listens from one library song to another, either all of them or only the given groups. The change persists for future listens of the moved groups, including local plays of the same song. It is submitted to ListenBrainz as a manual mapping when the target song has a recording MBID.

ILyricsCandidateService

Lyrics of songs from several providers. Every provider answer is kept as a candidate so a client can choose which version to show.

Function Parameters Returns Permissions Errors Description
getLyrics songId (PlatformUUID): The song unique identifier.
candidateId (PlatformUUID?): The candidate to return instead of the default one.		 LyricsCandidate? - Get the lyrics a player shows. This is the default candidate or the given one, with the lyrics filled. Providers are not asked.
getLyricsInfo songIds (List<PlatformUUID>): The song unique identifiers. Map<PlatformUUID, SongLyricsInfo> - Get the lyrics summary of songs a client already has.
findLyrics songId (PlatformUUID): The song unique identifier.
providers (List<String>?): Identifiers of the providers to ask, or null for all enabled ones.
refresh (Boolean): Asks every provider again. Needs the edit capability.		 LyricsSearchResult - Get the stored candidates of a song and ask the providers that have not answered yet or are due again. New answers are stored and ranked.
findLyricsByQuery title (String): The title of the track.
artist (String): The artist of the track.
album (String?): The album of the track.
durationMs (Long?): The duration of the track in milliseconds.
providers (List<String>?): Identifiers of the providers to ask, or null for all enabled ones.		 LyricsSearchResult - Ask the providers for the lyrics of any track. Nothing is stored and the candidates are not tied to a song.
getLyricsCandidates songId (PlatformUUID): The song unique identifier.
includeContent (Boolean): Whether to fill the lyrics of every candidate.		 LyricsSearchResult - Get the stored candidates of a song. Providers are not asked.
getLyricsCandidate candidateId (PlatformUUID): The candidate unique identifier. LyricsCandidate? - Get one candidate with the lyrics filled.
setSyncedLyrics songId (PlatformUUID): The song unique identifier.
lyrics (SyncedLyrics?): The synced lyrics, or null to remove the manual candidate.		 LyricsSearchResult EDIT IllegalArgumentException Store hand-edited synced lyrics as the manual candidate of a song. A null value removes the manual candidate.
importSyncedLyrics songId (PlatformUUID): The song unique identifier.
file (LyricsImport): The file to import.		 LyricsSearchResult EDIT IllegalArgumentException Store synced lyrics parsed from a file as the manual candidate of a song.
setPreferredLyrics songId (PlatformUUID): The song unique identifier.
candidateId (PlatformUUID?): The candidate to pin, or null to use the best ranked one again.		 LyricsSearchResult EDIT Pin the default candidate of a song for everyone.
getLyricsProviders - List<LyricsProviderInfo> - Get the enabled providers in priority order.
streamLyrics songId (PlatformUUID): The song unique identifier.
providers (List<String>?): Identifiers of the providers to ask, or null for all enabled ones.		 Flow<LyricsCandidate> - Ask the providers for the lyrics of a song and emit each candidate as soon as its provider answers.

ILyricsSearch

Search for track lyrics using external providers.

Function Parameters Returns Permissions Errors Description
searchLyrics artist (String): The name of the artist.
title (String): The title of the song.
syncedOnly (Boolean): Whether to only return time-synced lyrics.		 List<String> - RuntimeException Search for lyrics text on external services.

ILyricsService

Syncing and management of track lyrics.

Function Parameters Returns Permissions Errors Description
getSyncedLyrics songId (PlatformUUID): The song unique identifier. SyncedLyrics? - Get time-synced lyrics for a song if they exist.
transcribeLyrics songId (PlatformUUID): The song unique identifier.
lyrics (String?): Optional raw lyrics text to transcribe.		 SyncedLyrics? - RuntimeException Trigger AI-based transcription or manual alignment of lyrics.
startSyncWorker - Boolean - Start the background lyrics synchronization worker.

IMirrorService

Exposes local data for server-to-server mirroring.

Function Parameters Returns Permissions Errors Description
getServerPaths - RemoteServerPaths Admin IllegalStateException Expose the local file system paths where media files are stored.
getSongs - Flow<Song> Admin IllegalStateException Stream all local songs with metadata for mirroring.
getArtists - Flow<Artist> Admin IllegalStateException Stream all local artists for mirroring.
getArtistAliases - Flow<ArtistAlias> Admin IllegalStateException Stream all artist name aliases for mirroring.
getArtistSplitAliases - Flow<ArtistSplitAlias> Admin IllegalStateException Stream all artist split-name mappings for mirroring.
getAlbums - Flow<Album> Admin IllegalStateException Stream all local albums for mirroring.
getPlaylists - Flow<Playlist> Admin IllegalStateException Stream all local system playlists for mirroring.
getUserPlaylists - Flow<UserPlaylist> Admin IllegalStateException Stream all local user playlists for mirroring.
getImageMetadata - Flow<Image> Admin IllegalStateException Stream all image metadata for mirroring.
getSongData songId (PlatformUUID): The song unique identifier.
quality (Int): Target audio quality level.
chunkSize (Int): Number of bytes per chunk in the stream.
force (Boolean): Whether to force re-transcoding and duration check.		 Flow<ByteArray> Admin IllegalStateException Stream raw audio data for a song.
getUsers - Flow<User> Admin IllegalStateException Stream all local user accounts (profiles) for mirroring.
getUserPasswordHashes - Flow<UserPasswordHash> Admin IllegalStateException Stream the password hashes of all local user accounts for mirroring.
getSongsByPlaylist playlistId (PlatformUUID): The playlist unique identifier. Flow<Song> Admin IllegalStateException Stream all songs belonging to a specific system playlist for mirroring.
getSongsByUserPlaylist playlistId (PlatformUUID): The playlist unique identifier. Flow<Song> Admin IllegalStateException Stream all songs belonging to a specific user playlist for mirroring.
getLikedSongs userId (PlatformUUID): The user unique identifier. Flow<Song> Admin IllegalStateException Stream all songs liked by a specific user for mirroring.

IPlaybackService

Synchronize music playback status across multiple devices.

Function Parameters Returns Permissions Errors Description
getPlaybackState sessionId (PlatformUUID): The session unique identifier. PlaybackState? - Retrieve the current playback state for a specific session.
setPlaybackState sessionId (PlatformUUID): The session unique identifier.
state (PlaybackState): The new playback state data.		 Boolean - Update the playback state for a specific session.
observePlaybackState sessionId (PlatformUUID): The session unique identifier. Flow<PlaybackState> - Watch real-time playback state changes for a session.

IPlaylistService

Management of system playlists.

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The playlist unique identifier. Playlist? - Get system playlist by ID.
byIds ids (List<PlatformUUID>): Collection of playlist IDs. List<Playlist> - Get multiple system playlists by their IDs.
byIdFull id (PlatformUUID): The playlist unique identifier. Pair<String, List<PlaylistEntry>>? - Get system playlist with all track entries.
byName name (String): The name of the playlist. Playlist? - Get system playlist by name.
rankedSearch page (Int): Page index.
pageSize (Int): Number of items per page.
query (String): The search query.		 PaginatedResponse<Playlist> - Search system playlists.
allPlaylists page (Int): Page index.
pageSize (Int): Number of items per page.		 PaginatedResponse<Playlist> - Get all system playlists.
delete id (PlatformUUID): The playlist unique identifier. Boolean DELETE Delete a system playlist.

IPodcastService

Manages podcasts, which are kept completely apart from the music library: an episode is never a song, is never scrobbled and never shows up in music search or statistics. A show is either an RSS feed the server follows or a folder of the local podcast library, and a feed show is stored once and shared by everyone subscribing to it. Subscriptions and listening positions are private to each user and sync across their devices. Episode audio is always played through streamEpisode, no matter whether the server stores the file or relays its origin.

Function Parameters Returns Permissions Errors Description
subscribe feedUrl (String): The address of the RSS feed to subscribe to. Must be an http or https address of at most 2048 characters. PodcastShow - IllegalArgumentException Subscribe to an RSS feed. The feed is fetched and parsed while the call runs when the server does not know it yet, so the call fails if the feed cannot be reached or is not a podcast feed. Subscribing again to a known feed is cheap and does not fetch anything.
subscribeToShow showId (PlatformUUID): The show to subscribe to. PodcastShow - IllegalArgumentException Subscribe to a show the server already knows, for example one found through browseShows.
unsubscribe showId (PlatformUUID): The show to unsubscribe from. Boolean - End the subscription of the user to a show. Returns false if the user was not subscribed. The show itself and its episodes stay on the server for a while after the last subscriber leaves.
getSubscriptions - List<PodcastShow> - Read the shows the user is subscribed to, ordered by title.
browseShows query (String): Search term matched against title, author and description. Blank returns every show.
page (Int): Page index.
pageSize (Int): Number of shows per page, at most 500.		 PaginatedResponse<PodcastShow> - Browse every show on the server, both feed shows and shows of the local podcast library, optionally narrowed down by a search term.
searchIndex query (String): The search term. Must not be blank.
limit (Int): Maximum number of results, clamped to 1 to 100.
indexes (List<String>): Identifiers of the directories to search, see getIndexes. Empty searches every configured directory.		 List<PodcastIndexResult> - IllegalArgumentException Search the podcast directories the server is connected to, for example Podcast Index, for shows by name or topic. Every result carries the address of its feed, so subscribing to it is done with subscribe. Directories that are not configured are skipped, a directory that fails answers with no results, and feeds the server already follows are left out because browseShows lists them.
getIndexes - List<PodcastIndexInfo> - Read the podcast directories the server can search and whether each of them is configured.
getShow showId (PlatformUUID): The show to read. PodcastShow? - Read a single show. Returns null if the show does not exist.
getEpisodes showId (PlatformUUID): The show to read the episodes of.
page (Int): Page index.
pageSize (Int): Number of episodes per page, at most 500.
newestFirst (Boolean): Whether the newest episode comes first.		 PaginatedResponse<PodcastEpisode> - Read a page of episodes of a show, together with the listening position of the user for each of them.
getEpisode episodeId (PlatformUUID): The episode to read. PodcastEpisode? - Read a single episode together with the listening position of the user. Returns null if the episode does not exist.
getEpisodesByIds episodeIds (List<PlatformUUID>): The episodes to read, at most 500. List<PodcastEpisode> - IllegalArgumentException Read several episodes at once, in the order of the given identifiers, each with the listening position of the user. Unknown identifiers are skipped. At most 500 identifiers.
getEpisodeWindow episodeId (PlatformUUID): The episode the window is built around.
older (Int): How many episodes published before it to read, at most 500. Values below 0 count as none.
newer (Int): How many episodes published after it to read, at most 500. Values below 0 count as none.		 List<PodcastEpisode> - Read the episodes around one episode of its show: up to older episodes published before it and up to newer published after it, in chronological order with the episode itself included and the listening position of the user on each. Returns an empty list if the episode does not exist.
searchEpisodes query (String): The search term. Must not be blank.
page (Int): Page index.
pageSize (Int): Number of episodes per page, at most 500.		 PaginatedResponse<PodcastEpisode> - IllegalArgumentException Search episodes of every show on the server by their title, their description and the title of their show.
getLatestEpisodes page (Int): Page index.
pageSize (Int): Number of episodes per page, at most 500.		 PaginatedResponse<PodcastEpisode> - Read the newest episodes across the shows the user is subscribed to, newest first.
getInProgress page (Int): Page index.
pageSize (Int): Number of episodes per page, at most 500.		 PaginatedResponse<PodcastEpisode> - Read the episodes the user started but did not finish, the most recently played one first.
getLastPlayed includeCompleted (Boolean): Whether an episode the user already completed may be returned. When false only an unfinished episode with a position after the start counts. PodcastEpisode? - Read the episode the user played most recently, with the listening position, so a client can offer to continue it. Returns null if the user never played an episode.
reportPlayback report (EpisodePlaybackReport): What the client is playing and how far it has got. PodcastEpisodeProgress - IllegalArgumentException Store the listening position of the user for an episode. A client reports on play, on pause, after a seek and every 10 to 15 seconds while playing, the same way song playback is reported. The last report wins, and the server marks an episode as completed on its own once the remaining time is under 30 seconds or under 5 percent of its length.
setPlayed episodeId (PlatformUUID): The episode to mark.
played (Boolean): Whether the episode counts as listened.		 PodcastEpisodeProgress - IllegalArgumentException Mark an episode as listened or as unlistened. Marking it as listened moves the position to the end of the episode, marking it as unlistened resets the position to the beginning.
observeProgress - Flow<PodcastEpisodeProgress> - Watch the listening positions of the user for changes, so other devices follow along while an episode is played somewhere else.
refreshShow showId (PlatformUUID): The show to refresh. PodcastShow - IllegalArgumentException Fetch the feed of a show right now and store what changed. The call runs to completion before it returns and is skipped when the feed was already fetched less than 60 seconds ago.
updateShowSettings showId (PlatformUUID): The show to change.
settings (PodcastShowSettings): The settings to store for the show.		 PodcastShow PODCAST_EDIT IllegalArgumentException Change how the server keeps the episodes of a show. Switching a show to import makes the server store new episodes on disk, and the number of episodes to keep must be at least 1 when it is given. With newest retention the server imports the newest episodes and deletes everything beyond that count, while unlistened retention, which needs import delivery, imports the episodes nobody has finished yet and only deletes an episode once every subscriber listened to it to the end, with the keep count capping how many episodes are stored or queued at once.
importEpisode episodeId (PlatformUUID): The episode to store on the server. PodcastEpisode PODCAST_EDIT IllegalArgumentException Queue a single episode to be stored on the server. The transfer itself runs in the background, so the returned episode usually reports that its import is queued.
removeImport episodeId (PlatformUUID): The episode whose stored audio is deleted. PodcastEpisode PODCAST_EDIT IllegalArgumentException Delete the stored audio of an episode of a feed show. The episode itself stays and is played from its origin afterwards. Episodes of the local podcast library cannot be removed this way, as that would delete the file of the user.
deleteShow showId (PlatformUUID): The show to remove. Boolean Admin IllegalArgumentException Remove a feed show from the server for everyone: its episodes, their transcripts, the listening positions of every user and every subscription to it are deleted, and the audio the server stored for it is deleted from disk. Returns false if the show does not exist. Shows of the local podcast library cannot be removed this way, as the server picks them up again on the next scan.
scanLocal - PodcastScanResult PODCAST_EDIT Scan the local podcast library for new, changed and vanished shows and episodes. The call runs to completion before it returns.
streamEpisode episodeId (PlatformUUID): The episode to play.
offset (Long): Byte offset to start streaming from.
chunkSize (Int): Size of each data chunk.		 Flow<ByteArray>? - Stream the audio of an episode. This is the only way a client plays an episode: the server serves the file when the episode is stored on it or belongs to the local podcast library, and relays the audio from its origin otherwise. Returns null if the episode has no audio at all.
getStreamSize episodeId (PlatformUUID): The episode to read the size of. Long - Get the total size of the audio of an episode in bytes, or 0 if the size cannot be determined.
getTranscripts episodeId (PlatformUUID): The episode to read the transcripts of. List<PodcastTranscript> - Read the transcripts known for an episode without their text.
getTranscript transcriptId (PlatformUUID): The transcript to read. PodcastTranscriptContent? - Read a single transcript together with its text. A transcript that only exists as a remote address is fetched once on first read and kept afterwards. Returns null if the transcript does not exist or its text cannot be obtained.

IQueueService

Manages the server-stored play queue shared between the devices of a user. Every write carries the version the client based its change on. If the server has moved on since then the write is rejected with a conflict carrying the current state, unless the client forces it.

Function Parameters Returns Permissions Errors Description
getQueueInfo - QueueInfo - Get the metadata of the queue without its entries. A user without a stored queue is reported at version 0 with no entries.
getQueue page (Int): Page index.
pageSize (Int): Number of items per page.
includeSongs (Boolean): Resolve each entry's song. Leave false for large queues and fetch songs separately.		 PaginatedResponse<QueueItem> - Read a page of queue entries, ordered by their position in the original order. Each entry also carries its shuffled position, and its song metadata only when the entries are requested with the songs resolved.
observeQueue - Flow<QueueInfo> - Watch the queue of the user for changes. A new metadata snapshot is emitted after every successful write, including writes made by other devices.
beginUpload baseVersion (Long): The queue version the upload is based on.
force (Boolean): Whether to start the upload even if the server is past the base version.		 QueueUploadStart - Start a chunked upload that replaces the whole queue. Entries are staged in memory with uploadPage and become visible only on commitUpload. Starting an upload discards any previous staged upload of the user, and a staged upload expires after a while if it is not committed.
uploadPage uploadId (PlatformUUID): The upload identifier returned by beginUpload.
items (List<QueueItem>): The entries of this page, in upload order.		 Int - Stage another page of entries for a started upload. Returns the total number of entries staged so far.
commitUpload uploadId (PlatformUUID): The upload identifier returned by beginUpload.
meta (QueueMeta): The playback metadata to store with the queue.
requestId (PlatformUUID?): The client request this upload answers, if any.		 QueueWriteResult - Replace the queue with the staged entries and store the supplied playback metadata. Entries referring to unknown songs are dropped and both orders are renumbered. When the upload answers a queue request of another device, its request identifier is passed so the requester is notified.
cancelUpload uploadId (PlatformUUID): The upload identifier returned by beginUpload. Unit - Discard a staged upload without touching the stored queue.
insert baseVersion (Long): The queue version the change is based on.
position (Int): Zero-based index in the active order at which the entries are inserted.
items (List<QueueItem>): The entries to insert, in the order they should appear.
force (Boolean): Whether to apply the change even if the server is past the base version.		 QueueWriteResult - Insert entries into the queue at a position of the active order (the shuffled order while shuffle is on, otherwise the original order). With shuffle on the entries are spliced into the shuffled order and appended to the end of the original order.
remove baseVersion (Long): The queue version the change is based on.
queueIds (List<Long>): The queue identifiers of the entries to remove.
force (Boolean): Whether to apply the change even if the server is past the base version.		 QueueWriteResult - Remove entries from the queue by their queue identifiers. Unknown identifiers are ignored and the current index is adjusted to stay on the playing entry.
move baseVersion (Long): The queue version the change is based on.
queueId (Long): The queue identifier of the entry to move.
toPosition (Int): Zero-based target index in the active order.
force (Boolean): Whether to apply the change even if the server is past the base version.		 QueueWriteResult - Move a single entry to another position of the active order (the shuffled order while shuffle is on, otherwise the original order).
setCurrentIndex baseVersion (Long): The queue version the change is based on.
currentIndex (Int): Zero-based index in the active order.
force (Boolean): Whether to apply the change even if the server is past the base version.		 QueueWriteResult - Set the entry that is currently playing, addressed by its index in the active order. The index is clamped to the size of the queue.
setModes baseVersion (Long): The queue version the change is based on.
shuffleMode (Boolean): Whether the queue is played in shuffled order.
repeatMode (RepeatMode): The repetition mode to store.
force (Boolean): Whether to apply the change even if the server is past the base version.		 QueueWriteResult - Set shuffle and repeat mode. Enabling shuffle makes the server generate a shuffled order that starts with the entry that is currently playing, so the current index becomes 0. Disabling it drops the shuffled order and puts the current index back on the original position of that entry. A player that shuffled on its own uploads its order instead.
setSyncEnabled enabled (Boolean): Whether this device takes part in queue synchronization.
deviceName (String): Human readable name of this device.		 Unit - Opt the calling session in or out of queue synchronization and record the name it is listed under on other devices.
ackSynced version (Long): The queue version this device is now in sync with. Unit - Record that the calling session pulled the queue up to a version, so it can tell later whether the server state is newer than its own.
getSyncDevices - List<QueueSyncDevice> - List the devices of the user that take part in queue synchronization, including which entry is the calling session.
requestUploadFrom sessionId (PlatformUUID): The session unique identifier of the device to ask. ClientRequestStatus - Ask another device of the same user to upload its current queue and wait for the outcome. The request is delivered over the client request channel. Sessions that are not listening are reported as unreachable and sessions that stay silent as timed out.

IRadioChannelService

Admin-curated radio channels: browse and play for everyone, create and edit for admins.

Function Parameters Returns Permissions Errors Description
listChannels - List<RadioChannel> - List radio channels. Non-admin users only see published channels.
getChannel id (PlatformUUID): The channel unique identifier. RadioChannel? - Get a radio channel by ID. Returns null for a draft channel when the caller is not an admin.
rankedSearch channelId (PlatformUUID): The channel unique identifier.
query (String): The search query. Empty to list all configured content.
explicit (Boolean): Whether to include explicit-content songs.
page (Int): The page index (starting from 0).
pageSize (Int): Items per page, applied per result type.		 RadioChannelSearchResults - Ranked search across the songs, artists and albums configured on a channel. An empty query lists all configured content.
startChannel id (PlatformUUID): The channel unique identifier. PlatformUUID - Start playing a channel. Returns a radio session id to feed into IRadioService.observeRadio.
createChannel channel (InsertableRadioChannel): The initial channel metadata. PlatformUUID Admin Create a new radio channel.
updateChannel id (PlatformUUID): The channel unique identifier.
channel (InsertableRadioChannel): The new metadata.		 Boolean Admin Update a channel's metadata (name, description, enabled, position, discovery).
deleteChannel id (PlatformUUID): The channel unique identifier. Boolean Admin Delete a radio channel.
setChannelImage id (PlatformUUID): The channel unique identifier.
bytes (ByteArray): The raw bytes of the image.		 Unit Admin Set the channel's cover image from raw bytes.
addChannelItem id (PlatformUUID): The channel unique identifier.
type (RadioChannelItemType): The kind of referenced entity.
itemId (PlatformUUID): The referenced entity unique identifier.		 Boolean Admin Add a song, artist or album to a channel's configured content.
removeChannelItem id (PlatformUUID): The channel unique identifier.
type (RadioChannelItemType): The kind of referenced entity.
itemId (PlatformUUID): The referenced entity unique identifier.		 Boolean Admin Remove a song, artist or album from a channel's configured content.

IRadioService

Infinite radio stations seeded from listen history, a seed selection, or pure randomness.

Function Parameters Returns Permissions Errors Description
createRadioSession type (RadioType): The strategy used to seed the station. Ignored when a seed is provided.
seed (RadioSeed?): Optional seed material. When set, the station plays songs similar to the seed.		 PlatformUUID - Create a radio session and return its identifier. The same identifier can be reused to resume the station where it left off.
observeRadio sessionId (PlatformUUID): The radio session identifier, as returned by createRadioSession. Flow<PlatformUUID> - Infinite stream of song identifiers for a radio session. Re-collecting the same session continues without repeating songs.

IRecommendationService

Personalized music recommendations from the learned embedding space.

Function Parameters Returns Permissions Errors Description
getSimilarSongs seedSongIds (List<PlatformUUID>): Seed song unique identifiers.
limit (Int): The maximum number of results to return.		 List<UserSong> - Songs most similar to the given seed songs in the learned embedding space.
getMix window (RecommendationWindow): Recency window used to seed the mix.
limit (Int): The maximum number of results to return.		 List<UserSong> - A personalized mix seeded from the user's recent listens over a time window.
getMoodPlaylist mood (String): The mood label, as returned by getMoods.
limit (Int): The maximum number of results to return.		 List<UserSong> - Songs belonging to a given mood cluster.
getMoods - List<MoodSummary> - Available mood labels with their song counts.

IReleaseService

Track and receive notifications for new music releases.

Function Parameters Returns Permissions Errors Description
followArtist musicBrainzId (PlatformUUID): The MusicBrainz Artist UUID. Boolean - Follow an artist by their MusicBrainz ID to track their releases.
unfollowArtist artistId (PlatformUUID): The artist unique identifier. Boolean - Unfollow an artist and stop tracking their releases.
unfollowArtistByMusicBrainzId musicBrainzId (PlatformUUID): The MusicBrainz Artist UUID. Boolean - Unfollow an artist by their MusicBrainz ID and stop tracking their releases.
getFollowedArtists - List<FollowedArtist> - Get a list of all artists the current user is following.
getRecentReleases page (Int): Page index, applied to every release type separately.
pageSize (Int): Number of entries per page for each release type.		 PaginatedResponse<RecentRelease> - Retrieve a feed of recent and upcoming music releases from followed artists, merged from MusicBrainz and the Apple Music catalog. Editions of one release are folded into a single entry carrying the others in versions. Paging applies per release type: one page holds up to pageSize entries of every type, a folded group counting once, in one list sorted by date.
getArtistRecentReleases artistId (PlatformUUID): The artist unique identifier.
page (Int): Page index.
pageSize (Int): Number of items per page.
includeHidden (Boolean): Include entries that have been hidden from the feed. They carry hidden = true.		 PaginatedResponse<RecentRelease> - Retrieve recent music releases for a specific artist. Editions of one release are folded into a single entry carrying the others in versions.
getRecentReleasesByMusicBrainzId musicBrainzId (PlatformUUID): The MusicBrainz Artist UUID.
page (Int): Page index.
pageSize (Int): Number of items per page.		 PaginatedResponse<RecentRelease> - Retrieve recent music releases for an artist by their MusicBrainz ID.
getReleaseImage releaseId (PlatformUUID): The MusicBrainz release-group UUID of the recent release, or the provider release id for non-MusicBrainz sources.
size (Int): Requested image size (width/height). 0 for original size.		 ByteArray? - Retrieve the cover image for a recent release, served from local storage when persisted or proxied from the Cover Art Archive on demand.
refreshRecentRelease releaseId (PlatformUUID): The MusicBrainz release-group UUID of the recent release to refresh, or the provider release id for non-MusicBrainz sources. Unit EDIT Kick off a background refresh of the cached metadata, provider links and cover image for a single recent release, returning immediately.
setReleaseHidden releaseId (PlatformUUID): The MusicBrainz release-group UUID of the recent release, or the provider release id for non-MusicBrainz sources.
hidden (Boolean): true to hide the entry, false to show it again.
includeRelated (Boolean): Also apply the change to the artist's Apple Music entries sharing the copyright holder or record label and record or clear the block. Ignored for MusicBrainz entries.		 Int EDIT IllegalArgumentException Hide an entry of the release feed for every user, or show it again. With includeRelated the other Apple Music entries of the same artist sharing the entry's copyright holder (or record label when no holder is known) are hidden or shown as well, and the holder or label is recorded as blocked (or unblocked) for the artist so future catalog runs hide matching entries automatically. Returns the number of entries whose visibility changed. The change applies to the whole display group, i.e. every edition the feed folds under one entry.
confirmRelease releaseId (PlatformUUID): The provider release id of the flagged entry. RecentRelease EDIT IllegalArgumentException Confirm that a provider entry flagged as possibly belonging to another artist is correct: clears the flag and records the entry's copyright holder, record label and ISRC registrants as known sources of the artist so future catalog runs do not flag matching entries again. Returns the updated entry.

IRemoteControlService

Controls playback on another device of the same user and watches what it is doing. Only devices that are connected to the request channel offering the remote control capability can be reported on or addressed, and a device is always addressed by its session. Nothing here is stored: a status lives as long as the device stays connected.

Function Parameters Returns Permissions Errors Description
reportStatus status (RemotePlaybackStatus): What this device is playing right now. The report timestamp is filled in by the server. Unit - IllegalArgumentException Publish what the calling session is playing, which every device watching it receives. A client reports after every change and every few seconds while it is playing, so watchers can follow the position. The calling session must be connected offering remote control.
getStatus sessionId (PlatformUUID): The session unique identifier of the device to read. RemotePlaybackStatus? - IllegalArgumentException, UnauthorizedException Read the last status another device of the user reported, or null when it has not reported anything since it connected.
observeStatus sessionId (PlatformUUID): The session unique identifier of the device to watch. Flow<RemotePlaybackStatus> - IllegalArgumentException, UnauthorizedException Watch what another device of the user is playing. The last reported status is replayed immediately, followed by every later report.
sendCommand sessionId (PlatformUUID): The session unique identifier of the device to control.
command (PlaybackCommand): The transport command to apply on that device.		 ClientRequestStatus - IllegalArgumentException, UnauthorizedException Send a transport command to another device of the user and wait for it to answer. The device must be connected offering remote control, and a volume command additionally requires the remote volume capability and a volume between 0 and 1. A device that stays silent is reported as timed out after ten seconds.

IRemoteMirrorService

Instance-to-instance data synchronization.

Function Parameters Returns Permissions Errors Description
getRemoteStats config (RemoteServerConfig): Connection configuration for the remote server. ServerStats Admin IllegalStateException Get statistics from a remote Synara instance.
startMirror config (RemoteServerConfig): Mirroring configuration and credentials. Unit Admin IllegalStateException Start mirroring content from another Synara instance.
stopMirror - Unit Admin IllegalStateException Stop the active mirroring process.
resetMirror - Unit Admin IllegalStateException Reset the internal mirroring state.
getActiveMirrorProgress - Flow<MirrorProgress> Admin Stream real-time progress updates for the active mirroring task.
getRemoteUsers config (RemoteServerConfig): Remote connection configuration. List<User> Admin IllegalStateException List all user accounts on a remote Synara instance.
getRemotePlaylists config (RemoteServerConfig): Remote connection configuration. List<Playlist> Admin IllegalStateException List all system playlists on a remote Synara instance.
getRemoteUserPlaylists config (RemoteServerConfig): Remote connection configuration. List<UserPlaylist> Admin IllegalStateException List all user playlists on a remote Synara instance.
getProxyInstances config (RemoteServerConfig): Remote connection configuration. List<ProxyInstanceInfo> Admin IllegalStateException List available proxy instances on a remote Synara instance.
getRemoteImageData config (RemoteServerConfig): Remote connection configuration.
imageId (PlatformUUID): The unique identifier of the image.
size (Int): Requested image size (width/height).		 ByteArray? Admin IllegalStateException Fetch raw image binary data from a remote Synara instance.

IRpcMetricsService

Admin-only access to RPC call usage metrics (how often each call is invoked, per user and over time).

Function Parameters Returns Permissions Errors Description
lifetimeTotals limit (Int): Maximum number of rows to return.
username (String?): Optional username filter. Null returns totals across all users.		 List<RpcCallTotal> Admin Lifetime invocation totals per call, ordered by count descending. These counters are never pruned.
timeSeries service (String): The RPC service (interface) name, e.g. "ISongService".
method (String): The RPC method (call) name.
sinceMillis (Long): Only include buckets at or after this epoch-millis timestamp.		 List<RpcCallStat> Admin Hourly time-series of invocation counts for a specific call, oldest first.
recentEvents limit (Int): Maximum number of events to return. List<RpcCallEvent> Admin The most recent recorded invocations from the capped event log, newest first.

IScheduledTaskConfigurationService

Management of background task configurations.

Function Parameters Returns Permissions Errors Description
getConfigurations - List<TaskConfiguration> Admin SecurityException Retrieve all background task configurations.
updateConfiguration configuration (TaskConfiguration) Unit Admin SecurityException, IllegalArgumentException Update a task configuration.
observeConfigurations - Flow<List<TaskConfiguration>> Admin SecurityException Stream real-time updates for all background task configurations.
triggerTask key (String) Boolean Admin SecurityException Manually trigger a background task by its unique key.

IScheduledTaskLogService

Monitoring and tracking of background scheduled tasks.

Function Parameters Returns Permissions Errors Description
getGroupedLogs - Map<String, List<ScheduledTaskLog>> Admin SecurityException Retrieve a snapshot of the most recent background task logs grouped by task name.
observeGroupedLogs - Flow<Map<String, List<ScheduledTaskLog>>> Admin SecurityException Stream real-time updates for all background task progress and completion.

IScrobbleService

Submit playback scrobbles and observe the current user's recently listened songs, artists and albums.

Function Parameters Returns Permissions Errors Description
nowPlaying songId (PlatformUUID): The library song now playing. Unit - Report the library song the current user is now playing. Auto-clears after the song's duration unless reported again.
reportPlayback report (PlaybackReport): The current playback state. Long - Report playback progress for the current user: call on play, pause, resume, seek and every 10-15 seconds while playing. Returns the server's epoch milliseconds at receipt so clients can align their clocks.
clearNowPlaying - Unit - Clear the current user's now-playing state, e.g. when playback stops.
listened request (ScrobbleRequest): The completed listen. Unit - Record that the current user finished listening to a library song.
recentListens limit (Int): Maximum number of recent songs to return. Clamped to 1..1000. RecentListens - Get the current user's recently listened songs and current now-playing once.
recentArtists limit (Int): Maximum number of artists to return. Clamped to 1..1000. List<ListenedArtist> - Get the current user's recently listened artists, most recently played first.
recentAlbums limit (Int): Maximum number of albums to return. Clamped to 1..1000. List<ListenedAlbum> - Get the current user's recently listened albums, most recently played first.

IServerStatsService

Basic server health and performance monitoring.

Function Parameters Returns Permissions Errors Description
getStats - ServerStats - Retrieve detailed system performance metrics and library statistics.
health - Boolean - Simple connectivity check to verify the server is responding.
getProxyInfo - ProxyInfo? - Retrieve information about the reverse proxy status and configuration.

ISessionService

Manages active user sessions and connected devices.

Function Parameters Returns Permissions Errors Description
deactivateSession sessionId (PlatformUUID): The session unique identifier. Unit - Terminate a specific user session.
getSessions - List<Session> - List all sessions for the current user.

ISongService

The primary interface for song discovery, streaming, and metadata.

Function Parameters Returns Permissions Errors Description
setLikeLevel id (PlatformUUID): The unique UUID of the song.
level (LikeLevel): The new like level. NONE removes the like and the super like.		 UserSong? - Set the like level of a song. A super like also counts as a like. Changing between LIKE and SUPER keeps the song's position among the liked songs.
setLyrics id (PlatformUUID): The song unique identifier.
lyrics (List<String>): List of lyric lines.		 UserSong? EDIT Manually set song lyrics.
setArtists id (PlatformUUID): The song unique identifier.
artistIds (List<PlatformUUID>): Collection of artist IDs.		 UserSong? EDIT Update song artists.
updateSong song (Song): The song with its updated editable fields. UserSong? EDIT Update a song's editable metadata (title, artists and their credited names, MusicBrainz link, album, release date, track and disc number).
setMusicBrainzId id (PlatformUUID): The song unique identifier.
musicBrainzId (PlatformUUID?): The MusicBrainz Recording UUID.		 UserSong? EDIT Link a song to its MusicBrainz Recording record.
fetchMusicBrainzId id (PlatformUUID): The song unique identifier. UserSong? EDIT Trigger automatic MusicBrainz ID matching for a song.
byId id (PlatformUUID): The song unique identifier. UserSong? - Get song by its unique identifier.
byMusicBrainzId musicBrainzId (PlatformUUID): The MusicBrainz Recording UUID. List<UserSong> - Find songs by their MusicBrainz Recording ID.
byIds ids (List<PlatformUUID>): Collection of song IDs. List<UserSong> - Get multiple songs by their unique identifiers.
byTitle page (Int): Page index.
pageSize (Int): Number of items per page.
title (String): The song title to search for.		 PaginatedResponse<UserSong> - Search for songs by title.
byArtist page (Int): Page index.
pageSize (Int): Number of items per page.
artistId (PlatformUUID): The artist unique identifier.		 PaginatedResponse<UserSong> - List songs by a specific artist.
likedByArtist page (Int): Page index.
pageSize (Int): Number of items per page.
artistId (PlatformUUID): The artist unique identifier.
explicit (Boolean): Whether to include explicit content.		 PaginatedResponse<UserSong> - List songs liked by the user for a specific artist.
byAlbum page (Int): Page index.
pageSize (Int): Number of items per page.
albumId (PlatformUUID): The album unique identifier.		 PaginatedResponse<UserSong> - List songs in an album.
byPlaylist page (Int): Page index.
pageSize (Int): Number of items per page.
playlistId (PlatformUUID): The playlist unique identifier.		 PaginatedResponse<UserSong> - List songs in a system playlist.
byUserPlaylist page (Int): Page index.
pageSize (Int): Number of items per page.
playlistId (PlatformUUID): The user playlist unique identifier.		 PaginatedResponse<UserSong> - List songs in a user playlist.
byOriginalIds ids (Collection<PrefixedId>): Collection of original platform-specific track identifiers. List<UserSong> - Find songs by their original platform-specific unique identifiers.
byOriginalUrls urls (Collection<String>): Collection of original platform URLs. Map<String, UserSong?> - Find songs by their original platform URLs, returning a mapping.
byOriginalTracks tracks (Collection<Track>): Collection of track metadata. List<UserSong> - Find songs matching external metadata records.
likedSongs page (Int): Page index.
pageSize (Int): Number of items per page.
explicit (Boolean): Whether to include explicit content.		 PaginatedResponse<UserSong> - Get all songs liked by the current user.
superLikedSongs page (Int): Page index.
pageSize (Int): Number of items per page.
explicit (Boolean): Whether to include explicit content.		 PaginatedResponse<UserSong> - Get all songs super liked by the current user, most recently super liked first.
exportFavouritesAsCsv - String - Export all favorited songs as a CSV string.
allSongs page (Int): Page index.
pageSize (Int): Number of items per page.
explicit (Boolean): Whether to include explicit content.
tags (List<SongTag>): Only include songs that match any of these tags.
excludeTags (List<SongTag>): Exclude songs that match any of these tags. All filters combine with AND.
titleTags (List<TitleTagKind>): Only include songs whose title carries any of these title tag kinds.
excludeTitleTags (List<TitleTagKind>): Exclude songs whose title carries any of these title tag kinds. Songs without title tags are kept.		 PaginatedResponse<UserSong> - Get all songs with optional filtering.
byColor page (Int): Page index.
pageSize (Int): Number of items per page.
color (Int): The target color in ARGB format.
range (Int): The allowed range (0-255).
explicit (Boolean): Whether to include explicit content.		 PaginatedResponse<UserSong> - Search for songs by color.
deleteSongs ids (List<PlatformUUID>): Collection of song IDs to delete. Boolean DELETE Delete multiple songs from the library.
rankedSearch page (Int): Page index.
pageSize (Int): Number of items per page.
query (String): The search query.
explicit (Boolean): Whether to include explicit content.
liked (Boolean): Only search within liked songs.		 PaginatedResponse<UserSong> - Perform a ranked search for songs.
searchByLyrics page (Int): Page index.
pageSize (Int): Number of items per page.
query (String): The search query.
explicit (Boolean): Whether to include explicit content.		 PaginatedResponse<UserSong> - Search for songs by their lyrics.
streamSong id (PlatformUUID): The song unique identifier.
offset (Long): Byte offset to start streaming from.
chunkSize (Int): Size of each data chunk.		 Flow<ByteArray>? - Stream song audio data for playback.
downloadSong id (PlatformUUID): The song unique identifier.
quality (Int): Target audio quality.
offset (Long): Byte offset to start from.
chunkSize (Int): Size of each data chunk.
force (Boolean): Whether to force re-transcoding and duration check.
format (AudioFormat): The target audio format.		 Flow<ByteArray>? - IOException, IllegalStateException Download song audio in specific quality.
getStreamSize id (PlatformUUID): The song unique identifier. Long - Get the total size of the song's audio stream.
streamSongAtmos id (PlatformUUID): The song unique identifier.
offset (Long): Byte offset to start streaming from.
chunkSize (Int): Size of each data chunk.		 Flow<ByteArray>? - Stream the Dolby Atmos (E-AC-3 JOC in MP4) variant of a song. Returns null if the song has no Atmos variant.
getAtmosStreamSize id (PlatformUUID): The song unique identifier. Long - Get the size of the song's Dolby Atmos stream, or 0 if the song has no Atmos variant.
getDownloadSize id (PlatformUUID): The song unique identifier.
quality (Int): The requested quality.
force (Boolean): Whether to force re-transcoding and duration check.
format (AudioFormat): The target audio format.		 Long - Get the size of the song audio for a specific quality.
getDownloadSizes ids (List<PlatformUUID>): The song unique identifiers.
quality (Int): The requested quality in kbps, or a value <= 0 for the original file.
format (AudioFormat): The target audio format.		 List<SongDownloadSize> - Get the recorded download sizes of songs for a quality and format, without transcoding. Songs without a recorded size are left out.
allSongIds explicit (Boolean): Whether to include explicit content.
tags (List<SongTag>): Only include songs that match any of these tags.
excludeTags (List<SongTag>): Exclude songs that match any of these tags. All filters combine with AND.
titleTags (List<TitleTagKind>): Only include songs whose title carries any of these title tag kinds.
excludeTitleTags (List<TitleTagKind>): Exclude songs whose title carries any of these title tag kinds. Songs without title tags are kept.		 Flow<PlatformUUID> - Stream all song IDs with optional filtering.
likedSongIds explicit (Boolean): Whether to include explicit content. Flow<PlatformUUID> - Stream all IDs of songs liked by the current user.
superLikedSongIds explicit (Boolean): Whether to include explicit content. Flow<PlatformUUID> - Stream all IDs of songs super liked by the current user, most recently super liked first.
songIdsByArtist artistId (PlatformUUID): The artist unique identifier. Flow<PlatformUUID> - Stream song IDs belonging to an artist.
songIdsByAlbum albumId (PlatformUUID): The album unique identifier. Flow<PlatformUUID> - Stream song IDs belonging to an album.
songIdsByPlaylist playlistId (PlatformUUID): The playlist unique identifier. Flow<PlatformUUID> - Stream song IDs belonging to a system playlist.
songIdsByUserPlaylist playlistId (PlatformUUID): The user playlist unique identifier. Flow<PlatformUUID> - Stream song IDs belonging to a user playlist.
moveSongs oldPath (String): Path prefix to match.
newPath (String): New base path.
originalIdPrefix (String?): Optional originalId prefix to filter by.		 Int Admin Batch update song file paths.
extendedMetadata id (PlatformUUID): The song unique identifier. SongExtendedMetadata? - Get extended metadata for a song.

IStorageService

Monitoring of physical disk usage for the media library.

Function Parameters Returns Permissions Errors Description
getTotalStorage - Long - Calculate and return the total storage space consumed by the music library in bytes.

ISubsonicCredentialService

Manages the current user's dedicated Subsonic credential used by Subsonic/OpenSubsonic clients.

Function Parameters Returns Permissions Errors Description
getSubsonicCredential - SubsonicCredentialInfo? - Get the current user's Subsonic credential, or null if none exists.
regenerateSubsonicCredential - SubsonicCredentialInfo - Generate a new Subsonic credential for the current user, replacing any existing one.
revokeSubsonicCredential - Boolean - Delete the current user's Subsonic credential. Returns true if a credential was deleted.

ITimecodeTagService

Stores the tags a user attaches to a song at a position in milliseconds, either as a chapter that names a section, as a marker that points at a single moment or as a free-form note. Tags are private to the user who created them, so they are never visible to anyone else, and a tag disappears together with the song it belongs to. The text of a tag holds at most 1000 characters and a user keeps at most 500 tags on a single song.

Function Parameters Returns Permissions Errors Description
createTag songId (PlatformUUID): The song to attach the tag to.
tagType (TimecodeTagType): How the tag is meant to be read by a client.
text (String): The text of the tag. May be blank.
timestampMs (Long): Position in the song in milliseconds at which the tag starts.
endMs (Long?): Position in the song in milliseconds at which the tag ends, or null for a tag that marks a single point.
action (TimecodeTagAction): What the playing client does when playback reaches the tag.
fade (Boolean): Whether the client fades in from the tag and fades out towards the tag around the action.		 TimecodeTag - IllegalArgumentException Create a single tag on a song. The position must not be negative and an end position, if one is given, must not lie before the position the tag starts at. The action must fit the type: PLAY_ONLY and SKIP need a chapter with an end position, SKIP_TO and PLAY_UNTIL need a marker without one, and a note only takes NONE.
getTags songId (PlatformUUID): The song to read the tags of. List<TimecodeTag> - Read the tags the user attached to a song, ordered by the position they start at.
updateTag tagId (PlatformUUID): The tag to change.
tagType (TimecodeTagType): How the tag is meant to be read by a client.
text (String): The text of the tag. May be blank.
timestampMs (Long): Position in the song in milliseconds at which the tag starts.
endMs (Long?): Position in the song in milliseconds at which the tag ends, or null for a tag that marks a single point.
action (TimecodeTagAction?): What the playing client does when playback reaches the tag, or null to keep the stored action.
fade (Boolean?): Whether the client fades in from the tag and fades out towards the tag around the action, or null to keep the stored value.		 TimecodeTag - IllegalArgumentException Overwrite a single tag of the user with new values. The call fails if the tag does not exist or belongs to another user. An action or fade flag left out keeps the stored value, and the resulting action must fit the type: PLAY_ONLY and SKIP need a chapter with an end position, SKIP_TO and PLAY_UNTIL need a marker without one, and a note only takes NONE.
deleteTag tagId (PlatformUUID): The tag to delete. Boolean - Delete a single tag of the user. Returns false if the tag does not exist or belongs to another user.
replaceTags songId (PlatformUUID): The song whose tags are replaced.
tags (List<TimecodeTagInput>): The tags to store for the song. An empty list removes every tag of the song.		 List<TimecodeTag> - IllegalArgumentException Replace every tag the user has on a song with the supplied ones. The write is all-or-nothing, so either all tags are stored or none of them are, and an empty list clears the tags of the song. Each tag carries its action and fade flag, which follow the same rules as in createTag.
listTags tagType (TimecodeTagType?): Only return tags of this kind, or null for every kind.
page (Int): Page index.
pageSize (Int): Number of tags per page, at most 500.		 PaginatedResponse<TimecodeTag> - Read the tags of the user across all songs, newest first, optionally narrowed down to a single kind of tag.

IUiService

Server-driven UI: lists, renders and drives slot, page and home-card contributions from the server and plugins. Text is localized using the Accept-Language header. Component trees are shaped to the X-Ui-Schema-Version header. Authorization is enforced per contribution.

Function Parameters Returns Permissions Errors Description
listContributions kind (UiContributionKind?): Filter by kind.
slot (String?): Filter by slot name.		 List<UiContributionInfo> - List UI contributions visible to the current user.
renderSlot slot (String): Slot name, see UiSlots.
context (UiContext): Host context of the slot.		 UiSlotRender - Render all contributions registered for a slot that the current user may see, in display order.
render contributionId (String): Contribution id.
context (UiContext): Host context.		 UiRender - IllegalArgumentException, UnauthorizedException Render a single contribution.
subscribe contributionId (String): Contribution id.
entityId (PlatformUUID?): Host entity id, if the contribution is rendered on an entity screen.		 Flow<UiRender> - IllegalArgumentException, UnauthorizedException Stream re-renders of a contribution. Emits the current render immediately, then on every change.
subscribeLive contributionId (String): Contribution id.
key (String): Key of the Live node.
entityId (PlatformUUID?): Host entity id, if the contribution is rendered on an entity screen.		 Flow<UiLiveUpdate> - IllegalArgumentException, UnauthorizedException Stream updates for a Live node of a contribution. Subscribe once per Live node while it is on screen.
subscribeWithContext contributionId (String): Contribution id.
context (UiContext): Host context, the same one passed to render.		 Flow<UiRender> - IllegalArgumentException, UnauthorizedException Stream re-renders of a contribution rendered with a full host context, including the params a page was opened with. Emits the current render immediately, then on every change. Prefer it over IUiService.subscribe, which only carries the entity id.
subscribeLiveWithContext contributionId (String): Contribution id.
key (String): Key of the Live node.
context (UiContext): Host context, the same one passed to render.		 Flow<UiLiveUpdate> - IllegalArgumentException, UnauthorizedException Stream updates for a Live node of a contribution rendered with a full host context, including the params a page was opened with. Subscribe once per Live node while it is on screen. Prefer it over IUiService.subscribeLive, which only carries the entity id.
invoke contributionId (String): Contribution id.
actionId (String): Action id from UiAction.Invoke.
payload (UiInvokePayload): Values and context.		 UiInvokeResult - IllegalArgumentException, UnauthorizedException Dispatch an action declared by a contribution, with form values and/or action parameters.
search contributionId (String): Id of the contribution that rendered the SearchField.
key (String): Key of the SearchField.
query (String): Text typed by the user.
context (UiContext): Host context the contribution was rendered with.		 List<UiOption> - IllegalArgumentException, UnauthorizedException Options for a SearchField of a contribution that match the typed query, at most 50.
dispatchHook event (UiHookEvent): The event. List<UiHookHandler> - Forward an app-level event (e.g. a shared URL). Returns every contribution offering to handle it. Perform the single action directly or let the user choose. An empty list means no server-side handler. Fall back to native behaviour then.
listHookHandlers kind (UiHookKind?): Only handlers serving this kind. Null lists all. List<UiHookHandlerInfo> - List every handler that may offer to take hook events for the current user, without an input. Intake resolvers serve every kind. Contributions list the kinds they declare. Whether a handler accepts a specific event is only known from dispatchHook.
intake items (List<IntakeItem>): Items to submit.
resolverId (String?): Handler to use, from a previous NEEDS_CHOICE result. Null lets the server decide.		 UiIntakeResult - Hand items (links, codes, ids, text) to the server. Unambiguous items are submitted immediately. When several handlers offer, NEEDS_CHOICE returns them and the client calls intake again with the chosen handler's action. Items nobody accepts are returned as rejected.
resolveIntake items (List<IntakeItem>): Items to resolve. List<UiHookHandler> - List the handlers offering to take the items without submitting anything.
getHomeCards - UiHomeLayout - Home-card layout of the current user, including cards available for pinning.
setHomeCardPinned contributionId (String): HOME_CARD contribution id.
pinned (Boolean): Whether the card should be pinned.		 UiHomeLayout - IllegalArgumentException Pin or unpin a home card for the current user.
setHomeCardOrder contributionIds (List<String>): Pinned contribution ids in display order. UiHomeLayout - Persist the order of the current user's pinned home cards.

IUserPlaylistBackupService

Personal playlist backup and restoration for individual users.

Function Parameters Returns Permissions Errors Description
createBackup - Unit - Create a backup of all playlists owned by the current user.
listBackups - List<BackupInfo> - List all available playlist backup files for the current user.
restoreBackup fileName (String?): Optional name of the backup file. If null, the latest backup is used. Unit - Restore user playlists from a backup file.
getBackupContent fileName (String): The name of the backup file. UserPlaylistBackup? - Peek into the contents of a specific user playlist backup.
deleteBackup fileName (String): The name of the backup file. Unit - Delete a personal playlist backup file.

IUserPlaylistService

Management of personal (user-created) playlists.

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The playlist unique identifier. UserPlaylist? - Get user playlist by ID.
byIds ids (List<PlatformUUID>): Collection of playlist IDs. List<UserPlaylist> - Get multiple user playlists by their IDs.
rankedSearch creator (PlatformUUID?): Optional creator ID to filter by.
page (Int): Page index.
pageSize (Int): Number of items per page.
query (String): The search query.		 PaginatedResponse<UserPlaylist> - Search user playlists.
allPlaylists creator (PlatformUUID?): Optional creator ID to filter by.
page (Int): Page index.
pageSize (Int): Number of items per page.		 PaginatedResponse<UserPlaylist> - Get all user playlists.
byColor creator (PlatformUUID?): Optional creator ID to filter by.
page (Int): Page index.
pageSize (Int): Number of items per page.
color (Int): The target color in ARGB format.
range (Int): The allowed range (0-255).		 PaginatedResponse<UserPlaylist> - Search for user playlists by color.
delete id (PlatformUUID): The playlist unique identifier. Boolean - UnauthorizedException Delete a user playlist.
getOrAddPlaylist userId (PlatformUUID): The user ID who owns the playlist.
customIdentifier (String?): Optional unique string identifier from an external source.
playlist (InsertablePlaylist): The initial playlist data.		 PlatformUUID - UnauthorizedException Create a new user playlist or retrieve an existing one by a custom identifier.
addToPlaylist id (PlatformUUID): The playlist unique identifier.
songIds (List<Pair<Long, PlatformUUID>>): Collection of song IDs and their added timestamps.		 Unit - UnauthorizedException Add songs to a user playlist.
addSongsToPlaylist id (PlatformUUID): The playlist unique identifier.
songIds (List<PlatformUUID>): Collection of song IDs to add.		 Unit - UnauthorizedException Add songs to a user playlist.
addAlbumToPlaylist id (PlatformUUID): The playlist unique identifier.
albumId (PlatformUUID): The album unique identifier.		 Unit - UnauthorizedException Add all songs of an album to a user playlist.
addPlaylistToPlaylist id (PlatformUUID): The target playlist unique identifier.
sourcePlaylistId (PlatformUUID): The source playlist unique identifier.		 Unit - UnauthorizedException Add all songs of a playlist to a user playlist.
addUserPlaylistToPlaylist id (PlatformUUID): The target playlist unique identifier.
sourcePlaylistId (PlatformUUID): The source user playlist unique identifier.		 Unit - UnauthorizedException Add all songs of a user playlist to a user playlist.
removeFromPlaylist id (PlatformUUID): The playlist unique identifier.
songIds (List<PlatformUUID>): Collection of song IDs to remove.		 Int - UnauthorizedException Remove songs from a user playlist.
setPlaylistImage id (PlatformUUID): The playlist unique identifier.
imageId (PlatformUUID?): The image unique identifier.		 Boolean - UnauthorizedException Set the cover image for a user playlist.
createPlaylistFromArtists userId (PlatformUUID): The user ID who owns the playlist.
name (String): The name of the playlist.
artistIds (List<PlatformUUID>): Collection of artist IDs.
maxSongsPerArtist (Int): Maximum number of songs per artist.
sortStrategy (ArtistPlaylistSortStrategy): Sorting strategy.		 PlatformUUID - UnauthorizedException Create a smart playlist based on artists.
setPublic id (PlatformUUID): The playlist unique identifier.
isPublic (Boolean): Whether the playlist is public.		 Boolean - UnauthorizedException Make a user playlist public or private. A public playlist can be found and opened by every user, a private one only by its owner and the users it is shared with. Returns false when the playlist does not exist.
setShare id (PlatformUUID): The playlist unique identifier.
userId (PlatformUUID): The unique identifier of the user to share the playlist with.
access (PlaylistAccess): What the user may do with the playlist.		 Unit - IllegalArgumentException, UnauthorizedException Share a user playlist with a user, or change the access of a user it is already shared with. Only the owner can do this, and the owner cannot be given a share.
removeShare id (PlatformUUID): The playlist unique identifier.
userId (PlatformUUID): The unique identifier of the user to remove.		 Boolean - UnauthorizedException Stop sharing a user playlist with a user. The owner can remove any share, and a user can remove their own to leave the playlist. Returns false when the playlist was not shared with that user.
sharedPlaylists page (Int): Page index.
pageSize (Int): Number of items per page.		 PaginatedResponse<UserPlaylist> - Get the user playlists that other users shared with the current user.
transferOwnership id (PlatformUUID): The playlist unique identifier.
newOwnerId (PlatformUUID): The unique identifier of the user who becomes the owner.		 Boolean - UnauthorizedException Hand a user playlist over to another user. The previous owner keeps write access through a share. Returns false when the playlist or the new owner does not exist or the user already owns the playlist.

IUserService

Manages user profiles and identities.

Function Parameters Returns Permissions Errors Description
byId id (PlatformUUID): The unique UUID of the user. User? - Look up a user by their unique ID.
byUsername username (String): The username of the user. User? - Look up a user by their username.
me - User - Get the profile of the current authenticated user.
allUsers - List<User> Admin IllegalStateException List all users on the server.
allProfiles - List<UserProfile> - List the name and avatar of every user on the server, ordered by username.
setProfileImage bytes (ByteArray): The raw bytes of the image. Unit - Update the current user's avatar.
setDisplayName name (String?): The new display name. Unit - Update the current user's display name.
setCapabilities id (PlatformUUID): The UUID of the user.
capabilities (List<UserCapability>): The new list of capabilities.		 Unit Admin Update the capabilities for a specific user.
createUser user (AuthenticationRequest): The user data.
isAdmin (Boolean): Whether the user is an admin.
capabilities (List<UserCapability>): The initial capabilities of the user.		 User? Admin Create a new user.

IImportService

Management of the integrated media importer.

Function Parameters Returns Permissions Errors Description
logs - Flow<LogLine> - Stream real-time import logs from active processes.
currentImport - ImportQueueEntry? - Get the currently active import task.
importQueue - List<ImportQueueEntry> - Get the list of pending import tasks in the queue.
finishedImports - List<FinishedImportQueueEntry> - Get a list of recently completed or failed import tasks.
syncFavouritesAvailable - Boolean - Check if favorite synchronization is available.
syncFavourites - Unit IMPORT IllegalStateException Synchronize favorites with the local library.
importIds ids (List<PrefixedId>): Collection of IDs.
type (Type): The type of content (SONG, ALBUM, etc.).
importer (ImportBackend?): The importer to use.		 Unit IMPORT Queue content for import by its IDs.
importUrls urls (List<String>): Collection of URLs, ISRCs, or UPCs. Unit IMPORT Queue content for import. Each entry may be a URL, an ISRC (track), or a UPC (album barcode). Codes are resolved to a supported importer (preferring the default).
getImporterForUrl url (String): The URL to check. ImportBackend? - Get the appropriate importer backend for a given URL.
existsByOriginalId id (PrefixedId): The original ID to check.
type (Type): The type of content.		 Boolean - Check if content with a specific original ID is already present in the library.
setImportService service (ImportBackend): The importer service to use. Unit Admin Set the preferred importer backend.
getImportService - ImportBackend - Get the currently active importer backend.
allImportServices - List<ImportBackend> - Get all available importer backends.
getImporterCapabilities - Map<String, Set<ImporterCapability>> - Get the capabilities supported by each importer backend, keyed by backend id.
setImportCredentials backend (ImportBackend): The importer backend to configure.
credentials (ImporterCredentials): The credentials to supply.		 Unit Admin IllegalArgumentException Provide credentials to an importer backend that supports credential injection.
importAuthorized - Boolean - Check if the importer is authorized.
importLogin - Flow<String> IMPORT Trigger the OAuth login flow and stream the login URL.
tidalSyncAuthorized - Boolean - Check if Tidal favorite synchronization is authorized.
getAuthUrl - String Admin IllegalArgumentException Get the Tidal OAuth authorization URL.
killAllChildProcesses - Unit Admin Immediately stop all active importer processes.
search query (String?): General search query.
title (String?): Filter by track title.
artist (String?): Filter by artist name.
count (Int): Maximum number of results.		 List<ImportSong> - IllegalStateException Search for tracks directly.

ILinkResolverService

Find links to a song or album on other streaming platforms.

Function Parameters Returns Permissions Errors Description
resolvePlatformLinks urls (List<String>): Links to the song or album on a streaming platform.
isrc (String?): The ISRC of the song.
upc (String?): The UPC or EAN barcode of the album.		 List<String> - Resolve links to the same song or album on other platforms without touching the library. The ISRC is tried first, then the UPC, then each seed URL in order. Returns an empty list when nothing resolves.

IMetadataService

Service for fetching metadata from external sources.

Function Parameters Returns Permissions Errors Description
getSupportedFeatures type (MetadataType): The metadata provider to check. Set<Feature> - Get the list of features supported by the specified metadata provider.
allMetadataTypes features (Set<Feature>): Optional set of features that must be supported by the provider. List<MetadataType> - Get all registered metadata providers, optionally filtered by supported features.
searchArtists type (MetadataType): The metadata provider to use.
query (String): The search query.
limit (Int): Maximum number of results to return.		 List<Artist> - Search for artists on the specified metadata provider.
search type (MetadataType): The metadata provider to use.
query (String): The search query.
limit (Int): Maximum number of results to return.		 List<Track> - Search for tracks on the specified metadata provider.
searchAlbums type (MetadataType): The metadata provider to use.
query (String): The search query.
limit (Int): Maximum number of results to return.
includeTracks (Boolean): Whether to include tracks in the album results.		 List<Album> - Search for albums on the specified metadata provider.
getAlbumIdByTrackId type (MetadataType): The metadata provider to use.
trackId (String): The external track ID.		 String? - Get the album ID for a given track ID.
getImageUrlByAlbumId type (MetadataType): The metadata provider to use.
albumId (String): The external album ID.		 List<Image> - Get image URLs for a given album ID.
getArtistByMbId type (MetadataType): The metadata provider to use.
mbId (PlatformUUID): The MusicBrainz Artist UUID.		 Artist? - Get an artist by their MusicBrainz ID.
getAlbumByMbId type (MetadataType): The metadata provider to use.
mbId (PlatformUUID): The MusicBrainz Album (Release) UUID.		 Album? - Get an album by its MusicBrainz ID.
getTrackByMbId type (MetadataType): The metadata provider to use.
mbId (PlatformUUID): The MusicBrainz Track (Recording) UUID.		 Track? - Get a track by its MusicBrainz ID.
getImageUrlByArtistMbId type (MetadataType): The metadata provider to use.
mbId (PlatformUUID): The MusicBrainz Artist UUID.		 List<Image> - Get image URLs for an artist by their MusicBrainz ID.
getImageUrlByAlbumMbId type (MetadataType): The metadata provider to use.
mbId (PlatformUUID): The MusicBrainz Album (Release) UUID.		 List<Image> - Get image URLs for an album by its MusicBrainz ID.
getImageUrlByTrackMbId type (MetadataType): The metadata provider to use.
mbId (PlatformUUID): The MusicBrainz Track (Recording) UUID.		 List<Image> - Get image URLs for a track by its MusicBrainz ID.
getImageUrlsByAlbumIds type (MetadataType): The metadata provider to use.
albumIds (List<String>): List of external album IDs.		 Map<String, List<Image>> - Get image URLs for multiple album IDs.
getImageUrlByImageId type (MetadataType): The metadata provider to use.
imageId (PlatformUUID): The image UUID.		 String? - Get the URL for a cached image by its ID.
getTrackById type (MetadataType): The metadata provider to use.
trackId (String): The external track ID.		 Track? - Get a track by its external ID.
getTrackByIsrc type (MetadataType): The metadata provider to use.
isrc (String): The ISRC.		 Track? - Get a track by its ISRC.
getTracksByIds type (MetadataType): The metadata provider to use.
trackIds (List<String>): List of external track IDs.		 List<Track> - Get multiple tracks by their external IDs.
getAlbumsByIds type (MetadataType): The metadata provider to use.
albumIds (List<String>): List of external album IDs.		 List<Album> - Get multiple albums by their external IDs.
getAlbumByBarcode type (MetadataType): The metadata provider to use.
barcode (String): The barcode.		 Album? - Get an album by its barcode.
albumExistsById type (MetadataType): The metadata provider to use.
albumId (String): The external album ID.		 Boolean - Check if an album exists by its external ID.
getArtistsByIds type (MetadataType): The metadata provider to use.
artistIds (List<String>): List of external artist IDs.		 List<Artist> - Get multiple artists by their external IDs.

IMusicBrainzService

Fetch raw metadata records directly from the MusicBrainz database.

Function Parameters Returns Permissions Errors Description
getArtist id (PlatformUUID): The MusicBrainz Artist UUID. MusicBrainzArtist? - Retrieve a MusicBrainz Artist record.
getRecording id (PlatformUUID): The MusicBrainz Recording UUID. MusicBrainzRecording? - Retrieve a MusicBrainz Recording record by its MusicBrainz Recording UUID.
getRecordingByIsrc isrc (String): The ISRC. MusicBrainzRecording? - Retrieve a MusicBrainz Recording record by its ISRC.
getRelease id (PlatformUUID): The MusicBrainz Release UUID. MusicBrainzRelease? - Retrieve a MusicBrainz Release record.
getReleaseGroup id (PlatformUUID): The MusicBrainz Release Group UUID. MusicBrainzReleaseGroup? - Retrieve a MusicBrainz Release Group record.
searchRecording title (String): The title of the recording.
artists (List<String>): The artists of the recording.		 MusicBrainzRecording? - Search for a recording on MusicBrainz.
searchRelease title (String): The title of the release.
artists (List<String>): The artists of the release.		 MusicBrainzRelease? - Search for a release (album) on MusicBrainz.
searchReleaseByBarcode barcode (String): The barcode (UPC/EAN).
artists (List<String>): The artists of the release.		 MusicBrainzRelease? - Search for a release by barcode on MusicBrainz.
getReleasesByReleaseGroup id (PlatformUUID): The MusicBrainz Release Group UUID. List<MusicBrainzRelease> - Retrieve all releases in a MusicBrainz Release Group.