Skip to Content
Mux Docs: Home

Add your own live closed captions

Learn how to add your own closed captions to your live stream for accessibility.

Why are closed captions important?

Closed captions refers to the visual display of the audio in a program. Closed captions make video more accessible to people who are deaf or hard of hearing, but the benefits go beyond accessibility. Closed captions empower your viewers to consume video content in whichever way is best for them, whether it be audio, text, or a combination.

Supported live caption formats

There are many types of closed caption sources, and each streaming standard may use a different format for embedding captions on the output. Mux supports receiving closed captions embedded in the H.264 video stream using the CEA-608 standard for a single language.

CEA-608 stems from the analog era where closed captions data was carried directly in the transmission in a line of the video content that wasn’t displayed unless the decoder was told to look for it. These were often referred to as “Line 21” captions. CEA-608 is still the primary standard for transmitting closed captions within the same stream as audio/video content.

Most major live caption providers (e.g. AI-Media, EEG Falcon, 3Play, Verbit) will support the CEA-608 standard. Mux will translate the CEA-608 captions into WebVTT that will be delivered as part of the HLS stream/manifest, in a standard HLS-supported manner. We will continue to evaluate demand for supporting captions for multiple languages and other caption formats.

Integrate your own closed captions

Add the embedded_subtitles array at time of stream creation or to an existing live stream. Closed captions are a type of subtitle. The resulting Asset's subtitle text track will have closed_captions: true set.

Input ParametersTypeDescription
namestringThe name of the track containing a human-readable description. This value must be unique across all the text type and subtitles text type tracks. Defaults to language_code if not provided.
passthroughstringArbitrary metadata set for the live closed caption track. Max 255 characters.
language_codestringThe language of the closed caption stream. Value must be BCP 47 compliant. Defaults to en if not provided
language_channelstringCEA-608 caption channel to read caption data from. Possible values: "cc1"

Step 1A: Create a live stream in Mux

Create a live stream using the Live Stream Creation API. Let Mux know that closed captions will be embedded in the RTMP stream at time of live stream creation.

API Request

POST /video/v1/live-streams
Request Body
{
"playback_policy" : [
"public"
],
"embedded_subtitles" : [
{
"name": "English CC",
"passthrough": "English closed captions",
"language_code": "en-US",
"language_channel" : "cc1"
}
],
"new_asset_settings" : {
"playback_policy" : [
"public"
]
}
}

API Response

{
"data": {
"stream_key": "5bd28537-7491-7ffa-050b-bbb506401234",
"playback_ids": [
{
"policy": "public",
"id": "U00gVu02hfLPdaGnlG1dFZ00ZkBUm2m0"
}
],
"new_asset_settings": {
"playback_policies": [
"public"
]
},
"embedded_subtitles" : [
{
"name": "English CC",
"passthrough": "English closed captions",
"language_code": "en-US",
"language_channel": "cc1"
}
],
"id": "e00Ed01C9ws015d5SLU00ZsaUZzh5nYt02u",
"created_at": "1624489336"
}
}

Step 1B: Configure live closed captions for an existing live stream

Use the Live Stream Closed Captions API to configure closed captions to an existing live stream. Live closed captions can not be configured to an active live stream.

API Request

PUT / video/v1/live-streams/{live_stream_id}/embedded-subtitles
Request Body
{
"embedded_subtitles": [
{
"name": "en-US",
"language_code": "en-US",
"language_channel": "cc1"
}
]
}

API Response

Response
{
"data": {
"stream_key": "5bd28537-7491-7ffa-050b-bbb506401234",
"playback_ids": [
{
"policy": "public",
"id": "U00gVu02hfLPdaGnlG1dFZ00ZkBUm2m0"
}
],
"new_asset_settings": {
"playback_policies": [
"public"
]
},
"embedded_subtitles" : [
{
"name": "English",
"language_code": "en-US",
"language_channel": "cc1"
}
],
"id": "e00Ed01C9ws015d5SLU00ZsaUZzh5nYt02u",
"created_at": "1624489336"
}
}

Step 2: Create an event with your preferred closed caption vendor

Log into your preferred closed caption provider account (e.g. AI-Media, 3Play, Verbit) and create an event that needs to be captioned. To create an event, you will need to provide the following inputs

  • Start date and time
  • Language of audio to be captioned
  • Destination Stream URL and Stream Key (Mux). The caption vendor will send video with captions encoded via the 608 standard to this destination.
RTMP Server URLDescriptionCommon Applications
rtmp://global-live.mux.com:5222/appMux's standard RTMP entry point. Compatible with the majority of streaming applications and services.Open Source RTMP SDKs, most app-store streaming applications.
rtmps://global-live.mux.com:443/appMux's secure RTMPS entry point. Compatible with fewer streaming applications, but offers a higher level of security.OBS, Wirecast, Streamaxia RTMP SDKs

Upon successful event creation, the closed caption provider will provide the following

  • Stream URL
  • Stream Key

Learn more about:

Step 3: Point your RTMP stream to your caption provider

Configure your video encoder with the Stream URL and Stream Key provided by the closed caption provider in Step 2.

Step 4: Start your live stream

When the stream goes live, a new live asset is created and tracks will be created for the corresponding captions.

Step 5: Monitor closed caption stream health

When your stream is live, visit the Live Health Dashboard to monitor closed caption stream health. The dashboard will show whether Mux is receiving closed captions. More details can be found at Debug live stream issues

Update stream to not expect live captioning for future connections

Let Mux know to not expect closed captions when the live stream starts again. This can be done by configuring your live stream to not have any captions. This request can only be made while the live stream is idle.

API Request

PUT /video/v1/live-streams/{live_stream_id}/embedded-subtitles
Request Body
{
"embedded_subtitles" : []
}

FAQ

Are there any language restrictions?

Yes. The 608 standard only supports the following languages: English, Spanish, French, German, Dutch, and Portuguese, or Italian. We currently only support live closed captions for a single language. We will evaluate supporting multiple languages based off of customer feedback.

Is the 608 standard supported by my closed caption vendor?

Caption vendors known to support the 608 captions: 3Play, AI-Media EEG Falcon, Verbit

Caption vendors known to not support 608 captions: Rev.ai

When can I edit my live closed caption configuration?

You can only edit your live caption configuration while the live stream is idle; you cannot make any changes while the live stream is active.

Will formatting be preserved?

Mux will translate the CEA-608 captions into WebVTT. Though Mux attempts to preserve the caption formatting, some formatting may be lost.

Does live captions work with audio-only?

No. If you have a use case for this, please let us know.

How do I download my closed caption track?

https://stream.mux.com/{PLAYBACK_ID}/text/{TRACK_ID}.vtt

More details can be found at Advanced Playback features

Does live closed captions work with low latency?

Not at this time. If you have a use case for this, please let us know.

Was this page helpful?