Devious Fish
pianod2 music server
profile for Perette at Stack Overflow, Q&A for professional and enthusiast programmers

pianod2 Protocols

pianod2 supports 2 protocols:

These procedures select the response protocol. Commands/requests can be issued in either form at any time.

For clarity, “commands” refers to command-line style directives, while “request” refers to JSON style.

Common elements of the protocols are:

TCP/IP Line Framing
For both text and JSON protocols over plain-old TCP, commands/requests are submitted as a line of text terminated by a newline. Newlines are also key in framing responses.
WebSocket Framing
When using WebSockets, each line is instead a WebSocket packet, for both commands/requests and responses. Newlines are omitted from WebSocket responses.
Mingling of spontaneous information and replies
pianod transmits both spontaneous information (such as playback status changes and current track information) and replies to clients. Clients must be able to separate the spontaneous from the replies. The protocols have been designed to allow this.
Reply & Ordering Guarantee
Furthermore, a command or request is guaranteed to receive a reply, and replies will arrive in the order in which requests were sent. Thus, a client may submit successive requests without waiting for replies, and replies can be handled (typically dispatched to callback functions) as they are received.
No Guarantee of Responsiveness

There is no guarantee how quickly the response will be provided. Clients should avoid using timeouts, or set them sufficiently high that normal delayed responses will not trigger them. Delays occur:

  • around song transitions & crossfades
  • preparing responses to complicated queries
  • if other connected users/sessions are submitting requests
  • if Internet music services are slow in responding due to network or server congestion
  • if pianod is on the Internet and being probed heavily for exploits