Skip to content

Playslave API

Jump to bottom
Matt Windsor edited this page Jul 14, 2014 · 7 revisions

Playslave API

General

See Playslave Meta-API for information on the general format of the protocol.

  • An implementation of playslave uses a text-based protocol, for reasons of ease of debugging, manual control of playslave without a frontend, and transparency.
  • The API is separated into requests, sent from the frontend/user to playslave, and responses, sent from playslave to the frontend/user.
  • Requests and responses both take the form WORD arg1 arg2… argn, where arguments are either single words or quoted strings (use \" to escape a string), and WORD is a four-character identifier (lowercase for requests, uppercase for responses).

Requests

play

  • Syntax: play
  • Valid when: stopped

Plays the currently loaded file from its current position.

stop

  • Syntax: stop
  • Valid when: playing

Stops the currently loaded file. Does not reset the position or unload the file. (As such, it is closer to a pause in conventional audio players).

To effect a ‘proper’ stop, follow the stop with a seek 0.

load

  • Usage: load FILE
  • Valid when: in any state
  • Example: load "/home/mattbw/Music/Violinski/Clog Dance - The Very Best of Violinski/01 - Clog Dance.mp3"

Loads the audio file whose path is given as the sole argument. The path should be absolute (playslave implementations may tolerate relative paths, but this should not be relied on by clients), and shell globs/tildes/etc must not be parsed by the playslave implementation.

Any paths with spaces must be quoted.

ejct

  • Syntax: ejct
  • Valid when: not ejected

Unloads the current audio file, stopping it if it is playing.

seek

  • Syntax: seek TIME
  • Valid when: not ejected
  • Examples: seek 10secs, seek 1m, seek 0

Seeks to a position in the file. The position can either be an integer, in which case it is taken as a number of microseconds, or an integer followed by one of the following unit suffices:

  • us, usec, usecs: Microseconds
  • ms, msec, msecs: Milliseconds
  • s, sec, secs: Seconds
  • m, min, mins: Minutes
  • h, hour, hours: Hours

quit

  • Syntax: quit
  • Valid when: in any state

Quits the player.

Responses

OHAI

  • Syntax: OHAI MESSAGE
  • Example: OHAI Playslave++ 0.1

Sent to the user on connect. The message is mainly for the benefit of humans, but may identify the version of playslave being used.

TIME

  • Syntax: TIME MICROSECONDS
  • Occurs when: playing
  • Example: TIME 10000000

Notifies the client of the current position in the song, measured in microseconds from its start.

TTFN

  • Syntax: TTFN MESSAGE
  • Example: TTFN See you later, alligator

Sent to the user on disconnect. The message is mainly for the benefit of humans.

WHAT

  • Syntax: WHAT MESSAGE
  • Example: WHAT Unrecognised command

Sent when a request the command parser doesn't recognise is sent.

To be continued

Proposals

These are not implemented in the API, but are proposals for extension.

FEAT

  • Syntax: FEAT [feat1 feat2 ...]
  • Example: FEAT MultiChannel Playlist Seek TapeControls

A FEAT response is sent to each client on connect, and lists the optional features the server supports. The features are space-delimited.

This response would allow the same API, and clients, to be recycled across playslave++ and any compatible implementations with additional features.

Potential optional features:

  • MultiChannel: This server has more than one channel. (TODO: Decide how to select a channel in requests.)
  • Playlist: This server supports playlist queuing.
  • Seek: This server supports seeking to an arbitrary point in the audio. Usually present, unless this playslave server controls an Internet stream.
  • TapeControls: This server, instead of Play/Stop commands and states, has Play/Pause/Stop commands and states.
  • Volume: This server supports software-side volume.

Channel prefixing

A possible solution to how to address individual channels in multi-channel Playslave:

  • A command may optionally be prefixed with the number of the channel to which it pertains.
  • A command with no channel prefix is taken to apply to all channels.
  • Commands that have no channel affinity (eg quit) ignore their assigned channel.
  • Example: 0 play plays channel 0; play plays channels 0, 1 and 2.
Clone this wiki locally