snapcast/doc/json_rpc_api/stream_plugin.md

Stream plugin

A stream plugin is (this might change in future) an executable binary or script that is started by the server for a specific stream and offers playback control capabilities and provides information about the stream's state, as well as metadata for the currently playing track. The Snapcast server communicates via stdin/stdout with the plugin and sends newline delimited JSON-RPC commands and receives responses and notifications from the plugin, as described below. In upcoming releases shared library plugins might be supported as well.

Requests

A Stream plugin must support and handle the following requests, sent by the Snapcast server

• Plugin.Stream.Player.Control
• Plugin.Stream.Player.SetProperty
• Plugin.Stream.Player.GetProperties

Notifications

The following messages can be sent by the plugin to notify the server about changes. The Plugin.Stream.Ready should be fired as soon as the plugin is ready to receive commands, upon reception, the server will query the stream's properties

• Plugin.Stream.Player.Properties
• Plugin.Stream.Log
• Plugin.Stream.Ready

Plugin.Stream.Player.Control

Used to control the player

{"id": 1, "jsonrpc": "2.0", "method": "Plugin.Stream.Player.Control", "params": {"command": "<command>", "params": { "<param 1>": <value 1>, "<param 2>": <value 2>}}}

Supported commands

• Play: Start playback
  • params: none
• Pause: Stop playback
  • params: none
• PlayPause: Toggle play/pause
  • params: none
• Stop: Stop playback
  • params: none
• Next: Skip to next track
  • params: none
• Previous: Skip to previous track
  • params: none
• Seek: Seek forward or backward in the current track
  • params:
    • Offset: [float] seek offset in seconds
• SetPosition: Set the current track position in seconds
  • params:
    • Position: [float] the new track position
    • TrackId: [string] the optional currently playing track's identifier

Example

{"id": 1, "jsonrpc": "2.0", "method": "Plugin.Stream.Player.Control", "params": {"command": "SetPosition", "params": { "Position": 17.827, "TrackId": "/org/mpris/MediaPlayer2/Track/2"}}}

Expected response

Success:

{"id": 1, "jsonrpc": "2.0", "result": "ok"}

Error:

todo

Plugin.Stream.Player.SetProperty

{"id": 1, "jsonrpc": "2.0", "method": "Plugin.Stream.Player.SetProperty", "params": {"<property>", <value>}}

Supported propertys

• loopStatus: [string] the current repeat status, one of:
  • none: the playback will stop when there are no more tracks to play
  • track: the current track will start again from the begining once it has finished playing
  • playlist: the playback loops through a list of tracks
• shuffle: [bool] play playlist in random order
• volume: [int] voume in percent, valid range [0..100]
• rate: [float] The current playback rate, valid range (0..)

Expected response

Success:

{"id": 1, "jsonrpc": "2.0", "result": "ok"}

Error:

todo

Plugin.Stream.Player.GetProperties

{"id": 1, "jsonrpc": "2.0", "method": "Plugin.Stream.Player.GetProperties"}

Expected response

Success:

{"id": 1, "jsonrpc": "2.0", "result": {"canControl":true,"canGoNext":true,"canGoPrevious":true,"canPause":true,"canPlay":true,"canSeek":false,"loopStatus":"none","playbackStatus":"playing","position":93.394,"shuffle":false,"volume":86}}

{"id": 1, "jsonrpc": "2.0", "result": {"canControl":true,"canGoNext":true,"canGoPrevious":true,"canPause":true,"canPlay":true,"canSeek":true,"loopStatus":"none","metadata":{"album":"Doldinger","albumArtist":["Klaus Doldinger's Passport"],"artUrl":"http://coverartarchive.org/release/0d4ff56b-2a2b-43b5-bf99-063cac1599e5/16940576164-250.jpg","artist":["Klaus Doldinger's Passport feat. Nils Landgren"],"contentCreated":"2016","duration":305.2929992675781,"genre":["Jazz"],"musicbrainzAlbumId":"0d4ff56b-2a2b-43b5-bf99-063cac1599e5","title":"Soul Town","trackId":"7","trackNumber":6,"url":"Klaus Doldinger's Passport - Doldinger (2016)/06 - Soul Town.mp3"},"playbackStatus":"playing","position":72.79499816894531,"shuffle":false,"volume":97}}

Supported propertys

• playbackStatus: [string] The current playback status, one of:
  • playing
  • paused
  • stopped
• loopStatus: [string] The current repeat status, one of:
  • none: The playback will stop when there are no more tracks to play
  • track: The current track will start again from the begining once it has finished playing
  • playlist: The playback loops through a list of tracks
• shuffle: [bool] Traverse through the playlist in random order
• volume: [int] Voume in percent, valid range [0..100]
• rate: [float] The current playback rate, valid range (0..)
• position: [float] Current playback position in seconds
• canGoNext: [bool] Whether the client can call the Next method on this interface and expect the current track to change
• canGoPrevious: [bool] Whether the client can call the Previous method on this interface and expect the current track to change
• canPlay: [bool] Whether playback can be started using Play or PlayPause
• canPause: [bool] Whether playback can be paused using Pause or PlayPause
• canSeek: [bool] Whether the client can control the playback position using Seek and SetPosition
• canControl: [bool] Whether the media player may be controlled over this interface

Error:

todo

Notifications

Plugin.Stream.Player.Metadata

TODO: Metadata are part of the properties

{"jsonrpc": "2.0", "method": "Plugin.Stream.Player.Metadata", "params": {"artist":["Travis Scott & HVME"],"file":"http://wdr-1live-live.icecast.wdr.de/wdr/1live/live/mp3/128/stream.mp3","name":"1Live, Westdeutscher Rundfunk Koeln","title":"Goosebumps (Remix)","trackId":"3"}}

Supported tags

• trackId: [string] A unique identity for this track within the context of an MPRIS object (eg: tracklist).
• file: [string] The current song.
• duration: [float] The duration of the song in seconds; may contain a fractional part.
• artist: [list of strings] The track artist(s).
• artistSort: [list of strings] Same as artist, but for sorting. This usually omits prefixes such as “The”.
• album: [string] The album name.
• albumSort: [string] Same as album, but for sorting.
• albumArtist: [list of strings] The album artist(s).
• albumArtistSort: [list of strings] Same as albumartist, but for sorting.
• name: [string] A name for this song. This is not the song title. The exact meaning of this tag is not well-defined. It is often used by badly configured internet radio stations with broken tags to squeeze both the artist name and the song title in one tag.
• date: [string] The song’s release date. This is usually a 4-digit year.
• originalDate: [string] The song’s original release date.
• composer: [list of strings] The composer(s) of the track.
• performer: [string] The artist who performed the song.
• conductor: [string] The conductor who conducted the song.
• work: [string] “a work is a distinct intellectual or artistic creation, which can be expressed in the form of one or more audio recordings”
• grouping: [string] “used if the sound belongs to a larger category of sounds/music” (from the IDv2.4.0 TIT1 description).
• comment: [list of string] A (list of) freeform comment(s)
• label: [string] The name of the label or publisher.
• musicbrainzArtistId: [string] The artist id in the MusicBrainz database.
• musicbrainzAlbumId: [string] The album id in the MusicBrainz database.
• musicbrainzAlbumArtistId: [string] The album artist id in the MusicBrainz database.
• musicbrainzTrackId: [string] The track id in the MusicBrainz database.
• musicbrainzReleaseTrackId: [string] The release track id in the MusicBrainz database.
• musicbrainzWorkId: [string] The work id in the MusicBrainz database.
• lyrics: [list of strings] The lyricist(s) of the track
• bpm: [integer] The speed of the music, in beats per minute.
• autoRating: [float] An automatically-generated rating, based on things such as how often it has been played. This should be in the range 0.0 to 1.0.
• comment: [list of strings] A (list of) freeform comment(s).
• composer: [list of strings] The composer(s) of the track.
• contentCreated: [string] Date/Time: When the track was created. Usually only the year component will be useful.
• discNumber: [integer] The disc number on the album that this track is from.
• firstUsed: [string] Date/Time: When the track was first played.
• genre: [list of strings] List of Strings: The genre(s) of the track.
• lastUsed: [string] Date/Time: When the track was last played.
• lyricist: [list of strings] List of Strings: The lyricist(s) of the track.
• title: [string] The track title.
• trackNumber: [string] The track number on the album disc.
• url: [string uri] The location of the media file.
• artUrl: [string uri] The location of an image representing the track or album. Clients should not assume this will continue to exist when the media player stops giving out the URL.
• useCount: [integer] The number of times the track has been played.
• userRating: [float] A user-specified rating. This should be in the range 0.0 to 1.0.
• spotifyArtistId: [string] The Spotify Artist ID
• spotifyTrackId: [string] The Spotify Track ID

Plugin.Stream.Player.Properties

{"jsonrpc": "2.0", "method": "Plugin.Stream.Player.Properties", "params": {"canControl":true,"canGoNext":true,"canGoPrevious":true,"canPause":true,"canPlay":true,"canSeek":false,"loopStatus":"none","playbackStatus":"playing","position":593.394,"shuffle":false,"volume":86}}

Supported propertys

Plugin.Stream.Log

Send a log message

{"jsonrpc": "2.0", "method": "Plugin.Stream.Log", "params": {"severity":"Info","message":"<Log message>"}}

Supported severitys

• trace verbose debug-level message
• debug debug-level message
• info informational message
• notice normal, but significant, condition
• warning warning conditions
• error error conditions
• fatal critical conditions

Plugin.Stream.Ready

The plugin shall send this notification when it's up and ready to receive commands

{"jsonrpc": "2.0", "method": "Plugin.Stream.Ready"}

Server

TODO: this belongs to doc/json_rpc_api/control.md

Requests

To control the stream state, the following commands can be sent to the Snapcast server and will be forwarded to the respective stream:

{"id": 1, "jsonrpc": "2.0", "method": "Stream.Control", "params": {"id": "Pipe", "command": command, "params": params}}

{"id": 1, "jsonrpc": "2.0", "method": "Stream.SetProperty", "params": {"id": "Pipe", "property": property, "value": value}}

Notifications

{"jsonrpc": "2.0", "method": "Stream.OnProperties", "params": {"id": "Pipe", "properties": {}}}