SRT servers
The SRT servers section covers the API endpoints used to provision and operate long-lived SRT ingest endpoints in Callaba Engine. This is the layer you use when an encoder, OBS, or an upstream transport should connect directly to a managed SRT listener.
Compared with SRT routes, an SRT server is the stable ingest boundary itself. The create and update calls do more than assign ports: they also shape latency, buffering, optional passphrase protection, publisher and player prefixes, routing behavior, and optional statistics callbacks.
The operational methods complete that lifecycle. Use start and stop to control the runtime process, getActiveStreams and getEventLogBySRTPort to inspect live connectivity, and /:serverPort/getStatisticHistory when you need the raw in-memory statistics history behind a given server port.
If your team drives these server actions from an operator workflow, the preset examples below also include ready-to-adapt vMix Script tabs alongside the usual API snippets.
See live SRT stats as a moving chart
This demo shows the kind of live statistics you can watch during a real contribution: bitrate, buffer delay, packet flow, receive capacity, and active streams. It is connected to the public demo endpoint at demo.callaba.io and updates from the same live event stream used by the product.
Examples by preset
The SRT server create flow naturally breaks into a few preset families. In practice, the most useful presets are a standalone listener with no routing, a listener that participates in PUBLIC_IP routing, a listener that participates in CALLABA routing, and a small set of security or monitoring add-ons such as passphrase protection, statistics callbacks, or IP-based access control.
We use that preset structure below because it is easier to copy from real operating scenarios than from one oversized catch-all payload.
No routing
{
"server_name": "Standalone ingest",
"server_type": "SERVER_TYPE_SRT",
"server_port": 1935,
"server_receiver_port": 1936,
"server_latency": 200,
"server_maxbw": -1,
"server_timeout": 10,
"server_rcvbuf": 48234496,
"server_active": true,
"routing": "DISABLED",
"routing_hosts": []
}PUBLIC_IP routing
{
"server_name": "Public edge ingest",
"server_type": "SERVER_TYPE_SRT",
"server_port": 1935,
"server_receiver_port": 1936,
"server_latency": 200,
"server_maxbw": -1,
"server_timeout": 10,
"server_rcvbuf": 48234496,
"server_active": true,
"routing": "PUBLIC_IP",
"routing_type": "PUSH",
"routing_hosts": [
{
"routing_host": "203.0.113.50",
"routing_port": 1935
}
]
}CALLABA routing
{
"server_name": "Callaba routed ingest",
"server_type": "SERVER_TYPE_SRT",
"server_port": 1935,
"server_receiver_port": 1936,
"server_latency": 200,
"server_maxbw": -1,
"server_timeout": 10,
"server_rcvbuf": 48234496,
"server_active": true,
"routing": "CALLABA",
"routing_type": "PUSH",
"routing_hosts": [
{
"routing_host": "ingest.callaba.cloud",
"routing_port": 1935,
"routing_server_name": "callaba-route-primary"
}
]
}Security and monitoring add-ons
{
"server_name": "Protected ingest",
"server_type": "SERVER_TYPE_SRT",
"server_port": 1935,
"server_receiver_port": 1936,
"server_latency": 200,
"server_maxbw": -1,
"server_timeout": 10,
"server_rcvbuf": 48234496,
"server_active": true,
"passphrase": "0123456789abcdef",
"stats_host": "https://monitoring.example.com/api/srt-stats",
"stats_interval": 2,
"stream_control_type": "CONTROL_ACCESS_IP_ADDRESS",
"access_settings": [
{
"host": "203.0.113.44",
"role_name": "publisher"
},
{
"host": "203.0.113.45",
"role_name": "receiver"
}
]
}Live SRT statistics
When an SRT server is already running, the next question is usually simple: is the stream healthy right now? This live statistics layer answers that without making you jump between logs, history, and control actions.
Use it when you want to watch bitrate, estimated bandwidth, round-trip time, and active streams while a contribution is live. It is especially useful during setup, QA, operator handoff, and incident response.
The embedded demo below connects to the public statistics stream and draws a moving chart from real websocket updates, so you can immediately see what kind of live signal the product exposes.
See live SRT stats as a moving chart
This demo shows the kind of live statistics you can watch during a real contribution: bitrate, buffer delay, packet flow, receive capacity, and active streams. It is connected to the public demo endpoint at demo.callaba.io and updates from the same live event stream used by the product.
What this live layer is good for
- Use live statistics for: watching stream health, spotting bitrate drops, checking RTT changes, and confirming that a stream is still active
- Use HTTP endpoints for: provisioning servers, reading event history, and pulling statistics history snapshots later
Implementation notes
- Path:
/ws-api - Main live events:
MODULE_SRT_SERVERS_STATSandMODULE_SRT_SERVERS_ACTIVE_STREAMS - Update pattern: active-stream ids are broadcast roughly every 3 seconds
- Practical filtering: clients usually group messages by
port,role, andid
Workflow examples
These scenarios help frame why an SRT server exists in a production design, not just what the create payload looks like.
Use an SRT server as the stable ingest boundary for external publishers
Create an SRT server when remote encoders, field units, or partner systems should target one controlled ingest endpoint that stays stable over time.
- Module chain:
Publisher / OBS / encoder->MODULE_SRT_SERVERS - Why it helps: ports, passphrase, publisher/player prefixes, and latency policy live in one server object instead of being spread across downstream jobs.
- Operational fit: good when the ingest boundary should survive changes or restarts in the downstream pipeline.
Use an SRT server in front of routing or restreaming
Use an SRT server when the ingest side belongs to one team, but downstream routing or restreaming may change independently later.
- Module chain:
MODULE_SRT_SERVERS->MODULE_SRT_ROUTERSorMODULE_RESTREAM - Why it helps: the ingest side stays fixed while route or restream jobs can be recreated, redirected, or restarted later.
- Typical fit: recurring contribution feeds, backup routing, or social distribution that changes more often than the ingest source.
Use an SRT server when monitoring and event history matter
SRT servers are also the better fit when your team needs live operational visibility around the ingest point itself.
- Useful endpoints:
getActiveStreams,getEventLogBySRTPort, and/:serverPort/getStatisticHistory - Why it helps: you can separate provisioning from runtime observation and debug connection behavior at the server boundary.
- Good fit for: support workflows, QA environments, managed events, and any setup where the ingest endpoint is a first-class operational object.
Creates a new SRT server resource in Callaba Engine.
The current Swagger definition exposes this method as POST /api/srt-servers/create with an application/json request body called SRT server parameters. The request example defines the API field names and values, while the field descriptions below are aligned with the real dashboard wording and the backend validation rules.
This method is broader than a minimal listener setup. Alongside the basic ports and latency values, the live product also accepts optional passphrase encryption, publisher and player prefixes, routing mode, routing hosts, statistics callbacks, and access-control settings.
The runtime layer chooses the underlying SRT config template from the routing mode: standalone, push, or pull. It also derives some lower-level transport values such as flow-control from server_rcvbuf, so you do not need to send a separate server_fc field yourself.
Units matter here: server_latency is in milliseconds, server_timeout is in seconds, server_maxbw is in bytes per second, and server_rcvbuf is in bytes.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
If this provisioning step is triggered from an operator toolchain, the preset examples below also expose a vMix Script tab so the same server-creation shapes can be adapted for button or shortcut workflows.
Examples by preset
The examples below are grouped by the preset families that matter most when creating an SRT server: No routing, PUBLIC_IP routing, CALLABA routing, and Security and monitoring.
That keeps the create method easier to scan: you can start from the preset that matches your topology and then copy only the extra fields you really need.
Workflow-oriented use cases
These examples are useful when you are deciding why the SRT server should exist in the pipeline, not only how to fill the request body.
Provision a reusable ingest point for OBS or an encoder
Use this pattern when an external publisher should target one stable SRT listener and the downstream modules may change later.
- Module chain:
Publisher / OBS / encoder->MODULE_SRT_SERVERS - Why teams use it: the ingest endpoint, passphrase policy, and prefixes live in one reusable server object.
- What stays stable: server listen port, receiver port, and server identity.
Provision a routed ingest endpoint for backup or handoff workflows
Use this pattern when the ingest boundary should stay the same, but the server still needs to route through push or pull mode.
- Module chain:
MODULE_SRT_SERVERS-> routed downstream target - Why teams use it: routing can be encoded directly into the server contract instead of being managed ad hoc around the ingest source.
- Typical fit: backup ingress, public-IP routing, or a named Callaba routing host.
Provision a monitored ingress point for operations
Use this pattern when the server itself should be observable as a first-class runtime object after creation.
- Follow-up methods:
start,stop,getActiveStreams,getEventLogBySRTPort,getStatisticHistory - Why teams use it: support and QA can inspect the ingest point directly instead of inferring state only from downstream modules.
- Operational fit: managed events, external publishers, and environments where connection history matters.
These examples keep routing disabled and rely on the server itself as the stable ingest boundary.
Use this shape when the server should act as a plain local SRT ingest endpoint without any routing layer. It is the simplest contract and the closest to the basic dashboard form.
The PUBLIC_IP mode is for direct routing to public network addresses. Use PUSH when this server should actively send toward the remote endpoint. Use PULL when the remote side should be treated as the upstream that this server reaches out to.
Use this shape when the server should actively push toward a public-IP routing target. Each routing host needs a host and port, while routing_server_name stays optional in this mode.
Use this shape when the routed side should be pulled instead of pushed. In practice this is the public-IP sibling of the push example, but with a pull lifecycle.
The CALLABA routing mode uses named routing hosts and is the stricter variant: host, port, and server name are all required. Use PUSH when this server should send into the Callaba-side route, and PULL when the Callaba-side route should behave as the upstream relationship you attach to.
Use this shape when the server should route toward the Callaba cloud path in push mode. In this routing mode each host item must also carry routing_server_name.
Use this shape when the routed Callaba side should be pulled instead of pushed. It keeps the same named routing host contract while switching the routing type.
These examples keep the basic ingest shape but turn on one advanced capability at a time so it is easier to copy the exact fields you need.
Use this shape when the ingest endpoint should require SRT encryption. The example uses a 16-character passphrase, which matches the product guidance for AES-128 sized protection.
Best fit: shared ingest points, partner contribution, or any case where the listener should not accept cleartext SRT sessions by default.
Use this shape when the server should post SRT statistics to an external monitoring endpoint. The backend validates the callback URL and interval together.
Best fit: managed events, support workflows, and long-running ingest points where you want external telemetry without polling the full server object.
Use this shape when only specific publisher or receiver hosts should be allowed. The validation layer checks host and role_name entries when stream_control_type is set to CONTROL_ACCESS_IP_ADDRESS.
Best fit: controlled ingest from known sites or fixed peer addresses. If peers change often, this mode is stricter to operate than a simple open listener.
Dashboard label: Name.
Set such a name for the created item to avoid confusion in the future. The validation layer accepts from 1 to 60 characters.
Current validated API contract accepts SERVER_TYPE_SRT.
The model still defines SERVER_TYPE_WEBRTC, but the live create/update validation currently allows only the SRT server type.
Dashboard label: Enable once created.
Enabled is a server state. Disconnecting the server turns off connections and data transfers for all publishers and recipients connected to this SRT server.
Dashboard label: Port.
Port used for listening to the SRT server. The live validation accepts values from 1024 to 65535.
Dashboard label: Receiver port.
Port used for receiving SRT streams. The current validated API also expects a value from 1024 to 65535.
The runtime has a fallback path when this port is missing, but the public create/update contract still requires it explicitly.
Dashboard label: Latency.
Latency is configured in milliseconds. The product guidance recommends using roughly ping × 4, with an absolute practical floor of about 120 ms for stable SRT contribution.
For practical setup guidance, see Find the perfect latency for your SRT setup.
Dashboard label: Max network bandwidth.
Network bandwidth or bitrate in Byte/s. Use -1 for unlimited. The validation layer currently accepts values up to 3125000000.
Dashboard label: Stream inactivity timeout.
Configured in seconds. When the timeout is reached, the server disconnects the client. -1 means unlimited timeout.
Dashboard label: Receiver buffer size.
This field is expressed in bytes. The current validation range is 12058624 to 200000000.
The dashboard wording uses 12058624 as the default and 48234496 as a recommended production value. The runtime derives flow-control internally from this receive buffer, so you do not send a separate server_fc field.
Dashboard label: Passphrase.
Optional SRT encryption secret for the ingest endpoint. The dashboard guidance recommends a length of 16, 24, or 32 characters for AES-128, AES-192, and AES-256 sized passphrases.
Dashboard label: Domain Publisher.
URL parameter or stream-id prefix for the publisher side. Valid characters are A-Z, a-z, and 0-9. The model defaults to publisher.
Dashboard label: Domain Player.
URL parameter or stream-id prefix for the receiver side. Valid characters are A-Z, a-z, and 0-9. The model defaults to receiver.
Dashboard section: Routing settings.
Controls whether the SRT server runs as a local standalone ingress or as a routed endpoint. The validated values are DISABLED, PUBLIC_IP, and CALLABA.
This choice affects which runtime config template is selected: standalone, push, or pull routing mode.
Routing strategy used when routing is enabled. The server model defines PUSH and PULL.
List of routing targets.
For CALLABA routing, each item must contain routing_host, routing_port, and routing_server_name. For PUBLIC_IP, the host and port are required while the server name stays optional.
The product also links this mode to backup-stream workflows. See how to set up an SRT backup stream in case of a main stream interruption.
Optional callback URL for SRT statistics delivery. When set, the value must be a valid http or https URI.
Statistics posting interval in seconds.
Create/update validation accepts values from 1 to 10. If statistics are enabled and no interval is provided, the service falls back to 1 second.
Control mode for per-stream access validation. When the value is set to IP-address based access control, the backend validates the related access_settings entries as host and role objects.
Optional list of access rules or stream identities created together with the server.
In responses, these appear as related access records rather than as the original request payload.
Mongo-style identifier of the created SRT server. The live product returns it on the top level of the response.
Convenience alias for the server identifier. In the live response, id matches _id.
Name stored for the created SRT server.
Slug-style code generated from server_name. The backend derives it with friendly URL normalization.
Type of the created server, for example SERVER_TYPE_SRT.
Listening port returned by the product for the created SRT server.
Receiver port returned by the product for the created SRT server.
Assigned UDP port document for the publisher side of the server.
Assigned UDP port document for the receiver side of the server.
Configured latency value in milliseconds.
Configured maximum bandwidth in Byte/s.
Configured inactivity timeout in seconds. The live document currently serializes it as a string.
Receive buffer size in bytes. Runtime flow-control is derived from this value internally.
Whether the created server is enabled immediately after creation.
Stored encryption field for the server. If passphrase protection is enabled, the backend stores an encoded value rather than a plaintext secret.
Publisher-side stream-id or URL prefix stored with the server.
Receiver-side stream-id or URL prefix stored with the server.
Routing targets saved with the server. In the minimal default create flow this is an empty array.
Resolved statistics interval. The live create flow defaults to 1.
Related access stream records for this SRT server. getById populates these more deeply than create/update.
Owner user identifier attached by the backend.
Creation timestamp returned by the live product.
Last modification timestamp returned by the live product.
Document version field returned by the model serialization.
The live product returns a boolean success flag together with the created SRT server object. On successful creation it is true.
Returns the number of SRT server documents that match the supplied filter.
Use this method when you need a lightweight inventory count for dashboards, checks, or paginated tooling without loading the full server list.
Optional Mongo-style filter object applied before counting. For example, you can count only active SRT servers.
Total number of SRT server documents that match the supplied filter.
Returns a list of SRT servers from Callaba Engine.
The current Swagger definition exposes this method as POST /api/srt-servers/getAll with an application/json request body used for pagination and sorting.
In live product tests, this method returns a bare array of SRT server objects. The response example below reflects that runtime behavior rather than the minimal Swagger success-only example.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
Maximum number of SRT servers to return in one response page.
Offset used for pagination. Use 0 for the first page.
Optional sort object. If omitted, the service defaults to { server_created: 1 }.
Optional filter object merged into the server query for the current user.
The live product returns a bare array of SRT server objects rather than a wrapped data envelope.
Identifier of each SRT server returned in the array.
Name of the SRT server.
Type of the SRT server, for example SERVER_TYPE_SRT.
Listening port of the SRT server.
Receiver port of the SRT server.
Whether the server is currently enabled.
Resolved statistics interval for each server object when present.
Each returned item currently includes success: true in the live product response.
Loads one SRT server by its identifier.
The current Swagger definition exposes this method as POST /api/srt-servers/getById with a small application/json body containing the server id.
In live product tests, this method returns the full SRT server object on the top level of the response together with success: true.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
Identifier of the SRT server you want to load.
Identifier of the requested SRT server.
Name of the requested SRT server.
Type of the SRT server.
Listening port of the SRT server.
Receiver port of the SRT server.
Stored passphrase field for the server.
Publisher prefix stored for the server.
Receiver prefix stored for the server.
Routing hosts stored with the server, when routing is configured.
Configured statistics interval.
The service populates related access stream records on getById, so this endpoint is the best place to inspect the full access layer attached to a server.
Whether the server is currently enabled.
The live product returns the requested server object together with success: true.
Starts an existing SRT server by id.
This method flips the stored server state to active and then launches the underlying runtime process for that server. Use it for operational control after provisioning, rather than recreating the server document every time.
Identifier of the SRT server to start.
After a successful start request the live product returns the server object with server_active: true.
Updated modification timestamp written during the start operation.
The returned document still includes success: true.
Stops an existing SRT server by id.
This method marks the server as inactive, tears down the runtime process, and clears in-memory runtime structures such as recent statistics and event-log state for that server port.
Identifier of the SRT server to stop.
After a successful stop request the live product returns the server object with server_active: false.
Updated modification timestamp written during the stop operation.
The returned document still includes success: true.
Returns the current active SRT stream identities together with the in-memory event-log snapshot.
Use this when you want a fast operational view of which remote peers are currently attached and which ports already have recent events recorded.
Current array of active SRT stream identities, typically represented as host:peer_port.
Current in-memory event log snapshot keyed by SRT server port. Each value is the event-log array for that port.
Returns the recent event log for a specific SRT server port.
This is the endpoint to use when you need connection history for a single port, including recent on_connect and on_close entries, peer information, and stream identifiers.
SRT listen port whose event log you want to inspect.
Maximum number of most recent log entries to return.
Optional offset counted from the end of the log buffer when you want older slices.
Array of recent event-log entries for the selected SRT port. The live API returns an empty array when nothing has happened yet.
Name of the event, such as on_connect or on_close.
Origin module for the event, typically MODULE_SRT_SERVERS.
Remote host associated with the event.
SRT server port that produced the event.
Peer UDP port captured for the event.
Publisher or receiver stream identifier when available.
Role attached to the event, such as publisher or receiver.
Whether the event was recorded while the stream entry was active.
Timestamp attached to the event-log record.
Returns the raw in-memory statistics history for a specific SRT server port.
The response is keyed by stream id. Each stream id maps to the collected statistics messages for that stream, which makes this endpoint useful for debugging transport behavior after the server has already been running.
SRT server listen port whose in-memory statistics history you want to retrieve.
The top-level response is keyed by stream identifier. Each key points to the recorded statistics history for that stream on the selected server port.
Array of statistics messages collected for that stream. If the server has no history yet, the live endpoint returns an empty array or an empty object branch.
Updates an existing SRT server resource in Callaba Engine.
The update contract mirrors the create contract closely: you can adjust ports, latency, buffering, passphrase protection, routing, statistics callbacks, and access-control settings in the same request shape, while targeting an existing server id.
If you pass ********** as the passphrase placeholder, the backend preserves the existing encrypted passphrase instead of overwriting it with a new plaintext value.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
Identifier of the SRT server you want to update.
Updated display name for the SRT server.
Updated server type. The current validated API still expects SERVER_TYPE_SRT.
Updated enabled state for the server.
Updated listening port.
Updated receiver port.
Updated latency value in milliseconds.
Updated maximum bandwidth in Byte/s.
Updated inactivity timeout in seconds.
Updated receiver buffer size. The live product accepts the same recommended values used during create.
Updated passphrase. Sending ********** preserves the existing encrypted value in the backend service.
Updated publisher prefix.
Updated receiver prefix.
Updated routing mode.
Updated routing type, such as PUSH or PULL.
Updated routing target list.
Updated callback URL for SRT statistics.
Updated statistics interval in seconds.
Updated access-control mode for streams attached to the server.
Updated access rules or stream identities to recreate alongside the server.
Identifier of the updated SRT server.
Updated name returned by the product.
Modification timestamp updated by the product.
The live product returns the updated server object together with success: true.
Deletes an SRT server and stops the related server process.
The current Swagger definition exposes this method as DELETE /api/srt-servers/remove with a JSON body containing the server id.
In live product tests, this method returns the deleted SRT server object on the top level of the response together with success: true.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
Identifier of the SRT server to delete.
Identifier of the deleted SRT server.
Name of the deleted SRT server.
The live product returns the deleted server object together with success: true.