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>[UserID]</userid> <!-- required-->
    <userkey>[UserKey]</userkey> <!-- required-->
    <action>[Action]</action> <!-- required-->
    <source>[SourceFile]</source> <!-- required-->
    <format>
        <output>[OutputFormat]</output> <!-- required-->
        <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|436m]</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>
            <align>[left|right|center]</align>
            <valign>[top|bottom|center]</valign>
            <margin_vertical>[VerticalMargin]</margin_vertical>
            <margin_left>[LeftMargin]</margin_left>
            <margin_right>[RightMargin]</margin_right>
            <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>
            <sub_path>[SubPath]</sub_path>
            <forced>[yes|no]</forced>
            <role>[SubtitleRole]</role>
            <get_from_manifest>[yes|no]</get_from_manifest>
            <add_to_manifest>[ManifestsList]</add_to_manifest>
            <vtt_split_segments>[yes|no]</vtt_split_segments>
            <cea_stream>[video|text|auto]</cea_stream>
            <page>[PageNumber]</page>
            <teletext_page_id>[PageID]</teletext_page_id>
        </closed_captions>
        <!-- Multiple closed captions params may be included in output format -->
        <closed_captions>
            <!-- closed captions params -->
        </closed_captions>
        <teletext>
            <vanc_line_1>[VANCLine1]</vanc_line_1>
            <vanc_line_2>[VANCLine2]</vanc_line_2>
            <vbi_line_1>[VBILine1]</vbi_line_1>
            <vbi_line_2>[VBILine2]</vbi_line_2>
        </teletext>
        <!-- format params -->
    </format>
</query>
{
    "query": {
        "userid": "[UserID]", // required
        "userkey": "[UserKey]", // 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|436m]",
                    "language": "[LanguageCode]",
                    "name": "[NameCode]",
                    "time_offset": "[TimeOffset]",
                    "vtt_segment_duration": "[SegmentDuration]",
                    "font_source": "[FontSourceURL]",
                    "font_size": "[FontSize]",
                    "align": "[left|right|center]",
                    "valign": "[top|bottom|center]",
                    "margin_vertical": "[VerticalMargin]",
                    "margin_left": "[LeftMargin]",
                    "margin_right": "[RightMargin]",
                    "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]",
                    "sub_path": "[SubPath]",
                    "forced": "[yes|no]",
                    "role": "[SubtitleRole]",
                    "get_from_manifest": "[yes|no]",
                    "add_to_manifest": "[ManifestsList]",
                    "vtt_split_segments": "[yes|no]",
                    "cea_stream": "[video|text|auto]",
                    "page": "[PageNumber]",
                    "teletext_page_id": "[PageID]"
                },
                {
                    // closed captions params
                }
            ],
            "teletext": {
                "vanc_line_1": "[VANCLine1]",
                "vanc_line_2": "[VANCLine2]",
                "vbi_line_1": "[VBILine1]",
                "vbi_line_2": "[VBILine2]"
            }
          	// format params
        }
    }
}
ParameterDescriptionAllowed ValuesDefault Value
Closed Captions Params
sourceSpecify 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
copyIf 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, nono
direct_copyIf 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, nono
mux_typeSpecify 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.

436m – SMPTE 436m muxed VBI data.
none
languageSet 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 namenone
nameWhen 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, dutchnone
extractIf 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_offsetSpecify the time offset for time in CC file.Positive or negative float number0
vtt_segment_durationSets segments duration for WebVTT Closed Captions.Positive float numbernone
font_sourceSpecify the Closed Captions font source file. Allowed font formats: ttf, otf.Valid URLnone
font_sizeSpecify the closed caption font size.Positive integer greater than 10.16
alignHorizontal captions alignmentleft, right, centercenter
valignVertival captions alignmenttop, bottom,centerbottom
margin_verticalVertical marginPositive integer numbernone
margin_leftLeft marginPositive integer numbernone
margin_rightRight marginPositive integer numbernone
add_source_offsetEnable use of initial closed captions timestamp from source file in output initial timestamp.yes, nono
ignore_cc_absenceIgnore closed captions absence in a source file while copy or direct_copy closed captions.yes, noyes
cea_data_fieldCEA-608 data field id (data type) to be extracted from cea-608 CC data.0 – NTSCCC_FIELD_1
_1
– NTSC_CC_FIELD_2
0
scte20Mux CEA closed captions with SCTE-20 stadnard.yes, nono
characteristicsCHARACTERISTICS attribute value for the EXT-X-MEDIA tag in HLS manifest according to RFC 8216Valid 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 manifestValid SCHEME valuenone
accessibility_value"value" attribute value for the Accessibility tag in DASH manifestValid stringnone
timescaleTimescale ValuePositive integer numbernone
cea_track_idTrack ID in MOV container with CEA CC data to copy/extract. First available track with CEA CC data is used by default.Integer numbernone
transparent_backgroundAdd transparent background for DFXP Closed Captionsyes, nono
sub_pathISMT and WebVTT Closed Captions files sub directory relative to the output destinationStringnone
forcedAdd FORCED=YES attribute to subtitle in HLS manifestyes, nono
roleSet subtitle's Role attribute in DASH manifestcaption, subtitle, commentary, dub, description, metadata, forced-subtitle, easyreader, karaokesubtitle
get_from_manifestUse data from external manifestyes, nono
add_to_manifestAdd closed captions data to specified manifests. By default closed caption will be added to all manifests.Comma separated list of manifest namesnone
vtt_split_segmentsSplit WebVtt subtitles to segments for MPEG-DASH manifestyes, nono
cea_streamStream type for closed captions extractionvideo, text, autoauto
pageSet ttxt page valuePositive integer numbernone
teletext_page_idTeletext page id to copy or extractNon-negative integer numbernone
Teletext Parameters
vanc_line_1VANC Line 1 value for teletext ancillary dataPositive integer number12
vanc_line_2VANC Line 2 value for teletext ancillary dataPositive integer number575
vbi_line_1VBI Line 1 value for teletext ancillary dataPositive integer number21
vbi_line_2VBI Line 2 value for teletext ancillary dataPositive integer number334

🚧

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

parameter available only for mpeg2video video codec.

🚧

For characteristics parameter

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 parameters available only for advanced_dash and DASH manifests of advanced_fmp4 output formats.

🚧

For timescale parameter

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

🚧

For transparent_background parameter

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

🚧

For sub_path parameter

  • The <sub_path /> parameter available only for advanced multi-bitrate output formats.
  • The <sub_path /> parameter applied only if <mux_type /> set to ismt or webvtt.

🚧

For forced parameter

🚧

For role parameter

🚧

For get_from_manifest parameter

🚧

For add_to_manifest parameter

The <add_to_manifest /> parameter available only for advanced_hls, fmp4_hls, advanced_dash, and advanced_fmp4 output formats.

🚧

For vtt_split_segments parameter

The <vtt_split_segments /> parameter available only for advanced_dash and DASH manifests of advanced_fmp4 output formats.

🚧

For mux_type and teletext params

The mux_type value 436m and teletext parameters available only for mxf_op1a output format