-
Notifications
You must be signed in to change notification settings - Fork 4
Playslave Meta API
This page informally describes the general format of Playslave API messages.
Playslave applications are expected to follow Postel's principle: be liberal in what is accepted, and conservative in what is emitted.
Applications may accept a superset of the meta-API (eg, recognising sequences whose meaning is undefined here) if this eases the implementation of the API parser, but these extensions must not be relied upon.
A word is either:
- a series of characters delimited by two unescaped double quote characters
"; or - a series of non-delimited characters containing no unescaped whitespace.
Thus, word, white\ space, "christmas pudding", \"shusb\", and "quote \"unquote\"" are words (which tokenise as 'word', 'white space', 'christmas pudding', '"shusb"', and 'quote "unquote"' respectively), and white space, "asdf, and "triple""triad" are not words.
A message is zero or more words, delimited by any non-zero run of whitespace, and ending with a new-line sequence (\r\n or \n). Messages should not contain leading or trailing whitespace.
Requests are messages that begin with a command word, which is comprised of four lowercase ASCII characters. Similarly, responses are messages that begin with a command word of four uppercase ASCII characters. The command word should occupy the first four bytes of the message, for ease of parsing.
Targeted requests are requests prefixed with the sequence @K:, where K is an arbitrary length address consisting of a run of one or more characters excluding :. Sourced responses are responses prefixed in the same way. Since the @ occurs in the first byte and cannot be part of a legal command word, addresses may easily be detected and handled by optimised parsers.
Targeted requests and sourced responses are used to specify targets/sources for commands in which there is ambiguity: for example, a play request in a multiple-channel player may need a target describing which channel is expected to be played.