Restreams
Restreams are Callaba Engine live pipeline jobs. Use this API when an existing live input must be forwarded, transformed, repackaged, protocol-bridged, or connected into another module as a managed running process.
Choose Restreams when the team needs job-level control over how live media moves after ingest. Use ingest modules or server endpoints when you are defining how contribution enters the platform, and use SRT routes when you only need a transport path rather than a managed processing pipeline.
This API covers the full operating cycle: create the job, start and stop the live pipeline, inspect job objects, track fleet visibility, and check live statistics to confirm the stream is healthy in production. Operator-driven examples below also include vMix Script tabs for workflow automation.
Live restream runtime preview
getStat is the fastest process-level check once a restream job is already running. It answers a narrower operational question than the full job object: is media still moving through this bridge right now, and do bitrate and frame cadence still look believable.
The preview below mirrors the same runtime fields documented for getStat. Use it as a quick visual reference when an output destination was restarted, the upstream source changed, or the job configuration still looks correct but the live pipeline needs proof of motion.
See how a live restream job is behaving right now
This preview mirrors the same process fields exposed by getStat for a running restream: current bitrate and frame cadence. It is the fastest check when the saved job looks correct but the live bridge still needs proof of motion.
bitrate_kbits
Previewing the same runtime signal operators usually inspect first.
1,842 kbits/s
Process-level throughput reported by getStat while the restream job is active.
30.0
Frame cadence is the fastest way to spot whether the bridge still looks believable.
running
The saved object can exist while the live process is unhealthy. This preview focuses on runtime state instead.
stable
A simple operational read derived from current bitrate and cadence.
This panel visualizes the same runtime shape documented for getStat. In production, teams usually look here right after a destination restart or an upstream source swap.
This runtime check becomes especially useful when one source is feeding multiple outputs over time. The saved job can still exist in the list while the actual live bridge no longer behaves the way the show expects.
Examples by preset
The most useful presets for this module are not transport families alone, but repeatable workflow shapes: take one live source, send it somewhere new, and keep enough control in the middle to make that handoff safe for production.
SRT URL to RTMP output
{
"restream_name": "SRT to RTMP social output",
"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": "SRT to RTMP social output",
"module_name": "MODULE_RESTREAM"
},
"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": "Disabled",
"output_audio_bitrate": 128,
"sample_rate": 44100
},
"output": {
"output_type": "OUTPUT_TYPE_OTHER_RTMP_URL",
"application": "IO_APPLICATION_FFMPEG",
"output_stream_url": "rtmp://a.rtmp.youtube.com/live2/example-stream-key",
"output_stream_listen_port": {},
"output_settings": {},
"output_stream_key": "",
"entity_name": "SRT to RTMP social output",
"module_name": "MODULE_RESTREAM"
},
"modify_audio": {
"type": "DISABLED",
"channel": "1,2",
"track": "0"
},
"modify_video": {
"type": "DISABLED"
},
"overlay": {
"type": "DISABLED",
"position": {
"x": 1,
"y": 1
}
},
"active": true
}SRT URL to SRT output
{
"restream_name": "SRT bridge to another SRT destination",
"input": {
"input_type": "INPUT_TYPE_SRT_URL",
"application": "IO_APPLICATION_FFMPEG",
"input_stream_url": "srt://127.0.0.1:1936",
"input_stream_listen_port": {},
"input_settings": {},
"input_module_id": "",
"input_stream_id": "",
"entity_name": "SRT bridge to another SRT destination",
"module_name": "MODULE_RESTREAM"
},
"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": "Disabled",
"output_audio_bitrate": 128,
"sample_rate": 44100
},
"output": {
"output_type": "OUTPUT_TYPE_SRT_URL",
"application": "IO_APPLICATION_FFMPEG",
"output_stream_url": "srt://127.0.0.1:2035",
"output_stream_listen_port": {},
"output_settings": {},
"output_stream_key": "",
"entity_name": "SRT bridge to another SRT destination",
"module_name": "MODULE_RESTREAM"
},
"modify_audio": {
"type": "DISABLED",
"channel": "1,2",
"track": "0"
},
"modify_video": {
"type": "DISABLED"
},
"overlay": {
"type": "DISABLED",
"position": {
"x": 1,
"y": 1
}
},
"active": true
}HLS input to null output
{
"restream_name": "HLS playback probe",
"input": {
"input_type": "INPUT_TYPE_HLS_URL",
"application": "IO_APPLICATION_FFMPEG",
"input_stream_url": "https://example.com/live/index.m3u8",
"input_stream_listen_port": {},
"input_settings": {},
"input_module_id": "",
"input_stream_id": "",
"entity_name": "HLS playback probe",
"module_name": "MODULE_RESTREAM"
},
"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": "Disabled",
"output_audio_bitrate": 128,
"sample_rate": 44100
},
"output": {
"output_type": "OUTPUT_TYPE_DEV_NULL",
"application": "IO_APPLICATION_FFMPEG",
"output_stream_listen_port": {},
"output_settings": {},
"output_stream_key": "",
"entity_name": "HLS playback probe",
"module_name": "MODULE_RESTREAM"
},
"modify_audio": {
"type": "DISABLED",
"channel": "1,2",
"track": "0"
},
"modify_video": {
"type": "DISABLED"
},
"overlay": {
"type": "DISABLED",
"position": {
"x": 1,
"y": 1
}
},
"active": true
}Workflow examples
These scenarios frame why a restream job exists in a production design, not only how the request body is shaped.
Use a restream job when one source should feed multiple delivery plans over time
Create a restream when the source side should stay stable, but the output side may move between social platforms, RTMP destinations, SRT outputs, or local monitoring targets later.
- Why it helps: the pipeline object keeps input, processing, and output together.
- Typical fit: SRT to social distribution, transport bridging, or one-off destination changes during operations.
Use a restream job when transcoding or media modification belongs in the pipeline
The restream module is the place where transcoding, audio modification, video modification, and overlays are attached to the flow.
- Processing layer:
transcoding,modify_audio,modify_video, andoverlay - Typical fit: destination-specific bitrate changes, repackaging, branded overlays, and operator-side media adjustments.
Use a restream job when you need a live process object rather than only a static route
Restreams deserve their own runtime controls because teams often care less about the saved row and more about whether the live bridge is actually healthy, producing output, and ready for the next destination.
- Why it helps: the same job object can be provisioned, started, stopped, and observed over time.
- Operational fit: demos, recurring social outputs, active bridge jobs, and monitored media workflows.
Creates a new restream job in Callaba Engine.
This method creates one managed media pipeline. In practice, that means the team can define where the signal comes from, what should happen to it on the way through, and where it should go next inside one saved restream job.
The payload is broad because real restreams are broad: source choice, destination choice, optional transcoding, optional audio or video changes, and optional overlays all belong to the same production decision.
Authentication uses the dashboard-issued JWT token in the x-access-token header.
Examples by preset
The examples below are grouped by operational presets rather than by one oversized catch-all payload. That makes them much easier to copy into a real integration or operator workflow.
Workflow-oriented use cases
Use a restream job when you want the source, processing rules, and destination to live inside one managed pipeline object.
- Good fit for: SRT-to-social delivery, transport conversion, republishing, transcoding, overlays, and destination-specific output profiles.
- Not the same as: a fixed ingest boundary like
SRT serversorRTMP servers.
Use this preset when one incoming SRT contribution should be forwarded to an RTMP destination such as a social platform or another managed RTMP target.
This is the most recognizable restream workflow: ingest on SRT, keep transcoding disabled or minimal, and push the result to an RTMP output.
Use this preset when the job should bridge one SRT source into another SRT destination while preserving the pipeline as a managed process object.
This is useful when the ingest side and the delivery side should remain decoupled but still live inside one active restream job.
Use this preset when you want to read from HLS as an input and run the media pipeline for monitoring, testing, or measurement without forwarding the output to another delivery target.
This shape comes directly from the testing tools and is a good reminder that restream jobs are also used for controlled playback and probe workflows.
Human-readable job name. The dashboard validates this as a required field.
Input definition built by the dashboard InputSource controls. This object determines the source transport or module connection.
Output definition built by the dashboard OutputSource controls. This object determines where the pipeline pushes or exposes the result.
Optional transcoding profile used by the FFmpeg pipeline. The dashboard always submits this block, even when transcoding is disabled.
Optional audio modification settings. The dashboard sends a disabled-state object when no audio modification is requested.
Optional video modification settings. This can remain in a disabled state for pass-through jobs.
Optional overlay settings. The create flow can still send an explicit disabled overlay object.
Controls whether the job should be active after provisioning.
Mongo-style identifier of the restream job.
Convenience alias for _id.
Name stored for the restream job.
Populated linked input object or objects for the pipeline.
Populated linked output object or objects for the pipeline.
Processing settings stored on the job object.
Current enabled state of the restream job.
Timestamps managed by the backend.
The model exposes success: true as a virtual field in successful responses.
Returns the number of restream jobs visible to the authenticated user.
This is the lightweight companion to getAll when the dashboard or your integration needs list pagination or filtered counters.
Total number of restream jobs currently visible to the authenticated user.
Returns the list of restream jobs visible to the authenticated user.
The backend populates the linked input and output objects, so this method is useful when you need a full list view rather than only ids and names.
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 populated array of restream jobs, not a wrapped object.
Returns one restream job with the linked input and output objects populated.
This is the method to use when you need the fully expanded pipeline shape after provisioning or before editing the job.
Identifier of the restream job you want to load.
The backend returns the fully populated job object with linked input and output records.
Updates an existing restream 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 restream job being updated.
The update contract mirrors create and reuses the same validation and pipeline regeneration path.
The backend returns the updated job object together with success: true.
Starts a restream job by id.
The service marks the job as active, cancels any previous runtime instance for the same id, and then runs the pipeline again using the current input/output/transcoding configuration.
Identifier of the restream job to start.
The backend marks the job as active and returns the populated job object.
Stops a restream job by id.
The backend marks the job as inactive and cancels the running process. This is the operational counterpart to start.
Identifier of the restream job to stop.
The backend marks the job as inactive and returns the populated job object.
Removes a restream job by id.
This operation also stops the running process and removes the linked input/output objects created for the pipeline.
Identifier of the restream job to delete.
The backend removes the job and linked IO records, while returning the previously loaded restream object.
Returns current process statistics for active restream jobs.
Use this when the team needs a live answer about restream health: is the process moving media, what bitrate it is producing, and whether the pipeline still looks stable enough to trust during the event.
Current per-process statistics used by the dashboard polling layer.
Ingress-worker bitrate metric when that runtime path is active.
Current FPS metric when the runtime reports it.