Restreaming, multiplexing, transcoding

This section will cover methods that perform restreaming, transcoding, and multiplexing of video streams.

The way this module's operating comes down to 3 simple things: the presence of an input, the presence of an action to be done and the presence of an output.

 

You can compare this module to a device that has input and output plugs and also some controls.

 

Use this module if you need to:

  • Convert the incoming stream to another format. For example, convert SRT to RTMP. For a complete list of supported inputs, please visit technical specification.
  • Convert video codec. For example, convert H.265 to H.264 or vice versa.
  • Change the video resolution.
  • Add or modify the number of keyframes or GOP. For example, insert a keyframe every 2 seconds.
  • Adjust bitrate - Adjust encoding quality.
  • Perform all of the mentioned above actions at the same time.
Creating a restreaming process
Expand
POST
/api/restream/create

Use this method to convert the incoming stream

Query parameters
restream_name
string | required | unique

Unique process name

input
object | required

Accepts an object with specified input parameters.

To convert, transcode or simply change the format of a video stream, it is enough to specify 1 input.

Examples will be added later on how multiple inputs can be passed.

Depending on the input type, different parameters are passed:

 

1. When input is SRT Servers module from the Callaba Engine:

{ input_type: "INPUT_TYPE_SRT_SOFTWARE", input_server_id: Objectid, input_stream_id: "publisher/srt-server-name/srt-stream-01" }

Note:

Use INPUT_TYPE_SRT_HARDWARE, if you plan to get your stream from a hardware encoder. This will perform additional optimization
inside Callaba Engine. If your senders are mobile devices or computers, use INPUT_TYPE_SRT_SOFTWARE

 

2. When input is RTMP Servers module from Callaba Engine:

{ input_type: "INPUT_TYPE_RTMP_SOFTWARE" input_server_id: Objectid, input_stream_id: "publisher/srt-server-name/srt-stream-01" }

In this case, you pass in the ID of your RTMP server and the key of the stream you want to convert.

Note

Use INPUT_TYPE_RTMP_HARDWARE, if you plan get your stream from a hardware encoder. This will perform additional optimization inside Callaba Engine. If your senders are mobile devices or computers, use INPUT_TYPE_RTMP_SOFTWARE

In this case, you are passing in the id of your SRT server and the publisher's id of the stream you want to convert.

3. When input is received via port listening, without using other modules.

Possible input_type values:

INPUT_TYPE_SRT_LISTEN: listen on SRT port
INPUT_TYPE_RTMP_LISTEN: listen on RTMP port
INPUT_TYPE_RTSP_LISTEN: listen on RSTP port
INPUT_TYPE_UDP_LISTEN: listen on UDP port
INPUT_TYPE_HTTP_LISTEN: - listen on HTTP port


Example of the SRT listen request on port 2035 :

{ input_type: 'INPUT_TYPE_SRT_URL' , input_stream_listen_port: { port: 2035, transport: "UDP" } }

For this type of input, you must explicitly specify the port you are listening and the type of transport you are using.
Optionally, you can also pass module_name and module_type for more flexible organization of your application.

For example, if you use the method for receiving all the inputs, you'd be able to see which of the processes you've made earlier occupies the server port.

This type of input accepts the following transport values :

For SRT, WEBRTC, RTP the transport value is UDP.
For all of the rest transport value is TCP.

 

4. When input is a URL, from where the stream is picked up for further conversion.

Possible input_type values:

INPUT_TYPE_SRT_URL: listen SRT address
INPUT_TYPE_RTMP_URL: listen RTMP address
INPUT_TYPE_RTSP_URL: listen RTSP address
INPUT_TYPE_UDP_URL: listen UDP address
INPUT_TYPE_HTTP_URL: listen HTTP address
INPUT_TYPE_OTHER: listen any address
INPUT_TYPE_HLS_URL: listen HLS address
INPUT_TYPE_MPEG_DASH_URL: listen MPEG-DASH address

For this type of input, specify the address where you want to receive video.

{ input_type: "INPUT_TYPE_SRT_URL", input_stream_url : "srt://1.2.3.4:8000" }

Additionally, you can control the protocol by adjusting its parameters.

For example:

{ input_stream_url : "srt://1.2.3.4:8000?rcvbuf=12036704" }

Controlling parameters is available for all protocols.

 

5. When you don't have video but need a test stream of video and audio

{ input_type: "INPUT_TYPE_GENERATE_TEST_VIDEO" } 

It generate a default test stream (1920x1080, 24, 6000Kbit/s) with a duration of 1 hour and 216 Hz sine wave audio.

If necessary, you can control the settings of the test video by passing parameters to the input object:

  • encoding_rate. Default value is 24 
  • sound_hz. Default value is 216
  • resolution_width. Default value is 1920
  • resolution_height. Default value is 1080
  • video_duration_sec. Default value is 3600
  • test_video_bitrate. Default value is 6000

Example:

{ input_type: "INPUT_TYPE_GENERATE_TEST_VIDEO", test_video_bitrate: 2500 } 

transcoding
object | required

Takes an object with transform settings:

Example:

{ video_transcoding: "libx265", output_video_bitrate: 4000 } 

Properties:

video_transcoding - controls output codec type. Possible values:

  • libx264 - convert to H.264 via CPU
  • libx265 - convert to H.265 via CPU
  • mpsoc_vcu_h264 - convert to H.264 via graphics accelerator card on Amazon Web Services (VT1 instances)
  • mpsoc_vcu_hevc - convert to HEVC via graphics accelerator card on Amazon Web Services (VT1 instances)

output_video_bitrate - controls output bitrate. The value is specified in kilobits.

force_key_frames - use this parameter if you need to cut your stream into smaller HLS fragments. For good the streaming experience we recommend inserting a key frame every 2 seconds

gop - Set this to 2x frame rate for a 2 second GOP

Frame width  - For example, 1920

Frame height  - For example, 1080

preset - controls codec preset settings. Possible values: Disabled, ultrafast, superfast, very fast, faster, fast, medium, slow, slower, veryslow

tune - controls the fine tuning of the codec, possible values: Disabled, film, animation, grain, stillimage, fastdecode, zerolatency.

crf - sets the constant video quality to be controlled. Possible values are from 0 to 51 where 0 is lossless and 51 is the worst possible.

pix_fmt - video pixel format. Possible values: Disable, yuv420p, yuvj420p, yuv422p, yuvj422p, yuv444p, yuvj444p, nv12, nv16, nv21, yuv420p10le, yuv444p10le, nv20le

filter_fps - allows you to change the number of frames per second, through a filter
after transcoding and before output.

audio_trancoding - allows to convert audio. Possible values: aac, mp3

output_audio_bitrate - sets the output bitrate, in kilobits, for example 320

sample_rate - sets the resampling rate, in hertz. For example 44100. We recommend using AAC, because some browsers still don't work well with MP3s

Additional settings for the graphics accelerator card:

  • slices. Valid values: 0 to 68 Slices are a fundamental part of the stream format. You can operate on slices in parallel to increase speed at which a stream is processed. However, operating on multiple “slices” of video at once will have a negative impact on video quality. This option must be used when encoding 4k streams to H.264 in order to sustain real-time performance. The maximum practical value for this option is 4 since there are 4 encoder cores in a device.
  • cores. Valid values: 0 to 4 The encoder plugin automatically determines how many encoder cores are needed to sustain real-time performance (e.g. 1 for 1080p60, 4 for 4K60). The -cores option can be used to manually specify how many encoder cores are to be used for a given job. When encoding file-based clips with a resolution of 1080p60 or lower, leveraging additional cores may increase performance. This option will provide diminishing returns when multiple streams are processed on the same device. This option has no impact on live streaming use-cases as a video stream cannot be processed faster than it is received.
output
object | required

Like the input it also accepts an object, with output parameters:

1. output_type - output type, possible values:

OUTPUT_TYPE_LOCAL_RTMP_URL - restream RTMP to the same server

OUTPUT_TYPE_OTHER_RTMP_URL - restream to another RTMP server

OUTPUT_TYPE_RTSP_URL - restream to RTSP server (using TCP)

OUTPUT_TYPE_SRT_URL - restream to SRT host (any)

OUTPUT_TYPE_UDP_URL - restream to UDP video server

OUTPUT_TYPE_HTTP_URL - restream to any other HTTP server

OUTPUT_TYPE_RTP_URL - restream to RTP server

2. output_stream_url - the address where you want to deliver the video

3. output_stream_key - stream key (only applicable for RTMP)

Note, it is possible to control protocols through parameters, for example "srt://1.2.3.4:8000?sndbuf=12036704"

For example, a redirect to Youtube will be like this : 

{ "output_type": "OUTPUT_TYPE_OTHER_RTMP_URL", "output_stream_url" : "rtmp://a.rtmp.youtube.com/live2/" , "output_stream_key": "AWESOME_YOUTUBE_STREAM_KEY" }

Note: Use a separate process for the same input stream if you need multiple transformations simultaneously.

active
boolean | optional

Controls the state of the process. Possible values are true or false. The default value is true.

Creating a restreaming process
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/restream/create' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "restream_name": "Awesome restream",
  "input": {
    "input_type": "INPUT_TYPE_RTSP_URL",
    "input_stream_url": "rtsp://127.0.0.1/live.sdp"
  },
  "output": {
    "output_type": "OUTPUT_TYPE_SRT_URL",
    "output_stream_url": "srt://127.0.0.1:2035"
  },
  "active": true
}'
Response
id
ObjectId | unique

A unique identifier of the restreaming, transcoding or multiplexing process. 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 process.

created
date

Returns the creation date of the process

Response: Creating a restreaming process
JSON
{
  "id": "62275f1bccaa650032da2b53",
  "created": "2022-03-08T13:50:19.650Z"
}
Editing the restreaming process
Expand
POST
/api/restream/update

Use this method to change the restreaming, trancoding or multiplexing parameters.

This method can take the same parameters as /api/restream/create method

Query parameters
This method has no parameters
Editing the restreaming process
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/restream/update' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "62275f1bccaa650032da2b53",
  "restream_name": "Awesome restream. Updated",
  "input": {
    "input_type": "INPUT_TYPE_RTSP_URL",
    "input_stream_url": "rtsp://127.0.0.1/live.sdp"
  },
  "output": {
    "output_type": "OUTPUT_TYPE_SRT_URL",
    "output_stream_url": "srt://127.0.0.1:2036"
  },
  "active": true
}'
Response
id
ObjectId

A unique identifier of the process

updated
date

Returns the date the restreaming process was last modified

success
boolean

Success result. Possible value: true or false.

Response: Editing the restreaming process
JSON
{
  "success": true
}
Stopping the restreaming process
Expand
POST
/api/restream/stop

Use this method to stop the restreaming process

Query parameters
id
ObjectId | required

id - identifier of the restreaming process to be stopped.

Stopping the restreaming process
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/restream/stop' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "62275f1bccaa650032da2b53"
}'
Response
success
boolean

Success result. Possible value: true or false.

Response: Stopping the restreaming process
JSON
{
  "success": true
}
Starting the restreaming process
Expand
POST
/api/restream/start

Use this method to start the restreaming process

Query parameters
id
ObjectId | required

id - identifier of the restreaming process to be started.

Starting the restreaming process
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/restream/start' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "62275f1bccaa650032da2b53"
}'
Response
success
boolean

Success result. Possible value: true or false.

Response: Starting the restreaming process
JSON
{
  "success": true
}
Getting a list the restreaming processes
Expand
POST
/api/restream/getAll

Use this method for getting a list the restreaming processes

Query parameters
This method has no parameters
Getting a list the restreaming processes
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/restream/getAll' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -d ''
Response
list of processes
array

Returns an array of processes

Response: Getting a list the restreaming processes
JSON
[
  {


    "id": "62275f1bccaa650032da2b53",
    "restream_name": "Awesome restream. Updated",
    "restream_type": "RESTREAM_TYPE_SRT_TO_RTMP",
    "active": true,
    "created": "2022-03-08T13:50:19.650Z",
    "modified": "2022-03-08T15:14:25.355Z"
  }
]
Getting the restreaming info by ID
Expand
POST
/api/restream/getById

Use this method to get information about the restreaming process

Query parameters
id
ObjectId | required

id - identifier of the restreaming process

Getting the restreaming info by ID
cURL
curl -X 'POST' \
  'http://localhost/api/restream/getById' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "62275f1bccaa650032da2b53"
}'
Response
Object of process
object

Returns an object of restreaming process

Response: Getting the restreaming info by ID
JSON
{
  "input": [
    {
      "id": "6227655bccaa650032da37d2",
      "input_type": "INPUT_TYPE_RTSP_URL",
      "input_stream_url": "rtsp://127.0.0.1/live.sdp",
    }
  ],
  "output": [
    {
      "id": "6227655bccaa650032da37d4",
      "output_type": "OUTPUT_TYPE_SRT_URL",
      "output_stream_url": "srt://127.0.0.1:2036",
    }
  ],
  "id": "62275f1bccaa650032da2b53",
  "restream_name": "Awesome restream. Updated",
  "restream_type": "RESTREAM_TYPE_SRT_TO_RTMP",
  "active": true,
  "created": "2022-03-08T13:50:19.650Z",
  "modified": "2022-03-08T15:14:25.355Z"
}
Getting the statistic of processes
Expand
POST
/api/restream/getStat

Use this method to get the statistics of the restreaming process

Query parameters
This method has no parameters
Getting the statistic of processes
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/restream/getProcessData' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d ''
Response
bitrate
string

Current bitrate (kilobits)

Response: Getting the statistic of processes
JSON
[
  {
     id: ObjectId,
     bitrate: 6500
  }
]
Removing the process
Expand
DELETE
/api/restream/remove

Use this method to remove the restreaming process

Query parameters
id
ObjectId | required

id - identifier of the restreaming process to be removed.

Removing the process
cURL
curl -X 'DELETE' \
  'http://1.2.3.4/api/restream/remove' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "62275f1bccaa650032da2b53"
}'
Response
success
boolean

Success result. Possible value: true or false.

Response: Removing the process
JSON
{
  "success": true
}