## Cinnafilm Tachyon Frame Rate Conversion Introduced support for Cinnafilm's Tachyon motion-compensated frame rate conversion, telecine (pulldown) handling, and Dark Energy image restoration. Set the [video settings](ref:output-videosettings) parameter **framerate_method** to **tachyon** to process the output with Tachyon, and fine-tune the engine with the optional **tachyon_parameters** group. See details on [Tachyon settings page](ref:output-tachyon). ```xml [UserID] [UserKey] [Action] [SourceFile] [OutputFormat] [FrameRate] tachyon ``` ```json { "query": { "userid": "[UserID]", // required "userkey": "[UserKey]", // required "action": "[Action]", // required "source": "[SourceFile]", // required "format": { "output": "[OutputFormat]", "framerate": "[FrameRate]", "framerate_method": "tachyon", "tachyon_parameters": { // see Tachyon / Dark Energy filter parameters on Tachyon settings page } } } } ``` | Parameter | Description | Allowed Values | Default Value | |:------------------------|:--------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--------------| | **framerate_method** | Frame rate conversion method | default, filter, tachyon | default | | **tachyon_parameters** | Optional group of Tachyon engine settings. Applied only when **framerate_method** is **tachyon** | See [Tachyon Frame Rate Conversion](ref:output-tachyon) | _none_ | See the full list of Tachyon and Dark Energy filter parameters on the [Tachyon settings](ref:output-tachyon) page. ## Frame offset for closed captions **frame_offset** [option](ref:closed-captions-conversion) to shift the closed captions time by a number of frames The **framerate** option is now also used to convert **frame_offset** to seconds, and accepts fraction values (e.g. `30000/1001`). ```xml [UserID] [UserKey] [Action] [SourceFile] closed_captions [srt|scc|webvtt|dfxp|ttml|mcc|stl] [FRAME_OFFSET] [Frame rate value] [Frame rate value] ``` ```json { "query": { "userid": "[UserID]", // required "userkey": "[UserKey]", // required "action": "[Action]", // required "source": "[SourceFile]", // required "format": { "output": "closed_captions", "type": "[srt|scc|webvtt|dfxp|ttml|mcc|stl]", "frame_offset": "[FRAME_OFFSET]", "source_framerate": "[Frame rate value]", "framerate": "[Frame rate value]" } } } ``` > 🚧 A framerate is required to apply frame_offset > > The offset in frames is converted to seconds with the value, which must be set whenever is used. The source frame rate and the output format defaults are not used to interpret it, so requests specifying without are rejected for every output format (SCC, MCC and STL included). An SCC source holds its timings as frame counts, and so does a video the captions are extracted from (it is read as an MCC), so reading one needs a framerate as well — and one value cannot be both that and the rate the offset is counted in. is the offset's rate, so such a source is read with , or with the rate it states itself (an MCC names it in its header), or failing both with the rate its format is conventionally in, 29.97 for an SCC. Set when the source is not at that rate, a 25 fps SCC for instance. Other sources need none: SubRip and WebVTT hold time, EBU STL and TTML carry their own framerate. If you already pass to say what rate your SCC is in, move that value to when you add an offset in frames — is the offset's rate from then on, and the source would otherwise be read at 29.97. The closed captions offset options are mutually exclusive: a request specifying together with or is rejected. An empty value is not a request — the unused elements can be sent empty. The captions offset options apply to generated captions as well: the result of a speech to text () or a request is shifted the same way. | Parameter | Description | Allowed Values | Default Value | |:------------------|:---------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------|:--------------| | **frame_offset** | Specify the offset for time in CC file in frames. Conflicts with `time_offset` and `set_first_timecode`. | Positive or negative integer | 0 | | **source_framerate** | Framerate the captions source is read with, when `frame_offset` makes `framerate` the offset's rate. Set it for an SCC that is not at 29.97; an MCC names its own rate and needs none. | 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** | Captions framerate, also used to convert `frame_offset` to seconds. Required whenever `frame_offset` is set. | 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_ | ## Set the first closed captions timecode **set_first_timecode** [option](ref:closed-captions-conversion) to move the first cue of the converted closed captions to the requested time — all the other cues are shifted by the same offset, so the captions keep their relative timings. ```xml [UserID] [UserKey] [Action] [SourceFile] closed_captions [srt|scc|webvtt|dfxp|ttml|mcc|stl] [FIRST_TIMECODE] [Frame rate value] [Frame rate value] ``` ```json { "query": { "userid": "[UserID]", // required "userkey": "[UserKey]", // required "action": "[Action]", // required "source": "[SourceFile]", // required "format": { "output": "closed_captions", "type": "[srt|scc|webvtt|dfxp|ttml|mcc|stl]", "set_first_timecode": "[FIRST_TIMECODE]", "source_framerate": "[Frame rate value]", "framerate": "[Frame rate value]" } } } ``` The value is a `HH:MM:SS:FF` timecode (`HH:MM:SS;FF` for drop frame), a `HH:MM:SS.mmm` timestamp or a plain number of seconds. For example, captions starting at `00:00:01.500` requested with `01:00:00.000` are shifted by `+3598.5` seconds. For an SCC or MCC source the first cue is the moment the first caption is **displayed**, not the moment its data starts: a line of an SCC holds the caption data, which a pop on caption shows only when its end of caption code arrives, and a line can carry no caption at all (XDS packets and null padding are lines too). The source is decoded exactly the way a SubRip conversion of it is decoded. Set a to be sure of the measurement: without one the source is read with the source video's frame rate, or with the output format's default framerate, which is 25 fps for an STL output even when the source is an SCC. Mind the drop frame separator for the NTSC framerates: at 29.97 fps `01:00:00:00` (non drop) is 3603.6 seconds while `01:00:00;00` (drop frame) is 3600 seconds — 3.6 seconds apart. > 🚧 A framerate is required to read a timecode > > A `HH:MM:SS:FF` value is converted to seconds with the value, which must be set whenever the timecode form is used. The source frame rate and the output format defaults are not used to read it, so requests specifying a `HH:MM:SS:FF` timecode without are rejected for every output format (SCC, MCC and STL included). The values that need no framerate (`HH:MM:SS.mmm` or seconds) are always accepted. The first cue has to be read from the source to calculate the offset, so a request asking for on captions whose cues can't be read fails instead of returning the original timings. An empty captions source is the exception: there is nothing to shift and the conversion proceeds. An SCC source holds its timings as frame counts, and so does a video the captions are extracted from (it is read as an MCC), so reading one needs a framerate as well — and one value cannot be both that and the rate the offset is counted in. is the offset's rate, so such a source is read with , or with the rate it states itself (an MCC names it in its header), or failing both with the rate its format is conventionally in, 29.97 for an SCC. Set when the source is not at that rate, a 25 fps SCC for instance. Other sources need none: SubRip and WebVTT hold time, EBU STL and TTML carry their own framerate. If you already pass to say what rate your SCC is in, move that value to when you add an offset in frames — is the offset's rate from then on, and the source would otherwise be read at 29.97. The closed captions offset options are mutually exclusive: a request specifying together with or is rejected. An empty value is not a request — the unused elements can be sent empty. The captions offset options apply to generated captions as well: the result of a speech to text () or a request is shifted the same way. | Parameter | Description | Allowed Values | Default Value | |:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------|:--------------| | **set_first_timecode** | Time of the first cue in the result, the other cues are shifted by the same offset. Conflicts with `time_offset` and `frame_offset`. | `HH:MM:SS:FF` timecode, `HH:MM:SS.mmm` (or `HH:MM:SS,mmm`) timestamp or a non negative number of seconds | _none_ | | **source_framerate** | Framerate the captions source is read with, when a `HH:MM:SS:FF` `set_first_timecode` makes `framerate` the offset's rate. Set it for an SCC that is not at 29.97; an MCC names its own rate and needs none. | 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** | Captions framerate, also used to read the `HH:MM:SS:FF` values. Required whenever a `HH:MM:SS:FF` timecode is given. | 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_ | ## H.264 encoder defaults and automatic level ### Encoder defaults New **use_defaults** [video codec parameter](ref:adv-h-264) for `libx264` codec selects the defaults for the parameters under `video_codec_parameters` that are not set in the request: `edc` applies the EDC default values listed in the documentation, `codec` leaves them unset, so the x264 encoder uses its defaults, except the profile and preset, which follow the format-level settings. ```xml [UserID] [UserKey] [Action] [SourceFile] [OutputFormat] libx264 [high|main|baseline] [edc|codec] ``` ```json { "query": { "userid": "[UserID]", // required "userkey": "[UserKey]", // required "action": "[Action]", // required "source": "[SourceFile]", // required "format": { "output": "[OutputFormat]", // required "video_codec": "libx264", "profile": "[high|main|baseline]", "video_codec_parameters": { "use_defaults": "[edc|codec]" // video_codec parameters }, // format parameters } } } ``` | Parameter | Description | Allowed Values | Default Value | |:-----------------|:----------------------------------------------------------------------------------------------|:---------------|:--------------| | **use_defaults** | Defaults for the parameters that are not set: Encoding.com defaults or x264 encoder defaults | edc, codec | edc | ### Automatic level Updated [level video codec parameter](ref:adv-h-264-frametype) of `libx264` to accept `auto`: the encoder chooses the lowest level that fits the output frame size, frame rate and bitrate. ```xml auto ``` ```json { "video_codec_parameters": { "level": "auto" } } ``` | Parameter | Description | Allowed Values | Default Value | |:----------|:----------------------------------------------------------------------|:------------------------------|:------------------------------------------------------------------------| | **level** | As set of constraints that specify decoder performance for a profile. | Positive integer number, auto | **high**, **main** profile: 30 (3.0)
**baseline** profile: 13 (1.3) |

Changelog