Recordings
Use Recordings to capture a live input as a continuous file or timed segments for archive, replay, compliance, or post-production.
Choose this whenA live source must become a continuous or segmented file.
Use another module whenUse Files when media is already stored; use Restreams when the output must stay live.
/api/recording/createBefore you start
All methods require a valid x-access-token. Create or verify the input first, confirm local disk capacity, select the output format, and define any retention setting before the event.
What you can do
createandupdateconfigure input, format, recording mode, processing, and retention.getAll,getCount, andgetByIdinspect jobs and produced artifacts.startandstopcontrol capture.getStatreports available bitrate, frame cadence, encode speed, and output progress.removeFiledeletes one produced file without removing the job.removedeletes the recording job.
Example workflow
- Create a job from an SRT server, RTMP server, video-call source, or supported stream URL.
- Select MP4, HLS, or another supported output format and continuous or time-split mode.
- Start the job before the required capture window.
- Use
getStatto confirm input bitrate and output time continue to advance. - Stop the job, verify the files, and copy them to configured storage.
Common use cases
- Create a continuous program archive for a live event.
- Split a long surveillance or broadcast recording into predictable intervals.
- Record a compatible RIST contribution feed for archive or replay.
- Keep a backup recording with automatic age-based cleanup.
Limits and troubleshooting
A recording needs a healthy live input plus enough disk and processing capacity. Monitor input bitrate and recording progress while it runs, verify the produced files before cleanup, and test any RIST source with the required profile and security settings before the event.
Next steps
Use Files to inspect or transfer the result and Storages to configure durable off-instance retention.
Record a live input continuously or in segments
Create a recording from a healthy live source, choose continuous or timed output, start capture, and monitor progress.
- Create the recordingChoose the source, format, recording mode, processing, and retention.
POST /api/recording/create - Start captureStart only after the source and storage path are ready.
POST /api/recording/start - Monitor progressWatch bitrate, frame cadence, encode speed, and output progress.
POST /api/recording/getStat
Confirm disk capacity and retention before the event. Verify produced files before automated deletion or off-instance transfer.
Turn a completed live capture into on-demand browser playback
Capture the event, stop the recording cleanly, read the completed file from recordedFiles, then create and validate a browser player from the matching managed-file input preset.
- Create the live captureSelect the live input, a browser-compatible archive format, and a retention policy.
POST /api/recording/create - Start the event recordingStart capture after the source is healthy and storage capacity is confirmed.
POST /api/recording/start - Finalize the captureStop the worker at event end so the output can be finalized before playback.
POST /api/recording/stop - Resolve the completed fileReload the recording and select a completed entry from recordedFiles for the player handoff.
POST /api/recording/getById - Create on-demand playbackUse the matching managed-file input preset, then configure access, delivery, and presentation.
POST /api/vod/create - Start the VOD playerStart the player only after the recorded file is finalized and available.
POST /api/vod/start - Validate browser deliveryCheck process progress and viewer delivery, then test the generated URL in representative browsers.
POST /api/vod/getStat
Do not publish a file that is still being written. Stop the recording, load the recording resource, choose a completed recordedFiles entry, and keep that file managed for as long as the player depends on it.
Record a live source and copy the finished file to object storage
Register the storage destination, capture the live source, finalize the recording, resolve its recordedFiles entry, and copy the resulting managed file to the reviewed target.
- Register object storageCreate the reviewed S3 or Backblaze target with its bucket and metadata configuration.
POST /api/storages/create - Verify the saved targetConfirm the non-secret destination fields and retain its id for the copy operation.
POST /api/storages/getById - Create the capture jobSelect the reviewed live input preset, output format, segmentation, and retention behavior.
POST /api/recording/create - Start captureStart only after the upstream source is healthy and local capacity has been checked.
POST /api/recording/start - Monitor the recording workerWatch bitrate, FPS, progress, and process state while media is being written.
POST /api/recording/getStat - Finalize the outputStop the recording cleanly before treating the produced file as transferable.
POST /api/recording/stop - Resolve recordedFilesReload the job and select the finalized managed-file identity from recordedFiles.
POST /api/recording/getById - Copy to the target storageSend the file id with the reviewed storage type and storage id, then follow the documented progress call.
POST /api/files/copyTo
Storage credentials are write-only operational secrets. Stop and reload the recording before using a recordedFiles id, and monitor copy progress instead of assuming that a successful request means the remote transfer is complete.
Create a managed recording job with its source, output format, clip behavior, optional processing, retention settings, and initial active state. Send the dashboard-issued JWT in the x-access-token header.
Supported sources include SRT and RTMP servers, video-call rooms or participants, and URL inputs such as HLS, MPEG-DASH, RTSP, RTP, UDP, and RIST. For a RIST URL, use INPUT_TYPE_RIST_URL and set input_stream_url.
Request examples
Choose the preset that matches the desired archive format and capture behavior, then add only the processing options required by the output.
Common use cases
- Capture a complete event as MP4 for archive or post-production.
- Create time-split files for long-running or continuous inputs.
- Record HLS output for a file-based playback workflow.
After the job starts, use getStat for bitrate, FPS, and progress, and inspect recordedFiles for produced output.
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. URL-based RIST capture uses INPUT_TYPE_RIST_URL with input_stream_url through the shared I/O input path.
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.
Resource id returned when you create or list 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.