Screenberry JSON API

The Screenberry JSON API allows external applications to communicate with the server to:

• Retrieve and set parameter values

• Fetch nodes with parameters and links

• Access Media Players, playlists, and Media Library items

• Modify playlist, timeline, and matrix items

• Control playback

All requests are sent as JSON objects. All responses, when applicable, are returned as JSON objects serialized as strings.

Listener Nodes

The following nodes support JSON API communication:

• HTTP Listener

• TCP Listener

• Serial Input

• UDP Listener

• OSC Listener

The Screenberry API parameter is enabled by default on listener nodes. You can toggle it in the node’s settings panel (Screenberry API: Enabled/Disabled) if needed.

Each JSON request must include a "cmd" field with the command name. Additional fields depend on the command used.

HTTP Listener

• Supports GET and POST requests.

• Returns a JSON response string.

Example — Get Media Players list:

{
    "cmd": "GetMediaPlayers"
}

If the server is local (127.0.0.1) and the HTTP Listener port is 8080:

GET request:

http://127.0.0.1:8080/request?command={"cmd":"GetMediaPlayers"}

POST request:
Send to /command with the JSON object in the request body:

http://127.0.0.1:8080/command

TCP Listener

• Accepts JSON messages separated by \r\n (carriage return + newline).

• Only \r\n is recognized as a delimiter; \n alone is not supported.

• Responses include:

  • Command ID

  • Original request parameters
    This allows the client to correctly match responses when multiple requests are sent in the same stream.

Serial Input

• Used for communication with devices over a serial port.

• Works similarly to the TCP Listener.

• Messages must be JSON objects separated by \r\n.

UDP Listener

• Receives JSON objects via UDP.

• To receive a reply, the request must include "replyIp" and "replyPort".

• Responses include identifiers (command ID and echoed parameters) so clients can match them to the correct request.

Example — Get Media Players list with reply address:

{
  "cmd": "GetMediaPlayers",
  "replyIp": "127.0.0.1",
  "replyPort": 8081
}

OSC Listener

• Works similarly to the UDP Listener.

• The JSON object must be provided as the first string parameter of the OSC message.

• If additional OSC parameters are included, they are ignored. Order is strict: JSON must be the first parameter.

Listener Quick Reference

Node Graph Commands

GetParameter

Retrieves the value of a node parameter in the Node Graph.

Parameters:

• node — name of the node. Can be:

  • Full path: "Root/Media Player" or "Root/Group/Media Player"

  • Partial path (without "Root/"): "Media Player" or "Group/Media Player"
    (This rule applies to all commands that use node name fields.)

• parameter — name of the parameter. Use only the parameter name, even if it belongs to a group.

Request:

{
    "cmd": "GetParameter",
    "node": "Audio Out",
    "parameter": "Volume"
}

HTTP Response:

{ "value": 1.0 }

TCP/UDP Response:

{
  "cmd": "ParameterValue",
  "node": "Audio Out",
  "parameter": "Volume",
  "value": 1.0
}

Media Player Commands

GetMediaPlayers

Retrieves the list of Media Players.

Request:

{ "cmd": "GetMediaPlayers" }

HTTP Response:

{ "mediaPlayers": ["Media Player", "Media Player 2"] }

TCP/UDP Response:

{
  "cmd": "MediaPlayers",
  "mediaPlayers": ["Media Player", "Media Player 2"]
}

GetPlaylists

Retrieves the list of playlists for a Media Player.

Parameters:

• mediaPlayer — name of the Media Player.

Request:

{
  "cmd": "GetPlaylists",
  "mediaPlayer": "Media Player 1"
}

HTTP Response:

{
  "playlists": [
    { "type": "Playlist", "name": "Playlist", "id": 2 },
    { "type": "Timeline", "name": "Timeline1", "id": 3 },
    { "type": "Matrix", "name": "Matrix1", "id": 4 },
    { "type": "Playlist", "name": "folder1/subPlaylist", "id": 6 }
  ]
}

TCP/UDP Response:

Includes additional fields "cmd" and "mediaPlayer".

{
  "cmd": "Playlists",
  "mediaPlayer": "Media Player 1",
  "playlists": [...]
}

GetMediaPlayerStatus

Retrieves the current status of a Media Player.

Parameters:

• mediaPlayer — name of the Media Player.

Request:

{
  "cmd": "GetMediaPlayerStatus",
  "mediaPlayer": "Media Player 1"
}

HTTP Responses:

• Stopped playlist:

{ "playlistType": "Playlist", "playlistName": "Show", "state": "Stopped" }

• Playlist playing:

{
  "playlistType": "Playlist",
  "playlistName": "Show",
  "state": "Playing",
  "itemIndex": 0,
  "itemName": "You",
  "itemId": 1,
  "position": 177.924
}

• Paused timeline:

{
  "playlistType": "Timeline",
  "playlistName": "Timeline1",
  "state": "Paused",
  "position": 47.0
}

• Matrix:

{
  "playlistType": "Matrix",
  "playlistName": "Matrix1",
  "rows": [
    { "rowName": "Output 1", "state": "Paused", "itemIndex": 0, "itemName": "You", "itemId": 1, "position": 2.627 },
    { "rowName": "Output 2", "state": "Playing", "itemIndex": 1, "itemName": "clip2", "itemId": 2, "position": 3.837 },
    { "rowName": "Output 3", "state": "Stopped" }
  ]
}

TCP/UDP Response:
Same as HTTP, but includes "cmd" and "mediaPlayer".

{
  "cmd": "MediaPlayerStatus",
  "mediaPlayer": "Media Player 1",
  ...
}

GetPlaylistItems

Retrieves items from a playlist, timeline, or matrix.

Note:

• Playlists can be addressed by playlistId or playlistName.

• Playlist IDs are unique within a Media Player.

• Item IDs are unique only within a single playlist.

Request (by playlistId):

{
  "cmd": "GetPlaylistItems",
  "mediaPlayer": "MediaPlayer1",
  "playlistId": 2
}

Request (by playlistName):

{
  "cmd": "GetPlaylistItems",
  "mediaPlayer": "MediaPlayer1",
  "playlistName": "Show1"
}

HTTP Responses:

• Playlist:

{
  "playlistType": "Playlist",
  "playlistName": "Playlist",
  "playlistId": 3,
  "items": [
    { "id": 0, "path": "TestMedia/sequenceRva.rva", "duration": 7.2 }
  ]
}

• Timeline:

{
  "playlistType": "Timeline",
  "playlistName": "Timeline1",
  "playlistId": 4,
  "tracks": [
    {
      "name": "Track 1",
      "items": [
        { "id": 0, "path": "TestMedia/sequenceRva.rva", "position": 1.0, "duration": 10.0 }
      ]
    }
  ]
}

• Matrix:

{
  "playlistType": "Matrix",
  "playlistName": "Matrix1",
  "playlistId": 5,
  "items": [
    { "id": 0, "path": "TestMedia/sequenceRva.rva", "duration": 7.2, "column": 0, "row": 0 },
    { "id": 1, "path": "TestMedia/sequenceRva.rva", "duration": 7.2, "column": 1, "row": 1 }
  ]
}

Playback Control Commands

• Play — Starts or resumes playback.

• Pause — Pauses playback.

• Stop — Stops playback.

• PlayPlaylistItem — Plays a specific item in a Playlist.

• PlayTimeline — Plays a Timeline from a defined position (in seconds).

• PlayMatrixItem — Plays a specific item in a Matrix by row/column.

• PlayMatrixColumn — Plays an entire Matrix column.

All commands use the following pattern:

Request (Play example):

{
  "cmd": "Play",
  "mediaPlayer": "Media Player 1"
}

HTTP Response:

{ "cmd": "Success" }

TCP/UDP Response:
Includes the original request in "request".

{
  "cmd": "PlayPlaylistItem", "mediaPlayer": "Media Player 1",
  "playlistId": 2
  "itemId": 1
}

PlayPlaylistItem — Plays item in Playlist

Request:

{
  "cmd": "PlayPlaylistItem",
  "mediaPlayer": "Media Player 1",
  "playlistId": 2,
  "itemId": 1
}

HTTP Response:

{
  "cmd": "Success"
}

TCP/UDP Response (echoes original request):

{
  "cmd": "Success",
  "request": { 
    "cmd": "Play",
    "mediaPlayer": "Media Player 1", 
    "playlistId": 2, 
    "itemId": 1 
}
}

Note:

• Playlist can be addressed using playlistId or playlistName.

• Item can be addressed using itemId or itemIndex.

• If both itemId and itemIndex are missing, the playlist starts from the first item.

PlayTimeline — Plays Timeline from selected position (seconds)

Request:

{
  "cmd": "PlayTimeline",
  "mediaPlayer": "Media Player 1",
  "playlistId": 2,
  "position": 2.5
}

HTTP Response:

{
  "cmd": "Success"
}

TCP/UDP Response (echoes original request):

{
  "cmd": "Success",
  "request": { 
    "cmd": "PlayTimeline", 
    "mediaPlayer": "Media Player 1", 
    "playlistId": 2, 
    "position": 2.5 
}
}

Note:

• Playlist can be addressed using playlistId or playlistName.

• position is optional; start = beginning if position is 0 or missing.

PlayMatrixItem — Plays item in Matrix (by row/column)

Request:

{
  "cmd": "PlayMatrixItem",
  "mediaPlayer": "Media Player 1",
  "playlistId": 2,
  "row": 3,
  "column": 1
}

HTTP Response:

{
  "cmd": "Success"
}

TCP/UDP Response (echoes original request):

{
  "cmd": "Success",
  "request": { 
    "cmd": "PlayMatrixItem", 
    "mediaPlayer": "Media Player 1", 
    "playlistId": 2, 
    "row": 3,
    "column": 1 
}
}

Note: * Playlist can be addressed using playlistId or playlistName.

PlayMatrixColumn — Plays column in Matrix

Request:

{
  "cmd": "PlayPlaylistItem",
  "mediaPlayer": "Media Player 1",
  "playlistId": 2,
  "column": 1
}

HTTP Response:

{
  "cmd": "Success"
}

TCP/UDP Response (echoes original request):

{
  "cmd": "Success",
  "request": { 
    "cmd": "PlayMatrixColumn", 
    "mediaPlayer": "Media Player 1", 
    "playlistId": 2, 
    "column": 1 
}
}

Note: * Playlist can be addressed using playlistId or playlistName.

Editing Playlists

• CreatePlaylist — Creates a new Playlist, Timeline, or Matrix.

• AddPlaylistItem — Inserts an item into a Playlist.

• AddTimelineItem — Adds an item to a Timeline track.

• AddMatrixItem — Adds an item to a Matrix grid.

CreatePlaylist

Creates a new Playlist, Timeline, or Matrix inside a Media Player.

Request:

{
  "cmd": "CreatePlaylist",
  "mediaPlayer": "Media Player 1",
  "name": "New Playlist",
  "playlistType": "Timeline",
  "framerate": 30
}

Note:

• playlistType must be "Playlist", "Timeline", or "Matrix". (Case sensitive.)

• framerate is optional and applies only to Timelines. The default value is 30.

AddPlaylistItem

Inserts an item into a playlist. The item must be uploaded to the Media Library beforehand.

Request:

{
  "cmd": "AddPlaylistItem",
  "mediaPlayer": "Media Player 1",
  "playlistId": 2,
  "index": 2,
  "itemPath": "folder/Video.rva"
}

Note:

• A playlist can be referenced by playlistId or playlistName.

• index (optional): defines where the item is placed in the playlist.

  • Use -1 to insert at the end.

  • If omitted, the item is inserted at the end.

AddTimelineItem

Adds an item into a timeline track. The item must be uploaded to the Media Library beforehand.

Request:

{
  "cmd": "AddTimelineItem",
  "mediaPlayer": "Media Player 1",
  "playlistId": 2,
  "track": 0,
  "position": 2.5,
  "itemPath": "folder/Video.rva"
}

Note:

• A timeline can be referenced by playlistId or playlistName.

• track (optional): index of the track where the item is inserted. If the track does not exist, it is created. If omitted, the item is placed in the first track.

• position (optional): time in seconds from the start of the timeline. If omitted, the item is placed after the last item in the track.

AddMatrixItem

Adds an item into a matrix grid. The item must be uploaded to the Media Library beforehand.

Request:

{
  "cmd": "AddMatrixItem",
  "mediaPlayer": "Media Player 1",
  "playlistId": 2,
  "column": 2,
  "row": 2,
  "itemPath": "folder/Video.rva"
}

Note:

• A matrix can be referenced by playlistId or playlistName.

• row and column (optional): define the grid position.

  • If omitted, the item is placed at the end of the first row.

Upload Manager Commands

GetUploadingItems

Retrieves the status of current uploads.

Request:

{ "cmd": "GetUploadingItems" }

HTTP Response:

{
    "items": [
        {
            "path": "Media/Untitled2.rva",
            "progress": 1,
            "status": "done"
        },
        {
            "path": "Media/2024-02-03 22-50-50 (1).rva",
            "progress": 0.010,
            "status": "converting"
        }
    ]
}