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 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.

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