Working with SRT servers

This section will cover methods for organizing broadcasting via the SRT protocol from your application or infrastructure using the Restful API. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed. For this workflow, Player & embed is the most direct fit., and scaling guide.

These methods can be called from any type of client or server, whether it's an ajax request from a browser, or the Android operating system.

You don't need to install anything.

To get started, all you need is an API token, which gets purchased and assigned to you the moment you launch an instance with Callaba Cloud.

If you haven't already done so, please follow the link. It will take no more than 5 minutes.

For each method of establishing streaming over the SRT protocol, CURL requests and JSON responses will be presented as an example, as well as all possible parameters with SRT settings will be considered.

Using these methods, you will be able to broadcast SRT from your infrastructure or application. If you need something extra that is not in the API, you can contact our technical support and request customization from the internal Callaba Engine development team.

If you have any questions, please contact us at: [email protected]
We will respond to you within 24 hours.

Happy developing and streaming!

Creating an SRT server
Expand
POST
/api/srt-servers/create

Creates an SRT server on the specified port, with parameters.

Once the request is executed, Callaba Engine is ready to receive and send SRT streams.

Publish SRT stream:

ffmpeg -re -i "./videos/awesome-video.mp4" -f mpegts "srt://100.204.59.138:1935?streamid=publisher/awesome-srt-server/srt-stream-01"

Receive SRT stream:

ffplay -i "srt://100.204.59.138:1935?streamid=receiver/awesome-srt-server/srt-stream-01"

If ffmpeg is not available, you can send and receive a stream from OBS, use this tutorial

Query parameters
server_name
string | required | unique

SRT server name. This parameter must be unique and is required. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with How to multi-stream from Zoom to Twitch, Youtube and Facebook and Low latency streaming that actually works protocols, configs, and pitfalls.

server_type
string | required

SRT server type. The following types are supported For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview.

  • SERVER_TYPE_SRT - creates an SRT server for production usage.
  • SERVER_TYPE_SRT_DEBUG - creates an SRT server for testing and diagnostic (for the internal development team).

Use SERVER_TYPE_SRT if you are developing your own application based on the Callaba Engine.

server_port
string | required | unique

SRT server port. Acceptable values are from 1 to 65535. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with SRT Servers. server_receiver_port and How to set up CloudFront on AWS and optimize data transfer.

 

Since SRT uses UDP as a transport, after creating an SRT server on the specified port, the corresponding UDP port will be used.

 

To find out if a port is free, use the /api/ports/getAll method from the ports section

 

IMPORTANT. Make sure the specified port is open in your infrastructure and AWS infrastructure.

server_latency
number | required

SRT delay. Use RTT*4 but not less than 120ms. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Create, edit, start and delete SRT Server or Gateway using Callaba Cloud and Common live streaming problems and how to solve them.

To find out the RTT, use the API method /utils/get-rtt

server_maxbw
number | required

Maximum bandwidth of your network (Byte/s).

 

The maximum bandwidth will be the weakest point in the network (Wi-Fi router, ISP etc).

 

To find out the bandwidth of the server hosting Callaba Engine, use the /api/utils/speedtest method For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Create, edit, start and delete SRT Server or Gateway using Callaba Cloud and Common live streaming problems and how to solve them. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview. Before full production rollout, run a Test and QA pass with a test app for end-to-end validation.

server_rcvbuf
number | required

Server receiver buffer in bytes.

 

The default value in SRT library is 12058624 bytes. For 4k streaming and above, we recommend using ~ 48234496 bytes. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Create, edit, start and delete SRT Server or Gateway using Callaba Cloud and Creating a Test App to manage Callaba Engine on AWS using a RESTful API. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview.

passphrase
string | optional

Passphrase for SRT streams. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Creating a Test App to manage Callaba Engine on AWS using a RESTful API and How to set up CloudFront on AWS and optimize data transfer. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview.

 

Note : some encoders require at least 10 characters, please keep this in mind when creating your application.

routing
string | optional

Initializes routing mode of the SRT streams. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Create, edit, start and delete SRT Server or Gateway using Callaba Cloud and How to set up streaming from JVC GY-HC500U camera using SRT protocol and Callaba Cloud.

 

Use this parameter if you want to set up SRT connection with another SRT host. Possible values:

  • DISABLED. Stream routing is disabled. Default value
  • CALLABA. Stream routing to another Callaba host
  • PUBLIC_IP. Stream routing to any other SRT destination. Use this setting if you are listening on your host SRT stream, or on your decoder in the listener mode
routing_hosts
array | optional

An array of hosts you need to establish a connection with in order to route SRT streams. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed. For this workflow, Player & embed is the most direct fit., and scaling guide. For implementation details, continue with Setting up Main/Backup SRT connection bonding in Callaba Cloud and How to multi-stream from Zoom to Twitch, Youtube and Facebook.

 

Each element of the array must include:

  • routing_host (required) - IPv4 address of the host to connect to
  • routing_port  (required) - SRT port of the host
  • routing_server_name (optional) - (only for CALLABA connection type) SRT server name (server_name) of the remote node you want to connect to.

Example the routing_hosts property: 

routing_hosts: [ {routing_host: "100.101.102.103", routing_port: 1936, routing_server_name: "SRT point in New York" } ]

routing_type
string | optional

Stream routing type. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with How to set up CloudFront on AWS and optimize data transfer and Create, edit, start and delete SRT Server or Gateway using Callaba Cloud.

Possible values:

  • PUSH - Redirect received streams to specified routing_hosts. Use this option if
    • you send a stream from one country/region, and receive it in another or several others.
    • you send a stream to 1 server, but you want to be able to receive from a number of servers
  • PULL - Request streams from servers specified by routing_hosts. use this option to request video from possible servers.
server_active
boolean | optional

Controls the state of the server. Possible values are true or false. Disabling the SRT server will make it drop all connections and free up resources. The default value is true. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Create a Virtual Events Platform Setup CloudFront CDN for Live Events. Part I and How to set up CloudFront on AWS and optimize data transfer.

server_receiver_port
string | required | unique

SRT receiver port. Acceptable values are from 1 to 65535. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with SRT Servers. server_port and How to set up CloudFront on AWS and optimize data transfer.

 

Since SRT uses UDP as a transport, after creating an SRT server on the specified port, the corresponding UDP port will be used.

 

To find out if a port is free, use the /api/ports/getAll method from the ports section

 

IMPORTANT. Make sure the specified port is open in your infrastructure and AWS infrastructure.

Creating an SRT server
cURL
curl -X 'POST' \ 'http://100.204.59.138/api/srt-servers/create' \ -H 'accept: application/json' \ -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0NDk0ODU0MiwiZXhwIjoxNjQ3NTQwNTQyfQ.ujxKkZHU9lvg9PYSG5-8DNuJgyJlqgkNw-VAu_uw5tI' \ -H 'Content-Type: application/json' \ -d '{ "server_name": "Awesome SRT server", "server_type": "SERVER_TYPE_SRT", "server_port": 1935, "server_latency": 200, "server_maxbw": -1, "server_timeout": 60, "server_rcvbuf": 48234496, "server_active": true }'
Response
id
ObjectId | unique

A unique identifier of the SRT server. Is an object and looks similar to the hashed string. As Callaba Engine uses MongoDb, it's a common practice to consider it as an ObjectId type, to avoid introducing unnecessary entities. Use this option to get, edit, delete a specific SRT server. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide.

server_created
date

Returns the creation date of the SRT server For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Creating a Test App to manage Callaba Engine on AWS using a RESTful API and art servers response server_updated. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview.

success
boolean

Success result. Possible value: true or false.

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Players remove success and Players response change success. For implementation details, continue with Players response start success and Players response stop success. For implementation details, continue with Recording remove success and Recording response change success. For implementation details, continue with Restream Io and Video Hosting.

Response: Creating an SRT server
JSON
{
  "id": "620bf227137bb3002c8f6039",
  "server_name": "Awesome SRT server",
  "server_type": "SERVER_TYPE_SRT",
  "server_port": "1935",
  "server_latency": 200,
  "server_maxbw": -1,
  "server_timeout": "60",
  "server_rcvbuf": 48234496,
  "server_active": true,
  "server_user_id": "620beb06137bb3002c8f600a",
  "server_name_code": "awesome-srt-server",
  "server_publisher": "publisher",
  "server_player": "receiver",
  "routing_hosts": [],
  "server_created": "2022-02-15T18:34:15.331Z",
}
Editing the SRT Server
Expand
POST
/api/srt-servers/update

Use this method to change the settings of a previously created server by its ID.

Once the method is executed, the server will be stopped and all its clients will be disconnected. Then the server would be re-started with the new parameters.

Use the same query parameters as when creating the server

Query parameters
id
ObjectId | required

id - identifier of the server to be changed.

For implementation details, continue with RTMP servers change id and Akamai Cdn.

For implementation details, continue with Common live streaming problems and how to solve them and How to generate Test Videos to test your setups. For this workflow, teams usually combine 24/7 streaming channels, Ingest & route, and Video platform API. Before full production rollout, run a Test and QA pass with streaming quality check and video preview and a test app for end-to-end validation.

Editing the SRT Server
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/srt-servers/update' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0NTczMTE5OCwiZXhwIjoxNjQ4MzIzMTk4fQ.8JuWlhn4lEY11hAUsaw10O_5-HiKH_GuQq8k2qRBvbA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "620bf227137bb3002c8f6039",
  "server_name": "Awesome SRT server",
  "server_type": "SERVER_TYPE_SRT",
  "server_port": 1936,
  "server_latency": 200,
  "server_maxbw": -1,
  "server_timeout": 60,
  "server_rcvbuf": 48234496,
  "server_active": true
}'
Response
id
ObjectId

A unique identifier of the SRT server. For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with SRT Servers. Create. id and How to assign transcoding to Alveo™ U30 accelerator card.

server_updated
date

Returns the date the SRT server was last modified For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Create a Virtual Events Platform Setup CloudFront CDN for Live Events. Part I and Creating a Test App to manage Callaba Engine on AWS using a RESTful API. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview.

success
boolean

Success result. Possible value: true or false.

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Players remove success and Players response change success. For implementation details, continue with Players response start success and Players response stop success. For implementation details, continue with Recording remove success and Recording response change success. For implementation details, continue with Restream Io and Video Hosting.

Response: Editing the SRT Server
JSON
{
  "routing_hosts": [],
  "id": "620bf227137bb3002c8f6039",
  "server_name": "Awesome SRT server",
  "server_type": "SERVER_TYPE_SRT",
  "server_port": "1936",
  "server_latency": 200,
  "server_maxbw": -1,
  "server_timeout": "60",
  "server_rcvbuf": 48234496,
  "server_active": true,
  "server_user_id": "620beb06137bb3002c8f600a",
  "server_name_code": "awesome-srt-server",
  "server_publisher": "publisher",
  "server_player": "receiver",
  "server_created": "2022-02-15T18:34:15.331Z",
  "server_modified": "2022-02-24T19:35:04.287Z"
}
Stopping the SRT server
Expand
POST
/api/srt-servers/stop

Use this method if you need to stop an SRT server by its id. 

Query parameters
id
ObjectId | required

id - identifier of the server to be stopped.

For implementation details, continue with Create, edit, start and delete SRT Server or Gateway using Callaba Cloud and RTMP servers stop id. For this workflow, Ingest & route is the most direct fit. For implementation details, continue with Next generation video transcoding via graphics accelerator card with Callaba Cloud and Creating a Test App to manage Callaba Engine on AWS using a RESTful API. For this workflow, teams usually start with Video platform API and combine it with Calls & webinars. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview. For this workflow, Paywall & access is the most direct fit.

Stopping the SRT server
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/srt-servers/stop' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0NTczMTE5OCwiZXhwIjoxNjQ4MzIzMTk4fQ.8JuWlhn4lEY11hAUsaw10O_5-HiKH_GuQq8k2qRBvbA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "620bf227137bb3002c8f6039"
}'
Response
success
boolean

Success result. Possible value: true or false.

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Players remove success and Players response change success. For implementation details, continue with Players response start success and Players response stop success. For implementation details, continue with Recording remove success and Recording response change success. For implementation details, continue with Restream Io and Video Hosting.

Response: Stopping the SRT server
JSON
{
"success": true
}
Starting the SRT server
Expand
POST
/api/srt-servers/start

Use this method if you need to start an SRT server by its id.

Query parameters
id
ObjectId | required

id - identifier of the server to be started.

For this workflow, teams usually combine Calls & webinars, Video platform API, and Player & embed. For implementation details, continue with RTMP servers start id and Recording start id. For implementation details, continue with Video Platforms and Rtmp.

Starting the SRT server
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/srt-servers/start' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0NTczMTE5OCwiZXhwIjoxNjQ4MzIzMTk4fQ.8JuWlhn4lEY11hAUsaw10O_5-HiKH_GuQq8k2qRBvbA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "620bf227137bb3002c8f6039"
}'
Response
success
boolean

Success result. Possible value: true or false.

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Players remove success and Players response change success. For implementation details, continue with Players response start success and Players response stop success. For implementation details, continue with Recording remove success and Recording response change success. For implementation details, continue with Restream Io and Video Hosting.

Response: Starting the SRT server
JSON
{
"success": true
}
Getting a list of SRT servers
Expand
POST
/api/srt-servers/getAll

Use this method to get a list of SRT servers

Query parameters
This method has no parameters
Getting a list of SRT servers
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/srt-servers/getAll' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0NTczMTE5OCwiZXhwIjoxNjQ4MzIzMTk4fQ.8JuWlhn4lEY11hAUsaw10O_5-HiKH_GuQq8k2qRBvbA' \
  -H 'Content-Type: application/json' \
  -d ''
Response
array of SRT servers
array

Returns an array of SRT servers For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Creating a Test App to manage Callaba Engine on AWS using a RESTful API and art servers response server_updated. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview.

Response: Getting a list of SRT servers
JSON
[
  {
    "routing_hosts": [],
    "id": "620bf227137bb3002c8f6039",
    "server_name": "Awesome SRT server",
    "server_type": "SERVER_TYPE_SRT",
    "server_port": "1936",
    "server_latency": 200,
    "server_maxbw": -1,
    "server_timeout": "60",
    "server_rcvbuf": 48234496,
    "server_active": false,
    "server_user_id": "620beb06137bb3002c8f600a",
    "server_name_code": "awesome-srt-server",
    "server_publisher": "publisher",
    "server_player": "receiver",
    "server_created": "2022-02-15T18:34:15.331Z"
    "server_modified": "2022-02-25T14:25:41.388Z"
  }
]
Getting server SRT information by ID
Expand
POST
/api/srt-servers/getById

Use this method if you need to get information about the server created by your application.

Query parameters
id
ObjectId | required

id - identifier of the server

For implementation details, continue with Akamai Cdn and Content protection and DRM safeguarding content from piracy and unauthorized access.

Getting server SRT information by ID
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/srt-servers/getById' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0NTczMTE5OCwiZXhwIjoxNjQ4MzIzMTk4fQ.8JuWlhn4lEY11hAUsaw10O_5-HiKH_GuQq8k2qRBvbA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "620bf227137bb3002c8f6039"
}'
Response
Object of SRT server
object

Returns an object of SRT server For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed., and scaling guide. For implementation details, continue with Creating a Test App to manage Callaba Engine on AWS using a RESTful API and art servers response server_updated. Before full production rollout, run a Test and QA pass with Generate test videos and streaming quality check and video preview.

Response: Getting server SRT information by ID
JSON
{
  "routing_hosts": [],
  "id": "620bf227137bb3002c8f6039",
  "server_name": "Awesome SRT server",
  "server_type": "SERVER_TYPE_SRT",
  "server_port": "1936",
  "server_latency": 200,
  "server_maxbw": -1,
  "server_timeout": "60",
  "server_rcvbuf": 48234496,
  "server_active": true,
  "server_user_id": "620beb06137bb3002c8f600a",
  "server_name_code": "awesome-srt-server",
  "server_publisher": "publisher",
  "server_player": "receiver",
  "server_created": "2022-02-15T18:34:15.331Z",
  "server_modified": "2022-02-25T14:22:53.067Z"
}
Removing the SRT server
Expand
DELETE
/api/srt-servers/remove

Use this method if you need to remove an SRT server by its id. 

Query parameters
id
ObjectId | required

id - identifier of the server to be removed.

For implementation details, continue with Content protection and DRM safeguarding content from piracy and unauthorized access and RTMP servers remove id.

For implementation details, continue with What is DRM and how it works in Live Video Streaming and Content protection methods for streaming. For this workflow, teams usually combine Paywall & access, 24/7 streaming channels, and Ingest & route.

Removing the SRT server
cURL
curl -X 'DELETE' \
  'http://1.2.3.4/api/srt-servers/remove' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0NTczMTE5OCwiZXhwIjoxNjQ4MzIzMTk4fQ.8JuWlhn4lEY11hAUsaw10O_5-HiKH_GuQq8k2qRBvbA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "620bf227137bb3002c8f6039"
}'
Response
success
boolean

Success result. Possible value: true or false.

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Players remove success and Players response change success. For implementation details, continue with Players response start success and Players response stop success. For implementation details, continue with Recording remove success and Recording response change success. For implementation details, continue with Restream Io and Video Hosting.

Response: Removing the SRT server
JSON
{
"success": true
}