Search the module, then move faster through the API
Find the exact module, copy the working request shape, and move from product workflow to API call without getting buried in the tree.
AI workflow helperDescribe what you want to buildOptional tool
Write the workflow in plain language. We will turn it into a GPT-ready brief you can use to generate requests, module order, and starter payloads.
Recordings
Find an endpoint
The Recordings section covers the API endpoints for production recording jobs in Callaba Engine: managed jobs that take a live source, optionally process it, and write durable media outputs for archive, compliance, replay prep, or segmented post-event workflows.
Choose Recordings when the outcome you care about is stored media: the right files, in the right format, created at the right time, and available for operators to inspect or clean up during and after an event.
Choose Restreams instead when the same live input should be sent onward to another live destination. Both modules can use the same kinds of inputs and can apply transcoding, audio or video modifications, and overlays, but they serve different operational goals: Restreams is for live delivery, while Recordings is for managed file creation and retention.
- Use this module to control capture windows: create jobs ahead of time, then start and stop them from automation or an operator position.
- Use this module to monitor active recordings: check whether a recorder is running, whether the incoming live signal still looks healthy, and whether output is progressing as expected.
- Use this module to manage recorded artifacts: review produced files, remove the wrong file without deleting the whole job, and keep archive workflows operationally clean.
This makes the module useful not only for setup, but for real-time production operations where teams need confidence that a live contribution is still being captured and that the expected files will exist when the event ends.
If your team starts and stops recording jobs from a live operator position, the create, start, and stop examples below also include ready-to-adapt vMix Script tabs.
Live recording runtime preview
getStat is where a recording job becomes operational instead of merely configured. It is the fastest check for whether media is still arriving, whether encode speed is keeping up with the event, and whether output time is still advancing the way the archive plan expects.
The preview below mirrors the same runtime fields documented for getStat: bitrate, frame cadence, encode speed, and output progress. Use it when the main question is not “does the job exist?” but “is this recording still becoming the archive we expect?”
See the signals operators watch while a recording job is running
The getStat response for recordings is more than a simple heartbeat. It tells you whether media is still arriving, whether encode speed is keeping up, and whether output time keeps moving the way the archive plan expects.
bitrate_kbits
Previewing the same runtime signal operators usually inspect first.
1,842 kbits/s
A quick signal that media is still arriving before you inspect produced files.
25.0
Useful when the archive must preserve the same cadence the live source promised.
1.00x
If speed falls behind too far, the recording job may not keep up with a real-time event.
continue
17:00:00 written · 395.6 MB
In practice, operators pair these runtime fields with start and stop controls to confirm that the capture window is still producing a usable archive, not just holding an object in the list.
Examples by preset
The most useful presets for this module are recording workflows rather than transport families alone: one continuous archive, one segmented archive, or one output format selected for playback and storage needs.
These examples keep the input on SRT Stream URL (srt://) for clarity, but the same recording object is also used in the product for SRT server, RTMP server, video call room or participant, and URL-based sources such as HLS, MPEG-DASH, RTSP, RTP, UDP, and RIST.
SRT URL to MP4 archive
{
"recording_name": "Main program archive",
"recording_type": "RECORDING_STREAM_TO_FILE",
"input": {
"input_type": "INPUT_TYPE_SRT_URL",
"application": "IO_APPLICATION_FFMPEG",
"input_stream_url": "srt://127.0.0.1:1935",
"input_stream_listen_port": {},
"input_settings": {},
"input_module_id": "",
"input_stream_id": "",
"entity_name": "Main program archive",
"module_name": "MODULE_RECORDINGS"
},
"output_format": "mp4",
"recording_mode": "RECORDING_MODE_INFINITY",
"recording_mode_settings": {
"hours": 0,
"minutes": 0,
"seconds": 0
},
"transcoding": {
"video_transcoding": "Disabled",
"output_video_bitrate": 6000,
"preset": "ultrafast",
"tune": "Disabled",
"crf": "Disabled",
"pix_fmt": "Disabled",
"encoding_rate": "",
"filter_fps": "",
"gop": "Disabled",
"force_key_frames": 2,
"frame_width": "",
"frame_height": "",
"slices": "",
"cores": "",
"xlnx_hwdev": "0",
"audio_transcoding": "aac",
"output_audio_bitrate": 128,
"sample_rate": 44100
},
"modify_audio": {
"type": "DISABLED",
"channel": "1,2",
"track": "0"
},
"modify_video": {
"type": "DISABLED"
},
"overlay": {
"type": "DISABLED",
"position": {
"x": 1,
"y": 1
}
},
"delete_after": 0,
"active": true
}SRT URL to split-by-time archive
{
"recording_name": "Program segments every 10 minutes",
"recording_type": "RECORDING_STREAM_TO_FILE",
"input": {
"input_type": "INPUT_TYPE_SRT_URL",
"application": "IO_APPLICATION_FFMPEG",
"input_stream_url": "srt://127.0.0.1:1935",
"input_stream_listen_port": {},
"input_settings": {},
"input_module_id": "",
"input_stream_id": "",
"entity_name": "Program segments every 10 minutes",
"module_name": "MODULE_RECORDINGS"
},
"output_format": "mp4",
"recording_mode": "RECORDING_MODE_SPLIT_BY_TIME",
"recording_mode_settings": {
"hours": 0,
"minutes": 10,
"seconds": 0
},
"transcoding": {
"video_transcoding": "Disabled",
"output_video_bitrate": 6000,
"preset": "ultrafast",
"tune": "Disabled",
"crf": "Disabled",
"pix_fmt": "Disabled",
"encoding_rate": "",
"filter_fps": "",
"gop": "Disabled",
"force_key_frames": 2,
"frame_width": "",
"frame_height": "",
"slices": "",
"cores": "",
"xlnx_hwdev": "0",
"audio_transcoding": "aac",
"output_audio_bitrate": 128,
"sample_rate": 44100
},
"modify_audio": {
"type": "DISABLED",
"channel": "1,2",
"track": "0"
},
"modify_video": {
"type": "DISABLED"
},
"overlay": {
"type": "DISABLED",
"position": {
"x": 1,
"y": 1
}
},
"delete_after": 0,
"active": true
}SRT URL to HLS recording
{
"recording_name": "HLS archive output",
"recording_type": "RECORDING_STREAM_TO_FILE",
"input": {
"input_type": "INPUT_TYPE_SRT_URL",
"application": "IO_APPLICATION_FFMPEG",
"input_stream_url": "srt://127.0.0.1:1935",
"input_stream_listen_port": {},
"input_settings": {},
"input_module_id": "",
"input_stream_id": "",
"entity_name": "HLS archive output",
"module_name": "MODULE_RECORDINGS"
},
"output_format": "m3u8",
"recording_mode": "RECORDING_MODE_INFINITY",
"recording_mode_settings": {
"hours": 0,
"minutes": 0,
"seconds": 0
},
"transcoding": {
"video_transcoding": "Disabled",
"output_video_bitrate": 6000,
"preset": "ultrafast",
"tune": "Disabled",
"crf": "Disabled",
"pix_fmt": "Disabled",
"encoding_rate": "",
"filter_fps": "",
"gop": "Disabled",
"force_key_frames": 2,
"frame_width": "",
"frame_height": "",
"slices": "",
"cores": "",
"xlnx_hwdev": "0",
"audio_transcoding": "aac",
"output_audio_bitrate": 128,
"sample_rate": 44100
},
"modify_audio": {
"type": "DISABLED",
"channel": "1,2",
"track": "0"
},
"modify_video": {
"type": "DISABLED"
},
"overlay": {
"type": "DISABLED",
"position": {
"x": 1,
"y": 1
}
},
"delete_after": 0,
"active": true
}Workflow examples
These scenarios frame why a recording job exists in a production design, not only how the request body is shaped.
Use a recording job when a live contribution should become a durable archive
Create a recording when the main goal is to preserve a source stream as a file rather than forward it to another live destination.
- Why it helps: the recorder keeps the source, processing settings, output format, and produced files under one managed job.
- Typical fit: event archive capture, program backup, and operational compliance recording.
Use a recording job when file segmentation matters as much as the source
Recording mode changes the way files are produced. Some workflows need one continuous file, while others need predictable time-based segments for storage, post-production, or downstream automation.
- Key controls:
recording_mode,recording_mode_settings, andoutput_format - Typical fit: long events, auto-rotated archive windows, and HLS-style capture workflows.
This matters in production because some teams need one continuous archive while others need predictable clip boundaries they can review, move, or publish quickly after the event.
Use a recording job when operations need both live process status and stored file management
The module is not only about creating files. It also has lifecycle controls and file cleanup actions through start, stop, getStat, and removeFile.
- Why it helps: one API object covers capture, running state, progress polling, and the resulting recorded files.
- Operational fit: recurring productions, rolling capture jobs, and post-event file housekeeping.
That same workflow also includes auto deletion after N days and a product-facing seamless recording feature for maintaining one continuous recording even when a source is interrupted and resumed.
Creates a new recording job in Callaba Engine.
This method creates one managed recording job. In practice, that means choosing the live source, the file shape you need at the end, and the recording behavior that fits the event you are trying to capture.
The payload is intentionally broad because recording decisions are rarely just about starting capture. Teams also decide file format, clip strategy, optional processing, and how much they want the stored output shaped before it lands.
The key production decisions here are easy to state even if the payload is large: what file should come out, whether capture should run continuously or in clips, and how long the result should stay around afterward.
Although the examples below keep the source on SRT Stream URL (srt://) for readability, the same method also supports product-facing inputs such as SRT server, RTMP server, video call room or participant, and URL-driven inputs like HLS, MPEG-DASH, RTSP, RTP, UDP, and RIST.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
Examples by preset
The examples below are grouped by recording presets rather than by one oversized payload. That makes them easier to reuse for real archive and capture workflows.
Workflow-oriented use cases
Use a recording job when the destination should be stored media, not another live endpoint.
- Good fit for: event archives, backup captures, split recordings, HLS recording outputs, and file-based post-event workflows.
- Not the same as: a live transport bridge like
Restreamsor a stable ingest boundary likeSRT servers.
Once the job is running, operators usually care about three things first: whether recording is active, what bitrate and FPS the process is reporting, and how many files have already been produced.
Use this preset when the main goal is one stable archive file from a live SRT contribution.
This is the most common recording shape: preserve the incoming stream as one continuous archive and keep the processing layer minimal.
Use this preset when long captures should be cut into predictable time windows for storage, automation, or post-production.
The recording mode changes from one continuous file to rolling segments while keeping the rest of the capture pipeline largely the same.
Use this preset when the output side should be written as HLS-style media instead of one classic archive container.
This is useful when the stored output format matters for later playback or downstream delivery tooling.
Dashboard label: Name.
Human-readable job name. The dashboard validates this as a required field and uses the same character guidance shown in the UI: A-Z, a-z, 0-9, and -.
The current recording flow uses RECORDING_STREAM_TO_FILE.
Input definition built from the source form. It determines which live source is being captured.
Dashboard label: Output format.
Real product options include mp4, avi, flv, mp3, m3u8, mpegts, and mkv, depending on the selected input protocol.
Dashboard label: Auto Clip Mode.
Controls whether the recorder writes one continuous file or splits output by time. The real modes are RECORDING_MODE_INFINITY and RECORDING_MODE_SPLIT_BY_TIME.
Used with split-by-time mode. The dashboard sends hours, minutes, and seconds, and presents this as a drag-and-drop timing control.
Optional transcoding profile for the FFmpeg worker. The dashboard still sends this block when transcoding is disabled.
Optional audio modification settings. Disabled-state objects are still part of the normal payload shape.
Optional video modification settings.
Optional overlay settings for branded or annotated recordings.
Dashboard label: Auto deletion after.
Optional auto-deletion horizon in days. 0 means no automatic deletion, and the default UI guidance keeps 0 as the normal disabled state.
Dashboard label: Enable once created.
Controls whether the recording worker should be active after provisioning.
Mongo-style identifier of the recording job.
Convenience alias for _id.
Name stored for the recording job.
Recording type returned by the backend.
Linked input object or objects used by the capture pipeline.
Stored output format for the recording.
Recording mode and any split-by-time settings stored on the job object.
Processing settings attached to the recording job.
Recorded files already linked to the job. This becomes especially important for finished or segmented captures.
Auto-deletion setting in days.
Current running-state flag for the recording job.
Timestamps managed by the backend.
The model exposes success: true as a virtual field in successful responses.