Recordings
The Recordings section covers the API endpoints used to create, run, monitor, and manage file-based recording jobs in Callaba Engine. This is the layer you use when one live input should be captured to disk as a durable archive, segmented recording, or output-format-specific file workflow.
Compared with Restreams, a recording job ends in stored media rather than another live destination. It still uses a live input pipeline, optional transcoding, optional audio or video modifications, and overlay controls, but the end goal is much more practical: produce the right files, in the right format, on the right schedule.
The operational methods matter because recording is rarely just “save a config and forget it.” Teams need to start and stop capture on time, inspect which files were actually produced, remove the wrong file without deleting the whole job, and check progress when a running recorder is part of a real event.
This module is useful both for setup and for operations. In practice, teams care about whether recording is active, whether the live signal still looks healthy, and whether the expected files are actually being produced while the event is in progress.
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 process signals
When a recording job is fed from an SRT contribution, teams often want one fast visual check before digging into the full job object: is the live source still moving, is bitrate present, and does buffering still look healthy.
The compact demo below reuses the same live SRT statistics stream we expose elsewhere in the docs. It is most helpful when a recording depends on a live SRT contribution and you want a quick operational read before or alongside getStat.
See live SRT stats as a moving chart
This demo shows the kind of live statistics you can watch during a real contribution: bitrate, buffer delay, packet flow, receive capacity, and active streams. It is connected to the public demo endpoint at demo.callaba.io and updates from the same live event stream used by the product.
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.
Returns the number of recording jobs visible to the authenticated user.
This is the lightweight companion to getAll when the dashboard or your integration needs pagination, list counters, or filtered archive counts.
Total number of recording jobs currently visible to the authenticated user.
Returns the list of recording jobs visible to the authenticated user.
The backend populates related recordedFiles, so this method is useful when you need a list view that includes the file lifecycle rather than only job ids and names.
This is the natural companion to the dashboard listing, where teams scan job name, current live bitrate, current FPS, creation time, and the number of files already attached to each recording.
Optional page size for the list query.
Optional offset for paginated listing.
Optional sort descriptor. The dashboard store defaults to { created: 1 }.
Optional filter object forwarded to the backend query.
The backend returns a bare array of recording jobs, not a wrapped object.
Returns one recording job with its linked input object and recorded files populated.
This is the method to use when you need the fully expanded job shape before editing, troubleshooting, or cleaning up one file from the recording output.
Identifier of the recording job you want to load.
The backend returns the populated recording job object with linked input and recorded files.
Updates an existing recording job by id.
The backend reuses the same validation path as create, so the update payload mirrors the create payload with the addition of id.
Identifier of the recording job being updated.
The update contract mirrors create and reuses the same validation plus worker-regeneration path.
The backend returns the updated job object together with success: true.
Starts a recording job by id.
The service marks the job as active, stops any previous worker for the same recording id, and then runs the recording pipeline again using the current input, format, and processing configuration.
Identifier of the recording job to start.
The backend marks the job as active and returns the recording object.
Stops a recording job by id.
The backend marks the job as inactive and stops the running recording worker. This is the operational counterpart to start.
Identifier of the recording job to stop.
The backend marks the job as inactive and returns the recording object.
Removes a recording job by id.
This operation also stops the worker, removes the linked input object, and deletes the files produced by the recording process.
Identifier of the recording job to delete.
The backend stops the worker, removes linked input and file records, and returns the previously loaded recording object.
Removes one recorded file from a recording job.
Use this when you want to keep the recording job itself but delete a specific file that was produced by it.
Identifier of the parent recording job.
Identifier of the recorded file that should be deleted.
The backend returns { success: true } when the file was removed from storage and detached from the recording job.
Returns current process statistics for active recording jobs.
The dashboard uses this method to poll live FFmpeg progress data every 3 seconds. Depending on the worker state, the response can include fields such as bitrate, bitrate_kbits, fps, out_time_ms, speed, and progress.
In practice, this is the method behind the operator-facing live recording indicators: current bitrate, current FPS, and whether the worker is still progressing through output time as expected.
Current per-process statistics used by the dashboard polling layer.
Current FFmpeg-reported bitrate and a normalized integer bitrate_kbits field.
Current frames-per-second progress value when FFmpeg reports it.
Current processed output time in milliseconds.
Current FFmpeg processing speed, for example 1.00x.
FFmpeg progress status such as continue or end.