Closed Captions

Manage the use of closed captions with your source video.

Encoding.com has industry-leading, proprietary support for a vast variety of caption standards into common distribution and broadcast standards. Support for adaptive packages, H.264 and H.265 embeds, transport stream encodings, MXF containers, and sidecar formats are all well-supported. Extraction and copying caption services is possible as well, and timecode offsets and framerate conversions can even be applied to some embeds.

<?xml version="1.0"?>
<query>
    <userid><<id>></userid> <!-- required-->
    <userkey><<key>></userkey> <!-- required-->
    <action>[Action]</action> <!-- required-->
    <source>[SourceFile]</source> <!-- required-->
    <format>
        <output>[OutputFormat]</output> <!-- required-->
        <!-- Format params -->
        <closed_captions>
            <source>[CCSource]</source>
            <copy>[yes|no]</copy>
            <direct_copy>[yes|no]</direct_copy>
            <extract>[srt|scc|dfxp]</extract>
            <mux_type>[cea-608|cea-708|timed-text|webvtt|burn-in|ismt]</mux_type>
            <language>[LanguageCode]</language>
            <name>[NameCode]</name>
            <time_offset>[TimeOffset]</time_offset>
            <vtt_segment_duration>[SegmentDuration]</vtt_segment_duration>
            <font_source>[FontSourceURL]</font_source>
            <font_size>[FontSize]</font_size>
            <add_source_offset>[yes|no]</add_source_offset>
            <!-- add_source_offset feature works only with mxf source -->
            <ignore_cc_absence>[yes|no]</ignore_cc_absence>
            <cea_data_field>[0|1]</cea_data_field>
            <scte20>[yes|no]</scte20>
            <characteristics>[Characteristics]</characteristics>
            <accessibility_scheme>[Scheme]</accessibility_scheme>
            <accessibility_value>[Value]</accessibility_value>
            <timescale>[Timescale]</timescale>
            <cea_track_id>[TrackID]</cea_track_id>
            <transparent_background>[yes|no]</transparent_background>
        </closed_captions>
        <!-- Multiple closed captions params may be included in output format -->
        <closed_captions>
            <!-- closed captions params -->
        </closed_captions>
        <!-- format params -->
    </format></query>
{
    "query": {
        "userid": "<<id>>", // required
        "userkey": "<<key>>", // required
        "action": "[Action]", // required
        "source": "[SourceFile]", // required
        "format": {
            "output": "[OutputFormat]", // required
            "closed_captions": [
                {
                    "source": "[CCSource]",
                    "copy": "[yes|no]",
                    "direct_copy": "[yes|no]",
                    "extract": "[srt|scc|dfxp]",
                    "mux_type": "[cea-608|cea-708|timed-text|webvtt|burn-in|ismt]",
                    "language": "[LanguageCode]",
                    "name": "[NameCode]",
                    "time_offset": "[TimeOffset]",
                    "vtt_segment_duration": "[SegmentDuration]",
                    "font_source": "[FontSourceURL]",
                    "font_size": "[FontSize]",
                    "add_source_offset": "[yes|no]",
                    // add_source_offset feature works only with mxf source
                    "ignore_cc_absence": "[yes|no]",
                    "cea_data_field": "[0|1]",
                    "scte20": "[yes|no]",
                    "characteristics": "[Characteristics]",
                    "accessibility_scheme": "[Scheme]",
                    "accessibility_value": "[Value]",
                    "timescale": "[Timescale]",
                    "cea_track_id": "[TrackID]",
                    "transparent_background": "[yes|no]"
                },
                {
                    // closed captions params
                }
            ]
            // format params
        }
    }
}

Parameter

Description

Allowed Values

Default Value

source

Specify the URL to the closed captions file.

Valid URL to Closed Captions file in one of the following formats: SCC, SubRip, DFXP (TTML), SAMI, WebvTT, PAC, STL.

none

copy

If video has Closed Captions data stored in Timed Text or cea-608/cea-708 tracks, system will try to extract closed captions, and mux them to the output. If you want to mux Closed Captions to video in other (than in source video) format, you should specify source and mux_type.

yes, no

no

direct_copy

If video has Closed Captions data stored in cea-608/cea-708 tracks, system will directly copy closed captions to the output. Source and output must be the same frame rate.

yes, no

no

mux_type

Specify the closed captions mux type.

timed-text — Closed Captions would be muxed in video as 3GPP Timed Text track.

cea-608 — Closed Captions would be muxed in video as cea-608 track.

cea-708 — 608 closed captions would be up-converted to 708 closed captions. And both, cea-608 and cea-708 closed captions, would be muxed in video stream.

webvtt — webvtt file would be uploaded to same destination as result file (for HLS it would be segmented). Not available for advanced_mss output format.

burn-in – SRT video subtitle burn-in.

ismt – Closed Captions would be muxed in video as ismt track. Available only for advanced_dash and advanced_mss output formats.

none

language

Set language of 3GPP Timed Text track. Works only for mux_type=timed-text.

ISO 639-1 2-char code, ISO 639-2 3-char code, or the full language name

none

name

When using a foreign language caption file for one’s outputs, you will also need to include a node in between the parent nodes for the labeling to be correct at the player level. If not defined in the request the label will default to English.

english, spanish, french, german, italian, dutch

none

extract

If video has Closed Captions data stored in Timed Text or cea-608/cea-708 tracks, system will try to extract closed captions, and upload them to same destination as the output. If video has multiple text tracks extracted files will have a numeric suffix.

srt — Closed Captions would be extracted in SubRip format
scc — Closed Captions would be extracted in Scenarist Closed Captions format
dfxp — Closed Captions would be extracted in DFXP format

none

time_offset

Specify the time offset for time in CC file.

Positive or negative float number

0

vtt_segment_duration

Sets segments duration for WebVTT Closed Captions.

Positive float number

none

font_source

Specify the Closed Captions font source file. Allowed font formats: ttf, otf.

Valid URL

none

font_size

Specify the closed caption font size.

Positive integer greater than 10.

16

add_source_offset

Enable use of initial closed captions timestamp from source file in output initial timestamp.

yes, no

no

ignore_cc_absence

Ignore closed captions absence in a source file while copy or direct_copy closed captions.

yes, no

yes

cea_data_field

CEA-608 data field id (data type) to be extracted from cea-608 CC data.

0 – NTSC_CC_FIELD_1
1 – NTSC_CC_FIELD_2

0

scte20

Mux CEA closed captions with SCTE-20 stadnard.

yes, no

no

characteristics

CHARACTERISTICS attribute value for the EXT-X-MEDIA tag in HLS manifest according to RFC 8216

Valid CHARACTERISTICS value
For example:
public.accessibility.transcribes-spoken-dialog
public.accessibility.describes-music-and-sound

none

accessibility_scheme

"schemeIdUri" attribute value for the Accessibility tag in DASH manifest

Valid SCHEME value

none

accessibility_value

"value" attribute value for the Accessibility tag in DASH manifest

Valid string

none

timescale

Timescale Value

Positive integer number

none

cea_track_id

Track ID in MOV container with CEA CC data to copy/extract. First available track with CEA CC data is used by default.

Integer number

none

transparent_background

Add transparent background for DFXP Closed Captions

yes, no

no

🚧

For mux_type parameter

cea-608 mux type works with libx264 and hevc video codec.
cea-708 mux type works only with libx264 video codec.

🚧

For font_source and font_size parameters

<font_source /> and <font_size /> work only with burn-in mux type.

🚧

For scte20 parameter

<scte20 /> parameter available only for mpeg2video video codec.

🚧

For characteristics parameter

<characteristics /> parameter available only for advanced_hls, fmp4_hls, and HLS manifests of advanced_fmp4 output formats.

🚧

For accessibility_scheme, accessibility_value, and timescale parameters

<accessibility_scheme />, <accessibility_value />, and <timescale /> parameters available only for advanced_dash and DASH manifests of advanced_fmp4 output formats.

🚧

For timescale parameter

The <timescale /> parameter applied only if <mux_type /> set to ismt.

🚧

For transparent_background

The <transparent_background /> parameter applied only if <extract /> set to dfxp and <mux_type /> not set.