Screenberry logo
Skip to Content
Integration & ControlScreenberry JSON API

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

ListenerProtocolMessage FormatDelimiter / RulesResponse BehaviorSpecial Notes
HTTP ListenerHTTP (GET / POST)JSON objectN/AReturns JSON string in responseFor GET requests, JSON must be URL-encoded. POST accepts JSON in body.
TCP ListenerTCP streamJSON objectMessages separated by \r\n (required)Includes command ID + echoed request parametersSupports multiple requests/responses in the same stream.
Serial InputSerial (COM port)JSON objectMessages separated by \r\n (required)Same as TCP ListenerUsed for direct device communication.
UDP ListenerUDP datagramJSON objectEntire JSON object in one datagramResponse includes command ID + echoed request; requires "replyIp" + "replyPort"Lightweight but requires reply address fields in request.
OSC ListenerOSCJSON object inside OSC messageJSON must be the first string parameterSame as UDP ListenerAdditional OSC parameters are ignored. Order strict.

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 }

SetParameter

Sets the value of a node parameter.

{ "cmd": "SetParameter", "node": "Slider", "parameter": "Value", "value": 0.75 }

AddNode

Adds a node to the Node Graph.

{ "cmd": "AddNode", "nodePath": "My Media Player Node", "nodeType": "Media Player", "position": [11.2, 12.5] }

The optional position field contains the node coordinates. If it is omitted, the node is placed to the right of all existing nodes.

RemoveNode

Removes a node from the Node Graph.

{ "cmd": "RemoveNode", "node": "Slider" }

Creates a link between two node parameters.

{ "cmd": "Link", "sourceNode": "Float", "sourceParameter": "Out", "sinkNode": "Slider", "sinkParameter": "External Control" }

Removes a link between two node parameters.

{ "cmd": "Unlink", "sourceNode": "Float", "sourceParameter": "Out", "sinkNode": "Slider", "sinkParameter": "External Control" }

GetNodeGraph

Returns the nodes and links in the Node Graph.

{ "cmd": "GetNodeGraph" }

HTTP Response:

{ "nodes": [ { "path": "Root/HTTP Listener", "type": "HTTP Listener" }, { "path": "Root/Solid Color", "type": "Solid Color" }, { "path": "Root/Canvas", "type": "Canvas" } ], "links": [ { "sourceNode": "Root/Solid Color", "sourceParam": "Image", "sinkNode": "Root/Canvas", "sinkParam": "Background Image" } ] }

GetNodeParameters

Returns the parameters of a node, including each parameter’s direction, type, pin visibility, and value where applicable.

{ "cmd": "GetNodeParameters", "node": "Media Player" }

HTTP Response (abbreviated):

{ "params": [ { "name": "Enabled", "direction": "input", "type": "Bool", "pin": true, "value": true }, { "name": "Image Size", "direction": "input", "type": "IVec2", "pin": false, "value": [1920, 1080] } ] }

GetNodeTypes

Returns all node types that can be added to the Node Graph, grouped by category.

{ "cmd": "GetNodeTypes" }

HTTP Response (abbreviated):

{ "types": [ { "type": "3D Camera", "category": "3D" }, { "type": "3D Combine", "category": "3D" }, { "type": "3D Model Export", "category": "3D" }, { "type": "3D Model File", "category": "3D" } ] }

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": [ { "type": "Playlist", "name": "Playlist", "id": 2 }, { "type": "Timeline", "name": "Timeline1", "id": 3 }, { "type": "Matrix", "name": "Matrix1", "id": 4 } ] }

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", "playlistType": "Playlist", "playlistName": "Show", "state": "Playing", "itemIndex": 0, "itemName": "You", "itemId": 1, "position": 177.924 }

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.

  • All duration values are floating-point numbers of seconds.

  • Set the optional showAllFields field to true to include fields whose values have not been modified.

Request (by playlistId):

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

Request (by playlistName):

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

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": "Success", "request": { "cmd": "Play", "mediaPlayer": "Media Player 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": "PlayPlaylistItem", "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. If it is 0 or omitted, playback starts at the beginning of the timeline.

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": "PlayMatrixColumn", "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.

PlayMatrixRow

Plays a row in the currently selected Matrix.

{ "cmd": "PlayMatrixRow", "mediaPlayer": "Media Player 1", "row": 1 }

PauseMatrixRow

Pauses a row in the currently selected Matrix.

{ "cmd": "PauseMatrixRow", "mediaPlayer": "Media Player 1", "row": 1 }

StopMatrixRow

Stops a row in the currently selected Matrix.

{ "cmd": "StopMatrixRow", "mediaPlayer": "Media Player 1", "row": 1 }

The Matrix row commands apply only when the current playlist is a Matrix.

Seek

Moves playback to a specified position in the current Playlist or Timeline.

{ "cmd": "Seek", "mediaPlayer": "Media Player 1", "position": 2.0 }

position is a time in seconds. This command applies only to Playlists and Timelines.

SetVolume

Sets the Media Player volume.

{ "cmd": "SetVolume", "mediaPlayer": "Media Player 1", "volume": 0.75 }

volume is a floating-point value. Use 0.0 for silence and 1.0 for the original volume level.

SeekMatrixItem

Moves playback to a specified position in the item playing in a Matrix row.

{ "cmd": "SeekMatrixItem", "mediaPlayer": "Media Player 1", "row": 1, "position": 2.0 }

row identifies the Matrix row. position is the playback position in seconds. This command applies only when the current playlist is a Matrix.

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.

ReplaceItem

Replaces an item in a Playlist, Timeline, or Matrix.

{ "cmd": "ReplaceItem", "mediaPlayer": "Media Player 1", "playlistName": "Playlist", "itemId": 0, "itemPath": "Media/Uploaded/111.rva", "updateDuration": true, "moveRightItems": true }

The playlist can be addressed using playlistId or playlistName. Use the fields supported by the playlist type to identify the item:

  • Playlist: itemId or itemIndex.

  • Timeline: itemId only.

  • Matrix: itemId, or both itemRowIndex and itemColumnIndex. Matrix row and column indices start at 0.

For Timeline items, set the optional updateDuration field to true to update the item duration to match the new Media Library item. If updateDuration is enabled, set moveRightItems to true to move subsequent items according to the duration change.

ModifyTimelineItem

Modifies an item in a Timeline. The playlist can be addressed using playlistId or playlistName; the item must be addressed using itemId. All modification fields are optional.

{ "cmd": "ModifyTimelineItem", "mediaPlayer": "Media Player 1", "playlistName": "Timeline", "itemId": 0, "duration": 100.0, "position": 3.0, "fadeIn": 0.2, "fadeOut": 0.2, "opacity": 0.85, "volume": 0.9, "muted": false, "transformations": { "mode": "Custom", "crop": [1, 10, 12, 15], "anchor": [10, 20], "position": [30, 40], "scale": [0.9, 0.8], "rotate": 90 }, "disableVideo": true, "multiplyByAlpha": true, "freezeFrameEnable": false, "freezeFramePosition": 0.0, "audioFiles": ["en.wav"], "subtitles": "subs.srt" }

The transformation crop values are ordered left, top, right, bottom. anchor and position contain horizontal and vertical coordinates; scale contains horizontal and vertical scale factors; and rotate is measured counterclockwise in degrees. audioFiles and subtitles apply only to Media items. Use aux for AUX items.

ModifyPlaylistItem

Modifies an item in a Playlist. The playlist can be addressed using playlistId or playlistName; the item can be addressed using itemId or itemIndex. All modification fields are optional.

{ "cmd": "ModifyPlaylistItem", "mediaPlayer": "Media Player 1", "playlistName": "Playlist", "itemId": 0, "volume": 0.9, "muted": false, "loop": true, "pauseOnStart": false, "pauseOnEnd": false, "inPoint": 1.0, "outPoint": 6.0, "fadeIn": 0.25, "sendTimecodeEnable": true, "sendTimecodeOffset": 0.0, "startOnTimecodeEnable": false, "startOnTimecodeValue": 0.0 }

Media and AUX items also support volume, muted, transformations, disableVideo, multiplyByAlpha, freezeFrameEnable, and freezeFramePosition. Media items support audioFiles and subtitles; AUX items support aux.

ModifyMatrixItem

Modifies an item in a Matrix. The playlist can be addressed using playlistId or playlistName. The item can be addressed using itemId, or by providing both itemRowIndex and itemColumnIndex. Matrix row and column indices start at 0. All modification fields are optional.

{ "cmd": "ModifyMatrixItem", "mediaPlayer": "Media Player 1", "playlistName": "Matrix", "itemId": 0, "column": 0, "row": 0, "volume": 0.9, "muted": false, "loop": true, "inPoint": 1.0, "outPoint": 6.0, "fadeIn": 0.25 }

Matrix items support the same Media- and AUX-specific fields as Playlist items.

RemovePlaylistItem

Removes an item from a Playlist. The item can be addressed using itemIndex or itemId.

{ "cmd": "RemovePlaylistItem", "mediaPlayer": "Media Player", "playlistName": "Playlist1", "itemIndex": 0 }

RemoveTimelineItem

Removes an item from a Timeline. The item must be addressed using itemId.

{ "cmd": "RemoveTimelineItem", "mediaPlayer": "Media Player", "playlistName": "Timeline1", "itemId": 0 }

RemoveMatrixItem

Removes an item from a Matrix. The item can be addressed using itemId or its row and column indices.

{ "cmd": "RemoveMatrixItem", "mediaPlayer": "Media Player", "playlistName": "Matrix1", "itemId": 0 }

Timeline Marker Commands

GetTimelineMarkers

Returns the markers in a Timeline.

{ "cmd": "GetTimelineMarkers", "mediaPlayer": "Media Player", "playlistName": "Timeline1" }

HTTP Response:

{ "markers": [ { "name": "Marker 1", "position": 5.866, "type": "Control", "id": 1, "enabled": true }, { "name": "Jump 1", "position": 7.666, "type": "Jump", "id": 2, "enabled": true, "jumpTime": 2.1, "jumpType": "time" } ] }

AddTimelineMarker

Adds a marker to a Timeline. The playlist can be addressed using playlistId or playlistName, and the marker name must be unique.

{ "cmd": "AddTimelineMarker", "mediaPlayer": "Media Player", "playlistName": "Timeline1", "type": "Marker", "position": 2.5, "name": "My Marker" }

The case-sensitive marker types are Marker, Pause, Jump, and TimecodeTrigger. A Jump marker also requires jumpType. Use jumpTime when jumpType is time, or jumpMarkerId when jumpType is marker.

RemoveTimelineMarker

Removes a marker from a Timeline.

{ "cmd": "RemoveTimelineMarker", "mediaPlayer": "Media Player", "playlistName": "Timeline1", "markerId": 4 }

ModifyTimelineMarker

Modifies a marker in a Timeline. The playlist can be addressed using playlistId or playlistName, and the marker is identified by markerId.

{ "cmd": "ModifyTimelineMarker", "mediaPlayer": "Media Player", "playlistName": "Timeline1", "markerId": 4, "name": "Updated Marker", "position": 3.5, "enabled": true }

The name, position, and enabled fields are optional. Jump markers can also be updated using jumpType together with jumpTime or jumpMarkerId.

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" } ] }

File System Commands

GetMediaFolder

Returns the contents of a directory.

{ "cmd": "GetMediaFolder", "path": "Media" }

path is optional. If omitted, the current project directory is returned. It can be relative to the current project directory or an absolute path, but paths outside the configured work folders are not permitted.

HTTP Response:

{ "entries": [ { "path": "Media/someMedia.rva", "type": "Content", "size": 35784144 }, { "path": "Media/Synced", "type": "Folder" } ] }

GetWorkFolders

Returns the configured Screenberry work folders.

{ "cmd": "GetWorkFolders" }

HTTP Response:

{ "workFolders": [ "/Users/username/Documents/Screenberry" ] }

GetMediaItem

Returns information about an RVA media item.

{ "cmd": "GetMediaItem", "itemPath": "Media/someMedia.rva" }

itemPath is the path to the RVA media file.

HTTP Response:

{ "mediaItem": { "path": "Media/someMedia.rva", "fps": 60.0, "duration": 17.116, "width": 1920, "height": 1080, "size": 35784144, "date": 1763038182, "audioFiles": ["2025-08-06 14-56-07 6.wav"] } }

duration is a floating-point number of seconds.

General Commands

The following commands control the Screenberry Server application or its computer. Use them carefully.

Exit

Closes the Screenberry Server application.

{ "cmd": "Exit" }

Restart

Restarts the Screenberry Server application.

{ "cmd": "Restart" }

Shutdown

Shuts down the Screenberry Server computer.

{ "cmd": "Shutdown" }

Reboot

Reboots the Screenberry Server computer.

{ "cmd": "Reboot" }

Last updated on