PLAYD(1) General Commands Manual PLAYD(1)

NAME

playd — basic TCP/IP-driven audio player

SYNOPSIS

playd [device-id] [address] [port]

DESCRIPTION

playd is a simple audio player, intended to be driven by other software via a line-based TCP protocol. Its feature set is described in COMMANDS.
playd has a simple feature list: it can load one audio file (given its path), play that file, pause playback of that file, seek and eject that file, and periodically emit the current position in that file.

Invocation

If no arguments are given, playd lists all possible valid values for the device argument. Otherwise, it is launched as a daemon, with the arguments meaning:
device
The ID of the device onto which playd will output audio. The device must be on the list given when playd is executed with zero arguments.
address
The IP address to which playd will bind when listening for client connections; the default is 127.0.0.1 (only local connections). To accept all connections, use 0.0.0.0.
port
The TCP port on which playd will listen for client connections; the default is 1350.

Protocol

playd speaks a simple, textual protocol inspired by the POSIX shell:
  • Requests and responses consist of one or more whitespace-delimited words, followed by a line-feed.
  • The first word, the tag, uniquely identifies the request being sent or answered. Examples of good tags include UUIDs, or hashes of the command send time and originating host. Broadcasts from the server have the tag '!'.
  • The next word, the command word, denotes the specific request (if in lowercase), or response (if in CAPITALS): playd is case-sensitive.
  • Words may contain backslashes, which escape the next character, reproducing it verbatim. This can be used to permit whitespace, which would otherwise end the word.
  • In addition, words may be quoted in either double quotes, in which backslash escaping is respected, or single quotes, in which it is ignored.

Controlling from a terminal

Since playd only speaks TCP/IP (by design), it can be hard to speak with it from a terminal on the local machine. Programs such as nc(1) or socat(1) may bridge this gap in functionality.

COMMANDS

The sets of valid requests to, and responses from, a playd session are:

Requests

eject
Unloads the current file, stopping any playback.
fload path
Loads the file at path, which must be absolute.
play
Starts, or resumes, playback of the current file.
pos micros
Seeks to micros microseconds past the start of the file. Seeking past a file's end is equivalent to seeking to the end directly.
stop
Stops playback of the current file, keeping the current position.
end
Makes playd behave as if the current file has just ended.
dump
Asks playd to emit all current state to this client as responses.

Responses

OHAI id protocol server
Sent upon connection. id is the ID assigned to the connected client. protocol is the name and version of the Bifrost protocol being used. server identifies the playd server and version number.
IAMA role
Describes the Bifrost role playd implements. This identifies the features playd provides to external clients.
ACK OK details
playd just finished processing a request, identified by the tag of this response. Further details are provided in details.
ACK FAIL details
playd failed to execute a request, identified by the tag of this response. Further details are provided in details.
ACK WHAT details
playd did not understand a request, identified by the tag of this response. Further details are provided in details.
DUMP
playd has finished responding to a dump command.
END
The loaded file has reached its physical end.
EJECT
There is no currently loaded file.
FLOAD path
The file at path is loaded.
PLAY
The currently loaded file is now playing.
STOP
The currently loaded file is now stopped.
POS pos
Periodic announcement of the current file position in microseconds, pos.

EXAMPLES

Without arguments,
% playd
will produce a list of available devices:
0: HDA ATI SB: ALC892 Analog (hw:0,0) 
1: HDA ATI SB: ALC892 Digital (hw:0,1) 
2: HDA ATI SB: ALC892 Alt Analog (hw:0,2) 
3: HDA NVidia: ID 42 Digital (hw:1,3) 
4: Plantronics GameCom 780: USB Audio (hw:2,0) 
5: sysdefault 
6: front 
7: surround40 
8: default 
9: dmix
Say we want to output on the GameCon. The command
% playd 4
will start playd on its default address (localhost) and port, outputting on device ID 4.
To change the address and port, we specify them as arguments:
% playd 4 127.0.0.1 1350
To connect to playd from the terminal, we can use nc(1):
% nc 127.0.0.1 1350
A session with playd may look like the following:
-> ! OHAI 1 'bifrost-0.3.0' 'playd-0.3.0' 
-> ! IAMA player/file 
-> ! POS 0 
-> ! EJECT 
<- 1 fload '/usr/home/foo/awesome-mix.mp3' 
-> ! FLOAD '/usr/home/foo/awesome-mix.mp3' 
-> ! STOP 
-> 1 ACK OK success 
<- 2 play 
-> ! PLAY 
-> 2 ACK OK success 
(file plays to end) 
-> ! END 
-> ! STOP 
-> ! POS 0 
-> 3 eject 
<- ! EJECT 
<- 3 ACK OK success

AUTHORS

In alphabetical surname order, the main contributors to playd at time of writing are:

BUGS

Behaviour when escaping multi-byte UTF-8 characters with “\” is undefined; this is intentional, for reasons of code simplicity.
February 14, 2016 Linux 3.4.0+