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 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'


  • 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.


  • subid - Subscription ID. (integer)

set (Client -> Server) id:3


  • 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


  • 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.


  • 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.


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

move child (Server -> Client) id:7

Move a child between its siblings.


  • 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", ""]
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.