> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a Stream
> Update a stream's configuration or apply live adjustments, including turning dubbing on and off, without recreating it.
## Overview
Partially updates an existing stream. Send only the fields you want to change.
Updates are allowed while the stream is scheduled, setting up, or started.
There are two kinds of changes:
* **Configuration updates** - rescheduling, replacing voices or dictionaries,
and adding or modifying audio selections, profiles, pipelines, and targets.
These are persisted into the stream configuration.
* **Live pipeline patches** (`pipeline_patches`) - runtime-only adjustments to
a running stream: turn dubbing on or off, adjust the dubbing mix, or nudge
audio/video sync. These take effect within seconds and are not persisted.
List fields that carry `id`s (`audio_selections`, `processing_profiles`,
`encoding_profiles`, `pipelines`, `target_streams`) are **merged by `id`**:
entries you send are added or replaced as a whole, and existing entries are
never removed.
You can paste a full JSON body into the **Try it** form and the fields fill
in automatically - copy any example below as a starting point.
## Turning dubbing on and off
Set `dubbing_enabled` on a pipeline patch. With `false`, dubbing pauses and
the original audio passes through; with `true`, dubbing resumes.
```bash cURL (pause dubbing) theme={null}
curl -X PATCH "https://client.camb.ai/apis/stream/1234" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pipeline_patches": [
{ "pipeline_id": "spanish", "dubbing_enabled": false }
]
}'
```
```python Python (reschedule) theme={null}
import requests
payload = {
"start_time": "2026-08-01T11:00:00Z",
"end_time": "2026-08-01T13:00:00Z",
"timezone": "UTC",
}
response = requests.patch(
"https://client.camb.ai/apis/stream/1234",
headers={"x-api-key": "YOUR_API_KEY"},
json=payload,
)
response.raise_for_status()
print(response.json())
```
```python Python (adjust the live mix) theme={null}
import requests
payload = {
"pipeline_patches": [
{
"pipeline_id": "spanish",
"mixing": {
"original_audio_gain": 0.1,
"background_audio_gain": 0.8,
},
}
]
}
response = requests.patch(
"https://client.camb.ai/apis/stream/1234",
headers={"x-api-key": "YOUR_API_KEY"},
json=payload,
)
response.raise_for_status()
print(response.json())
```
## Common updates
| Goal | Fields to send |
| ----------------------------- | ----------------------------------------------------------------------- |
| Pause / resume dubbing | `pipeline_patches[].dubbing_enabled` |
| Adjust the dubbing mix live | `pipeline_patches[].mixing` gains (0.0–1.0) |
| Fix audio/video sync live | `pipeline_patches[].avsync.delay` (−2.0 to 2.0 s) |
| Reschedule | `start_time`, `end_time`, `timezone` |
| Change voices or dictionaries | `voices`, `dictionaries` |
| Add a target language | a new entry in `pipelines` (and its target) |
| Add or repoint an output | `target_streams` entry with the same `id` (replace) or a new `id` (add) |
## Errors
* `400` - The stream has already finished and can no longer be updated.
* `404` - No stream with this ID belongs to your team.
* `422` - Validation error: unknown `pipeline_id`, an `id` reference that
doesn't resolve, or times without a matching `timezone`.
## Related endpoints
* [Create a Stream](create-new-stream)
* [Get Stream Status](get-stream-status)
* [Delete a Stream](delete-stream)
## OpenAPI
````yaml patch /stream/{stream_id}
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://client.camb.ai/apis
security: []
paths:
/stream/{stream_id}:
patch:
tags:
- Apis
- Streaming
summary: Update Stream
description: >-
Update a stream's configuration (merged by `id`, never removing existing
entries) and apply live runtime adjustments such as toggling dubbing on
or off. Allowed while the stream is scheduled, setting up, or started.
operationId: patch_stream_data_stream__stream_id__patch
parameters:
- name: stream_id
in: path
required: true
schema:
type: integer
title: Stream Id
description: Identifier of the stream to update.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateStreamDataRequestPayload'
example:
pipeline_patches:
- pipeline_id: spanish
dubbing_enabled: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Patch Stream Data Stream Stream Id Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
UpdateStreamDataRequestPayload:
type: object
title: UpdateStreamDataRequestPayload
description: >-
Partial update of a stream. All fields are optional; omit anything you
do not want to change. List fields carrying `id`s (`audio_selections`,
`processing_profiles`, `encoding_profiles`, `pipelines`,
`target_streams`) are merged by `id`: entries you send are added or
replaced, existing entries are never removed.
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: New display name.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: New description.
initial_delay:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
title: Initial Delay
description: New setup lead time in seconds.
voices:
anyOf:
- type: array
items:
type: integer
- type: 'null'
title: Voices
description: >-
Replacement list of voice IDs. Empty means voices are cloned from
the source speakers.
dictionaries:
anyOf:
- type: array
items:
type: integer
maxItems: 5
- type: 'null'
title: Dictionaries
description: Replacement list of dictionary IDs (up to 5).
start_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Start Time
description: New scheduled start (ISO 8601 with UTC offset). Requires `timezone`.
end_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: End Time
description: New scheduled end (ISO 8601 with UTC offset). Requires `timezone`.
timezone:
anyOf:
- type: string
- type: 'null'
title: Timezone
description: IANA time zone the updated times are expressed in.
audio_selections:
anyOf:
- type: array
items:
$ref: '#/components/schemas/AudioSelection'
- type: 'null'
title: Audio Selections
description: Audio selections to add or replace (merged by `id`).
processing_profiles:
anyOf:
- type: array
items:
$ref: '#/components/schemas/ProcessingProfile'
- type: 'null'
title: Processing Profiles
description: Processing profiles to add or replace (merged by `id`).
encoding_profiles:
anyOf:
- type: array
items:
$ref: '#/components/schemas/EncodingProfile'
- type: 'null'
title: Encoding Profiles
description: Encoding profiles to add or replace (merged by `id`).
pipelines:
anyOf:
- type: array
items:
$ref: '#/components/schemas/ProcessingPipeline'
- type: 'null'
title: Pipelines
description: Pipelines to add or replace (merged by `id`).
source_stream:
anyOf:
- $ref: '#/components/schemas/SourceStream'
- type: 'null'
description: Replacement source configuration.
target_streams:
anyOf:
- type: array
items:
$ref: '#/components/schemas/TargetStream'
- type: 'null'
title: Target Streams
description: Target streams to add or replace (merged by `id`).
pipeline_patches:
anyOf:
- type: array
items:
$ref: '#/components/schemas/PipelinePatch'
- type: 'null'
title: Pipeline Patches
description: >-
Live, runtime-only adjustments to running pipelines: toggle dubbing,
adjust the mix, or nudge A/V sync. Applied immediately and not
persisted into the stream configuration.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AudioSelection:
type: object
required:
- id
- source
- source_language
title: AudioSelection
description: >-
Names an audio track of the source so pipelines can reference it by
`id`.
properties:
id:
type: string
title: ID
description: >-
Your identifier for this selection, referenced by
`pipelines[].audio_selection`.
source:
type: string
title: Source
description: >-
Audio track selector. Accepts FFmpeg-style selectors (`a:0`, `1`,
`eng`, `#0x1fe`, `i:301`, optionally with a channel suffix like
`:ch0,1`) or magic selectors (`$first_audio`, `$second_audio`,
`$last_audio`). Use [Probe a Source
Stream](/api-reference/endpoint/streaming/probe-stream) to discover
tracks.
source_language:
$ref: '#/components/schemas/Languages'
description: >-
Language spoken on the selected track. If the audio mixes several
languages, use the main one; multilingual input is handled
automatically. Numeric language ID from [`GET
/source-languages`](/api-reference/endpoint/get-source-languages),
e.g. `1` for English (US).
background:
anyOf:
- type: string
- type: 'null'
title: Background
description: >-
Optional selector (same syntax as `source`) for a clean
background/music track. When set, it is used as the background bed
for mixing instead of demixing the source.
ProcessingProfile:
type: object
required:
- id
title: ProcessingProfile
description: >-
A reusable bundle of AI processing settings, referenced by
`pipelines[].profile`. Each step is `none` (off), `best_model` (quality)
or `fast_model` (latency).
properties:
id:
type: string
title: ID
description: >-
Your identifier for this profile, referenced by
`pipelines[].profile`.
demixing:
$ref: '#/components/schemas/ProcessingOption'
default: none
description: Separate speech from background music/effects before transcription.
transcribing:
$ref: '#/components/schemas/ProcessingOption'
default: none
description: Speech-to-text on the selected audio.
translating:
$ref: '#/components/schemas/ProcessingOption'
default: none
description: Translate the transcript into each output language.
revoicing:
$ref: '#/components/schemas/ProcessingOption'
default: none
description: Synthesise dubbed speech in the output language.
mixing:
anyOf:
- $ref: '#/components/schemas/OverdubConfig'
- type: 'null'
description: >-
Optional mix gains for dubbed output. Requires `revoicing` to be
enabled.
scte35_dubbing_control:
anyOf:
- $ref: '#/components/schemas/Scte35DubbingControl'
- type: 'null'
description: Optional automatic dubbing toggling on SCTE-35 ad-break markers.
EncodingProfile:
type: object
required:
- id
title: EncodingProfile
description: >-
Reusable encoding settings, referenced by
`target_streams[].inputs[].encoding_profile`. Must set at least one of
`audio_codec` or `video_codec`.
properties:
id:
type: string
title: ID
description: Your identifier for this profile.
audio_codec:
anyOf:
- type: string
- type: 'null'
title: Audio Codec
description: Audio codec, e.g. `aac`.
audio_bitrate:
anyOf:
- type: string
- type: 'null'
title: Audio Bitrate
description: Audio bitrate, e.g. `192k`.
audio_channel_layout:
anyOf:
- type: string
- type: 'null'
title: Audio Channel Layout
description: Channel layout, e.g. `stereo`.
video_codec:
anyOf:
- type: string
- type: 'null'
title: Video Codec
description: Video codec, e.g. `h264`.
video_bitrate:
anyOf:
- type: string
- type: 'null'
title: Video Bitrate
description: Video bitrate, e.g. `5M`.
ProcessingPipeline:
type: object
required:
- id
- profile
- audio_selection
- outputs
title: ProcessingPipeline
description: >-
Connects one audio selection to a processing profile and declares the
assets to produce. A pipeline that produces an `audio` output must also
produce a `subtitle` output.
properties:
id:
type: string
title: ID
description: Your identifier for this pipeline.
profile:
type: string
title: Profile
description: '`id` of an entry in `processing_profiles`.'
audio_selection:
type: string
title: Audio Selection
description: '`id` of an entry in `audio_selections`.'
outputs:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PipelineOutput'
title: Outputs
description: >-
Assets this pipeline produces. Output `id`s must be unique across
all pipelines.
SourceStream:
type: object
required:
- id
- url
title: SourceStream
description: The live source to ingest.
properties:
id:
type: string
title: ID
description: Your identifier for the source stream, e.g. `main-feed`.
url:
type: string
title: URL
description: >-
URL of the live source to ingest, e.g.
`srt://ingest.example.com:9000`.
category:
anyOf:
- $ref: '#/components/schemas/StreamCategory'
- type: 'null'
passphrase:
anyOf:
- type: string
minLength: 10
maxLength: 79
- type: 'null'
title: Passphrase
description: >-
SRT encryption passphrase for the source, if the source is encrypted
(10-79 characters).
streamid:
anyOf:
- type: string
- type: 'null'
title: Stream ID
description: >-
SRT `streamid` to send when connecting to the source, if it requires
one. Not the Camb.ai stream ID.
latency:
anyOf:
- type: integer
minimum: 20
maximum: 8000
- type: 'null'
title: Latency
description: >-
SRT receive latency in milliseconds (20-8000). Higher values
tolerate more network jitter at the cost of delay. Recommended:
`2000` for typical internet links.
TargetStream:
type: object
required:
- id
- type
title: TargetStream
description: >-
A destination for the processed stream. `url` is required except for
auto-hosted types (SRT listener and HLS recording), whose URLs are
generated and returned.
properties:
id:
type: string
title: ID
description: Your identifier for the target, e.g. `youtube-es`.
url:
anyOf:
- type: string
- type: 'null'
title: URL
description: >-
Destination URL to push to. Omit for SRT listener (`6`) and HLS
recording (`3`) targets - their URLs are generated and returned in
the create response and stream status.
type:
$ref: '#/components/schemas/StreamType'
description: Output protocol/type.
passthrough_policy:
$ref: '#/components/schemas/PassthroughPolicy'
default: all
description: >-
Which source tracks are forwarded alongside the listed `inputs`.
With `all` (the default), source tracks not replaced by a pipeline
output are forwarded automatically.
inputs:
type: array
items:
$ref: '#/components/schemas/TargetStreamInput'
title: Inputs
default: []
description: >-
Tracks to include in this output. May be omitted when
`passthrough_policy` is `all` or for auto-hosted target types.
passphrase:
anyOf:
- type: string
- type: 'null'
title: Passphrase
description: SRT encryption passphrase to use when pushing to the destination.
streamid:
anyOf:
- type: string
- type: 'null'
title: Stream ID
description: SRT `streamid` to send when connecting to the destination.
constant_bitrate:
anyOf:
- type: boolean
- type: string
- type: 'null'
title: Constant Bitrate
description: >-
MPEG-TS constant-bitrate control: `false`/omitted for variable
bitrate, `true` to derive the mux rate from the source bandwidth, or
an explicit rate string such as `"500k"` or `"5M"`.
latency:
anyOf:
- type: integer
minimum: 20
maximum: 8000
- type: 'null'
title: Latency
description: >-
SRT send latency in milliseconds (20-8000). Higher values tolerate
more network jitter at the cost of delay. Recommended: `2000` for
typical internet links.
PipelinePatch:
type: object
required:
- pipeline_id
title: PipelinePatch
description: >-
A live, runtime-only adjustment to one pipeline of a running stream. Not
persisted into the stream configuration.
properties:
pipeline_id:
type: string
title: Pipeline ID
description: '`id` of the pipeline to adjust.'
dubbing_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Dubbing Enabled
description: >-
Turn live dubbing on or off for this pipeline. `false` pauses
dubbing and passes the original audio through; `true` resumes it.
Takes effect within a few seconds.
mixing:
anyOf:
- $ref: '#/components/schemas/OverdubConfig'
- type: 'null'
description: Live adjustment of the dubbing mix gains.
avsync:
anyOf:
- $ref: '#/components/schemas/AVSyncConfig'
- type: 'null'
description: Live audio/video sync adjustment.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
Languages:
type: integer
title: Language ID
description: >-
Numeric language ID. Use [`GET
/source-languages`](/api-reference/endpoint/get-source-languages) for
valid `source_language` values and [`GET
/target-languages`](/api-reference/endpoint/get-target-languages) for
valid output `language` values. For example, `1` is English (US) and
`54` is Spanish (Spain).
ProcessingOption:
type: string
enum:
- none
- best_model
- fast_model
title: ProcessingOption
description: >-
Selects the model tier for a processing step: `none` disables the step,
`best_model` prioritises quality, `fast_model` prioritises latency.
OverdubConfig:
type: object
title: OverdubConfig
description: >-
Relative gains used when mixing dubbed audio over the original.
`original_audio_gain` + `background_audio_gain` must not exceed 1.0.
properties:
original_audio_gain:
anyOf:
- type: number
maximum: 1
minimum: 0
- type: 'null'
title: Original Audio Gain
description: Volume of the original speaker while dubbed audio plays (0.0-1.0).
background_audio_gain:
anyOf:
- type: number
maximum: 1
minimum: 0
- type: 'null'
title: Background Audio Gain
description: >-
Volume of background music/ambience during dubbed segments
(0.0-1.0).
fallback_audio_gain:
anyOf:
- type: number
maximum: 1
minimum: 0
- type: 'null'
title: Fallback Audio Gain
description: >-
Volume of the original audio while nothing is being dubbed
(0.0-1.0).
fade_time:
type: number
minimum: 0
maximum: 5
default: 1
title: Fade Time
description: >-
Cross-fade duration in seconds when switching between original and
dubbed audio (0-5).
Scte35DubbingControl:
type: object
title: Scte35DubbingControl
description: >-
Automatically toggles dubbing on SCTE-35 ad-break markers. Each field is
the dubbing state to apply on that marker (`enabled` or `disabled`); set
a field to `null` to ignore that marker. Omit the whole object to ignore
SCTE-35 entirely.
properties:
on_out_of_network_start:
anyOf:
- type: string
- type: 'null'
title: On Out-of-Network Start
description: Dubbing state applied when an ad break starts.
default: disabled
on_out_of_network_end:
anyOf:
- type: string
- type: 'null'
title: On Out-of-Network End
description: Dubbing state applied when an ad break ends.
default: enabled
PipelineOutput:
type: object
required:
- id
- kind
title: PipelineOutput
properties:
id:
type: string
title: ID
description: >-
Your identifier for the produced asset, referenced by
`target_streams[].inputs[].asset_id`.
kind:
$ref: '#/components/schemas/ProducedAssetKind'
description: Type of asset to produce.
language:
anyOf:
- $ref: '#/components/schemas/Languages'
- type: 'null'
description: >-
Language of the asset. Required for `audio` and `subtitle` outputs.
Numeric language ID. Use [`GET
/source-languages`](/api-reference/endpoint/get-source-languages)
for valid `source_language` values and [`GET
/target-languages`](/api-reference/endpoint/get-target-languages)
for valid output `language` values. For example, `1` is English (US)
and `54` is Spanish (Spain).
StreamCategory:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
title: StreamCategory
description: |-
Content category of the source stream, used to tune processing.
| Value | Category |
|---|---|
| `1` | News and information |
| `2` | Sports and entertainment |
| `3` | Business and professional |
| `4` | Education and training |
| `5` | Events and ceremonies |
| `6` | Government and official |
StreamType:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
title: StreamType
description: >-
Protocol/type of a target stream.
| Value | Type | Description |
|---|---|---|
| `1` | SRT caller | Push output to your SRT endpoint (Camb.ai connects
out to `url`). |
| `2` | RTMP | Push output to an RTMP ingest `url`. |
| `3` | HLS recording | Camb.ai-hosted HLS output; `url` and `inputs`
are auto-assigned, and the playback URL is returned. |
| `4` | YouTube RTMP | Push directly to a YouTube RTMP ingest URL. |
| `5` | YouTube HLS | Push directly to a YouTube HLS ingest URL. |
| `6` | SRT listener | Camb.ai hosts an SRT endpoint that you (or your
player) pull from; `url` is auto-assigned and returned. |
PassthroughPolicy:
type: string
enum:
- all
- none
title: PassthroughPolicy
description: >-
`all` forwards every source track that is not replaced by a pipeline
output; `none` forwards nothing unless explicitly selected.
TargetStreamInput:
type: object
title: TargetStreamInput
description: >-
One track of a target output. Set exactly one of `asset_id` (a pipeline
output) or `passthrough_selector` (an unprocessed source track).
properties:
asset_id:
anyOf:
- type: string
- type: 'null'
title: Asset ID
description: '`id` of a pipeline output to include.'
passthrough_selector:
anyOf:
- type: string
- type: 'null'
title: Passthrough Selector
description: >-
Selector (e.g. `v:0`, `a:eng`) for a source track to forward
unprocessed.
pid_policy:
$ref: '#/components/schemas/PIDPolicy'
default: auto
description: How the MPEG-TS PID for this track is chosen.
pid:
anyOf:
- type: integer
minimum: 32
maximum: 8190
- type: 'null'
title: PID
description: >-
Explicit MPEG-TS PID (32-8190). Required when `pid_policy` is
`explicit`, forbidden otherwise.
encoding_policy:
$ref: '#/components/schemas/EncodingPolicy'
default: auto
description: How this track is encoded.
encoding_profile:
anyOf:
- type: string
- type: 'null'
title: Encoding Profile
description: >-
`id` of an entry in `encoding_profiles`. Required when
`encoding_policy` is `explicit`, forbidden otherwise.
AVSyncConfig:
type: object
title: AVSyncConfig
properties:
delay:
anyOf:
- type: number
minimum: -2
maximum: 2
- type: 'null'
title: Delay
description: >-
Audio/video sync adjustment in seconds (-2.0 to 2.0). Positive
values delay audio. Unset by default (no adjustment).
default: null
ProducedAssetKind:
type: string
enum:
- audio
- subtitle
- video
- data
title: ProducedAssetKind
description: Type of asset a pipeline output produces.
PIDPolicy:
type: string
enum:
- preserve
- auto
- explicit
title: PIDPolicy
description: >-
How MPEG-TS packet identifiers (PIDs) are assigned on the output:
`preserve` keeps the source PID (passthrough inputs only), `auto`
assigns one automatically, `explicit` uses the provided `pid`.
EncodingPolicy:
type: string
enum:
- preserve
- auto
- explicit
title: EncodingPolicy
description: >-
How this input is encoded on the output: `preserve` copies the source
codec where possible, `auto` picks sensible defaults, `explicit` applies
the referenced `encoding_profile`.
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
description: >-
The `x-api-key` is a custom header required for authenticating requests
to our API. Include this header in your request with the appropriate API
key value to securely access our endpoints. You can find your API key(s)
in the 'API' section of our studio website.
````