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 the delimiter configured on the TCP Listener. The default is \r\n (carriage return followed by line feed).
Ends each response with the same configured delimiter. Configure the client to use it for both sending requests and reading responses.
Includes the command ID and original request parameters in responses so the client can match responses to requests sent in the same stream.

Note: Use the default \r\n delimiter. Delimiters of other lengths can cause parsing errors, especially when several requests arrive together.

Serial Input

Receives JSON commands over a serial port.
By default, terminate each JSON request with \r (carriage return).
Receive-message separation is configurable: by a separator, by start and end symbols, or by a timeout. Configure the sending device to match the selected mode.
JSON responses end with \r. Do not wait for \r\n when reading a response.

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

Send the OSC message to the address /jsonApi.
Supply the serialized JSON object as the first OSC argument, with the OSC string type. Additional arguments are ignored.
To request a reply, include "replyIp" and "replyPort" inside the JSON object.

Example — Get Media Players list with a reply address:

OSC address: /jsonApi

OSC type tag: ,s

First argument (string):


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

Send the OSC packet to the IP address and listening port configured for the OSC Listener. The reply address in this example is suitable only when the client runs on the server computer; for a remote client, supply that client’s reachable IP address and reply port.

Listener Quick Reference

Listener	Protocol	Message Format	Delimiter / Rules	Response Behavior	Special Notes
HTTP Listener	HTTP (GET / POST)	JSON object	N/A	Returns JSON string in response	For GET requests, JSON must be URL-encoded. POST accepts JSON in body.
TCP Listener	TCP stream	JSON object	Configured delimiter; default `\r\n`. Use the default; delimiters of other lengths can cause parsing errors.	Includes command ID and echoed request parameters; ends with the configured delimiter	Supports multiple requests/responses in the same stream.
Serial Input	Serial port	JSON object	Configurable receive-message separation; default `\r`	JSON responses end with `\r`	Match the sending device to the configured receive mode.
UDP Listener	UDP datagram	JSON object	Entire JSON object in one datagram	Response includes command ID + echoed request; requires `"replyIp"` + `"replyPort"`	Lightweight but requires reply address fields in request.
OSC Listener	OSC	Serialized JSON in the first argument, with OSC string type	OSC address must be `/jsonApi`	Requires `"replyIp"` and `"replyPort"` in the JSON request for a reply	Additional arguments are ignored.

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

Link

Creates a link between two node parameters.


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

Unlink

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: Address the playlist using playlistId or playlistName. An item selector is required: provide itemId or the zero-based itemIndex. To play the first item, use "itemIndex": 0. If both selectors are omitted, the command fails.

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 to a matrix grid. The media must already be uploaded to the Media Library.

Important: If the destination cell is occupied, AddMatrixItem removes the existing matrix item before inserting the new one. Its item-specific configuration is removed with it. This is a remove-and-add operation; use ReplaceItem when you intend to replace the media of an addressed existing item.

Request:


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

Note: Address the matrix using playlistId or playlistName. Supply both row and column as nonnegative, zero-based indices, or omit both. If both are omitted, the item is appended to the first row (row 0). Supplying only one coordinate is invalid.

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": "Marker",
      "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" }