Stream recordings

This page provides methods for recording the streams to the server's disk.

If necessary, the stream can be transcoded here without calling additional modules.

Note:

Use /api/utils/getStat to find out the amount of free disk space

Create a recording task
Expand
POST
/api/recording/create

Creates a process that receives and writes a video stream to disk.

Once the process is added, the server will wait for the video stream and immediately start recording it to the server disk. In case if connection is interrupted, the writing process will be stopped. Resuming the stream will result in writing to a new file.

Publish RTSP stream for recording:

ffmpeg -re -i "./videos/awesome-video.mp4" -f mpegts "rtsp://127.0.0.1/live.sdp"

 

Query parameters
recording_name
string | required | unique

Unique process name

recording_type
string | required

Recording input type. The following types are supported:

  • RECORDING_STREAM_TO_FILE - record stream as file to disk.
  • RECORDING_STREAM_TO_MEMORY - record stream as sequence in memory (only for advanced usage).
input
object | required

Accepts an object with specified input parameters.

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 a video, but you need a test video/audio stream

{ input_type: "INPUT_TYPE_GENERATE_TEST_VIDEO" } 

It generate a default test stream (1920 by 1080, 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 } 

output_format
string | required

Format of the recording. Possible values:

  • mp4
  • mov
  • avi
  • flv
active
boolean | optional

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

Create a recording task
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/recording/create' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "recording_name": "Awesome recorded stream",
  "recording_type": "RECORDING_STREAM_TO_FILE",
  "input": {
    "input_type": "INPUT_TYPE_RTSP_URL",
    "input_stream_url": "rtsp://127.0.0.1/live.sdp"
  },
  "output_format": "mp4",
  "active": true
}'
Response
id
ObjectId | unique

A unique identifier of the recording process. Is an object and looks similar to the hashed string. 

created
date

Returns the creation date of the recording process

Response: Create a recording task
JSON
{
  "id": "622e2f97f678990032d434b4",
  "created": "2022-03-12T12:36:03.890Z"
}
Updating the recording task
Expand
POST
/api/recording/update

Use this method to change the recording task.

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

 

Query parameters
id
ObjectId | required

id - identifier of the recording process to be changed.

Updating the recording task
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/recording/update' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "622e2f97f678990032d434b4",
  "recording_name": "Awesome recorded stream MOV",
  "recording_type": "RECORDING_STREAM_TO_FILE",
  "input": {
    "input_type": "INPUT_TYPE_RTSP_URL",
    "input_stream_url": "rtsp://127.0.0.1/live.sdp"
  },
  "output_format": "mov",
  "active": true
}'
Response
id
ObjectId

A unique identifier of the process

updated
date

Returns the date of the process was last modified

success
boolean

Success result. Possible value: true or false.

Response: Updating the recording task
JSON
{
  "success": true
}
Starting the recording
Expand
POST
/api/recording/start

Use this method to start the recording.

Query parameters
id
ObjectId | required

id - identifier of the recording process to be started.

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

Success result. Possible value: true or false.

Response: Starting the recording
JSON
{
  "success": true
}
Stopping the recording
Expand
POST
/api/recording/stop

Use this method to stop the recording.

Query parameters
id
ObjectId | required

id - identifier of the recording process to be stopped.

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

Success result. Possible value: true or false.

Response: Stopping the recording
JSON
{
  "success": true
}
Getting a list the recording processes
Expand
POST
/api/recording/getAll

Use this method to get a list the recording process

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

Returns an array of the recording processes

Response: Getting a list the recording processes
JSON
[
  {


    "id": "622e2f97f678990032d434b4",
    "recording_name": "Awesome recorded stream MOV",
    "recording_type": "RECORDING_STREAM_TO_FILE",
    "output_format": "mov",
    "active": true,
    "created": "2022-03-13T17:53:27.614Z",
    "recordedFiles": [],
    "modified": "2022-03-13T18:28:54.236Z"
  }
]
Getting the recording info by ID
Expand
POST
/api/recording/getById

Use this method to get information about the recording task.

Query parameters
id
ObjectId | required

id - identifier of the recording process

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

Returns an object of the recording process

Response: Getting the recording info by ID
JSON
{
  "id": "622e2f97f678990032d434b4",
  "recording_name": "Awesome recorded stream MOV",
  "recording_type": "RECORDING_STREAM_TO_FILE",
  "output_format": "mov",
  "active": true,
  "created": "2022-03-13T17:53:27.614Z",
  "recordedFiles": [],
  "modified": "2022-03-13T18:28:54.236Z"
}
Getting the recording statistics
Expand
POST
/api/recording/getStat

Use this method to get the statistics of the recording processes

Query parameters
This method has no parameters
Getting the recording statistics
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/recording/getStat' \
  -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 recording statistics
JSON
[
  {
     id: ObjectId,
     bitrate: 6500
  }
]
Removing the recorded file
Expand
POST
/api/recording/removeFile

Use this method to remove the recording file

Query parameters
record_id
ObjectId | required

record_id - identifier of the recording process

file_id
ObjectId | required

file_id - identifier of the file

Removing the recorded file
cURL
curl -X 'POST' \
  'http://1.2.3.4/api/recording/removeFile' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "record_id": "StringObjectId",
  "file_id": "StringObjectId"
}'
Response
success
boolean

Success result. Possible value: true or false.

Response: Removing the recorded file
JSON
{
  "success": true
}
Remove the recording
Expand
DELETE
/api/recording/remove

Use this method to remove the recording task.

Query parameters
id
ObjectId | required

id - identifier of the recording process to be removed.

Remove the recording
cURL
curl -X 'DELETE' \
  'http://1.2.3.4/api/recording/remove' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyMGJlYjA2MTM3YmIzMDAyYzhmNjAwYSIsImlhdCI6MTY0Njc0Njk4MiwiZXhwIjoxNjQ5MzM4OTgyfQ.qRphsD6OD8KYnRL5fUX8XEckp1XNCmZAYldWWnZbAxE' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "622e2f97f678990032d434b4"
}'
Response
success
boolean

Success result. Possible value: true or false.

Response: Remove the recording
JSON
{
  "success": true
}