Showtime Property Protocol

STPP is a protocol that requires a bidirectional message passing transport. One such is websocket which is what the current implementation uses.

The websocket version can currently be accessed via http://127.0.0.1:42000/showtime/stpp. However, for this to work the "experimental features" flag
must be turned on in settings:dev

subscribe (Client -> Server) id:1

This is used by the client to subscribe to updates for a given property. The property is found by searching the 'path' starting at 'propref'

Arguments:

  • subid - Subscription ID. An integer assigned by client. It's up to the client to not reuse these. Subscription ID 0 should not be used.
  • propref - Integer reference to a property. 0 would mean global root prop
  • path - A string that's a dot separated path to property

unsubscribe (Client -> Server) id:2

Unsubscribes from a subscription. Note that the client may still get notifications for the subscription ID for a little while even after the message have been sent. This is because messages might be in flight over the wire.

Arguments:

  • subid - Subscription ID. (integer)

set (Client -> Server) id:3

Arguments:

  • propref - Reference to a property (integer). 0 would mean global root prop
  • path - dot separated path to property (string)
  • value - Value (See value formatting below)
  • skip - Optional parameter that, if set, should be a subscription ID that will NOT be notified about the change. This is useful if an app want to suppress getting an update on a prop that it changes.

notify value (Server -> Client) id:4

Set the property to a given value

Arguments:

  • subid - Subscription ID. (integer)
  • value - Value (See value formatting below)

add childs (Server -> Client) id:5

Add a list of child-properties to the property referred to by the subscription.

Arguments:

  • subid - Subscription ID. (integer)
  • before - The new properties should be inserted before this property. If 0 it means they should be inserted at the end.
  • properties - List of properties that was added

del childs (Server -> Client) id:6

Delete a set of child-properties from the property referred to by the subscription.

Arguments:

  • subid - Subscription ID. (integer)
  • properties - List of properties that was deleted

move child (Server -> Client) id:7

Move a child between its siblings.

Arguments:

  • subid - Subscription ID. (integer)
  • property - Property to move
  • before - Property moved to before this item. if 0 it's to the end of the list.

JSON formating

Message formating

Each message is encoded as a JSON Array as follows:

[cmd, ...]

cmd is an integer encoding the command such as:

1. subscribe
2. unsubscribe
3. set
4. notify
5. add child
6. del child
7. move child

So for example to create a subscription with ID 100 for master volume the JSON message would look like this:

[1, 100, 0, "audio.mastervolume"]

and then to unsubscribe:

[2, 100]

Set master volume (master volume is in dB):

[3, 0, "audio.mastervolume", -10.5]

When master volume updates the server will send a notification:

[4, 100, -10.5]

Value formating

type JSON formating example Comment
void null
float/integer 123
string "foobar"
uri ["uri", "The best site", "http://www.lonelycoder.com"]
directory ["dir"] Means property is a collection of other properties

Note that for a property that is currently a directory if the value is set to something else than ["dir"] all the items should be considered deleted. Typically the STPP Server (aka Showtime) will send a void to clear out all items in a directory and then reset it to ["dir"] again.