Skip to content

Playslave API

Jump to bottom
Matt Windsor edited this page Jun 25, 2014 · 7 revisions

Playslave API

General

  • 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 must be absolute, and shell globs/tildes/etc are not parsed.

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

Clone this wiki locally