Cloud JSON Protocol

Cloud JSON Protocol

SOUND4 Helpdesk
SOUND4 Helpdesk

This is the communication protocol used in all .CL libraries, and in some standalone products.

The protocol is based on JSON only.

Commands and answers

All exchanges are in the form : { "command" : data... }.

The process/library is passive : it only answers when something is asked.

Answers will start with either :

  • When the command is requesting some value (get or change for instance), the answer will start with the command containing the requested object.
  • "OK" when the command is doing an action, with a string property containing the command. For instance: {"OK":"set"}
  • "ERROR" if the command failed, with a string property containing the command. For instance: {"ERROR":"load"}

Basic commands

Get

{ "get" : `object` }

Get values. If object is NULL, get all parameters, and so show the possibilities.

Otherwise, return the requested object.

For instance, {"get":{"status":null}} returns {"get":{"status":{"preset_changed":false,"license_valid":true,"version":"1.1.19"}}}

Change

{ "change" : null }

Get all changes since last request from this port. This behaves like "get", but only providing changes. Each call reset the state for this connection to current.

For instance : {"change":null} returns {"change":{"vu":{"in":{"vu":{"pk":[-9.467268943786621,-10.68277359008789],"vu":[-20.523719787597656,-21.058277130126953]}}}}}

Note: For X1.CL≤1.3.7, IMPACT.CL≤1.1.7,BIGVOICE.CL≤0.9.7, the state is reset also for filtered out objects. So avoid alternating objects filter between calls, or you will miss some changes

Set

{ "set" : `object` }

Set values. object can be any subpart, only those will be changed.

For instance: {"set":{"settings":{"general":{"operate":false}}}} returns {"OK":"set"}

Commands for undo/redo

If the process has undo/redo, you can use those.

Undo

{ "undo" : `count` }

Undo last(s) count preset change

Redo

{ "redo" : `count` }

Redo last(s) count preset change

Commands for presets

If the process has presets, you can use those.

Getting information

The "status" object has an extra "preset_changed" boolean value.

There are also :

  • "presetinfo" object : contains the name, factory name, and dates of the onair preset.
  • "saved" object : contains the on air preset's saved content (without current changes)
  • "factory" object: contains the on air preset's factory preset
  • "presetlist" array of presetinfo object for all presets
  • "factorylist" array of string with factory preset names

Load

{ "load" : "`presetname`" }

Loads the preset with this name

Save

{ "save" : "`presetname`" }

Saves the preset. If NULL is given, save on air preset.

Delete

{ "delete" : "`presetname`" }

Deletes the preset. Can also be an array of preset names.

Factoryload

{ "factoryload" : "`presetname`" }

Creates a preset from factory and loads it.

Rename

{ "rename" : { "preset" : "`presetname`", "name": "`newname`" } }

Renames a preset.

Import

{ "import" : { "preset" : "`presetname`", "content": `presetcontent` } }

Imports a preset.

Export

{ "export" : "`presetname`" }

Exports a preset : get preset's content, so it can be imported later.

New

{ "new" : { "name": "`presetname`", "factory": "`presetname`" } }

Creates a new preset from a factory. Can use array for multiple.

Commands for extensions

Some process may have some extensions.

In this case, each extension provides a root object with its name, and then follow the same protocol.

NOTE: currently, undo/redo and presets does not work on extensions, you can only use basic commands (set,get,change).

Accessing JSON from HTTP server

When there is an HTTP server, you can access the JSON protocol in /json.

There are multiple ways to access a command and an object :

  • Using the parameters in get/post/put, where the parameter name is the command wget -O- --post-data 'load="Jazz"' http://localhost:8080/json
  • Using the body as direct JSON request echo '{"get":{"presetlist":null}}' | http POST localhost:8080/json
  • Using the path to construct a JSON request http localhost:8080/json/get/presetlist
  • To get all JSON get/set possibilities http localhost:8080/json/get

The possible commands are:

  • get or set with a full path, and value for set or null for get
  • load, factoryload or save with the preset name
  • delete with the preset name to delete .../json/delete/presetname
  • new with the factory preset name to create a new preset .../json/new/factoryname
  • rename with from preset name then to preset name .../json/rename/from/to
  • export with from preset name .../json/export/presetname
  • undo/redo with optional count .../json/undo/2

Here are some examples :

  • Set http://localhost:8080/json/set/preset/agc/attack/15 or http://localhost:8080/json?set={"preset":{"agc":{"attack":15}}}
  • Get http://localhost:8080/json/get/preset/agc or http://localhost:8080/json?get={"preset":{"agc":null}}