URY playd
C++ minimalist audio player
README.commands.md
1 # Command Reference
2 
3 `playd` implements the BAPS3 Internal API (specifically the `End`, `FileLoad`,
4 `PlayStop`, `Seek`, and `TimeReport` features), as described in the [BAPS3
5 specification][]. The specification provides more formal definitions of the
6 commands supported by `playd`.
7 
8 ## Sending Commands Manually
9 
10 To talk to `playd`, open a raw TCP/IP session on the host and port on which
11 `playd` was started. For example, using [netcat][]:
12 
13  nc ${ADDRESS} ${PORT}
14 
15 On Windows, use [PuTTY][] in _raw mode_ with an _Implicit CR for every LF_.
16 
17 ## Initial Responses
18 
19 When connecting to `playd`, it will send a few initial responses to inform
20 the client of its current state. This will look something like:
21 
22  ! OHAI 1 bifrost-0.3.0 playd-0.3.0
23  ! IAMA player/file
24  ! PLAY
25  ! FLOAD 'C:\Users\mattbw\Music\07 - Games Without Frontiers.mp3'
26  ! POS 72399818
27  ! DUMP
28 
29 This tells the client:
30 
31 * Its client ID is 1 (mostly used for debug purposes);
32 * This server speaks the Bifrost protocol, version 0.3.0;
33 * This server runs `playd` version 0.3.0;
34 * This server is a file player;
35 * There is a file loaded and it is playing;
36 * The file loaded is 'C:\Users\mattbw\Music\07 - Games Without Frontiers.mp3'
37  (a brilliant song from Peter Gabriel)
38 * We are 72,399,818 microseconds, or 72.4 seconds, into the song;
39 * This is all the information we need to begin sending commands.
40 
41 ## Command Format
42 
43 `playd` uses _shell-style_ commands:
44 
45 * Each command is a linefeed-delimited _line_ of whitespace-delimited _words_;
46 * Whitespace and quotes can be _escaped_ by using backslash;
47 * Words can be _quoted_ to avoid needing to backslash-escape large amounts of
48  whitespace: either using _double quotes_, which allows backslash escaping, or
49  _single quotes_, which doesn't;
50 * The first word is a _tag_, which _should_ uniquely identify the command among
51  any other commands `playd` receives. If you're confident you're the only
52  user of a `playd`, feel free to use anything here, as long as it contains
53  neither `!` nor `:`. If you're sharing a `playd` with something else, you
54  will need to make sure your tags don't clash with theirs (eg, using GUIDs, or
55  hashes including your hostname/MAC address/etc).
56 * The second word represents the _command_, and each subsequent word is an
57  _argument_ to that command.
58 
59 ## Requests
60 
61 These are the requests that clients can send to `playd`. Request commands are
62 always in _lowercase_.
63 
64 ### quit
65 
66 Terminates `playd`. (May be removed in future versions.)
67 
68 ### fload _file_
69 
70 Loads _file_, which is an _absolute_ path to an audio file.
71 
72 ### eject
73 
74 Unloads the current file, stopping it if it is currently playing.
75 
76 ### play
77 
78 Starts playing the currently loaded file.
79 
80 ### stop
81 
82 Stops playing the currently loaded file. This does not alter the position;
83 use `seek 0` after `stop` to rewind the file.
84 
85 ### pos _position_
86 
87 Seeks to _position_ microseconds since the beginning of the file.
88 
89 ### end
90 
91 Causes the song to jump right to the end; this is useful for skipping to the
92 next file if you're using a playlist manager like `listd` with `playd`.
93 
94 ### dump
95 
96 Dumps all of the current state, as if you had just connected (except we don't
97 show you the `OHAI` or `IAMA` again).
98 
99 ## Responses
100 
101 These are the responses sent to clients by `playd`. Response commands are
102 always in _uppercase_.
103 
104 ### OHAI _id_ _protocol-ver_ _server-ver_
105 
106 Identifies the server program and version, the protocol server and version, and
107 the client ID.
108 
109 ### IAMA _role_
110 
111 States the Bifrost role of `playd`, ie `player/file`.
112 
113 ### END
114 
115 Marks the end of a file. This is sent if a file finishes playing of its own
116 accord, or if `end` is sent.
117 
118 ### POS _position_
119 
120 Announces the current position in the file, in microseconds.
121 
122 ### PLAY
123 
124 Announces that the file is now being played.
125 
126 ### STOP
127 
128 Announces that the file is now stopped.
129 
130 ### EJECT
131 
132 Announces that no file is loaded.
133 
134 ### QUIT
135 
136 Announces that the server is quitting (may be removed in future versions).
137 
138 ### FLOAD _file_
139 
140 Announces that _file_ has just been loaded.
141 
142 ### ACK _status_ _message_ _command..._
143 
144 _The format of this response may change in future versions._
145 
146 Announces that a _command_ has just been received and processed.
147 
148 The result of the command is given by _status_:
149 
150 * `WHAT`: command is syntactically invalid.
151 * `FAIL`: command unsuccessfully completed.
152 * `OK`: command successfully completed.
153 
154 [BAPS3 specification]: https://UniversityRadioYork.github.io/baps3-spec
155 [PuTTY]: http://www.chiark.greenend.org.uk/~sgtatham/putty/
156 [netcat]: http://nc110.sourceforge.net/