Streams

Use Streams to create named publisher and receiver connections for SRT or RTMP endpoints. Each record gives applications a stable connection identity and reusable media settings.

What it doesCreate a named media connection

Choose this whenEach publisher or receiver needs its own identity on an existing SRT or RTMP server.

Use another module whenUse SRT Servers or RTMP Servers to create the ingest endpoint itself.

1Choose publisher or receiver2Set the endpoint3Use the connection

POST /api/streams/create

Filter endpoints10 endpoints

Before you start

All methods require a valid x-access-token. Create the related SRT or RTMP server first and keep the server and stream identifiers consistent.

What you can do

create, update, getAll, getCount, and getById manage connection records.
start and stop control supported stream lifecycle actions.
getStreamInfo reads connection information.
setStreamInfo applies supported stream information.
remove deletes a stream record.

Example workflow

Create a publisher record for the intended SRT or RTMP server.
Assign its role, stream_id, host details, and required audio settings.
Give the generated connection details to the publisher.
Use getStreamInfo during setup and troubleshooting.

Common use cases

Issue a dedicated connection to each remote camera team.
Separate publisher and receiver identities on a shared ingest server.
Store audio-channel settings for repeatable contribution feeds.

Limits and troubleshooting

Duplicate or mismatched stream identifiers can prevent the expected connection. A stream record depends on its parent server and cannot make an unreachable publisher healthy. Do not expose credentials or unrestricted connection details outside the intended participant.

Next steps

Connect the publisher or receiver, then inspect the parent SRT or RTMP server's runtime statistics.

REST solution recipe

Register and operate a reusable stream source

Create the stream identity and connection settings once, start it when required, and read its current stream information for downstream automation.

Create the streamSave the reviewed source identity and connection contract.POST /api/streams/create
Start the sourceStart it before attaching downstream modules.POST /api/streams/start
Read stream informationUse current stream metadata in your control workflow.POST /api/streams/getStreamInfo

A successful create response confirms configuration, not media health. Start the resource, then verify its runtime statistics before sending production traffic.

POST

/api/streams/create

API token required

Create a managed stream identity above an SRT or RTMP transport resource. The stream stores its name, publisher or receiver role, stream id, optional host, linked entity, and optional audio metadata.

A vMix Script example is available when an operator workflow must provision the stream.

Request examples

Choose the preset for an SRT publisher, SRT receiver, RTMP publisher, or stream with a saved audio layout.

Common use cases

Name multiple publisher streams that share one SRT listener.
Keep a stable receiver identity for routed or pulled traffic.
Store channel names, layouts, or track meaning with the stream.

SRT publisher stream

Use this when one SRT listener hosts a named publisher stream that operators should treat as a first-class object.

SRT publisher stream

SRT receiver stream

Use this when a receiver-side or returned feed should keep its own stream identity and optional host binding.

SRT receiver stream

RTMP publisher stream

Use this when the backing transport entity is an RTMP server rather than an SRT listener.

RTMP publisher stream

Stream with saved audio layout

Use this when channel layout and naming should be stored with the stream row after inspection.

Stream with saved audio layout

curl --request POST \
  --url http://localhost/api/streams/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Commentary audio stream",
  "role_name": "publisher",
  "stream_id": "publisher/commentary/audio-main",
  "entity_id": "680400000000000000000001",
  "module_name": "MODULE_SRT_SERVERS",
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Commentary",
        "channel_layout": "mono",
        "channels": [
          {
            "id": "FC",
            "name": "Commentary"
          }
        ]
      }
    ]
  },
  "active": true
}'

Request body parameters

Identity

name

string

Dashboard label: Name.

Human-facing name of the saved stream row.

role_name

string

Dashboard label: Role.

Typical product values include publisher, receiver, pusher, and puller.

stream_id

string

Stable stream identifier stored above the backing transport entity.

host

string

Optional host binding used when the stream identity should stay tied to a concrete remote peer.

Transport link

entity_id

string

Identifier of the backing transport-side entity, for example an SRT server or RTMP server.

module_name

string

Module family behind the stream row. In practice this is most often MODULE_SRT_SERVERS or MODULE_RTMP_SERVERS.

Metadata

audio_settings

object

Optional saved audio layout with named tracks and channels.

Runtime

active

boolean

Dashboard label: Enable once created.

Controls whether the stream row should be active right after provisioning.

Create stream

Response

Identity

_id / id / name / role_name / stream_id / host

mixed

Identifiers and the saved stream identity fields.

Transport link

entity_id / entityModel / module_name

mixed

Reference back to the transport object that owns or serves the stream.

Metadata

stream_meta_data / audio_settings

mixed

Saved inspection output, codec notes, and optional channel mapping metadata.

Runtime

active / created / modified

mixed

Runtime flag and backend-managed timestamps.

Operation result

success

boolean

Successful stream model responses expose success: true as a virtual field.

Response: Create stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/getCount

API token required

POST

/api/streams/getAll

API token required

Returns the stream resources visible to the authenticated account.

Use this when the team needs one view of the active stream identities across SRT and RTMP-backed workflows, especially when publisher and receiver roles should stay easy to scan during operations.

Request body parameters

limit

integer

Optional page size for the listing query.

skip

integer

Optional offset for paginated listing.

sort

object

Optional sort descriptor. The dashboard store defaults to { created: 1 }.

filter

object

Optional filter object used for search and role/module filtering.

Get all streams

Response

array of stream objects

array

The backend returns a bare array of stream rows, not a wrapped object.

Response: Get all streams

JSON

[
  {
    "_id": "680600000000000000000001",
    "id": "680600000000000000000001",
    "name": "Main stage publisher",
    "role_name": "publisher",
    "host": "",
    "stream_id": "publisher/main-stage/srt-main",
    "entity_id": "680400000000000000000001",
    "entityModel": "ServerModel",
    "module_name": "MODULE_SRT_SERVERS",
    "stream_meta_data": {
      "codec_name": "h264",
      "fps": "30/1"
    },
    "audio_settings": {
      "streams": [
        {
          "id": 0,
          "name": "Track-0",
          "channel_layout": "stereo",
          "channels": [
            {
              "id": "FL",
              "name": "Left"
            },
            {
              "id": "FR",
              "name": "Right"
            }
          ]
        }
      ]
    },
    "created": "2026-03-24T08:45:00.000Z",
    "modified": "2026-03-24T08:45:00.000Z",
    "active": true,
    "success": true
  }
]

POST

/api/streams/getById

API token required

Loads one saved stream resource by id.

Use this before editing when you need the current stream identity, associated transport entity, or stored audio settings exactly as they were saved.

Request body parameters

string

Identifier of the stream row you want to load.

Get stream by id

Response

stream object

object

The backend returns the saved stream row with its transport link and any stored metadata.

Response: Get stream by id

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/update

API token required

Updates a saved stream resource.

In practice this is where teams rename a stream, adjust its role-facing metadata, attach or revise saved audio settings, or correct the stream id and host pairing after live inspection.

Request body parameters

string

Identifier of the stream row to update.

name / role_name / stream_id / host

mixed

Updated stream identity fields.

audio_settings

object

Optional replacement audio layout or saved channel naming data.

active

boolean

Current runtime-enabled flag after the update.

Update stream

curl --request POST \
  --url http://localhost/api/streams/update \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "module_name": "MODULE_SRT_SERVERS",
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Program",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "active": true
}'

Response

updated stream object

object

The backend returns the updated stream row.

Response: Update stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/setStreamInfo

API token required

DELETE

/api/streams/remove

API token required

POST

/api/streams/start

API token required

Starts the selected stream.

Use this when a saved stream identity should become active for a player or downstream workflow.

If this action is triggered from an operator workflow, the example set below includes a vMix Script tab as well.

Request body parameters

string

Identifier of the stream row to start.

Start stream

Response

started stream object

object

The backend returns the stream row after the start action is accepted.

Response: Start stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/stop

API token required

Stops the selected stream.

Use this to take the stream offline without deleting the saved metadata and identity around it.

If this action is triggered from an operator workflow, the example set below includes a vMix Script tab as well.

Request body parameters

string

Identifier of the stream row to stop.

Stop stream

Response

stopped stream object

object

The backend returns the stream row after the stop action is accepted.

Response: Stop stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/getStreamInfo

API token required

Runs a stream inspection against a live URL and returns codec, audio, and timing details for the real upstream feed.

Use it when the team needs facts from the live signal before deciding what should be saved with the stream or passed on to another workflow.

Request body parameters

stream_url

string

Live input URL that should be inspected with FFprobe.

Get stream info

Response

streams[]

array

FFprobe-style stream descriptors for video, audio, or data tracks discovered on the live input.

streams[].codec_name / codec_type

mixed

Codec identity for each discovered track.

streams[].width / height / avg_frame_rate

mixed

Representative video properties when the input includes a video track.

streams[].sample_rate / channels / channel_layout

mixed

Representative audio properties when the input includes audio tracks.

format

object

Top-level FFprobe format object for the inspected URL.

Response: Get stream info

JSON

{
  "streams": [
    {
      "index": 0,
      "codec_name": "h264",
      "codec_type": "video",
      "width": 1920,
      "height": 1080,
      "avg_frame_rate": "30/1",
      "pix_fmt": "yuv420p"
    },
    {
      "index": 1,
      "codec_name": "aac",
      "codec_type": "audio",
      "sample_rate": "48000",
      "channels": 2,
      "channel_layout": "stereo"
    }
  ],
  "format": {
    "filename": "srt://127.0.0.1:1936",
    "nb_streams": 2,
    "format_name": "mpegts",
    "start_time": "0.000000",
    "probe_score": 100
  }
}

Back toRestreams Next toRecordings