Convert captions files between formats.
<?xml version="1.0"?>
<query>
<userid>[UserID]</userid> <!-- required-->
<userkey>[UserKey]</userkey> <!-- required-->
<action>AddMedia</action> <!-- required-->
<source>[ClosedCaptionsSourceFile]</source> <!-- required-->
<format>
<output>closed_captions</output> <!-- required-->
<destination>[DestinationURL]</destination> <!-- required-->
<type>[srt|scc|webvtt|dfxp|ttml|mcc|stl]</type>
<strip_formatting>[yes|no]</strip_formatting>
<time_offset>[TIME_OFFSET]</time_offset>
<frame_offset>[FRAME_OFFSET]</frame_offset>
<set_first_timecode>[FIRST_TIMECODE]</set_first_timecode>
<cea_data_field>[0|1]</cea_data_field>
<transparent_background>[yes|no]</transparent_background>
<cea_stream>[video|text|auto]</cea_stream>
<teletext_page_id>[PageID]</teletext_page_id>
<ttml_profile>[TTMLProfile]</ttml_profile>
<make_preconvert>[no|scc]</make_preconvert>
<emulate_rollup>[yes|no]</emulate_rollup>
<charset>[utf8|cp1252]</charset>
<stl_dsc>[0|1|2]</stl_dsc>
<webvtt_strip_cue_settings>[vertical|line|position|size|align|region],...</webvtt_strip_cue_settings>
<align>[left|right|center]</align>
<valign>[top|bottom|center]</valign>
<scc_strict_check>[yes|no]</scc_strict_check>
<source_framerate>[Frame rate value]</source_framerate>
<framerate>[Frame rate value]</framerate>
<scc_converter>[v1|v2]</scc_converter>
<stt>
<model>[base|tiny|small|medium|largev2|largev3]</model>
<language>[LanguageCode]</language>
<prompt></prompt>
<refine_timing>[yes|no]</refine_timing>
<audio_stream>
[AudioStreamDefinition]
</audio_stream>
</stt>
<legalize>
<mode>[cea-608|teletext|custom]</mode>
<max_line_count>[MaxLineCount]</max_line_count>
<max_line_length>[MaxLineLength]</max_line_length>
<min_duration>[MinDuration]</min_duration>
<max_duration>[MaxDuration]</max_duration>
<max_cps>[MaxCPS]</max_cps>
</legalize>
<scc_last_unclosed_duration>[FloatDuration]</scc_last_unclosed_duration>
<scc_last_unclosed_end>[Float or Timecode]</scc_last_unclosed_end>
</format>
</query>{
"query": {
"userid": "[UserID]", // required
"userkey": "[UserKey]", // required
"action": "AddMedia", // required
"source": ["[ClosedCaptionsSourceFile]"], // required
"format": {
"output": "closed_captions", // required
"destination": "[DestinationURL]", // required
"type": "[srt|scc|webvtt|dfxp|ttml|mcc|stl]",
"strip_formatting": "[yes|no]",
"time_offset": "[TIME_OFFSET]",
"frame_offset": "[FRAME_OFFSET]",
"set_first_timecode": "[FIRST_TIMECODE]",
"cea_data_field": "[0|1]",
"transparent_background": "[yes|no]",
"cea_stream": "[video|text|auto]",
"teletext_page_id": "[PageID]",
"ttml_profile": "[TTMLProfile]",
"make_preconvert": "[no|scc]",
"emulate_rollup": "[yes|no]",
"charset": "[utf8|cp1252]",
"stl_dsc": "[0|1|2]",
"webvtt_strip_cue_settings": "[vertical|line|position|size|align|region],...",
"align": "[left|right|center]",
"valign": "[top|bottom|center]",
"scc_strict_check": "[yes|no]",
"source_framerate": "[Frame rate value]",
"framerate": "[Frame rate value]",
"scc_converter": "[v1|v2]",
"stt": {
"model": "[base|tiny|small|medium|largev2|largev3]",
"language": "[LanguageCode]",
"prompt": "",
"refine_timing": "[yes|no]",
"audio_stream": {
[AudioStreamDefinition]
}
},
"legalize": {
"mode": "[cea-608|teletext|custom]",
"max_line_count": "[MaxLineCount]",
"max_line_length": "[MaxLineLength]",
"min_duration": "[MinDuration]",
"max_duration": "[MaxDuration]",
"max_cps": "[MaxCPS]"
},
"scc_last_unclosed_duration": "[FloatDuration]",
"scc_last_unclosed_end": "[Float or Timecode]"
}
}
}| Parameter | Description | Allowed Values | Default Value |
|---|---|---|---|
| source | Specify the URL to Closed Captions file or video with muxed closed captions. | Valid URL to Closed Captions file (in one of the following formats: SCC, SubRip, DFXP (TTML), SAMI, WebvTT, PAC, STL) or video with muxed closed captions (in cea-6/708 or timed-text format). | none |
| type | Convert closed captions to specified type | srt, scc, webvtt, dfxp, ttml, mcc, stl | srt |
| strip_formatting | Remove all formatting tags (available only for TTML (DFXP) output and TTML to WebVTT conversion). | yes, no | no |
| time_offset | Specify the time offset for time in CC file. Cannot be used together with frame_offset or set_first_timecode. | Positive or negative float number. | 0 |
| frame_offset | Specify the offset for time in CC file in frames. Converted to seconds with the framerate value, which is required whenever frame_offset is used — the source frame rate and the output format defaults are not used to interpret it. Cannot be used together with time_offset or set_first_timecode. | Positive or negative integer. | 0 |
| set_first_timecode | Move the first cue of the result to the specified time and shift all the other cues by the same offset. A HH:MM:SS:FF timecode (HH:MM:SS;FF for drop frame) is read with the framerate value, which is required whenever a timecode is given — the source frame rate and the output format defaults are not used to read it. The HH:MM:SS.mmm timestamp and plain seconds forms need no framerate. Cannot be used together with time_offset or frame_offset. Mind the drop frame separator: at 29.97 fps 01:00:00:00 is 3603.6 seconds while 01:00:00;00 is 3600 seconds. The conversion fails when the first cue can't be found in the source. | HH:MM:SS:FF timecode, HH:MM:SS.mmm (or HH:MM:SS,mmm) timestamp or a non negative float number of seconds. | none |
| 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 |
| transparent_background | Add transparent background for DFXP Closed Captions | yes, no | no |
| cea_stream | Stream type for closed captions extraction | video, text, auto | auto |
| teletext_page_id | Teletext page id to copy or extract | Non-negative integer number | none |
| ttml_profile | TTML profile | basic, smpte_st2052, smpte_ismc1, smpte_ismc1_1, smpte_itt | basic |
| make_preconvert | Perform a pre-conversion of the source file to another format. For example, you may pre-convert TTML to SCC before converting to MCC to remove paint-on emulation in the original source file. | no, scc | no |
| emulate_rollup | Perform RollUp emulation when converting an SCC file to other formats | yes, no | yes |
| charset | Specify character set for SRT output | utf8, cp1252 | none |
| stl_dsc | Output STL Display Standard Code 0 — Open Subtitling 1 — Level 1 Teletext 2 — Level 2 Teletext | 0, 1, 2 | 1 |
| webvtt_strip_cue_settings | Strip certain cue settings | Comma separated list of the following values: vertical,line,position,size,align,region | none |
| align | Horizontal captions alignment (STL only) | left, right, center | none |
| valign | Vertival captions alignment (STL only) | top, bottom,center | none |
| scc_strict_check | Fail in case of SCC source errors (e.g. incorrect timecodes) | yes, no | none |
| source_framerate | Framerate the captions source is read with, for a source whose timings are frame counts (SCC, or a video the captions are extracted from as MCC). Set it when framerate is counting an offset in frames (frame_offset, or a HH:MM:SS:FF set_first_timecode) and the source is not at its format's usual rate — a 25 fps SCC, say. Otherwise the source is read with the rate it states itself (an MCC names it in its Time Code Rate header), else framerate, else the source video frame rate, else 29.97 for SCC and MCC. | Any positive number or fraction, e.g. 60, 59.94, 60000/1001, 50, 30, 29.97, 30000/1001, 25, 24, 23.98, 24000/1001 | none |
| framerate | Input framerate (e.g. for SCC source), and the rate a frames-based offset is counted in. Required to apply frame_offset or a HH:MM:SS:FF set_first_timecode, for every output format. | Any positive number or fraction, e.g. 60, 59.94, 60000/1001, 50, 30, 29.97, 30000/1001, 25, 24, 23.98, 24000/1001 | none |
| scc_converter | SCC converter version | v1, v2 | v1 |
| scc_last_unclosed_duration | Set the last subtitle item duration in case of SCC doesn't contain trailing EOC or EDM | Positive float | none |
| scc_last_unclosed_end | Set the last subtitle item end time if SCC doesn't contain trailing EOC or EDM | Positive float or SRT/VTT timecode | none |
| STT (Speech to text) parameters | |||
| model | Language model to use | base, tiny, small, medium, largev2, largev3 (experimental) | largev2 |
| language | Language of speech | 2 or 3 characters language code | none |
| prompt | Prompt for speech to text conversion | Text | none |
| refine_timing | Refine timing | yes, no | no |
| audio_stream | Define audio stream to handle | see Audio Stream definition | |
| Legalize parameters | |||
| mode | CEA-608: 4 lines and 32 characters per item, Teletext: 4 lines and 37 characters, Custom: custom number of lines and characters | cea-608, teletext, custom | none |
| max_line_count | Max line count | Positive integer (max 4 for cea-608 and teletext mode) | none |
| max_line_length | Max line length | Positive integer (max 32 for cea-608, max 37 for teletext) | none |
| min_duration | Min duration | Positive integer | none |
| max_duration | Max duration | Positive integer | none |
| max_cps | Max characters per second | Positive integer | none |
For transparent_backgroundThe <transparent_background /> parameter applied only if
set to dfxp.
For ttml_profileThe <ttml_profile /> parameter applied only if
set to ttml.
For type=mccIf multiple source files (up to 4) are specified in the source array, these files will be merged into a single MCC file.
For type=sccIf 2 source files are specified in the source array, these files will be merged into a single SCC file, sources will be mapped to CC1 and CC2 channels respectively.
For scc_last_unclosed_duration and scc_last_unclosed_endThese options are applicable for SRT and WebVTT outputs.
For the captions offset options<time_offset />, <frame_offset /> and <set_first_timecode /> are mutually exclusive: only one of them can be set in a closed captions format. A request setting more than one of them is rejected with only one closed captions offset option can be used at a time, so that none of them is silently dropped. An empty value is not a request — the unused elements can be sent empty.
<frame_offset /> and a
HH:MM:SS:FF<set_first_timecode /> are expressed in frames and needto be converted to seconds, for every output format: the source frame rate and the output format defaults are not used to interpret them. An SCC source (and a video the captions are extracted from, which is read as an MCC) holds its timings as frame counts, so reading it needs a framerate too — and one value cannot be both that and the rate the offset is counted in. When an offset in frames is requested,
is the offset's rate, and the source is read with <source_framerate />, or with the rate it states itself (an MCC names it in its header), or with the rate its format is conventionally in — 29.97 for an SCC. Set <source_framerate /> when the source is not at that rate — in particular, a request that already passes to state the rate of its SCC should move that value to <source_framerate /> when it starts asking for an offset in frames.
For the frame rate valuesA fractional rate can be written as a fraction (
24000/1001) or as a decimal (23.98). Where the rate is used as a plain number — converting <frame_offset /> to seconds, and decoding a source whose timings are frame counts — the decimal is taken literally, so the two spellings are not always the same rate:24000/1001is 23.976, and an offset of 864000 frames counted at23.98lands 6 seconds earlier.29.97and30000/1001do come to the same number. Prefer the fraction. AHH:MM:SS:FF<set_first_timecode /> is not affected —23.98,29.97and59.94are read there as their fractional rates.
For STTModel LargeV3 is experimental and may cause unexpected results, it's not recommended to use for English, but still can show better results for some other languages.
Speech to text jobs are temporary unavailable in the following regions: us-west-1, af-south-1, eu-west-1, ap-southeast-1.