Stream recordings

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 "}" data-sheets-userformat="{"2":769,"3":{"1":0},"11":4,"12":0}">This page provides methods for recording the streams to the server's disk. 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 Create a Virtual Events Platform Setup CloudFront CDN for Live Events. Part I.

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

For implementation details, continue with How to assign transcoding to Alveo™ U30 accelerator card and How to add streaming overlays easily and for free. For this workflow, teams usually combine 24/7 streaming channels, Ingest & route, and Paywall & access.

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

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Vimeo Pro and Best podcast recording software.

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: For production ingest and monitoring, see continuous streaming. For playback integration and analytics, use video api. Recommended product path: Ingest & route, Player & embed, Calls & webinars. For this workflow, Player & embed is the most direct fit., and scaling guide. For implementation details, continue with Players. input and Restreaming. input. For implementation details, continue with How to generate Test Videos to test your setups and How to transform UDP feed from a CCTV camera into RTMP [Part 1]. Before full production rollout, run a Test and QA pass with streaming quality check and video preview. For this workflow, Paywall & access is the most direct fit.

{ input_type: "INPUT_TYPE_SRT_SOFTWARE", input_module_id: "ID of SRT server", input_stream_id: "streamID(optional)" }

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 Pricing path: validate with bitrate calculator, self hosted streaming solution, and AWS Marketplace listing.

 

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

{ input_type: "INPUT_TYPE_RTMP_SOFTWARE" input_module_id: "RTMP Server ID", input_stream_id: "rtmp_stream_key" }

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

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with How to live stream 24/7 on Youtube? and Rtmp.

active
boolean | optional

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

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Players. active and Restream. active. For implementation details, continue with Create a Virtual Events Platform Setup CloudFront CDN for Live Events. Part I and Restream Io.

Create a recording task
cURL
curl -X 'POST' \
  'http://localhost/api/recording/create' \
  -H 'accept: application/json' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY3MDgyNzU1ZGYxZTNkZTljZjY3M2VmOSIsImlhdCI6MTcyODU4NzYwNSwiZXhwIjoyMDQ0MTYzNjA1fQ.g7NZJznrLm3r3TvG1VXiXtTFwB5FJBw-lwOO-F6JqoQ' \
  -H 'Content-Type: application/json' \
  -d '{
  "recording_name": "Awesome recorded stream",
  "recording_type": "RECORDING_STREAM_TO_FILE",
  "input": {
    "input_type": "INPUT_TYPE_SRT_SOFTWARE",
    "input_module_id": "670fe44e12a2054e88a0457f",
    "input_stream_id": ""
  },
  "transcoding": {
   "video_transcoding": "Disabled",
   "audio_transcoding": "Disabled"
  },
  "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. 

For this workflow, teams usually combine Video platform API, Calls & webinars, and Player & embed. For this workflow, 24/7 streaming channels is the most direct fit. For implementation details, continue with Players response Create. id and recording response getById object. For implementation details, continue with How to organize live media production and Video Hosting.

created
date

Returns the creation date of the recording process

For implementation details, continue with Creating a Test App to manage Callaba Engine on AWS using a RESTful API and Digital Product Trends for 2023. For this workflow, Video platform API is the most direct fit. For this workflow, teams usually start with Calls & webinars and combine it with Player & embed. 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.

Response: Create a recording task
JSON
{
  "id": "622e2f97f678990032d434b4",
  "created": "2022-03-12T12:36:03.890Z",
"success": "true"
}
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.

For implementation details, continue with How to create a sales video and Players change id. For this workflow, teams usually combine Video platform API, Calls & webinars, and Player & embed. For implementation details, continue with Players response Create. id and Recording response Create. id. For implementation details, continue with How artificial intelligence helps marketers create video content and Common live streaming problems and how to solve them. For this workflow, 24/7 streaming channels is the most direct fit.

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

For implementation details, continue with Content protection and DRM safeguarding content from piracy and unauthorized access and Players response Create. id.

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

updated
date

Returns the date of the process was last modified

, and scaling guide. For this workflow, teams usually combine Ingest & route, 24/7 streaming channels, and Paywall & access. For implementation details, continue with Players response updated and RTMP servers response server_updated. For implementation details, continue with Common live streaming problems and how to solve them and Create a Virtual Events Platform Setup CloudFront CDN for Live Events. Part I.

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 removeFile success. For implementation details, continue with Restream Io and Video Hosting.

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.

For this workflow, teams usually combine Calls & webinars, Video platform API, and Player & embed. For implementation details, continue with Recording removeFile record_id and Recording response Create. id. For implementation details, continue with Distance learning in post-pandemic times. [Part 2] and Nonstop recording amid stream interruptions. For this workflow, Ingest & route is the most direct fit.

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.

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

For implementation details, continue with Create, edit, start and delete SRT Server or Gateway using Callaba Cloud and Recording change id. For this workflow, Ingest & route is the most direct fit. For implementation details, continue with Recording response getAll array and RTMP servers stop id. For implementation details, continue with Next generation video transcoding via graphics accelerator card with Callaba Cloud and How to live stream 24/7 on Youtube?. For this workflow, teams usually start with 24/7 streaming channels and combine it with Video platform API.

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.

, 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 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

For implementation details, continue with Create, edit, start and delete SRT Server or Gateway using Callaba Cloud and Players response getAll array. For this workflow, Ingest & route is the most direct fit. For implementation details, continue with Creating a Test App to manage Callaba Engine on AWS using a RESTful API and Recording stop id. For this workflow, Video platform API is the most direct fit. For this workflow, Calls & webinars is the most direct fit. 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.

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

For implementation details, continue with Recording change id and Recording remove id.

For implementation details, continue with The Power of 360-Degree Video Immersive Experiences in Video Streaming and Broadcasting and Best cameras for streaming. For this workflow, teams usually combine Paywall & access, 24/7 streaming channels, and Ingest & route.

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

For this workflow, teams usually combine Video platform API, Calls & webinars, and Player & embed. For this workflow, 24/7 streaming channels is the most direct fit. For implementation details, continue with Players response getById object and Recording response Create. id. For implementation details, continue with Drm Protected and Free Cdn.

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)

For this workflow, teams usually combine Video platform API, Calls & webinars, and Player & embed. For this workflow, 24/7 streaming channels is the most direct fit. For implementation details, continue with Players response getStat bitrate and restream response getStat bitrate. For this workflow, Ingest & route is the most direct fit. For implementation details, continue with Video Stream and 16 9 Resolution.

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

For this workflow, teams usually combine Calls & webinars, Video platform API, and Player & embed. For implementation details, continue with Recording response Create. id and Recording start id. For implementation details, continue with Obs Live and Video Hosting.

file_id
ObjectId | required
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.

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

For implementation details, continue with Content protection and DRM safeguarding content from piracy and unauthorized access and Recording change id.

For implementation details, continue with Players getById id and Players change id.

For implementation details, continue with What is DRM and how it works in Live Video Streaming and Common live streaming problems and how to solve them. For this workflow, teams usually combine Paywall & access, 24/7 streaming channels, and Ingest & route.

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.

, 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 response change success and Recording response removeFile success. For implementation details, continue with Restream Io and Video Hosting.

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