🎧 Your Personal Streaming Service
Go airsonicmadsonicmedia-servermusicmusic-servernavidromeopensubsonicraspberry-piself-hostedstreamerstreaming-apistreaming-audiosubsonicsubsonic-server
version: v1-draft
exports:
nd_scrobbler_is_authorized:
description: IsAuthorized checks if a user is authorized to scrobble to this service.
input:
$ref: '#/components/schemas/IsAuthorizedRequest'
contentType: application/json
output:
type: boolean
contentType: application/json
nd_scrobbler_now_playing:
description: NowPlaying sends a now playing notification to the scrobbling service.
input:
$ref: '#/components/schemas/NowPlayingRequest'
contentType: application/json
nd_scrobbler_scrobble:
description: Scrobble submits a completed scrobble to the scrobbling service.
input:
$ref: '#/components/schemas/ScrobbleRequest'
contentType: application/json
nd_scrobbler_playback_report:
description: PlaybackReport sends a playback state report to the scrobbling service.
input:
$ref: '#/components/schemas/PlaybackReportRequest'
contentType: application/json
components:
schemas:
IsAuthorizedRequest:
description: IsAuthorizedRequest is the request for authorization check.
properties:
username:
type: string
description: Username is the username of the user.
required:
- username
NowPlayingRequest:
description: NowPlayingRequest is the request for now playing notification.
properties:
username:
type: string
description: Username is the username of the user.
track:
$ref: '#/components/schemas/TrackInfo'
description: Track is the track currently playing.
position:
type: integer
format: int32
description: Position is the current playback position in seconds.
required:
- username
- track
- position
PlaybackReportRequest:
description: PlaybackReportRequest is the request for playback report notifications.
properties:
username:
type: string
description: Username is the username of the user.
track:
$ref: '#/components/schemas/TrackInfo'
description: Track is the track being played.
state:
type: string
description: State is the current playback state (starting/playing/paused/stopped/expired).
positionMs:
type: integer
format: int64
description: PositionMs is the current playback position in milliseconds.
playbackRate:
type: number
format: float
description: PlaybackRate is the playback speed (1.0 = normal).
playerId:
type: string
description: PlayerId is the unique client identifier.
playerName:
type: string
description: PlayerName is the human-readable player name.
timestamp:
type: integer
format: int64
description: Timestamp is the Unix timestamp when this report was generated.
required:
- username
- track
- state
- positionMs
- playbackRate
- playerId
- playerName
- timestamp
ScrobbleRequest:
description: ScrobbleRequest is the request for submitting a scrobble.
properties:
username:
type: string
description: Username is the username of the user.
track:
$ref: '#/components/schemas/TrackInfo'
description: Track is the track that was played.
timestamp:
type: integer
format: int64
description: Timestamp is the Unix timestamp when the track started playing.
required:
- username
- track
- timestamp
TrackInfo:
description: TrackInfo contains track metadata.
properties:
id:
type: string
description: ID is the internal Navidrome track ID.
title:
type: string
description: Title is the track title.
album:
type: string
description: Album is the album name.
artist:
type: string
description: Artist is the formatted artist name for display (e.g., "Artist1 • Artist2").
albumArtist:
type: string
description: AlbumArtist is the formatted album artist name for display.
artists:
type: array
description: Artists is the list of track artists.
items:
$ref: '#/components/schemas/ArtistRef'
albumArtists:
type: array
description: AlbumArtists is the list of album artists.
items:
$ref: '#/components/schemas/ArtistRef'
duration:
type: number
format: float
description: Duration is the track duration in seconds.
trackNumber:
type: integer
format: int32
description: TrackNumber is the track number on the album.
discNumber:
type: integer
format: int32
description: DiscNumber is the disc number.
mbzRecordingId:
type: string
description: MBZRecordingID is the MusicBrainz recording ID.
mbzAlbumId:
type: string
description: MBZAlbumID is the MusicBrainz album/release ID.
mbzReleaseGroupId:
type: string
description: MBZReleaseGroupID is the MusicBrainz release group ID.
mbzReleaseTrackId:
type: string
description: MBZReleaseTrackID is the MusicBrainz release track ID.
libraryId:
type: integer
format: int32
description: |-
LibraryID is the ID of the library the track belongs to.
Only included if the plugin has library permission with filesystem access for the track's library.
path:
type: string
description: |-
Path is the full path to the track file, relative to the library root.
Only included if the plugin has library permission with filesystem access for the track's library.
required:
- id
- title
- album
- artist
- albumArtist
- artists
- albumArtists
- duration
- trackNumber
- discNumber
ArtistRef:
description: |-
ArtistRef is the minimal information a plugin returns for Navidrome to match an
artist against the library. It is a reference, not a full artist entity: it
carries only matching keys (name and optional internal/MusicBrainz IDs) plus a
few projection fields used when describing a track's participants, never
descriptive data such as biographies or images.
properties:
id:
type: string
description: ID is the internal Navidrome artist ID (if known).
name:
type: string
description: Name is the artist name.
mbid:
type: string
description: MBID is the MusicBrainz ID for the artist.
sortName:
type: string
description: SortName is the artist name used for sorting (if known).
role:
type: string
description: Role is the participation category (e.g. "artist", "composer", "performer").
subRole:
type: string
description: SubRole is a specialization within Role (e.g. the instrument for a performer).
required:
- name