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|dvb|mp4-ttml|mp4-webvtt]</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>
<emulate_rollup>[yes|no]</emulate_rollup>
<strip_formatting>[yes|no]</strip_formatting>
</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|dvb|mp4-ttml|mp4-webvtt]",
"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]",
"emulate_rollup": "[yes|no]",
"strip_formatting": "[yes|no]"
},
{
// closed captions params
}
],
"teletext": {
"vanc_line_1": "[VANCLine1]",
"vanc_line_2": "[VANCLine2]",
"vbi_line_1": "[VBILine1]",
"vbi_line_2": "[VBILine2]"
}
// format params
}
}
}
Parameter | Description | Allowed Values | Default Value |
---|---|---|---|
Closed Captions Params | |||
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. 436m – SMPTE 436m muxed VBI data. dvb - DVB subtitles, available only for MPEG-TS output mp4-webvtt – mux WebVTT to MP4 as wvtt track mp4-ttml – mux TTML to MP4 as stpp track | 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. Required for dvb mux_type. | none |
font_size | Specify the closed caption font size. | Positive integer greater than 10. | 16 |
align | Horizontal captions alignment | left, right, center | center |
valign | Vertival captions alignment | top, bottom,center | bottom |
margin_vertical | Vertical margin | Positive integer number | none |
margin_left | Left margin | Positive integer number | none |
margin_right | Right margin | Positive integer number | none |
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 – NTSCCC_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 |
sub_path | ISMT and WebVTT Closed Captions files sub directory relative to the output destination | String | none |
forced | Add FORCED=YES attribute to subtitle in HLS manifest | yes, no | no |
role | Set subtitle's Role attribute in DASH manifest | caption, subtitle, commentary, dub, description, metadata, forced-subtitle, easyreader, karaoke | subtitle |
get_from_manifest | Use data from external manifest | yes, no | no |
add_to_manifest | Add closed captions data to specified manifests. By default closed caption will be added to all manifests. | Comma separated list of manifest names | none |
vtt_split_segments | Split WebVtt subtitles to segments for MPEG-DASH manifest | yes, no | no |
cea_stream | Stream type for closed captions extraction | video, text, auto | auto |
page | Set ttxt page value | Positive integer number | none |
teletext_page_id | Teletext page id to copy or extract | Non-negative integer number | none |
emulate_rollup | Perform RollUp emulation when converting an SCC file to other formats | yes, no | yes |
strip_formatting | Remove all formatting tags (available only for TTML (DFXP) output and TTML to WebVTT conversion). | yes, no | no |
Teletext Parameters | |||
vanc_line_1 | VANC Line 1 value for teletext ancillary data | Positive integer number | 12 |
vanc_line_2 | VANC Line 2 value for teletext ancillary data | Positive integer number | 575 |
vbi_line_1 | VBI Line 1 value for teletext ancillary data | Positive integer number | 21 |
vbi_line_2 | VBI Line 2 value for teletext ancillary data | Positive integer number | 334 |
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
- The parameter available only for advanced_hls, fmp4_hls, and HLS manifests of advanced_fmp4 output formats.
For role parameter
- The parameter available only for advanced_dash and DASH manifests of advanced_fmp4 output formats.
For get_from_manifest parameter
- The <get_from_manifest /> parameter available only for advanced_hls, fmp4_hls, advanced_dash, and advanced_fmp4 output formats.
- The <get_from_manifest /> parameter available only if manifest are specified.
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