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.

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.

server_type
string | required

SRT server type. The following types are supported

  • 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.

 

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.

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

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.

passphrase
string | optional

Passphrase for SRT streams.

 

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.

 

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.

 

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.

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.

server_receiver_port
string | required | unique

SRT receiver port. Acceptable values are from 1 to 65535.

 

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
server_created
date

Returns the creation date of the SRT server

success
boolean

Success result. Possible value: true or false.

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.

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.

server_updated
date

Returns the date the SRT server was last modified

success
boolean

Success result. Possible value: true or false.

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.

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.

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.

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.

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

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

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

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.

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.

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