Skip to content
Synara
Synara
On this page

Synara Data Models

Services: RPC_SERVICES.md · REST routes: REST_API.md · Permissions: PERMISSIONS.md · Guides: README.md

Table of Contents

Data Models

Album

Full name: dev.dertyp.data.Album

Contains metadata about a collection of songs released together.

Field Type Description
id PlatformUUID The album unique identifier.
name String The name of the album.
artists List<ArtistCredit> Collection of artists credited for this album.
songCount Int Total number of songs in the album.
releaseDate PlatformLocalDate? The date the album was released.
totalDuration Long Sum of all track durations in milliseconds.
totalSize Long Total file size of all tracks in bytes.
coverId PlatformUUID? The album cover image unique identifier.
blurHash String? The blur hash of the album cover image.
genres List<Genre> Collection of genres associated with this album.
originalId String? The original ID of the album on external sources.
barcode String? The barcode or UPC of the album.
musicBrainzId PlatformUUID? The MusicBrainz Release unique identifier.
animatedCoverId PlatformUUID? The animated cover unique identifier.
animatedCoverImageId PlatformUUID? Identifier of the still Image from the animated cover's first frame.
animatedCoverBlurHash String? BlurHash of the animated cover's first frame.
tags List<TitleTag> Edition markers split off the name, e.g. Deluxe Edition, 10th Anniversary or 2011 Remaster, in order of extraction. The name never contains them.
versions List<Album> Other editions of the same album folded under this entry, such as deluxe, anniversary, remastered, explicit or clean variants. Each keeps its own identifiers and cover. Their own versions lists are always empty. Only filled by calls that return albums grouped into editions.
versionGroupId PlatformUUID? Identifies the group of editions this album belongs to. Albums with the same value are editions of each other. It stays the same for as long as the group exists.

AlbumExtendedMetadata

Extended metadata for an album.

Field Type Description
providers List<ProviderEntry> List of all external providers and IDs matching this album.

AnimatedImage

Metadata for a stored animated cover (a short looping video, e.g. motion album art).

Field Type Description
id PlatformUUID The animated image unique identifier.
path String Internal server path to the animated image file.
contentHash String Unique hash of the animated image content.
origin String The source or platform where the animated image originated.
format String? Container/format of the animated image (e.g. mp4, webm).
imageId PlatformUUID? Identifier of the still Image extracted from the first frame.
blurHash String? BlurHash of the first frame, surfaced for placeholders.

ApiKeyInfo

Metadata about an API key. Never contains the secret itself.

Field Type Description
id PlatformUUID The API key unique identifier.
label String Human-readable label describing where the key is used.
createdAt Long Unix timestamp (ms) when the key was created.
lastUsed Long? Unix timestamp (ms) of the last successful authentication with this key, if any.
expiresAt Long? Unix timestamp (ms) at which the key expires, if ever.
isRevoked Boolean Whether the key has been revoked.
scopes List<String> Identifiers of the scopes granted to this key.

ApiKeyScopeInfo

Describes an API key scope that can be granted to keys.

Field Type Description
id String The unique scope identifier.
name String Human-readable scope name.
description String Description of what the scope grants access to.
source String Origin of the scope: "server" for built-in scopes, otherwise the id of the plugin that registered it.

AppleChart

The current Apple Music chart of a country.

Field Type Description
country String Two-letter country code of the chart, in lower case.
kind AppleChartKind Whether the chart lists songs or albums.
updatedAt Long Time the chart was last updated, in epoch milliseconds.
entries List<AppleChartEntry> The chart entries ordered by rank.

AppleChartEntry

One entry of an Apple Music chart, with the matching library song or album when the library has it.

Field Type Description
rank Int Position in the chart, starting at 1.
appleId String Apple Music id of the song or album.
name String Title of the song or album.
artistName String Artist name as shown in the chart.
releaseDate String? Release date as an ISO date (yyyy-MM-dd), or null if unknown.
artworkUrl String? URL of the cover art, or null if there is none.
url String Apple Music URL of the song or album. It can be passed to the import service to import an entry that is not in the library.
genres List<String> Genre names of the entry.
song UserSong? The matching library song for a song chart, or null if the library does not have it.
album Album? The matching library album for an album chart, or null if the library does not have it.

AppleChartKind

The kind of an Apple Music chart. SONGS is the chart of the most played songs. ALBUMS is the chart of the most played albums.

Value Description
SONGS
ALBUMS

Artist

Full name: dev.dertyp.data.Artist

Contains metadata about a music artist or group.

Field Type Description
id PlatformUUID The artist unique identifier.
name String The name of the artist.
isGroup Boolean Whether the artist record represents a group of individuals.
artists List<Artist> Collection of sub-artists if this is a group.
about String A short biography or description of the artist.
genres List<Genre> Collection of genres associated with this artist.
imageId PlatformUUID? The artist image unique identifier.
blurHash String? The blur hash of the artist image.
musicBrainzId PlatformUUID? The MusicBrainz Artist unique identifier.
isFollowed Boolean Whether the current user is following this artist.
creditedName String? The name this artist was credited as in the current song/album context, if different from the canonical name.
joinPhrase String? The phrase that follows this artist in the credit of the current song/album context, such as " & " or " feat. ". Null when the credit source has none.

ArtistAlias

Represents an alternative name for an artist.

Field Type Description
artistId PlatformUUID The artist unique identifier.
name String The alternative name.

ArtistCredit

An artist as credited on a song or album. Carries the same fields as a full artist without the biography.

Field Type Description
id PlatformUUID The artist unique identifier.
name String The name of the artist.
isGroup Boolean Whether the artist record represents a group of individuals.
artists List<ArtistCredit> Collection of sub-artists if this is a group.
genres List<Genre> Collection of genres associated with this artist.
imageId PlatformUUID? The artist image unique identifier.
blurHash String? The blur hash of the artist image.
musicBrainzId PlatformUUID? The MusicBrainz Artist unique identifier.
isFollowed Boolean Whether the current user is following this artist.
creditedName String? The name this artist was credited as in the current song/album context, if different from the canonical name.
joinPhrase String? The phrase that follows this artist in the credit of the current song/album context, such as " & " or " feat. ". Null when the credit source has none.

ArtistPlaylistSortStrategy

Strategy for sorting songs when creating a playlist from artists.

Value Description
MB_RELEASE_DATE Sort by MusicBrainz release date (newest first).
MB_RELEASE_DATE_ASC Sort by MusicBrainz release date (oldest first).
SHUFFLED Randomly shuffle the songs.
ALBUM_ORDER Group by artist and album, following track order.
BY_GENRE Group by genre.

ArtistSplitAlias

Represents a split mapping for a combined artist name.

Field Type Description
artistId PlatformUUID The artist unique identifier.
name String The name to be split.

ArtistTopSong

A library song of an artist with its popularity across all listeners and the current user's own listen count.

Field Type Description
song UserSong The library song.
globalListenCount Long? Total listen count of the song across all listeners, or null if unknown.
globalUserCount Long? Number of distinct listeners of the song, or null if unknown.
ownListenCount Long Deduplicated listen count of the current user, including the listens of accounts linked for listen sharing.

ArtistTopSongOrder

How the top songs of an artist are ranked. GLOBAL_LISTENS ranks by the listen count across all listeners, songs without one come last. OWN_LISTENS ranks by the current user's own listen count.

Value Description
GLOBAL_LISTENS
OWN_LISTENS

ArtistType

The category of a MusicBrainz artist.

Value Description
PERSON
GROUP
ORCHESTRA
CHOIR
CHARACTER
OTHER
UNKNOWN

AudioBand

Frequency band of a song's level tracks.

Value Description
SUB Sub bass, 20-60 Hz.
KICK Kick and bass fundamentals, 60-130 Hz.
LOW_MID Low mids, 130-400 Hz.
MID Mids, 400-2000 Hz.
HIGH Highs, 2000-8000 Hz.

AudioFormat

Supported audio formats for transcoding.

Value Description
OPUS Opus audio codec in Ogg container.
AAC Advanced Audio Coding in MP4 container.

AudioInfo

Physical properties of one audio file belonging to a song.

Field Type Description
codec String Audio codec of the file, e.g. flac, wav, eac3.
sampleRate Int Audio sample rate in Hz.
bitsPerSample Int Number of bits per audio sample. 0 for lossy codecs.
bitRate Long Audio bit rate in kilobits per second.
fileSize Long Size of the audio file in bytes.
channels Int Number of audio channels, e.g. 2 for stereo or 6 for 5.1.

AudioScale

The musical scale of a track.

Value Description
Major
Minor
MajMin
Unknown

AuthenticationRequest

Request payload for user authentication.

Field Type Description
username String The username.
password String The plain text password.

AuthenticationResponse

Response payload containing JWT tokens after successful authentication.

Field Type Description
token String The primary JWT access token.
refreshToken String A long-lived token used to obtain new access tokens.
expiresAt PlatformDate Timestamp of when the access token expires.

BackupImage

Contains raw binary data for a cover image in a backup.

Field Type Description
image Image Metadata for the image.
data ByteArray The raw binary data of the image.

Change

A notification that a piece of the user's state changed. It carries no data, so the client reads the new state with the getter the ChangeTopic names.

Field Type Description
topic ChangeTopic What changed. Topics a client does not know are decoded as UNKNOWN.

ChangeTopic

The kind of state a change notification is about. Each topic names the getter a client calls again to read the new state.

Value Description
UNKNOWN A topic this client does not know yet. Clients ignore it.
ONLINE_DEVICES The connected devices of the user changed. Read them again with IClientRequestService.getOnlineDevices.
HOME_CARDS The pinned home cards or their layout changed. Read them again with IUiService.getHomeCards.
LISTENS The listen history or the song playing right now changed. Read it again with IScrobbleService.recentListens, IScrobbleService.recentArtists or IScrobbleService.recentAlbums.
LISTENBRAINZ_STATUS The ListenBrainz link or its sync status changed. Read it again with IListenBrainzService.getStatus.

ClientCapability

A cross-device feature a client offers for as long as it keeps its request subscription open.

Value Description
QUEUE_SYNC The client keeps the shared play queue in sync and can be asked to upload its own queue.
REMOTE_CONTROL The client accepts transport commands from other devices of the user and reports what it is playing.
REMOTE_VOLUME The client can change its playback volume on request, which is not possible on every platform.

ClientDescription

How a client describes itself when it connects to the request channel. The description is kept only while the connection is open, so a client resubscribes to change it.

Field Type Description
deviceName String Human readable name the device is listed under on the other devices of the user.
platform String Free-form platform label of the device, for example Android, iOS or Desktop.
deviceId String? The settings synchronization device identifier of the client, when it has one, so other devices can correlate the connection with stored settings.
capabilities Set<ClientCapability> The cross-device features this client offers while the connection is open.

ClientDevice

A device of the user that stores settings on the server. Devices are identified by a stable identifier the client generates and persists itself.

Field Type Description
deviceId String The stable identifier the client chose for itself.
name String Human readable name the device reported for itself.
platform String Platform the device reported for itself, for example the operating system it runs on.
createdAt Long Unix timestamp in milliseconds at which the device was first seen.
lastSeenAt Long Unix timestamp in milliseconds of the last time the device read or wrote its settings.
settingsVersion Long The current version of the device scope of this device, or 0 if it never stored a device setting.

ClientRequest

A task the server asks a specific client session to perform. Clients observe these and answer by calling the matching RPC methods.

Field Type Description
id PlatformUUID Identifier of this request, reported back when the client completes it.
requestedAt Long Unix timestamp in milliseconds at which the request was issued.

ControlPlayback

Another device of the same user asks this client to change its playback. The client applies the command, publishes its new status through the remote control service and answers with complete, reporting the request as rejected when it does not apply the command. This request is only sent to sessions that connected with the remote control capability.

Field Type Description
id PlatformUUID Identifier of this request, passed to complete.
requestedAt Long Unix timestamp in milliseconds at which the request was issued.
requestedBySessionId PlatformUUID The session of the same user that asked for the change.
requestedByDeviceName String? Name of the device that asked for the change, if known.
command PlaybackCommand The transport command to apply.

UploadQueue

Another device asks this client for its current play queue. The client fulfils the request by calling beginUpload with force set to true, staging its entries with uploadPage and finishing with commitUpload passing this request ID, since the requester explicitly wants the queue of this device and therefore expects it to win over the server state. If the client refuses, it reports the request as rejected instead.

Field Type Description
id PlatformUUID Identifier of this request, passed to commitUpload or complete.
requestedAt Long Unix timestamp in milliseconds at which the request was issued.
requestedBySessionId PlatformUUID The session of the same user that asked for the queue.
requestedByDeviceName String? Name of the device that asked for the queue, if known.

ClientRequestStatus

Outcome of a server request sent to a client session.

Value Description
COMPLETED The client performed the requested task.
REJECTED The client received the request but declined it.
TIMED_OUT The client did not answer before the server stopped waiting.
UNREACHABLE The target session is not listening for requests.

ClientSetting

A single stored settings entry. The server is agnostic to what a setting means: the key is an opaque identifier chosen by the client and the value is an arbitrary JSON document stored as text.

Field Type Description
key String The opaque key of the entry, unique within its scope.
value String? The stored value as a JSON document in text form, or null when the entry is a tombstone.
deleted Boolean Whether the entry is a tombstone, meaning the key was deleted and is only kept so other devices learn about the deletion.
version Long The scope version this entry was last written at. The client passes it back as the base version of its next write to the key.
modifiedAt Long Unix timestamp in milliseconds of the write that produced this entry.
modifiedByDeviceId String? The device that performed the write, or null if the writer did not identify itself.
scope ClientSettingScope The scope the entry belongs to.
deviceId String? The device the entry belongs to in the device scope, and null in the synced scope.

ClientSettingConflict

A single key of a rejected write whose stored entry moved past the base version the client supplied.

Field Type Description
key String The key that was not written.
baseVersion Long The base version the client supplied for this key.
current ClientSetting? The entry currently stored on the server, or null if the key does not exist at all.

ClientSettingScope

Determines whether a settings entry is shared by all devices of the user or belongs to a single device. The client picks the scope per key.

Value Description
SYNCED The entry is shared by every device of the user and follows the user to new installations.
DEVICE The entry belongs to one device only and is addressed together with its device identifier.

ClientSettingWrite

A single change to a settings key, either a new value or a deletion, carrying the version the client based the change on.

Field Type Description
key String The opaque key to write.
value String? The value to store as a JSON document in text form. A null value deletes the key and leaves a tombstone behind.
baseVersion Long The version of the entry the client last saw, or 0 if it believes the key does not exist. The write is rejected with a conflict when the stored entry moved past this version, unless the write is forced.

ClientSettingsChange

Notification that a scope advanced to a new version, so other devices can pull the keys that changed.

Field Type Description
scope ClientSettingScope The scope that changed.
deviceId String? The device whose scope changed in the device scope, and null in the synced scope.
version Long The version the scope advanced to.
keys List<String> The keys written by this change, deletions included.
modifiedByDeviceId String? The device that performed the write, or null if the writer did not identify itself.

ClientSettingsChanges

A page of entries a scope changed since a version the client already knows, used to catch up without reading the whole scope.

Field Type Description
scope ClientSettingScope The scope the changes belong to.
deviceId String? The device the changes belong to in the device scope, and null in the synced scope.
version Long The current version of the scope.
entries List<ClientSetting> The entries written after the requested version, tombstones included, ordered by the version they were written at.
hasMore Boolean Whether more entries follow. The client asks again with the version of the last entry it received.
fullResync Boolean Whether tombstones the client never saw were already purged, so the changes are incomplete. The client has to read the whole scope again instead of applying them.

ClientSettingsSnapshot

The complete settings of one device: the live entries of the synced and the device scope with the current version of each. Reading a snapshot registers the device or refreshes its last seen time.

Field Type Description
deviceId String The device the snapshot was taken for.
syncedVersion Long The current version of the synced scope.
deviceVersion Long The current version of the device scope of this device.
entries List<ClientSetting> The live entries of both scopes, each tagged with the scope it belongs to and without tombstones. A device entry overrides a synced entry of the same key on the client.

ClientSettingsWriteResult

Result of a settings write, either the applied entries or the keys that are in conflict. A write is all-or-nothing.

Field Type Description
version Long The version of the scope after the write, or the unchanged current version when the write was rejected.

Conflict

Full name: dev.dertyp.data.ClientSettingsWriteResult.Conflict

Nothing was written because the listed keys moved past the base version the client supplied. The client pulls those keys and retries with the version it now knows, or repeats the write with force enabled to overwrite the server state.

Field Type Description
version Long The unchanged current version of the scope.
conflicts List<ClientSettingConflict> The keys of the batch that were in conflict, each with the entry currently stored on the server.

Ok

Full name: dev.dertyp.data.ClientSettingsWriteResult.Ok

Every entry of the batch was applied and the scope advanced to a new version.

Field Type Description
version Long The version of the scope after the write.
entries List<ClientSetting> The entries as they are now stored, each stamped with the new version.

CollectionItemType

The kind of entity a collection item refers to.

Value Description
SONG A single song.
ALBUM A whole album.
ARTIST A whole artist.
PLAYLIST A user-created playlist.

CollectionSearchResults

Ranked search results within a single collection, grouped by entity type.

Field Type Description
songs PaginatedResponse<CollectionSongMatch> Matching songs the collection resolves to (explicit and implicit members).
artists PaginatedResponse<Artist> Matching artists explicitly added to the collection.
albums PaginatedResponse<Album> Matching albums explicitly added to the collection.
playlists PaginatedResponse<UserPlaylist> Matching playlists explicitly added to the collection.

CollectionSongMatch

A song matched by a collection search, with how it belongs to the collection.

Field Type Description
song UserSong The matched song.
directMember Boolean True when the song is added directly to the collection. False when it is reached via an album, artist or playlist that is in the collection.

CoverGenerationOptions

Styles and asset packs the current user may choose from.

Field Type Description
styles List<CoverStyle> Available styles.
packs List<CoverPackInfo> Available asset packs. NSFW packs are only listed when enabled on the server.
nsfwEnabled Boolean Whether NSFW packs are enabled on the server.

CoverGenerationParams

Parameters controlling how a cover is generated.

Field Type Description
style CoverStyle Layout style.
seed Long? Seed for deterministic output. Null derives a stable seed from the content.
allowNsfw Boolean Whether NSFW asset packs may be used. Ignored unless enabled on the server.
includeTitle Boolean Whether to draw the playlist or collection name on the cover.
pack String? Asset pack id to use. Null picks the best match for the content.

CoverInfo

The current cover state of a playlist or collection.

Field Type Description
target CoverTarget The entity the info refers to.
imageId PlatformUUID? The current cover image unique identifier.
source ImageSource? Where the current cover came from. Null when there is no cover.
style CoverStyle? Style used for the last generated cover.
seed Long? Seed used for the last generated cover.

CoverPackInfo

An asset pack available for cover generation.

Field Type Description
id String Pack id.
name String Display name.
tags List<String> Tags the pack matches against, e.g. genres, mood:, energy:, palette:*.
nsfw Boolean Whether the pack contains adult content.
attribution String? Attribution or license note.

CoverStyle

Layout style of a generated cover.

Value Description
AUTO Pick a style from the number of available source images.
SINGLE A single source image, full bleed.
GRID A 2x2 grid of source images.
MOSAIC A 3x3 grid of source images.
STACKED Overlapping, slightly rotated source images.
GRADIENT No source images. A gradient derived from the content palette.

CoverTarget

Identifies the playlist or collection a cover operation applies to.

Field Type Description
type CoverTargetType The kind of entity.
id PlatformUUID The entity unique identifier.

CoverTargetType

The kind of entity a generated cover belongs to.

Value Description
PLAYLIST A user playlist.
COLLECTION A media collection.

CustomMetadata

Manually provided metadata for custom audio uploads.

Field Type Description
title String? The title of the song.
artists List<String>? Collection of artist names.
album String? The name of the album.
year String? The release year.
genre String? The musical genre.
coverData ByteArray? The raw binary data of the cover image.

Discoveries

Songs and artists listened to for the first time within the range.

Field Type Description
songs List<TopSongEntry> Songs first listened to within the range, ranked by the requested top order.
artists List<TopArtistEntry> Artists first listened to within the range, ranked by the requested top order.

EntityChange

A recorded change of one part of one entity. An entry carries no data, it says that this part of this entity changed and has to be read again. Only the latest change per entity and part is kept, so several changes of the same part arrive as one entry. A deleted entity appears as a single entry with the aspect DATA and the kind DELETED.

Field Type Description
entityType EntityType The kind of entity that changed. Types a client does not know are decoded as UNKNOWN.
entityId PlatformUUID The unique identifier of the entity that changed.
aspect EntityChangeAspect The part of the entity that changed. Parts a client does not know are decoded as UNKNOWN.
kind EntityChangeKind What happened to that part. Kinds a client does not know are decoded as UNKNOWN.
changedAt Long When the change was recorded (epoch milliseconds).

EntityChangeAspect

The part of an entity that changed. Parts change independently, so a like says nothing about the entity's own fields.

Value Description
UNKNOWN A part this client does not know yet. Clients ignore it.
DATA The entity's own fields a client can read, such as names, tags, credits, cover, lyrics, numbers and links.
MEMBERS What the entity contains, such as the songs of an album or playlist, the items of a collection, or the albums and songs of an artist.
LIKE The like state of the calling user, meaning the like level of a song, the star of an album or following an artist. It belongs to one user.
TIMECODES The timecode tags of the calling user on a song. It belongs to one user.

EntityChangeKind

What happened to the part of an entity a recorded change is about.

Value Description
UNKNOWN A kind this client does not know yet. Clients treat it as a reason to read the entity again.
CREATED The entity was created. An entry keeps CREATED when the entity is updated afterwards and only its time moves, so a client that already has the entity can receive CREATED again and reads the entity again.
UPDATED The part of the entity was updated.
DELETED The entity was deleted.

EntityChangeWindow

The time frame a client needs around a pull of recorded changes. It tells which time to ask from next and how far back the recorded changes reach.

Field Type Description
serverTime Long The time the client passes as since on its next pull (epoch milliseconds). It lies slightly in the past, so a change written while the client was pulling is not missed. Entries can therefore repeat between two pulls.
availableSince Long The earliest time from which the recorded changes are complete (epoch milliseconds). A client whose since lies before it reads everything again instead of pulling.

EntityType

The kind of library entity a recorded change is about.

Value Description
UNKNOWN An entity type this client does not know yet. Clients ignore it.
SONG A song.
ALBUM An album.
ARTIST An artist.
USER_PLAYLIST A playlist a user owns.
PLAYLIST A global playlist, mirrored or imported from a platform.
COLLECTION A collection.

EpisodePlaybackReport

What a client reports about the episode it is playing so the server can keep the listening position of the user up to date.

Field Type Description
episodeId PlatformUUID The episode being played.
positionMs Long The current listening position in the episode in milliseconds. Must not be negative.
durationMs Long? The length of the episode in milliseconds as the client knows it, or null to let the server use the length it stored.
completed Boolean Whether the client considers the episode finished. The server also completes an episode on its own near its end.
deviceId String? A stable identifier of the device the episode is played on, at most 64 characters.

FavSync

Record of a successful favorite synchronization task.

Field Type Description
userId PlatformUUID The user who initiated the synchronization.
service SyncServiceType The external service that was synchronized (e.g., TIDAL).
syncedAt PlatformDate Timestamp of when the synchronization was completed.

Genre

Represents a musical genre or category.

Field Type Description
id PlatformUUID The genre unique identifier.
name String The name of the genre.

HandshakeResponse

Response for the server handshake/reachability test.

Field Type Description
secure Boolean Whether the current connection is secure (HTTPS/WSS).
sslSupported Boolean Whether the server supports secure connections (HTTPS/WSS).
apiVersion Int Highest API version the server supports. Clients send the version they support in the X-Api-Version header. An absent header means 1.
uiSchemaVersion Int Highest server-driven UI schema version the server supports. 0 means unsupported. Clients send theirs in the X-Ui-Schema-Version header.

HueBridgeCandidate

A Hue bridge found on the network but not necessarily paired yet.

Field Type Description
bridgeId String? Bridge hardware id (hex), when known.
ip String IP address of the bridge.
modelId String? Model id, when known.
paired Boolean Whether this bridge is already paired by the current user.
name String? Name reported by the bridge, when it answered.

HueBridgeInfo

A Hue bridge paired with this server.

Field Type Description
id PlatformUUID Server-side unique identifier of the bridge.
bridgeId String Bridge hardware id (hex).
ip String IP address of the bridge.
name String Display name.
modelId String? Model id, when known.
lastSeen Long? Unix timestamp in milliseconds of the last successful contact.
lastError String? Last error talking to the bridge, if any.

HueIntensity

How strongly the lights react.

Value Description
LOW Dim, subtle colors.
MEDIUM Balanced.
HIGH Bright, saturated.

HueMotionMode

Ambient light movement while a song plays.

Value Description
OFF Set the colors once per track.
SLOW Slowly rotate the palette across the lights with long crossfades.
TEMPO Rotate the palette once per bar of the song's tempo and let brightness follow the loudness envelope.
BASS Rotate the palette once per bar of the song's tempo and let brightness follow the bass energy (kick and sub) with a wide swing.

HuePairingState

State of a pairing attempt.

Value Description
CONNECTING Contacting the bridge.
WAITING_FOR_BUTTON Waiting for the link button on the bridge to be pressed.
PAIRED Pairing succeeded.
TIMEOUT The link button was not pressed in time.
ERROR Pairing failed.

HuePairingStatus

Progress of a pairing attempt.

Field Type Description
state HuePairingState Current state.
message String? Human-readable detail, e.g. the error.
bridge HueBridgeInfo? The paired bridge once state is PAIRED.

HueScene

A scene on a bridge, scoped to a room or zone.

Field Type Description
id String Bridge resource id of the scene.
name String Display name.
groupType HueTargetType Kind of group the scene belongs to. ROOM or ZONE.
groupId String Bridge resource id of the room or zone.
groupName String Display name of the room or zone.

HueStatus

Current light state for a user's links.

Field Type Description
lastCommandAt Long? Unix timestamp in milliseconds of the last command sent for the user, if any.
lastError String? Last error for any of the user's bridges, if any.
currentColors List<Int> Colors (ARGB) most recently applied, in target order.

HueStopMode

What happens to the lights when playback stops.

Value Description
KEEP Leave the lights as they are.
OFF Turn the linked lights off.
SCENE Recall the configured Hue scenes.

HueTarget

A light, room, zone or entertainment area on a bridge.

Field Type Description
type HueTargetType Kind of target.
id String Bridge resource id of the light, room, zone or entertainment configuration.
name String Display name.
groupedLightId String? Resource id of the grouped light for rooms and zones.

HueTargetType

Kind of light target on a bridge, including entertainment areas.

Value Description
LIGHT A single light.
ROOM A room. Controlled through its grouped light.
ZONE A zone. Controlled through its grouped light.
ENTERTAINMENT An entertainment area. Streamed over the Entertainment API at up to 25 frames per second, at most one per bridge link.

HueTransitionMode

How the transition duration between colors is chosen.

Value Description
FIXED Use the configured duration.
BPM Derive the duration from the song tempo.

A user's link to a bridge: which lights follow the user's playback and how.

Field Type Description
bridgeId PlatformUUID Server-side unique identifier of the bridge.
enabled Boolean Whether the link is active.
targets List<HueTarget> Lights, rooms and zones that follow playback. At most one entertainment area.
intensity HueIntensity Reaction strength.
transitionMode HueTransitionMode Transition duration mode.
transitionMs Int Transition duration in milliseconds for FIXED mode.
onStop HueStopMode Behaviour when playback stops.
updatedAt Long Unix timestamp in milliseconds of the last change.
motion HueMotionMode Ambient movement while a song plays.
latencyMs Int Milliseconds by which light changes are sent early to compensate bridge and lamp latency. Between 0 and 1000.
stopScenes List<HueScene> Scenes recalled when playback stops in SCENE mode. At most one per room or zone.

Image

Full name: dev.dertyp.data.Image

Metadata for a stored image file (e.g., cover art, profile picture).

Field Type Description
id PlatformUUID The image unique identifier.
path String Internal server path to the image file.
imageHash String Unique hash of the image content.
origin String The source or platform where the image originated.
blurHash String? BlurHash string for placeholders.
width Int? Width of the image in pixels.
height Int? Height of the image in pixels.
byteSize Long? Size of the image file in bytes.
primaryColor Int? Primary color of the image in ARGB format.
luminance Double? Perceived brightness of the image (0.0 to 1.0).
palette List<Int>? Top 5 dominant colors in the image.

ImageSource

Where the current cover image of a playlist or collection came from.

Value Description
USER Chosen or uploaded by the user. Never replaced automatically.
GENERATED Generated by the server. May be regenerated when the content changes.

InsertableAlbum

Configuration for creating or updating an album record.

Field Type Description
name String The name of the album.
artists List<String> Collection of artist names.
releaseDate PlatformLocalDate? The date the album was released.
songCount Int Total number of songs in the album.
coverHash String? The hash of the album cover image.
originalId String? The original ID of the album on external sources.
barcode String? The barcode or UPC of the album.
musicBrainzId PlatformUUID? The MusicBrainz Release unique identifier.
tags List<TitleTag> Edition markers. When empty the server splits them off the name.

InsertableAnimatedImage

Configuration for uploading or storing a new animated image.

Field Type Description
data ByteArray The raw binary data of the animated image.
contentHash String Unique hash of the animated image content.
origin String The source or platform where the animated image originated.

InsertableCollection

Configuration for creating or updating a collection.

Field Type Description
name String The name of the collection.
description String? An optional user-provided description.
imageId PlatformUUID? The optional cover image unique identifier.

InsertableImage

Configuration for uploading or storing a new image.

Field Type Description
data ByteArray The raw binary data of the image.
imageHash String Unique hash of the image content.
origin String The source or platform where the image originated.

InsertablePlaylist

Configuration for creating or updating a user playlist.

Field Type Description
name String The name of the playlist.
description String Optional description.
songPaths List<String> Collection of file paths for the songs to include.
imageHash String? Optional hash of the cover image.
origin String? Optional source platform identifier.

InsertableRadioChannel

Configuration for creating or updating a radio channel's metadata.

Field Type Description
name String The channel name.
description String? An optional description.
enabled Boolean Whether the channel is published and visible to non-admin users.
position Int Display ordering. Lower values appear first.
discovery Boolean When true the channel expands its configured content into recommended similar songs.

InsertableSong

Configuration for creating or updating a song record.

Field Type Description
title String The title of the song.
artists List<String> Collection of artist names.
album InsertableAlbum The album configuration.
duration Long Duration of the song in milliseconds.
explicit Boolean Whether the song contains explicit content.
releaseDate PlatformLocalDate? Original release date of the track.
lyrics String The plain text lyrics of the song.
path String Internal server path to the audio file.
originalUrl String The URL to the item on its original platform.
trackNumber Int The position of the track in the album.
discNumber Int The disc number in a multi-disc album.
copyright String Copyright information for the track.
audio AudioInfo Properties of the primary audio file.
coverHash String? The hash of the cover image.
musicBrainzId PlatformUUID? The MusicBrainz Recording unique identifier.
isrc String? The International Standard Recording Code.
audioData SongAudioData? Additional audio analysis data.
atmosPath String? Internal server path to the Dolby Atmos (E-AC-3 JOC in MP4) variant, if one exists.
atmos AudioInfo? Properties of the Dolby Atmos variant. Probed by the server when null and atmosPath is set.
tags List<TitleTag> Version markers. When empty the server splits them off the title.

LikeLevel

How strongly a user likes a song. A super like also counts as a like everywhere likes are used.

Value Description
NONE The song is not liked.
LIKE The song is liked.
SUPER The song is super liked. It is also a liked song.

LinkUnmatchedTrackRequest

Request to link a user's unmatched listens of a track to a library song, identified by recording MSID and/or MBID.

Field Type Description
songId PlatformUUID The library song to link the listens to.
recordingMsid PlatformUUID? A ListenBrainz recording MSID of the unmatched track. The server expands it to the whole group.
recordingMbid PlatformUUID? The MusicBrainz recording MBID of the unmatched track.

LinkUnmatchedTrackResult

Result of linking unmatched listens to a library song.

Field Type Description
linkedListens Int Number of listens that were linked to the song.
submittedToListenBrainz Int Number of manual mappings accepted by the ListenBrainz API. 0 when the song has no recording MBID, no account token is stored, or no listens carry an MSID.

LinkedListenGroup

A group of the user's listens that is linked to a library song.

Field Type Description
key LinkedListenGroupKey The key that identifies the group, to pass to relinkSong.
trackName String? The track name of the most recent listen in the group, or null if unknown.
artistName String? The artist name of the most recent listen in the group, or null if unknown.
releaseName String? The release name of the most recent listen in the group, or null if unknown.
listenCount Long Number of listens in the group.
listenedMs Long Total milliseconds listened across the group.
lastListenedAt Long Time of the most recent listen in the group (epoch milliseconds).
linkedManually Boolean True when the group was linked to the song by the user rather than automatically.

LinkedListenGroupKey

Identifies a group of listens linked to a library song. LOCAL groups are keyed by the song that was actually played. LISTENBRAINZ groups are keyed by recording MBID, or by recording MSID when there is no MBID. A LISTENBRAINZ key with neither holds the listens that carry no recording identity.

Field Type Description
source ListenGroupSource The kind of listens in the group.
playedSongId PlatformUUID? The library song that was actually played, for LOCAL groups. Null for LISTENBRAINZ groups.
recordingMbid PlatformUUID? The MusicBrainz recording MBID of a LISTENBRAINZ group, or null.
recordingMsid PlatformUUID? The ListenBrainz recording MSID of a LISTENBRAINZ group without a recording MBID, or null.

ListenBackupConfig

Configuration for backing up server-side listens to a remote listen-backup receiver.

Field Type Description
enabled Boolean Whether the backup worker pushes listens to the receiver.
url String Base URL of the listen-backup receiver, e.g. https://backup.example.com:8082.
key String? API key sent to the receiver. Null on update keeps the stored key. The server never returns it.
batchSize Int Maximum number of listens sent per request (1..10000).

ListenBackupConnectionTest

Result of probing a listen-backup receiver.

Field Type Description
ok Boolean Whether the receiver responded successfully.
message String? Error message if the probe failed.
remoteListenCount Long? Number of listens the receiver holds for this server, when available.

ListenBackupState

Current configuration and progress of the listen backup.

Field Type Description
config ListenBackupConfig The stored configuration, with the key omitted.
hasKey Boolean Whether an API key is stored.
serverId PlatformUUID Identifier of this server as known to the receiver.
lastSyncAt Long? Unix millis of the last completed sync run, or null if never synced.
lastSyncedUpdatedAt Long Update timestamp (unix millis) of the newest listen confirmed by the receiver.
lastSyncedCount Int Number of listens sent during the last sync run.
lastError String? Error message of the last failed sync run, or null if it succeeded.
pendingCount Long Number of local listens that have not been pushed yet.

ListenBrainzStatus

The status of a user's ListenBrainz connection.

Field Type Description
username String The linked ListenBrainz username.
enabled Boolean Whether automatic syncing is enabled.
lastListenedAt Long? Timestamp (unix seconds) of the most recent synced listen.
lastSyncedAt Long? When the account was last synced (epoch milliseconds).
matchedListenCount Long Number of the account's listens matched to local songs.

ListenClock

Distribution of listens over the hours of the day and days of the week, in the requested timezone.

Field Type Description
hourOfDay List<Long> Listen counts per hour of day. 24 entries, index 0 = 00:00-00:59.
dayOfWeek List<Long> Listen counts per day of week. 7 entries, index 0 = Monday.

ListenGroupSource

The kind of listens in a linked listen group. LOCAL groups hold plays on this server. LISTENBRAINZ groups hold listens imported from ListenBrainz.

Value Description
LOCAL
LISTENBRAINZ

ListenedAlbum

An album from the user's listen history, with when one of its songs was last played.

Field Type Description
album Album The listened album.
lastListenedAt Long When a song of the album was last played (epoch milliseconds).

ListenedArtist

An artist from the user's listen history, with when one of their songs was last played.

Field Type Description
artist Artist The listened artist.
lastListenedAt Long When a song of the artist was last played (epoch milliseconds).

ListenedSong

A song from the user's listen history, with when it was played.

Field Type Description
song UserSong The listened song with full metadata.
listenedAt Long When the song was played (epoch milliseconds).

ListeningStats

Listening statistics for a time range over the user's unified listen history, deduplicated across local scrobbles and ListenBrainz imports.

Field Type Description
range StatsRange The requested time range.
timezone String The timezone used for range boundaries.
rangeStart Long Start of the range (epoch milliseconds, inclusive). 0 for ALL_TIME.
rangeEnd Long End of the range (epoch milliseconds, exclusive). Now for open-ended ranges, the period end for LAST_WEEK, LAST_MONTH and LAST_YEAR.
listenCount Long Deduplicated listen count in the range. A play only counts when at least half of the song or at least 3 minutes were played. Plays without a known played duration always count.
listenedMs Long Total milliseconds listened in the range, including plays too short to count as a listen. Plays without a known played duration count the whole song duration.
comparison RangeComparison? Comparison against the previous equivalent range, or null for ALL_TIME.
uniqueSongs Int Distinct songs listened to in the range.
uniqueArtists Int Distinct artists listened to in the range.
uniqueAlbums Int Distinct albums listened to in the range.
topSongs List<TopSongEntry> Most listened songs in the range, ranked by the requested top order.
topArtists List<TopArtistEntry> Most listened artists in the range, ranked by the requested top order.
topAlbums List<TopAlbumEntry> Most listened albums in the range, ranked by the requested top order.
listenClock ListenClock Hour-of-day and day-of-week listen distribution for the range.
streaks ListeningStreaks Daily listening streaks over the full history.
discoveries Discoveries Songs and artists first listened to within the range.

ListeningStreaks

Daily listening streaks, computed over the full listen history in the requested timezone.

Field Type Description
currentStreakDays Int Consecutive days with at least one listen, ending today or yesterday.
longestStreakDays Int Longest run of consecutive days with at least one listen.

MediaCollection

A user-owned, downloadable grouping of songs, albums, artists and playlists.

Field Type Description
id PlatformUUID The collection unique identifier.
name String The name of the collection.
description String? An optional user-provided description.
imageId PlatformUUID? The optional cover image unique identifier.
blurHash String? The blur hash of the cover image.
creator PlatformUUID The unique identifier of the user who created the collection.
totalSizeBytes Long Total size in bytes of all distinct songs the collection resolves to.
songCount Int Number of distinct songs the collection resolves to.
songItemCount Int Number of songs explicitly added as items.
albumCount Int Number of albums explicitly added as items.
artistCount Int Number of artists explicitly added as items.
playlistCount Int Number of playlists explicitly added as items.
imageSource ImageSource? Where the cover image came from. Null when there is no cover.

MergeArtists

Configuration for merging multiple artist records into one.

Field Type Description
name String The target name of the merged artist.
image String? The target image URL for the merged artist.
artistIds List<PlatformUUID> Collection of artist IDs to merge.

MirrorProgress

Real-time progress information for an active server mirroring task.

Field Type Description
currentTask String The current step of the synchronization process.
processedItems Int Number of items processed in the current task.
totalItems Int Total items expected for the current task.
isFinished Boolean Whether the entire mirroring task has completed.
error String? Error message if the task failed.
currentItem String? The name or ID of the item currently being processed.
currentItemProgress Float? Fraction (0 to 1) of progress for the current item.
speed String? Current transfer speed formatted as a string.
eta String? Estimated time of completion for the task.
statusMessage String? Human-readable status or log message.
syncBreakdown SyncBreakdown? Breakdown of imported and existing items.

MoodSummary

A mood cluster label with the number of songs assigned to it.

Field Type Description
mood String The mood label.
count Int Number of songs assigned to this mood.

MosaicGenerationResponse

Progress information for an image mosaic generation task.

Field Type Description
progress Double Current progress fraction (0.0 to 1.0).
status String Status or log message.
chunk ByteArray? A chunk of the generated mosaic image data.
isLast Boolean True if this is the final message in the flow.

NowPlaying

The song a user is currently playing.

Field Type Description
song UserSong The song being played, with full metadata.
startedAt Long When playback started (epoch milliseconds).

OnlineDevice

A device of the calling user that is connected to the request channel right now. Presence is not stored, so an entry exists exactly while that device keeps its connection open.

Field Type Description
sessionId PlatformUUID The session unique identifier of the connected device, used to address it for remote control.
deviceName String Human readable name the device reported for itself.
platform String Free-form platform label the device reported for itself.
deviceId String? The settings synchronization device identifier the device reported, if any.
capabilities Set<ClientCapability> The cross-device features the device offers on this connection.
isCurrent Boolean Whether this entry describes the calling session.
connectedAt Long Unix timestamp in milliseconds at which the device connected.

PaginatedResponse

A generic wrapper for paginated data collections.

Field Type Description
data List<T> The collection of items for the current page.
page Int The current page index (starting from 0).
total Int The total number of items across all pages.
pageSize Int The number of items per page.
hasNextPage Boolean Whether there are more pages available.

PlaybackCommand

A transport command sent to a remote-controllable device of the same user.

Field Type Description

Next

Skip to the next entry of the queue of the device.

Field Type Description

Pause

Pause playback on the device.

Field Type Description

Play

Start or resume playback on the device.

Field Type Description

PlayQueueItem

Select and play the entry with this queue id of the shared queue of the user. The device first applies at least the given queue version of the shared queue, pulling it when it has not seen it yet, and rejects the command when the entry is not in its queue afterwards, which is how a controller loads a new queue and then plays a song in it without a race.

Field Type Description
queueId Long The queue id of the entry within the shared queue.
queueVersion Long The shared queue version that contains the entry, as returned to the controller by its queue write.

Previous

Go back to the previous entry of the queue of the device, or restart the current one, as the device decides.

Field Type Description

SeekTo

Jump to a position within the song the device is playing.

Field Type Description
positionMs Long Target position within the song in milliseconds.

SetRepeat

Set the repetition mode of the device.

Field Type Description
mode RepeatMode The repetition mode to apply.

SetShuffle

Turn shuffled playback of the device on or off.

Field Type Description
enabled Boolean Whether the device plays its queue in shuffled order.

SetVolume

Set the playback volume of the device. Only accepted by devices that also offer the remote volume capability.

Field Type Description
volume Float The volume to apply, between 0 and 1.

TogglePlayPause

Pause the device while it plays and resume it while it is paused.

Field Type Description

PlaybackReport

A playback progress report for the song the user is playing.

Field Type Description
songId PlatformUUID The library song being played.
positionMs Long Playback position in milliseconds at the time the report was sampled.
isPlaying Boolean Whether playback is running. False while paused.
sentAt Long? Client epoch milliseconds when the position was sampled. Lets the server compensate transport delay.

PlaybackState

Represents the real-time status of music playback on a device.

Field Type Description
queue List<QueueEntry> Collection of song entries in the current queue.
currentIndex Int Index of the currently playing song in the queue.
isPlaying Boolean Whether the playback is currently active.
positionMs Long Current playback position in milliseconds.
isShuffled Boolean Whether the queue is being played in random order.
repeatMode RepeatMode The current repetition mode.
sourceId String? Identifier for the origin of the current queue (e.g., a playlist ID).

QueueEntry

Base class for entries in the playback queue.

Field Type Description
queueId Long A unique identifier for this specific instance in the queue.

FromSource

A queue entry linked to a persistent song ID.

Field Type Description
songId PlatformUUID The song unique identifier.
queueId Long A unique identifier for this specific instance in the queue.

WithSong

A queue entry containing full song metadata.

Field Type Description
song UserSong The complete song metadata.
queueId Long A unique identifier for this specific instance in the queue.

Playlist

Full name: dev.dertyp.data.Playlist

Represents a system-managed collection of tracks.

Field Type Description
id PlatformUUID The playlist unique identifier.
name String The name of the playlist.
songs List<PlatformUUID> Collection of song IDs in the playlist.
totalDuration Long Total duration of all tracks in milliseconds.
imageId PlatformUUID? The playlist cover image unique identifier.
blurHash String? The blur hash of the playlist cover image.

PlaylistAccess

What a user a playlist is shared with may do with it.

Value Description
READ The user can find, open and play the playlist.
WRITE The user can also add and remove songs.

PlaylistEntry

A simplified representation of a track within a system playlist.

Field Type Description
id PlatformUUID The song unique identifier.
name String The title of the song.
duration Long Duration of the song in milliseconds.

PlaylistShare

Grants a single user access to a user playlist.

Field Type Description
userId PlatformUUID The unique identifier of the user the playlist is shared with.
access PlaylistAccess What the user may do with the playlist.

PodcastDeliveryMode

Decides whether the server only relays the audio of a feed show or stores its episodes on disk.

Value Description
STREAM Episodes stay at their origin and the server relays their audio while a client plays them.
IMPORT New episodes are imported to the storage of the server so clients play them from the server itself.

PodcastEpisode

A single episode of a podcast show. An episode is never a song: it is not scrobbled, does not appear in the music library and carries its own listening position per user.

Field Type Description
id PlatformUUID The unique identifier of the episode.
showId PlatformUUID The show the episode belongs to.
showTitle String The title of the show the episode belongs to.
guid String The identifier the source of the show gives the episode. Unique within the show.
title String The title of the episode.
description String The description or show notes of the episode. May be blank and may contain HTML.
link String? The website of the episode, if the source names one.
publishedAt Long Unix timestamp in milliseconds at which the episode was published.
durationMs Long? The length of the episode in milliseconds, or null if it is unknown.
enclosureUrl String? The address of the audio at its origin, purely informational. Clients never fetch it themselves and always play an episode through streamEpisode, which serves the stored file or relays the origin as needed.
enclosureType String? The media type of the audio as announced by the source, for example audio/mpeg.
enclosureLength Long? The size of the audio in bytes as announced by the source, or null if it is unknown.
imageId PlatformUUID? The artwork of the episode, or null if the episode has none of its own.
showImageId PlatformUUID? The artwork of the show the episode belongs to, so a client can fall back to it.
seasonNumber Int? The season the episode belongs to, if the source names one.
episodeNumber Int? The number of the episode within its season or show, if the source names one.
episodeType PodcastEpisodeType The role the episode plays within its show.
explicit Boolean Whether the episode is marked as explicit by its source.
importState PodcastImportState How far the server has got with storing the audio of the episode on disk.
imported Boolean Whether the audio of the episode is stored on the server and can be played without reaching its origin.
importedAt Long? Unix timestamp in milliseconds at which the audio of the episode was stored on the server, or null if it is not stored.
fileSize Long? The size of the stored audio in bytes, or null if the audio is not stored on the server.
format String? The format of the stored audio, for example mp3, or null if the audio is not stored on the server.
hasTranscript Boolean Whether at least one transcript is known for the episode.
progress PodcastEpisodeProgress? The listening position of the calling user, or null if the user never played the episode.
createdAt Long Unix timestamp in milliseconds at which the episode was added to the server.
updatedAt Long Unix timestamp in milliseconds of the last change to the episode.

PodcastEpisodeProgress

How far a user has listened to an episode. Progress is private to the user and shared between all of their devices.

Field Type Description
episodeId PlatformUUID The episode the position belongs to.
showId PlatformUUID The show the episode belongs to.
positionMs Long The listening position in the episode in milliseconds.
durationMs Long? The length of the episode in milliseconds as the client reported it, or null if it is unknown.
completed Boolean Whether the episode counts as listened to the end.
lastPlayedAt Long Unix timestamp in milliseconds of the last time the user played the episode.
updatedAt Long Unix timestamp in milliseconds of the last change to the position.
deviceId String? The device that reported the position last, or null if the client did not name one.

PodcastEpisodeType

The role an episode plays within its show.

Value Description
FULL A regular episode of the show.
TRAILER A short preview of the show or of a season.
BONUS Extra material that is not part of the regular run of the show.

PodcastImportState

How far the server has got with storing the audio of an episode on disk.

Value Description
NONE The audio of the episode is not stored on the server.
QUEUED The episode is waiting to be imported.
IMPORTING The audio of the episode is being transferred to the server right now.
IMPORTED The audio of the episode is stored on the server.
FAILED The last import attempt failed. The server retries a few times before giving up.

PodcastIndexInfo

A podcast directory the server can search for shows.

Field Type Description
id String The identifier to pass to searchIndex to restrict a search to this directory.
name String The display name of the directory.
configured Boolean Whether the directory is ready to be searched. An unconfigured directory is skipped by searchIndex.

PodcastIndexResult

A show found in an external podcast directory. The server does not know the show yet. Subscribing to it is done with subscribe and the feed address of the result, which fetches the feed and stores the show.

Field Type Description
indexId String The identifier of the directory the result came from, see getIndexes.
indexName String The display name of the directory the result came from.
feedUrl String The address of the RSS feed of the show. Pass it to subscribe.
title String The title of the show.
description String The description of the show. May be blank.
author String? The author, publisher or owner of the show as the directory names it.
imageUrl String? The address of the artwork of the show, if the directory has one.
link String? The website of the show, if the directory names one.
language String? The language of the show as reported by the directory, for example en or de-DE.
episodeCount Int? Number of episodes the directory knows of, or null if it does not say.
lastPublishedAt Long? Unix timestamp in milliseconds of the newest episode the directory knows of, or null if it does not say.
explicit Boolean Whether the directory marks the show as explicit.
categories List<String> The categories the directory files the show under.

PodcastRetention

Decides which episodes of an imported show the server keeps on disk.

Value Description
NEWEST The server keeps the newest episodes of the show and deletes everything older than that.
UNLISTENED The server keeps the episodes nobody has finished yet and deletes an episode once every subscriber of the show listened to it to the end.

PodcastScanResult

What a scan of the local podcast library changed.

Field Type Description
shows Int Number of shows found in the local podcast library.
episodesAdded Int Number of episodes added by the scan.
episodesUpdated Int Number of episodes updated by the scan.
episodesRemoved Int Number of episodes removed because their file is gone.
showsRemoved Int Number of shows removed because their folder is gone.

PodcastShow

A podcast show, either an RSS feed the server follows or a folder of the local podcast library. A feed show is stored once and shared by everyone who subscribes to it, while subscriptions themselves are private to each user.

Field Type Description
id PlatformUUID The unique identifier of the show.
source PodcastSource Where the episodes of the show come from.
feedUrl String? The address of the RSS feed of the show, or null for a show of the local podcast library.
localPath String? The folder of the show inside the local podcast library, or null for a feed show.
title String The title of the show.
description String The description of the show. May be blank.
author String? The author or publisher of the show, if the source names one.
language String? The language of the show as reported by its source, for example en or de-DE.
link String? The website of the show, if the source names one.
imageId PlatformUUID? The artwork of the show, or null if the show has none.
explicit Boolean Whether the show is marked as explicit by its source.
deliveryMode PodcastDeliveryMode Whether the server only relays the audio of the show or stores its episodes on disk.
keepEpisodes Int? How many of the newest episodes are kept on disk while the show is imported, or null to keep every imported episode.
retention PodcastRetention Which episodes of the show the server keeps on disk while the show is imported.
lastFetchedAt Long? Unix timestamp in milliseconds of the last time the feed of the show was fetched, or null if it was never fetched.
lastFetchError String? The error of the last failed fetch of the feed, or null if the last fetch succeeded.
episodeCount Int Number of episodes the show currently has.
subscriberCount Int Number of users subscribed to the show.
subscribed Boolean Whether the calling user is subscribed to the show.
createdAt Long Unix timestamp in milliseconds at which the show was added to the server.
updatedAt Long Unix timestamp in milliseconds of the last change to the show.

PodcastShowSettings

The settings of a show that decide how the server keeps its episodes.

Field Type Description
deliveryMode PodcastDeliveryMode Whether the server only relays the audio of the show or stores its episodes on disk.
keepEpisodes Int? How many episodes to keep on disk while the show is imported, at least 1, or null for no limit. With unlistened retention this caps how many episodes of the show are stored or queued at once.
retention PodcastRetention Which episodes of the show the server keeps on disk while the show is imported. Only import delivery accepts unlistened retention.

PodcastSource

Where the episodes of a podcast show come from.

Value Description
FEED The show is an RSS feed the server fetches and keeps up to date.
LOCAL The show is a folder of audio files in the local podcast library of the server.

PodcastTranscript

A transcript of an episode, announced by the feed, found next to a local file or embedded in the audio itself.

Field Type Description
id PlatformUUID The unique identifier of the transcript.
episodeId PlatformUUID The episode the transcript belongs to.
type String The media type of the transcript, for example text/vtt, application/srt, application/json or text/plain.
language String? The language of the transcript, if it is known.
rel String? The relation the transcript has to the episode, for example captions.
available Boolean Whether the content of the transcript can be read. A transcript that only exists as a remote address becomes available on first read.

PodcastTranscriptContent

A transcript together with its text.

Field Type Description
transcript PodcastTranscript The transcript the text belongs to.
content String The text of the transcript in the format the transcript announces.

ProviderEntry

External provider information for a song or album.

Field Type Description
provider String The provider name (e.g. spotify, youtube).
externalId String The unique identifier on the external platform.
type String? The type of the item on the external platform (e.g. track, album).
rawUrl String The original raw URL.
addedAt Long Timestamp of when this entry was added.

ProxyInfo

Information about a connected reverse proxy instance.

Field Type Description
host String The hostname or IP of the proxy.
controlPort Int The port used for the control connection.
ssl Boolean Whether the proxy uses SSL/TLS.
id String? The unique identifier of the proxy instance.

ProxyInstanceInfo

Information about a proxy instance connected to a Synara server.

Field Type Description
id String The unique identifier of the proxy instance.
name String? The human-readable name of the proxy instance.

QueueInfo

Metadata describing the state of the server-stored play queue of a user.

Field Type Description
version Long Monotonically increasing revision of the queue, incremented by every successful write. A fresh queue is at version 0.
modifiedAt Long Unix timestamp in milliseconds of the last successful write.
modifiedBySessionId PlatformUUID? The session that performed the last write, or null if the queue was never written.
modifiedByDeviceName String? Snapshot of the device name of the session that performed the last write.
currentIndex Int Index of the currently playing entry in the active order (the shuffled order while shuffle is on, otherwise the original order).
isShuffled Boolean Whether the queue is played in the stored shuffled order.
repeatMode RepeatMode The current repetition mode.
sourceId String? Identifier for the origin of the queue (e.g., a playlist ID).
total Int Total number of entries in the queue.

QueueItem

A single entry of the server-stored play queue.

Field Type Description
songId PlatformUUID The song unique identifier. Entries whose song no longer exists are dropped silently.
queueId Long Identifier of this specific instance in the queue, unique per user. The same song may appear multiple times with different queue IDs.
position Int Zero-based index in the original (unshuffled) order.
shuffledPosition Int? Zero-based index in the shuffled order, or null while shuffle is off.
userAdded Boolean Whether this entry was added explicitly by the user rather than by the source.
song UserSong? The resolved song metadata. Filled in by the server only when the queue is read with includeSongs enabled, and ignored on writes.

QueueMeta

Playback metadata written together with a full queue upload.

Field Type Description
currentIndex Int Index of the currently playing entry in the active order.
isShuffled Boolean Whether the queue is played in the uploaded shuffled order.
repeatMode RepeatMode The repetition mode to store.
sourceId String? Identifier for the origin of the queue (e.g., a playlist ID).

QueueSyncDevice

A device of the user that participates in queue synchronization.

Field Type Description
sessionId PlatformUUID The session unique identifier of the device.
deviceName String Human readable name the device reported for itself.
enabled Boolean Whether the device currently takes part in queue synchronization.
lastSyncedVersion Long The queue version this device last pulled or wrote.
lastSyncAt Long Unix timestamp in milliseconds of the last synchronization of this device.
lastActive Long Unix timestamp in milliseconds of the last activity of the session.
isCurrent Boolean Whether this entry describes the calling session.

QueueUploadStart

Result of starting a chunked queue upload.

Field Type Description

Conflict

Full name: dev.dertyp.data.QueueUploadStart.Conflict

No upload was started because the server moved past the supplied base version. The client either pulls the server queue or repeats the call with force enabled.

Field Type Description
info QueueInfo The unchanged current queue metadata on the server.

Started

An upload slot was reserved and items can be staged with the returned upload ID.

Field Type Description
uploadId PlatformUUID Identifier of the staged upload, passed to every subsequent page, commit or cancel call.
expiresAt Long Unix timestamp in milliseconds after which the staged upload is discarded.

QueueWriteResult

Result of a queue write, either the applied new state or a version conflict.

Field Type Description
info QueueInfo The queue metadata after the write, or the current server state when the write was rejected.

Conflict

Full name: dev.dertyp.data.QueueWriteResult.Conflict

The write was rejected because the server moved past the supplied base version. The client either pulls the server queue or repeats the write with force enabled.

Field Type Description
info QueueInfo The unchanged current queue metadata on the server.

Ok

Full name: dev.dertyp.data.QueueWriteResult.Ok

The write was applied and the queue advanced to a new version.

Field Type Description
info QueueInfo The queue metadata after the write.

RadioChannel

An admin-curated radio station scoped to a configured set of songs, artists and albums.

Field Type Description
id PlatformUUID The channel unique identifier.
name String The channel name.
description String? An optional description.
imageId PlatformUUID? The optional cover image unique identifier.
blurHash String? The blur hash of the cover image.
enabled Boolean Whether the channel is published and visible to non-admin users.
position Int Display ordering. Lower values appear first.
discovery Boolean When true the channel expands its configured content into recommended similar songs. When false it plays only the configured content.
songCount Int Number of songs explicitly configured on the channel.
artistCount Int Number of artists configured on the channel.
albumCount Int Number of albums configured on the channel.

RadioChannelItemType

The kind of entity configured on a radio channel.

Value Description
SONG A single song.
ALBUM A whole album.
ARTIST A whole artist.

RadioChannelSearchResults

Ranked search results within a single radio channel's configured content, grouped by entity type.

Field Type Description
songs PaginatedResponse<RadioChannelSongMatch> Matching songs the channel resolves to (explicit and implicit members).
artists PaginatedResponse<Artist> Matching artists configured on the channel.
albums PaginatedResponse<Album> Matching albums configured on the channel.

RadioChannelSongMatch

A song matched by a radio channel search, with how it belongs to the channel.

Field Type Description
song UserSong The matched song.
directMember Boolean True when the song is added directly to the channel. False when it is reached via an album or artist that is configured on the channel.

RadioSeed

Seed material for a radio station. When any field is set, the radio is built from songs similar to the seed rather than from listen history.

Field Type Description
songIds List<PlatformUUID> Explicit seed song unique identifiers.
playlistId PlatformUUID? Seed from all songs in a playlist.
albumId PlatformUUID? Seed from all songs in an album.
artistId PlatformUUID? Seed from an artist's songs.

RadioType

The source strategy used to seed a radio station.

Value Description
RANDOM
LAST_WEEK
LAST_MONTH
LAST_YEAR

RangeComparison

Comparison of the current range's listen count against the previous equivalent range.

Field Type Description
previousStart Long Start of the previous range (epoch milliseconds, inclusive).
previousEnd Long End of the previous range (epoch milliseconds, exclusive).
previousCount Long Deduplicated listen count in the previous range.
percentChange Double? Percent change of the current count relative to the previous count, or null if the previous range had no listens.
previousListenedMs Long Total milliseconds listened in the previous range.

RecentListens

A user's recently listened songs together with what they are currently playing.

Field Type Description
nowPlaying NowPlaying? The song the user is currently playing, or null if nothing is playing.
recent List<ListenedSong> Recently listened songs, newest first.

RefreshToken

Represents a stored refresh token for session persistence.

Field Type Description
id PlatformUUID The unique identifier of the refresh token.
tokenHash String Hashed representation of the token string.
isRevoked Boolean Whether the token has been manually invalidated.
userId PlatformUUID The user who owns this token.
expiresAt PlatformDate Timestamp of when the token expires.

RefreshTokenRequest

Request payload for refreshing an authentication token.

Field Type Description
refreshToken String The refresh token.

ReleaseSource

The catalog an entry of the release feed originates from.

Value Description
MusicBrainz
Apple

ReleaseType

The classification of a music release.

Value Description
Album
Single
EP
Broadcast
Other
Unknown

RemotePlaybackStatus

What a remote-controllable device is playing, as it last reported it. A controlling device projects the current position from the position and the report timestamp while the device is playing, instead of expecting a report for every second.

Field Type Description
songId PlatformUUID? The song the device is playing, or null when it is not playing anything.
isPlaying Boolean Whether the device is playing right now rather than paused or stopped.
positionMs Long Playback position within the song in milliseconds at the time of the report.
durationMs Long? Length of the song in milliseconds, when the device knows it.
isShuffled Boolean Whether the device plays its queue in shuffled order.
repeatMode RepeatMode The repetition mode of the device.
volume Float? Playback volume between 0 and 1, or null on a device that does not expose its volume.
currentQueueId Long? Queue id of the shared queue entry the device is playing, or null when the device is not playing its shared queue.
queueVersion Long? The version of the shared queue the device has applied, or null when it does not take part in queue sync.
reportedAt Long Unix timestamp in milliseconds at which the server received the report. Ignored on report and filled in by the server.

RemoteServerConfig

Configuration for connecting and mirroring data from another Synara server.

Field Type Description
host String The host address of the remote server.
port Int The port number of the remote server.
username String Username for remote authentication.
password String Password for remote authentication.
secure Boolean Whether to use SSL/TLS for the connection.
quality Int Requested audio quality level for mirrored tracks.
playlistIds List<PlatformUUID>? Optional collection of system playlist IDs to mirror.
userPlaylistIds List<PlatformUUID>? Optional collection of user playlist IDs to mirror.
likedByUserIds List<PlatformUUID>? Optional collection of user IDs whose liked songs should be mirrored.
useProxy Boolean Whether to connect to the remote server via a proxy.
proxyInstanceId String? The identifier of the proxy instance to use.
targetUserId PlatformUUID? The target user ID on the local server for imported user data.
isImport Boolean Whether this mirroring task is considered a one-time import.
importUsers Boolean Whether to import all user accounts from the remote server.

RemoteServerPaths

Collection of local file system paths for media storage on the server.

Field Type Description
tracksPath String? Path to the main tracks storage directory.
albumsPath String? Path to the main albums storage directory.
playlistsPath String? Path to the main playlists storage directory.
customAudioPath String? Path to the custom uploaded audio storage directory.
secondaryTracksPaths List<String> Collection of alternative paths for track storage.

RepeatMode

Modes for track repetition in the playback queue.

Value Description
OFF Repeat disabled.
ALL Repeat the entire queue.
ONE Repeat the current track.

RpcCallEvent

A single recorded RPC invocation from the capped recent-events log.

Field Type Description
service String The RPC service (interface) name.
method String The RPC method (call) name.
username String? The username that made the call, or null for unauthenticated/public calls.
timestamp Long Timestamp of the invocation as epoch milliseconds.

RpcCallStat

Invocation count for a single RPC call within one hourly time bucket.

Field Type Description
service String The RPC service (interface) name.
method String The RPC method (call) name.
username String? The username that made the calls, or null for unauthenticated/public calls.
bucketStart Long Start of the hourly bucket as epoch milliseconds (truncated to the hour).
count Long Number of invocations in this bucket.

RpcCallTotal

Lifetime invocation count for a single RPC call, per user. This counter only ever increases.

Field Type Description
service String The RPC service (interface) name, e.g. "ISongService".
method String The RPC method (call) name.
username String? The username that made the calls, or null for unauthenticated/public calls.
count Long Total number of times this call was invoked over the lifetime of the server.

ScheduledTaskLog

Detailed log entry for a background scheduled task execution.

Field Type Description
id PlatformUUID The unique identifier of the log entry.
taskName String The internal name of the task.
startTime Long Unix timestamp of when the task started.
endTime Long Unix timestamp of when the task ended.
status TaskStatus The current or final status of the task.
message String? Summary message about the task execution.
details Map<String, String>? Key-value pairs containing task-specific details.
progress Double Progress of the task as a fraction (0.0 to 1.0).
logs List<String> Collection of log lines produced by the task.
logTime Long Unix timestamp of the log entry.

ScrobbleRequest

A scrobble reporting a library song the user is playing or has played.

Field Type Description
songId PlatformUUID The library song being scrobbled.
listenedAt Long? When the song was played (epoch milliseconds). Defaults to the server's current time.
msPlayed Long? How much of the song was played, in milliseconds.

ServerStats

Detailed system metrics and library statistics.

Field Type Description
songCount Int Total number of songs in the library.
albumCount Int Total number of albums.
artistCount Int Total number of artists.
imagesCount Int Total number of images stored.
animatedImagesCount Int Total number of animated images stored.
playlistCount Int Total number of system playlists.
totalFileSize Long Total file size of the media library in bytes.
indexedFileSize Long Size of files that have been successfully indexed.
imagesFileSize Long Total disk space consumed by stored images in bytes.
animatedImagesFileSize Long Total disk space consumed by stored animated images in bytes.
averageSizePerSong Long Average file size per track in bytes.
totalDuration Long Summed duration of all tracks in milliseconds.
podcastShowCount Int Total number of podcast shows known to the server, from feed subscriptions and from the local podcast library.
podcastEpisodeCount Int Total number of podcast episodes known to the server.
podcastImportedEpisodeCount Int Number of podcast episodes whose audio is stored on the server, either imported from a feed or part of the local podcast library.
podcastFileSize Long Total disk space consumed by the podcast library and by imported episodes in bytes.
transcodeStats List<TranscodeStats> Statistics about transcoded audio versions.
musicBrainzCache MusicBrainzCacheStats Statistics about the MusicBrainz metadata cache.
version Version Information about the server software version.

MusicBrainzCacheStats

Statistics about the MusicBrainz metadata cache.

Field Type Description
artistCount Int Total number of cached artists.
staleArtistCount Int Number of stale artists in the cache.
releaseGroupCount Int Total number of cached release groups.
staleReleaseGroupCount Int Number of stale release groups in the cache.
releaseCount Int Total number of cached releases.
staleReleaseCount Int Number of stale releases in the cache.
recordingCount Int Total number of cached recordings.
staleRecordingCount Int Number of stale recordings in the cache.

TranscodeStats

Statistics for a specific bitrate and format combination.

Field Type Description
bitrate Int The audio bitrate in kbps.
format AudioFormat The audio format.
count Int Number of songs transcoded to this version.
totalSize Long Total file size in bytes.

Version

Details about the server's version and build environment.

Field Type Description
version String The application version number.
buildTime String Timestamp of when the server was built.
commitHash String The Git commit hash for this build.
runtime String The Java runtime version.
kernel String The operating system kernel information.

Session

Represents an active or historical user login session.

Field Type Description
id PlatformUUID The session unique identifier.
userAgent String Browser or application identifier of the connecting device.
ipAddress String The IP address from which the user last connected.
lastActive Long Unix timestamp of the last activity in this session.
isActive Boolean Whether the session is currently considered active.

SimpleSong

A simplified representation of a song.

Field Type Description
id PlatformUUID The song unique identifier.
title String The title of the song.
duration Long Duration of the song in milliseconds.
explicit Boolean Whether the song contains explicit content.
releaseDate PlatformLocalDate? Original release date of the track.
path String Internal server path to the audio file.
originalUrl String The URL to the item on its original platform.
trackNumber Int The position of the track in the album.
discNumber Int The disc number in a multi-disc album.
audio AudioInfo Properties of the primary audio file.
coverId PlatformUUID? The song cover image unique identifier.
blurHash String? The blur hash of the song cover image.
musicBrainzId PlatformUUID? The MusicBrainz Recording unique identifier.
isrc String? The International Standard Recording Code.
transcodedTo List<TranscodedVersion> List of bitrates for which a transcoded version exists.
tags List<TitleTag> Version markers split off the title, e.g. remix, live or featuring, in order of extraction. The title never contains them.

Song

Contains core metadata about a track that is common for all users.

Field Type Description
id PlatformUUID The song unique identifier.
title String The title of the song.
artists List<ArtistCredit> Collection of performing artists.
album Album? The album this song belongs to.
duration Long Duration of the song in milliseconds.
explicit Boolean Whether the song contains explicit content.
releaseDate PlatformLocalDate? Original release date of the track.
path String Internal server path to the audio file.
originalUrl String The URL to the item on its original platform.
trackNumber Int The position of the track in the album.
discNumber Int The disc number in a multi-disc album.
copyright String Copyright information for the track.
audio AudioInfo? Properties of the primary audio file.
atmos AudioInfo? Properties of the Dolby Atmos (E-AC-3 JOC in MP4) variant, if one exists.
coverId PlatformUUID? The song cover image unique identifier.
blurHash String? The blur hash of the song cover image.
musicBrainzId PlatformUUID? The MusicBrainz Recording unique identifier.
isrc String? The International Standard Recording Code.
genres List<Genre> Collection of genres associated with this song.
animatedCoverId PlatformUUID? The animated cover unique identifier.
animatedCoverImageId PlatformUUID? Identifier of the still Image from the animated cover's first frame.
animatedCoverBlurHash String? BlurHash of the animated cover's first frame.
audioStartMs Long? Offset in milliseconds of the first audible sound, or null if not yet analyzed.
tags List<TitleTag> Version markers split off the title, e.g. remix, live or featuring, in order of extraction. The title never contains them.
lyricsInfo SongLyricsInfo? Summary of the lyrics available for this song.
atmosVariantPath String?

SongAudioBand

Level track of one frequency band of a song.

Field Type Description
band AudioBand The band.
lowHz Int Lower edge of the band in Hz.
highHz Int Upper edge of the band in Hz.
levelsDb List<Float> Band level in dBFS, one value per 1/bandHz seconds.

SongAudioData

Additional audio analysis data for a song.

Field Type Description
bpm Double? The beats per minute (BPM) of the song.
key String? The musical key of the song (e.g. C, G#, Bb).
scale AudioScale? The scale of the song (major or minor).
loudness Double? The perceived loudness of the track in LUFS.
energy Double? The energy level of the song (0.0 to 1.0).
valence Double? The musical positiveness of the song (0.0 to 1.0).
danceability Double? The danceability level of the song (0.0 to 1.0).
acousticness Double? The acousticness level of the song (0.0 to 1.0).
instrumentalness Double? The instrumentalness level of the song (0.0 to 1.0).
speechiness Double? The speechiness level of the song (0.0 to 1.0).
composer List<String>? The composer of the song.
lyricist List<String>? The lyricist of the song.
producers List<String>? The producers of the song.

SongAudioTimeline

Time-based analysis data of a song: beat grid, loudness envelope, bass envelope and per-band level tracks, for visualisations and light sync.

Field Type Description
songId PlatformUUID The song unique identifier.
beatsMs List<Int> Beat positions in milliseconds from the start of the file.
beatsCount Int? Number of detected beats.
onsetRate Double? Onsets per second.
envelopeHz Int Sample rate of the loudness envelope in samples per second.
envelopeDb List<Float> Loudness envelope in dBFS, one value per 1/envelopeHz seconds.
bassEnvelopeDb List<Float> Bass band (20-130 Hz) envelope in dBFS derived from the sub and kick bands, one value per 1/envelopeHz seconds. Empty when not extracted yet.
bandHz Int Sample rate of the band level tracks in samples per second. 0 when no bands are stored.
bands List<SongAudioBand> Per-band level tracks (sub, kick, low mid, mid, high) for visualisations and light sync. Empty when not extracted yet.
loudnessRange Double? Loudness range in LU.
dynamicComplexity Double? Dynamic complexity of the loudness.
source String Where the beat grid came from: essentia, rms or none.
version Int Encoding version of the stored data.

SongDownloadSize

The download size of a song for a requested quality and format.

Field Type Description
songId PlatformUUID The song unique identifier.
size Long The size of the download in bytes.

SongExtendedMetadata

Extended metadata for a song.

Field Type Description
providers List<ProviderEntry> List of all external providers and IDs matching this song.
audioData SongAudioData? Detailed audio analysis data.
insertedAt Long Timestamp of when the song was first inserted into the database.

SongLyricsInfo

Summary of the lyrics available for a song.

Field Type Description
available Boolean Whether the song has any lyrics at all.
syncLevel LyricsSyncLevel? The best sync level of the default lyrics, or null if there are none.
levels Set<LyricsSyncLevel> Every sync level that at least one lyrics candidate offers.
instrumental Boolean Whether the song is instrumental.
defaultCandidateId PlatformUUID? The identifier of the default lyrics candidate.
defaultProvider String? The identifier of the provider of the default lyrics candidate.
candidateCount Int Number of stored lyrics candidates.

SongTag

Flags and metadata attributes for a song.

Value Description
Q_44_48 Audio sample rate is 44.1kHz or 48kHz.
Q_96 Audio sample rate is 96kHz.
Q_192 Audio sample rate is 192kHz.
B_16 Bit depth is 16-bit.
B_24 Bit depth is 24-bit.
HAS_LYRICS The song has associated lyrics.
HAS_SYNCED_LYRICS The song has lyrics synced per line or per word.
HAS_WORD_SYNCED_LYRICS The song has lyrics synced per word.
CUSTOM_UPLOAD The song was manually uploaded by a user.
HAS_MUSICBRAINZ_ID The song has a linked MusicBrainz Recording ID.

SplitArtist

Configuration for splitting an artist record into multiple artists.

Field Type Description
artistId PlatformUUID The original artist ID to split.
newArtists Map<String, PlatformUUID?> Map of names to their new artist IDs.

StatsRange

A time range for listening statistics. DAY, WEEK, MONTH and YEAR run from the period start to now. LAST_WEEK, LAST_MONTH and LAST_YEAR cover the previous completed period.

Value Description
DAY
WEEK
LAST_WEEK
MONTH
LAST_MONTH
YEAR
LAST_YEAR
ALL_TIME

SubsonicCredentialInfo

The dedicated Subsonic credential for a user. The password is retrievable because Subsonic token authentication requires the server to know it.

Field Type Description
username String The username to use in Subsonic clients.
password String The generated Subsonic password.
createdAt Long Unix timestamp (ms) when the credential was created.

SyncBreakdown

Breakdown of newly imported versus existing items in a synchronization.

Field Type Description
songs Int New songs imported.
existingSongs Int Songs that already existed.
artists Int New artists imported.
existingArtists Int Artists that already existed.
albums Int New albums imported.
existingAlbums Int Albums that already existed.
images Int New images imported.
existingImages Int Images that already existed.
playlists Int New system playlists imported.
existingPlaylists Int System playlists that already existed.
userPlaylists Int New user playlists imported.
existingUserPlaylists Int User playlists that already existed.
errors Int Total number of errors encountered.
failedItems List<String> Collection of identifiers for items that failed to import.

TaskConfiguration

Configuration for a background scheduled task.

Field Type Description
key String The unique key identifying the task.
name String A human-readable name for the task.
enabled Boolean Whether the task is enabled and will be scheduled.
trigger TriggerDefinition The trigger definition for the task.

TaskStatus

The status of a background scheduled task.

Value Description
SUCCESS The task completed successfully.
FAILURE The task encountered an error.
RUNNING The task is currently in progress.

TimecodeTag

A tag a user attached to a song at a position in milliseconds. Tags are private to the user who created them and are removed together with the song they belong to.

Field Type Description
id PlatformUUID The unique identifier of the tag.
userId PlatformUUID The user the tag belongs to. Tags are never visible to other users.
songId PlatformUUID The song the tag is attached to.
type TimecodeTagType How the tag is meant to be read by a client.
text String The text of the tag, for example the name of a chapter or the remark of a note. 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.
createdAt Long Unix timestamp in milliseconds at which the tag was created.
updatedAt Long Unix timestamp in milliseconds of the last change to the tag.
action TimecodeTagAction What the playing client does when playback reaches the tag.
fade Boolean When set, the client fades in from the tag and fades out towards the tag around the action.

TimecodeTagAction

What the client that plays the song does when playback reaches a timecode tag. The playing client executes the action itself, a client that only controls another device does nothing. Chapter actions need a tag with an end position, marker actions a tag without one, and a note always uses NONE.

Value Description
NONE The tag is passive and does not change playback.
PLAY_ONLY Chapters only. Playback covers only the PLAY_ONLY chapters of the song and moves on to the next track after the last one.
SKIP Chapters only. Playback jumps over the chapter.
SKIP_TO Markers only. The song starts at the marker.
PLAY_UNTIL Markers only. Playback moves on to the next track when it reaches the marker.

TimecodeTagInput

A tag to store for a song, without the fields the server assigns itself. Used to write a whole set of tags of a song at once.

Field Type Description
type TimecodeTagType How the tag is meant to be read by a client.
text String The text of the tag, for example the name of a chapter or the remark of a note. 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 When set, the client fades in from the tag and fades out towards the tag around the action.

TimecodeTagType

Determines how a timecode tag is meant to be read by a client, so a player can render sections, cue points and remarks differently.

Value Description
CHAPTER A named section of a song, usually with an end position.
MARKER A single point of interest, for example a drop or a cue point.
NOTE A free-form remark the user left at a position.

TitleTag

A version marker that was split off the song title, shown by clients separately from the title.

Field Type Description
kind TitleTagKind The kind of marker. Kinds a client does not know are decoded as UNKNOWN.
label String The original text without brackets, e.g. Skrillex Remix, Live at Wembley, feat. Drake or Radio Edit.

TitleTagKind

Kind of version marker split off a song title.

Value Description
FEAT Featured artists, e.g. feat. Drake or with Artist.
PROD Producer credit, e.g. prod. Metro Boomin.
REMIX A remix, rework, bootleg, flip or VIP.
MIX A named mix, e.g. Extended Mix, Club Mix, Radio Mix or a Mix Cut from a DJ mix.
LIVE A live recording, optionally with venue or date.
COVER A cover version.
ACOUSTIC An acoustic or unplugged version.
INSTRUMENTAL An instrumental version.
EDIT An edit, e.g. Radio Edit or Extended Edit.
VERSION A generic alternate version, e.g. Album Version, Take 2, Sped Up, Bonus Track or Deluxe.
REMASTER A remaster, optionally with year.
DEMO A demo recording.
UNKNOWN A kind this client does not know yet. Clients treat it as a generic marker.

TopAlbumEntry

An album ranked by listen count or time listened. Fallback entries for listens not matched to a library album carry a null albumId.

Field Type Description
albumId PlatformUUID? The library album, or null for listens not matched to the library.
name String The album name.
coverId PlatformUUID? The album's cover image, or null if none.
listenCount Long Deduplicated listen count in the range.
listenedMs Long Total milliseconds listened to this album in the range, including plays too short to count as a listen.

TopArtistEntry

An artist ranked by listen count or time listened. Fallback entries for listens not matched to a library artist carry a null artistId.

Field Type Description
artistId PlatformUUID? The library artist, or null for listens not matched to the library.
name String The artist name.
imageId PlatformUUID? The artist's image, or null if none.
listenCount Long Deduplicated listen count in the range.
listenedMs Long Total milliseconds listened to this artist in the range, including plays too short to count as a listen.

TopOrder

How top lists are ranked. LISTEN_COUNT ranks by deduplicated listen count. LISTENED_MS ranks by total milliseconds listened, which also surfaces entries whose plays were too short to count as listens.

Value Description
LISTEN_COUNT
LISTENED_MS

TopSongEntry

A song ranked by listen count or time listened. Fallback entries for listens not matched to a library song carry a null songId.

Field Type Description
songId PlatformUUID? The library song, or null for listens not matched to the library.
title String The song title.
artistName String? The artist name, or null if unknown.
albumName String? The album name, or null if unknown.
coverId PlatformUUID? The song's cover image, or null if none.
listenCount Long Deduplicated listen count in the range.
recordingMbid PlatformUUID? The MusicBrainz recording MBID of an unmatched entry, or null.
recordingMsid PlatformUUID? A representative ListenBrainz recording MSID of an unmatched entry, or null. When recordingMbid and recordingMsid are both null the entry cannot be linked.
listenedMs Long Total milliseconds listened to this song in the range, including plays too short to count as a listen.

TranscodedVersion

Represents a transcoded version of a song.

Field Type Description
bitrate Int The bitrate of the transcoded version in kbps.
format AudioFormat The audio format of the transcoded version.

TriggerDefinition

A serializable definition of a task trigger.

Field Type Description

AfterTask

A trigger that executes after another task completes.

Field Type Description
dependencyKey String The unique key of the dependency task.

Cron

A trigger based on a cron expression.

Field Type Description
expression String The cron expression (UNIX style).

Interval

A trigger that executes at a fixed interval.

Field Type Description
intervalSeconds Long The interval in seconds.

Manual

A trigger that only executes when manually requested.

Field Type Description

User

Contains core identity and profile data for a Synara user.

Field Type Description
id PlatformUUID The user unique identifier.
username String The unique login name of the user.
displayName String? Optional display name shown to other users.
isAdmin Boolean Whether the user has administrative privileges.
capabilities List<UserCapability> List of specific capabilities granted to the user.
profileImageId PlatformUUID? The user's profile avatar image unique identifier.
blurHash String? The blur hash of the profile avatar image.

UserCapability

Specific actions or features a user is authorized to perform.

Value Description
IMPORT
EDIT
DELETE
PODCAST_EDIT

UserInfo

Publicly safe profile information about a user.

Field Type Description
id PlatformUUID The user unique identifier.
username String The unique login name of the user.
displayName String? Optional display name shown to other users.
isAdmin Boolean Whether the user has administrative privileges.
capabilities List<UserCapability> List of specific capabilities granted to the user.
profileImageId PlatformUUID? The user's profile avatar image unique identifier.
blurHash String? The blur hash of the profile avatar image.

UserPasswordHash

The stored password hash of a user, used only for server-to-server mirroring.

Field Type Description
id PlatformUUID The user unique identifier.
passwordHash String The bcrypt hash of the user password.

UserPlaylist

Represents a user-created and managed collection of tracks.

Field Type Description
id PlatformUUID The playlist unique identifier.
name String The name of the playlist.
songs List<PlatformUUID> Collection of song IDs in the playlist.
songEntries List<UserPlaylistSong>? Detailed entry data including added timestamps.
totalDuration Long Total duration of all tracks in milliseconds.
imageId PlatformUUID? The playlist cover image unique identifier.
blurHash String? The blur hash of the playlist cover image.
creator PlatformUUID The unique identifier of the user who created the playlist.
description String A user-provided description of the playlist.
origin String? The source or platform where the playlist originated.
modifiedAt PlatformDate? Timestamp of the last modification to the playlist.
imageSource ImageSource? Where the cover image came from. Null when there is no cover.
isPublic Boolean Whether every user can find and open the playlist. A playlist that is not public is visible only to its owner and the users it is shared with.
shares List<PlaylistShare> The users the playlist is shared with. Empty for a caller who is neither the owner nor one of these users.

UserPlaylistBackup

A complete backup of a user's playlists and their associated images.

Field Type Description
userId PlatformUUID The unique identifier of the user.
playlists List<UserPlaylist> Collection of user playlists.
images List<BackupImage>? Optional collection of raw images for the playlists.

UserPlaylistSong

Metadata for a single song entry within a user playlist.

Field Type Description
songId PlatformUUID The song unique identifier.
addedAt Long Unix timestamp of when the song was added.
musicBrainzId PlatformUUID? The MusicBrainz Recording unique identifier.

UserProfile

The name and avatar of a user, as shown to other users.

Field Type Description
id PlatformUUID The user unique identifier.
username String The unique login name of the user.
displayName String? Optional display name shown to other users.
profileImageId PlatformUUID? The user's profile avatar image unique identifier.
blurHash String? The blur hash of the profile avatar image.

UserSong

Extends track metadata with user-specific information like favorite status.

Field Type Description
id PlatformUUID The song unique identifier.
title String The title of the song.
artists List<ArtistCredit> Collection of performing artists.
album Album? The album this song belongs to.
duration Long Duration of the song in milliseconds.
explicit Boolean Whether the song contains explicit content.
releaseDate PlatformLocalDate? Original release date of the track.
path String Internal server path to the audio file.
originalUrl String The URL to the item on its original platform.
trackNumber Int The position of the track in the album.
discNumber Int The disc number in a multi-disc album.
copyright String Copyright information for the track.
audio AudioInfo? Properties of the primary audio file.
atmos AudioInfo? Properties of the Dolby Atmos (E-AC-3 JOC in MP4) variant, if one exists.
coverId PlatformUUID? The song cover image unique identifier.
blurHash String? The blur hash of the song cover image.
musicBrainzId PlatformUUID? The MusicBrainz Recording unique identifier.
isrc String? The International Standard Recording Code.
genres List<Genre> Collection of genres associated with this song.
animatedCoverId PlatformUUID? The animated cover unique identifier.
animatedCoverImageId PlatformUUID? Identifier of the still Image from the animated cover's first frame.
animatedCoverBlurHash String? BlurHash of the animated cover's first frame.
audioStartMs Long? Offset in milliseconds of the first audible sound, or null if not yet analyzed.
tags List<TitleTag> Version markers split off the title, e.g. remix, live or featuring, in order of extraction. The title never contains them.
lyricsInfo SongLyricsInfo? Summary of the lyrics available for this song.
atmosVariantPath String?
isFavourite Boolean? Whether the current user has marked this song as a favorite.
userSongCreatedAt PlatformDate? Timestamp of when the song record was created.
userSongUpdatedAt PlatformDate? Timestamp of the last update to the song metadata.
likeLevel LikeLevel? The current user's like level of this song. isFavourite is true for both LIKE and SUPER.
superLikedAt PlatformDate? Timestamp of when the current user super liked this song, or null if it is not super liked.
playbackTags List<TimecodeTag> The requesting user's timecode tags on this song whose action is not NONE, ordered by position. Read-only. Tags are changed through ITimecodeTagService, and the full list including passive tags comes from ITimecodeTagService.getTags.

BackupInfo

Metadata for a specific system backup file.

Field Type Description
name String The name of the backup file.
size Long Size of the backup in bytes.
date Long Creation date as a Unix timestamp.

BackupResult

Results of a successful system backup creation.

Field Type Description
fileName String The name of the newly created file.
size Long Final size of the backup in bytes.
imageCount Int Number of cover images included in the backup.

ImageStreamItem

A single item in a raw image binary stream.

Field Type Description
id PlatformUUID The image unique identifier.
data ByteArray The raw image binary data.

LrcLibResponse

Lyrics metadata from LrcLib.

Field Type Description
id Int The LrcLib internal ID.
trackName String The name of the track.
artistName String The name of the artist.
albumName String The name of the album.
duration Double Duration of the track in seconds.
instrumental Boolean Whether the track is instrumental.
plainLyrics String? The plain text lyrics.
syncedLyrics String? The synced lyrics in LRC format.

FavouriteImportQueueEntry

An import queue entry for a user's favorite collection.

Field Type Description
favoriteType ImportFavType The type of favorites to import.
byUser PlatformUUID? The ID of the user who initiated the import.
type Type? The type of content.
importer ImportBackend? The importer backend to use for this entry.
metadata BaseMetadata? Metadata for the content.
maxRetries Int
callback SuspendFunction0<Unit>

FinishedImportQueueEntry

Contains details about a completed or failed import task.

Field Type Description
importQueueEntry ImportQueueEntry The original queue entry.
result ProcessExecutionResult The result of the process execution.
logs List<String> The full logs from the import process.

GamdlCredentials

Apple Music credentials for the gamdl importer.

Field Type Description
cookiesTxt String
wvdBase64 String?

ImportBackend

Available backend services for importing content.

Field Type Description
id String

ImportFavType

The category of import favorites.

Value Description
tracks
artists
albums
videos

ImportQueueEntry

Base class for entries in the import queue.

Field Type Description
type Type? The type of content being imported.
maxRetries Int Maximum number of retry attempts on failure.
byUser PlatformUUID? The ID of the user who initiated the import.
importer ImportBackend? The importer backend to use for this entry.
callback SuspendFunction0<Unit>

ImportSong

Metadata for a track found.

Field Type Description
id String The track ID.
title String The title of the track.
artists List<String> Collection of artist names.
cover Map<Int, String> Map of cover image sizes to URLs.
explicit Boolean? Whether the track is marked explicit. Null when unknown.

ImporterCapability

A capability an importer backend supports, so clients can discover what each backend can do.

Value Description
IMPORT_SONG Can import individual songs/tracks.
IMPORT_ALBUM Can import full albums.
IMPORT_ARTIST Can import an artist's catalog.
IMPORT_PLAYLIST Can import playlists.
IMPORT_VIDEO Can import music videos.
IMPORT_MIX Can import curated mixes.
CREDENTIALS Accepts credentials injected at runtime via setImportCredentials/provideCredentials.
LOGIN Supports an interactive OAuth/login flow (importLogin).
FAVORITES Can import a user's favorite collection and sync favorites.
SEARCH Supports searching the source catalog.

ImporterCredentials

Base type for credentials supplied to an importer backend.

Field Type Description

LogLine

A single log line from an import process.

Field Type Description
queueEntry ImportQueueEntry The queue entry this log belongs to.
line String? The actual log text.

ProcessExecutionResult

Results of an external process execution (e.g., importer).

Field Type Description
exitCode Int The process exit code (0 for success).
fullOutput String The complete standard output of the process.
error String The complete error output of the process.

Type

The type of content available for import.

Value Description
MIX
SONG
ALBUM
PLAYLIST
ARTIST
VIDEO

UrlImportQueueEntry

An import queue entry for content specified by its URL.

Field Type Description
urls MutableList<String> Collection of URLs to import.
ids Collection<String> Collection of associated IDs.
byUser PlatformUUID? The ID of the user who initiated the import.
type Type? The type of content.
importer ImportBackend? The importer backend to use for this entry.
metadata BaseMetadata? Metadata for the content.
maxRetries Int
callback SuspendFunction0<Unit>

AccessTokenResponse

Response containing an access token for an external metadata service.

Field Type Description
access_token String The access token string.
token_type String The type of the token (e.g., Bearer).
expires_in Int Token lifetime in seconds.

Album

Full name: dev.dertyp.services.metadata.IMetadataService.Album

External metadata for a music album.

Field Type Description
id String The external album ID.
title String The title of the album.
artists List<String> Collection of artist names.
tracks Flow<Track> Stream of tracks included in the album.
duration Duration Total duration of the album.
trackCount Int Number of tracks in the album.
discCount Int Number of discs in the album.
releaseDate PlatformLocalDate? The date the album was released.
images List<Image> Collection of album images.
genres List<String> Genres associated with the album.
additionalTitles List<String> Alternative titles for the album.
barcode String? The barcode or UPC of the album.

Artist

Full name: dev.dertyp.services.metadata.IMetadataService.Artist

External metadata for a music artist.

Field Type Description
id String The external artist ID.
name String The name of the artist.
popularity Float Popularity score of the artist.
url String? The URL to the artist's profile.
images List<Image> Collection of artist images.
biography String? Biography or description text.
styles List<String> Musical styles associated with the artist.
genres List<String> Genres associated with the artist.

FlowPlaylist

Reactive flow-based external playlist metadata.

Field Type Description
id String The external playlist ID.
name String The name of the playlist.
description String Description of the playlist.
tracks Flow<Track> Stream of tracks in the playlist.
trackCount Int Number of tracks in the playlist.
createdAt PlatformOffsetDateTime? Timestamp of when the playlist was created.
modifiedAt PlatformOffsetDateTime? Timestamp of the last modification.
images List<Image> Collection of playlist images.
cache MutableList<Track>
collectionJob Deferred<List<Track>>?
mutex Mutex
sharedTracks Flow<Track>

Image

Full name: dev.dertyp.services.metadata.IMetadataService.Image

Metadata for an image from an external source.

Field Type Description
url String The URL of the image.
width Int Width in pixels.
height Int Height in pixels.
animated Boolean Whether the image is animated.

Mix

External metadata for a curated music mix.

Field Type Description
id String The external mix ID.
name String The name of the mix.
tracks Flow<Track> Stream of tracks included in the mix.
images List<Image> Collection of mix images.

Playlist

Full name: dev.dertyp.services.metadata.IMetadataService.Playlist

External metadata for a music playlist.

Field Type Description
id String The external playlist ID.
name String The name of the playlist.
description String Description of the playlist.
tracks List<Track> List of tracks in the playlist.
trackCount Int Number of tracks in the playlist.
createdAt PlatformOffsetDateTime? Timestamp of when the playlist was created.
modifiedAt PlatformOffsetDateTime? Timestamp of the last modification.
images List<Image> Collection of playlist images.

Track

External metadata for a music track.

Field Type Description
id String The external track ID.
title String The title of the track.
artists List<String> Collection of artist names.
duration Duration Duration of the track.
createdAt PlatformOffsetDateTime? Timestamp of when the track was created on the source platform.
addedAt PlatformOffsetDateTime? Timestamp of when the track was added to the source collection.
trackNumber Int? Track position in the album.
discNumber Int? Disc number in the album.
images List<Image> Collection of track images.
genres List<String> Genres associated with the track.
albumId String? The external album ID.
albumTitle String? The title of the album.
isrc String? The International Standard Recording Code.
explicit Boolean? Whether the track is marked explicit. Null when unknown.

FollowedArtist

Represents an artist that a user is following for release tracking.

Field Type Description
artistId PlatformUUID The artist unique identifier.
name String The name of the artist.
imageId PlatformUUID? The artist image unique identifier.

LyricChar

A single character in a synced lyric word with precise timing.

Field Type Description
char String The character text.
startTime Duration Timestamp of when the character starts.
endTime Duration Timestamp of when the character ends.

LyricLine

A single line of lyrics with timing information.

Field Type Description
startTime Duration Timestamp of when the line starts.
endTime Duration Timestamp of when the line ends.
words List<LyricWord> Collection of individual words in the line.
text String? The full text of the line. When set, the word texts joined without a separator equal it exactly. When null, the words are joined with a space.
voice String? The id of the voice singing the line, as a key of the voices of the lyrics.
background Boolean Whether the line is a backing vocal.
group Int Identifier shared by a lead line and the backing vocal lines that were split from the same line.

LyricVoice

A singer that lyric lines can be assigned to.

Field Type Description
name String The display name of the singer.
type LyricVoiceType Whether the voice is a single person or a group.

LyricVoiceType

Kind of singer behind a voice.

Value Description
PERSON A single person.
GROUP A group of singers.

LyricWord

A single word in a synced lyric line with precise timing.

Field Type Description
text String The text of the word.
startTime Duration Timestamp of when the word starts.
endTime Duration Timestamp of when the word ends.
chars List<LyricChar>? Optional character-level timing information.

LyricsCandidate

One version of the lyrics of a song as offered by a provider.

Field Type Description
id PlatformUUID The candidate unique identifier.
songId PlatformUUID? The song unique identifier, or null if the candidate is not tied to a song.
provider LyricsProviderInfo The provider the candidate comes from.
syncLevel LyricsSyncLevel How finely the lyrics are synced.
instrumental Boolean Whether the track is instrumental.
match LyricsMatch How sure it is that the lyrics belong to the song.
durationGapSec Int? Difference in seconds between the duration of the lyrics and of the song, or null if unknown.
rank Int Position among the candidates of the song, 1 is best.
preferred Boolean Whether an admin pinned this candidate as the default.
fetchedAt PlatformDate Timestamp of when the candidate was fetched.
plain String The plain text of the lyrics.
lyrics SyncedLyrics? The synced lyrics. Only filled when the content was requested.

LyricsImport

A lyrics file to import.

Field Type Description
format LyricsImportFormat The format of the content.
content String The content of the file.

LyricsImportFormat

File format of lyrics that are imported.

Value Description
LRC LRC with line stamps and optional word stamps.
TTML TTML with optionally timed words.
LYRICSFILE A lyricsfile in YAML.

LyricsMatch

How sure it is that lyrics belong to the song.

Value Description
VERIFIED The title, artist and duration of the lyrics were checked against the song.
PROVIDER The provider returned the lyrics for the song, but did not tell which track they are for.

LyricsProviderInfo

A source of lyrics.

Field Type Description
id String The provider identifier, such as betterlyrics or kugou.
name String The display name of the provider.
url String? The web address of the provider to credit, or null if it has none.
enabled Boolean Whether lookups ask this provider.
priority Int Position of the provider in the configured order, lower is asked and preferred first.

LyricsSearchResult

Lyrics candidates found for a song or a query.

Field Type Description
candidates List<LyricsCandidate> The candidates ordered by rank.
defaultCandidateId PlatformUUID? The identifier of the default candidate. This is the pinned one, otherwise the best ranked one.
pending List<String> Identifiers of the providers that did not answer in time and can be asked again later.

LyricsSyncLevel

How finely lyrics are synced to the audio.

Value Description
PLAIN Text only, without timing.
LINE Timed per line.
WORD Timed per word or syllable.

RecentRelease

Metadata for a recently released album or single from a followed artist.

Field Type Description
releaseId PlatformUUID The MusicBrainz release-group UUID, or the provider release id for non-MusicBrainz sources.
artistId PlatformUUID The internal artist unique identifier.
artistName String The name of the artist.
artistIds List<PlatformUUID> Every internal artist the release is linked to, the primary artist first.
title String The title of the release.
releaseDate PlatformDate? The date the content was released.
type ReleaseType The type of release (Album, Single, etc.).
imageId PlatformUUID? The release cover image unique identifier.
blurHash String? The blur hash of the release cover image.
links List<String> Collection of external URLs related to the release.
albumId PlatformUUID? The internal album ID if it has been indexed.
songId PlatformUUID? The internal song ID if a single track has been indexed.
source ReleaseSource The catalog this entry originates from.
upcoming Boolean Whether the release date still lies in the future.
hidden Boolean Whether the entry has been hidden from the release feed.
suspect Boolean Whether the catalog evidence suggests the entry belongs to a different artist with the same name. Only set for provider entries.
suspectReason String? Human-readable explanation of why the entry is suspect.
recordLabel String? The record label reported by the provider, when known.
copyright String? The copyright line reported by the provider, when known.
versions List<RecentRelease> Other editions of the same release folded under this entry: explicit, clean, deluxe or remastered variants, or the same release listed by another catalog. Each keeps its own identifiers, links and cover. Their own versions lists are always empty.

SyncedLyrics

A collection of time-synced lyrics for a song.

Field Type Description
lines List<LyricLine> List of individual lyric lines.
voices Map<String, LyricVoice> The singers of the lyrics by voice id, used by duets and backing vocals.

ClientTimeZone

The client's time zone, sent as an optional request header next to X-Ui-Schema-Version and Accept-Language. The server formats times on server-driven pages in this zone. Clients without it get times in UTC.

Field Type Description
HEADER String Header name. The value is an IANA time zone id such as Europe/Berlin. Invalid values are ignored.

IntakeItem

Something a user hands to the server to act on: a link, a catalog code, a provider id, free text or a file. Plugins offer to handle items through intake resolvers.

Field Type Description

Code

A catalog code.

Field Type Description
kind UiIntakeCodeKind Code kind.
value String Normalized code (uppercase, no separators).

File

A file previously uploaded to the server.

Field Type Description
fileId PlatformUUID Server file id.
name String Original file name.
mimeType String? MIME type if known.

Id

An id in a provider's namespace, e.g. provider "tidal", id "123".

Field Type Description
provider String Provider / importer id. Empty means the server default.
id String The id.
contentType Type? Content type if known.

Text

Full name: dev.dertyp.ui.IntakeItem.Text

Free text, e.g. a search query.

Field Type Description
text String The text.

Url

Full name: dev.dertyp.ui.IntakeItem.Url

A link.

Field Type Description
url String The URL.

UiAction

An action a client performs when the user interacts with a UI element.

Field Type Description

DismissKeyboard

Unfocus the current input and close the on-screen keyboard. No-op where there is none.

Field Type Description

Intake

Hand items to the server through IUiService.intake and show the result: toast on OK, chooser on NEEDS_CHOICE, error otherwise.

Field Type Description
items List<IntakeItem> Items to submit.
resolverId String? Preselected handler (resolver id). Null lets the server decide.
confirmText String? If set, ask the user to confirm with this text first.

Invoke

Dispatch an action to the contribution via IUiService.invoke.

Field Type Description
contributionId String Contribution that handles the action.
actionId String Action identifier understood by the contribution.
params Map<String, UiValue> Static parameters sent with the action.
formId String? If set, the current values of the Form with this id are sent as the payload values.
confirmText String? If set, the client asks the user to confirm with this text before dispatching.

OpenEntity

Navigate to a library entity using the client's native screen.

Field Type Description
entityType UiEntityType Type of the entity.
entityId PlatformUUID Id of the entity.

OpenMenu

Show a native menu (dropdown, context menu or bottom sheet) with the given entries, anchored to the element.

Field Type Description
items List<UiMenuItem> Menu entries in order.
title String? Optional menu title.

OpenNative

Open a native client screen identified by a portal name, see UiPortals.

Field Type Description
name String Portal name, e.g. externalSearch.
params Map<String, String> Parameters for the native screen, e.g. query.

OpenPage

Navigate to a server-driven page contribution.

Field Type Description
pageId String Id of the PAGE contribution.
params Map<String, String> Parameters passed to the page as UiContext.params.
modal Boolean Present the page modally (sheet/dialog) instead of pushing it.

OpenUrl

Open an external URL.

Field Type Description
url String The URL to open.

Refresh

Re-render the contribution the element belongs to.

Field Type Description

UiAlign

Cross-axis alignment of children inside a layout container.

Value Description
START Align to the start.
CENTER Center.
END Align to the end.
STRETCH Stretch to fill.
SPACE_BETWEEN Distribute with space between children.

UiButtonStyle

Semantic button style.

Value Description
PRIMARY Filled accent button.
SECONDARY Outlined/tonal button.
DESTRUCTIVE Destructive action button.
TEXT Text-only button.

UiCardSize

Preferred size of a home-screen card.

Value Description
SMALL Compact card.
MEDIUM Regular card.
LARGE Tall card.
WIDE Full-width card.

UiComponent

A node of a server-driven UI tree. Clients render each node with their native design system. Unknown nodes are replaced by the server with Fallback according to the client's X-Ui-Schema-Version.

Field Type Description

Badge

Small status label.

Field Type Description
text String Badge text.
tone UiTone Tone.
icon UiIcon? Semantic icon name shown before the text.

Button

A button.

Field Type Description
label String Label.
action UiAction Action performed when pressed.
style UiButtonStyle Style.
icon UiIcon? Semantic icon name.
enabled Boolean Whether the button is enabled.

Card

Elevated container with optional header and trailing actions.

Field Type Description
children List<UiComponent> Content of the card.
title String? Header title.
subtitle String? Header subtitle.
icon UiIcon? Semantic icon name shown in the header. Shown when there is no image.
image UiImageRef? Optional image shown in the header instead of the icon.
tone UiTone Tone of the card.
actions List<UiComponent> Action elements (typically Buttons) rendered in the card footer.

Column

Vertical layout container.

Field Type Description
children List<UiComponent> Children, top to bottom.
spacing UiSpacing Spacing between children.
align UiAlign Horizontal alignment of children.
weights List<Double>? Optional relative weights, one per child.

Divider

A horizontal divider.

Field Type Description

EmptyState

Placeholder for a screen or section without content: large muted icon, title and description, centered (iOS ContentUnavailableView).

Field Type Description
title String Title.
description String? Description.
icon UiIcon? Icon.
actions List<UiComponent> Optional action elements (Buttons) below the text.

Fallback

Placeholder the server substitutes for components the client's schema version does not support.

Field Type Description
text String? Optional text to show. Clients show a generic message when null.

FileField

File input. Clients pick a file with a native file picker and submit its content under key. Clients without file field support receive a multi-line TextField with the same key.

Field Type Description
key String Payload key.
label String Label.
accept List<String> Allowed file extensions including the dot, e.g. .p8. Empty allows any file.
binary Boolean Whether the file is binary. The submitted value is the UTF-8 text of the file when false and the base64 of its bytes when true.
allowPaste Boolean Whether the client also offers pasting the content, as text or as base64 for binary files.
secret Boolean Whether the content is secret. The value is never populated and an empty submitted value means unchanged.
value String? Current content. Never populated for secret fields.
helper String? Helper text.
error String? Validation error to display.
required Boolean Whether a value is required.
enabled Boolean Whether the field is editable.
toolbar List<UiComponent> Keyboard accessory toolbar shown above the on-screen keyboard while the field is focused. Items are trailing-aligned. Buttons, Icons and Native portals.

Form

Groups form fields. Their values are submitted together with the submit action.

Field Type Description
id String Form id referenced by UiAction.Invoke.formId.
children List<UiComponent> Content including form fields.
submit Invoke Action dispatched on submit. Its formId should equal this form's id.
submitLabel String Label of the submit button.
cancelLabel String? Label of an optional cancel/reset button.
actions List<UiComponent> Extra controls rendered in the trailing row next to (before) the submit button, e.g. a scanner portal.

Grid

Grid layout container.

Field Type Description
children List<UiComponent> Children, row-major.
columns Int Preferred number of columns. Clients may reduce it on narrow screens.
spacing UiSpacing Spacing between cells.

Icon

A standalone icon.

Field Type Description
icon UiIcon The icon.
tone UiTone Tone.

Image

Full name: dev.dertyp.ui.UiComponent.Image

An image, either from the server image store or an external URL.

Field Type Description
imageId PlatformUUID? Id of a server image.
url String? External image URL, used when imageId is null.
rounded Boolean Whether to render with rounded corners/circle.

ListItem

A list row.

Field Type Description
title String Title.
subtitle String? Subtitle.
icon UiIcon? Semantic icon name. Shown when there is no image.
trailing String? Trailing text.
action UiAction? Action performed when activated.
image UiImageRef? Optional image shown instead of the icon.

Live

A subtree that updates independently of the page: render child, then subscribe to IUiService.subscribeLive(contributionId, key) and apply each UiLiveUpdate to it.

Field Type Description
key String Key passed to subscribeLive.
child UiComponent Initial content.

Log

Fixed-height log pane: small monospaced secondary text, one entry per line, scrolled to the newest line. Usually wrapped in Live so lines can be appended via UiLiveUpdate.AppendLines.

Field Type Description
lines List<String> Current lines, oldest first.
maxLines Int Maximum number of lines to keep. Older lines are dropped when appending.

Native

Portal the client fills with its own native UI for a known portal name (see UiPortals). Unknown names render the fallback, or nothing.

Field Type Description
name String Portal name, e.g. barcodeScanner.
params Map<String, String> Parameters for the native UI, e.g. target = key of the form field a scanned code is appended to.
fallback UiComponent? Rendered when the client does not implement the portal.

NumberField

Numeric input.

Field Type Description
key String Payload key.
label String Label.
value Double? Current value.
min Double? Minimum value.
max Double? Maximum value.
step Double? Step. 1.0 for integers.
helper String? Helper text.
error String? Validation error to display.
required Boolean Whether a value is required.
enabled Boolean Whether the field is editable.
toolbar List<UiComponent> Keyboard accessory toolbar shown above the on-screen keyboard while the field is focused. Items are trailing-aligned. Buttons, Icons and Native portals.

Progress

Progress indicator.

Field Type Description
value Double? Progress from 0.0 to 1.0, or null for indeterminate.
label String? Optional label.

Row

Horizontal layout container.

Field Type Description
children List<UiComponent> Children, start to end.
spacing UiSpacing Spacing between children.
align UiAlign Vertical alignment of children.
weights List<Double>? Optional relative weights, one per child.

SearchField

Search-as-you-type picker. While the user types at least minChars characters, clients call IUiService.search(contributionId, key, query, context) with the contribution that rendered the field and show the returned options. The value of the picked option is submitted under key with the enclosing Form. Clients without search field support receive a query TextField, a Search button and a Select of the results.

Field Type Description
key String Payload key, also passed to IUiService.search.
label String Label.
value UiOption? Currently selected option. Its label is shown until the user picks another one.
placeholder String? Placeholder.
helper String? Helper text.
error String? Validation error to display.
required Boolean Whether a value is required.
enabled Boolean Whether the field is editable.
minChars Int Minimum number of typed characters before clients search.
toolbar List<UiComponent> Keyboard accessory toolbar shown above the on-screen keyboard while the field is focused. Items are trailing-aligned. Buttons, Icons and Native portals.

Section

Titled group of content.

Field Type Description
children List<UiComponent> Content of the section.
title String Section title.
collapsible Boolean Whether the user can collapse the section.
collapsed Boolean Initial collapsed state.

Select

Single choice from a list of options.

Field Type Description
key String Payload key.
label String Label.
value String? Currently selected option value.
options List<UiOption> Available options.
helper String? Helper text.
error String? Validation error to display.
required Boolean Whether a value is required.
enabled Boolean Whether the field is editable.

Spacer

Empty space.

Field Type Description
size UiSpacing Size.

Stat

A labeled statistic.

Field Type Description
label String Label.
value String Formatted value.
unit String? Optional unit suffix.
icon UiIcon? Semantic icon name.
tone UiTone Tone.

Switch

Boolean toggle.

Field Type Description
key String Payload key.
label String Label.
value Boolean Current value.
helper String? Helper text.
enabled Boolean Whether the field is editable.

Table

A simple table.

Field Type Description
columns List<String> Column headers.
rows List<UiTableRow> Rows.

Text

Full name: dev.dertyp.ui.UiComponent.Text

Text.

Field Type Description
text String The text.
style UiTextStyle Text style.
tone UiTone Tone.
emphasis UiEmphasis Emphasis.

TextField

Single- or multi-line text input.

Field Type Description
key String Payload key.
label String Label.
value String? Current value. Never populated for secret fields.
placeholder String? Placeholder.
secret Boolean Whether input is masked. An empty submitted value means unchanged.
multiline Boolean Whether the field is multi-line.
helper String? Helper text.
error String? Validation error to display.
required Boolean Whether a value is required.
enabled Boolean Whether the field is editable.
kind UiTextKind Input kind.
toolbar List<UiComponent> Keyboard accessory toolbar shown above the on-screen keyboard while the field is focused. Items are trailing-aligned. Buttons, Icons and Native portals.

Tile

A tappable tile with title, subtitle and icon.

Field Type Description
title String Title.
subtitle String? Subtitle.
icon UiIcon? Semantic icon name.
action UiAction? Action performed when activated.
tone UiTone Tone.

UiContext

Context in which a contribution is rendered, e.g. the entity whose detail screen hosts the slot.

Field Type Description
entityType UiEntityType? Type of the host entity, if any.
entityId PlatformUUID? Id of the host entity, if any.
params Map<String, String> Free-form parameters, e.g. from UiAction.OpenPage.

UiContributionInfo

Describes a UI contribution available to the current user.

Field Type Description
id String Unique id, matching [a-z0-9._-]+.
source String Origin: "server" or a plugin id.
kind UiContributionKind Kind of contribution.
slot String? Slot name for SLOT contributions.
title String Localized title.
description String? Localized description.
icon UiIcon? Icon.
order Int Sort order within a slot. Lower first.
live Boolean Whether subscribe() emits updates after the initial render.
cardSize UiCardSize Preferred card size for HOME_CARD contributions.
requiresAdmin Boolean Whether the contribution is restricted to admins.
requiredCapabilities List<UserCapability> User capabilities required to see and use the contribution.
hooks List<UiHookKind> App hooks the contribution offers to handle, see IUiService.dispatchHook.

UiContributionKind

Kind of a UI contribution.

Value Description
SLOT Rendered inside a named slot of a native screen.
PAGE A standalone page owned by the contribution.
HOME_CARD A pinnable card on the home screen.

UiEmphasis

Visual emphasis of a UI element.

Value Description
LOW Subtle.
MEDIUM Regular.
HIGH Prominent.

UiEntityType

Type of a library entity a UI element refers to.

Value Description
SONG A song.
ALBUM An album.
ARTIST An artist.
PLAYLIST A playlist.
USER A user.

UiHomeCard

A home-screen card and its pin state for the current user.

Field Type Description
contributionId String Id of the HOME_CARD contribution.
pinned Boolean Whether the user pinned the card.
position Int Position among pinned cards.
size UiCardSize Preferred card size.

UiHomeLayout

The current user's home-screen card layout, including unpinned cards available for pinning.

Field Type Description
cards List<UiHomeCard> Cards, pinned ones first in position order.

UiHookEvent

An app-level event forwarded by a client.

Field Type Description
kind UiHookKind

ShareText

Plain text was shared with the app.

Field Type Description
text String The shared text.
kind UiHookKind

ShareUrl

A URL was shared with the app.

Field Type Description
url String The shared URL.
title String? Optional title that accompanied the share.
kind UiHookKind

UiHookHandler

A contribution's offer to handle a hook event. The client performs the action directly when it is the only handler, otherwise it lets the user choose.

Field Type Description
id String Handler id, matches UiHookHandlerInfo.id and UiMenuItem.id. Pass it as resolverId to IUiService.intake.
contributionId String Id of the offering contribution. Equals id for the built-in handlers.
source String Origin: "server" or a plugin id.
title String Localized title, e.g. "Import with Tidal".
description String? Localized description.
icon UiIcon? Icon.
action UiAction Action to perform when chosen.
confirmText String? If set, ask the user to confirm with this text before performing the action, even when it is the only handler.

UiHookHandlerInfo

A handler that may offer to take hook events, listed without an input. Use for pickers. Whether it accepts a specific event is only known from IUiService.dispatchHook.

Field Type Description
id String Handler id, matches UiHookHandler.id.
source String Origin: "server" or a plugin id.
title String Localized title, e.g. "Import with Tidal".
description String? Localized description.
icon UiIcon? Icon.
kinds List<UiHookKind> Hook kinds the handler can serve.

UiHookKind

Kinds of app-level events clients can forward to the server.

Value Description
SHARE_URL A URL was shared with the app.
SHARE_TEXT Plain text was shared with the app.

UiIcon

An icon: a semantic name from UiIconName, an external URL, or a server image.

Field Type Description

Image

Full name: dev.dertyp.ui.UiIcon.Image

A server image (IImageService) rendered at icon size.

Field Type Description
imageId PlatformUUID Image id.

Named

A semantic icon the client renders from its own icon set.

Field Type Description
name UiIconName The icon.

Url

Full name: dev.dertyp.ui.UiIcon.Url

An image loaded from an external URL, rendered at icon size.

Field Type Description
url String Image URL.

UiIconName

Semantic icons clients map to their own icon set. Adding an entry requires a UI schema version bump.

Value Description
SETTINGS Settings / gear.
MUSIC Music note.
ALBUM Album.
ARTIST Artist.
PLAYLIST Playlist.
IMAGE Picture.
STORAGE Storage / disk.
STATS Statistics / chart.
TASK Scheduled task.
PLAY Play.
PAUSE Pause.
DOWNLOAD Download.
IMPORT Import.
QUEUE Queue / list.
PLUG Connected service / plug.
LOGIN Login.
HEART Heart / favorites.
SYNC Sync / refresh arrows.
SEARCH Search.
KEY Key / credentials.
DATABASE Database.
WARNING Warning.
ERROR Error.
INFO Info.
USER User / person.
CHECK Checkmark / done.
CLOSE Close / dismiss.
LINK Link.
FILE Generic file / document.
MORE More / overflow menu.
BARCODE Barcode scanner.

UiImageRef

A reference to a server image shown next to a row or option.

Field Type Description
imageId PlatformUUID Id of a server image.
blurHash String? Blur hash shown while the image loads.
rounded Boolean Whether to render the image as a circle.

UiIntakeCodeKind

Kind of a catalog code handed to the intake.

Value Description
ISRC International Standard Recording Code (a track).
UPC UPC/EAN/GTIN barcode (a release).

UiIntakeResult

Result of handing items to the intake.

Field Type Description
status UiIntakeStatus Outcome.
message String? Localized message to show the user.
accepted Int Number of items that were submitted.
rejected List<IntakeItem> Items no handler accepted.
handlers List<UiHookHandler> Handlers to choose from when status is NEEDS_CHOICE (each action is an Intake action with the handler preselected) or navigational alternatives.
next UiAction? Follow-up action the client should perform, e.g. open the queue.

UiIntakeStatus

Outcome of IUiService.intake.

Value Description
OK Everything acceptable was submitted.
NEEDS_CHOICE Several handlers offer. Let the user pick one of handlers and call intake again with its action.
UNHANDLED No handler accepted any item. Fall back to native behaviour.
UNAUTHORIZED The user may not use the offering handlers.
ERROR Submission failed. See message.

UiInvokePayload

Payload of an action invocation.

Field Type Description
values Map<String, UiValue> Form field values keyed by field key, merged with the action's static params.
context UiContext Context the element was rendered in.

UiInvokeResult

Result of an action invocation.

Field Type Description
status UiInvokeStatus Outcome.
message String? Localized message to show the user.
fieldErrors Map<String, String> Per-field validation errors keyed by field key.
refresh Boolean Whether the client should re-render the contribution.
next UiAction? Follow-up action the client should perform.

UiInvokeStatus

Outcome of a UI action invocation.

Value Description
OK The action succeeded.
VALIDATION_ERROR Submitted values were rejected. See fieldErrors.
ERROR The action failed.
UNAUTHORIZED The user is not allowed to perform the action.

UiLiveUpdate

An update for a Live subtree, streamed by IUiService.subscribeLive.

Field Type Description

AppendLines

Append lines to a Log child, dropping the oldest beyond its maxLines.

Field Type Description
lines List<String> Lines to append, oldest first.

Replace

Replace the Live child with a new component.

Field Type Description
child UiComponent The new child.

UiMenuItem

An entry of a menu opened by UiAction.OpenMenu.

Field Type Description
label String Localized label.
action UiAction Action performed when chosen. May itself be OpenMenu for a sub-menu.
icon UiIcon? Icon.
tone UiTone Tone, e.g. ERROR for destructive entries.
enabled Boolean Whether the entry can be chosen.
id String? Stable id, e.g. the handler id (UiHookHandler.id) when the menu lists hook handlers. Null for plain entries.

UiOption

A selectable option of a Select field.

Field Type Description
value String Value submitted when selected.
label String Display label.
icon UiIcon? Optional icon. Shown when there is no image.
image UiImageRef? Optional image shown instead of the icon.

UiRender

A rendered contribution.

Field Type Description
contributionId String Id of the contribution.
root UiComponent Root of the component tree.
title String? Localized title, e.g. for a page header.
schemaVersion Int UI schema version the tree was shaped for.
revision Long Monotonic revision, increases with each re-render.
toolbar List<UiComponent> Elements for the native toolbar/app bar of a page (Buttons, Icons, Native portals). Empty for slot items.

UiSlotRender

All contributions rendered for a slot.

Field Type Description
slot String Slot name.
items List<UiRender> Rendered contributions in display order.

UiSpacing

Relative spacing between children or around an element.

Value Description
NONE No spacing.
SMALL Small spacing.
MEDIUM Medium spacing.
LARGE Large spacing.

UiTableRow

A row of a Table.

Field Type Description
cells List<String> Cell texts, one per column.
action UiAction? Action performed when the row is activated.

UiTextKind

Input kind of a TextField. Lets clients pick a keyboard or offer a scanner.

Value Description
TEXT Plain text.
URL A single URL.
EMAIL An e-mail address.
BARCODE A barcode/ISRC/UPC. Clients may offer a scanner.
MULTILINE_URLS Multiple URLs or codes, one per line. Clients may offer a scanner that appends lines.

UiTextStyle

Semantic text style.

Value Description
TITLE Large heading.
SUBTITLE Secondary heading.
BODY Regular body text.
CAPTION Small helper text.
CODE Monospaced text.

UiTone

Semantic color tone of a UI element. Clients map tones to their own design system.

Value Description
DEFAULT Neutral default appearance.
PRIMARY Accent/brand color.
SUCCESS Positive state.
WARNING Warning state.
ERROR Error/destructive state.
MUTED De-emphasized/secondary appearance.

UiValue

Dynamic scalar or list value used in form payloads and action parameters. Exactly one field is set.

Field Type Description
text String? String value.
number Double? Numeric value.
flag Boolean? Boolean value.
items List<UiValue>? List value.