$$\ $$\
$$ | $$ |
$$$$$$\ $$$$$$\ $$$$$$$\ $$$$$$\ $$$$$$$\ $$\ $$\
\_$$ _|\_$$ _| $$ _____|$$ __$$\ $$ __$$\\$$\ $$ |
$$ | $$ | $$ / $$ / $$ |$$ | $$ |\$$\$$ /
$$ |$$\ $$ |$$\ $$ | $$ | $$ |$$ | $$ | \$$$ /
\$$$$ |\$$$$ |\$$$$$$$\ \$$$$$$ |$$ | $$ | \$ /
\____/ \____/ \_______| \______/ \__| \__| \_/
ttconv is a library and command line application written in pure Python for converting between timed text formats used in the presentations of captions, subtitles, karaoke, etc.
TTML / IMSC --- --- IMSC / TTML
\ /
SCC / CEA 608 ------- 0 or more document filters --------- WebVTT
/ [ Canonical Model ] \
EBU STL ------- --- SRT
/
SRT ---------
/
WebVTT ----
ttconv works by mapping the input document, whatever its format, into an internal canonical model, which is then optionally transformed by document filters, and finally mapped to the format of the output document is derived. The canonical model closely follows the TTML 2 data model, as constrained by the IMSC 1.1 Text Profile specification.
ttconv currently supports the following input and output formats. Additional input and output formats are planned, and suggestions/contributions are welcome.
To install the latest version of ttconv
, including pre-releases:
pip install --pre ttconv
tt convert -i <input .scc file> -o <output .ttml file>
tt convert [-h] -i INPUT -o OUTPUT [--itype ITYPE] [--otype OTYPE] [--config CONFIG] [--config_file CONFIG_FILE]
--itype
: TTML
| SCC
| STL
| SRT
(extrapolated from the filename, if omitted)--otype
: TTML
| SRT
| VTT
(extrapolated from the filename, if omitted)--filter
: specifies by name a filter to be applied to the content--config
and --config_file
: JSON dictionary where each property specifies
(optional) configuration parameters for readers, writers and filters.Example:
tt convert -i <.scc file> -o <.ttml file> --itype SCC --otype TTML --filter lcd --config '{"general": {"progress_bar":false, "log_level":"WARN"}, "lcd": {"bg_color": "transparent", "color": "#FF0000"}}'
"general"
)"progress_bar": true | false
A progress bar is displayed if progress_bar
is true
and log_level
is "INFO"
.
Default: true
"log_level": "INFO" | "WARN" | "ERROR"
Logging verbosity
Default: "INFO"
"document_lang": <RFC 5646 language tag>
Overrides the top-level language of the input document.
Example: "document_lang": "es-419"
Default: None
"imsc_writer"
)"time_format": "frames" | "clock_time" | "clock_time_with_frames"
Specifies whether the TTML time expressions are in frames (f
), HH:MM:SS.mmm
or HH:MM:SS:FF
Default: "frames"
if "fps"
is specified, "clock_time"
otherwise
"fps": "<num>/<denom>"
Specifies the ttp:frameRate
and ttp:frameRateMultiplier
of the output document.
Required when time_format
is frames
or clock_time_with_frames
. No effect otherwise.
Example:
--config '{"general": {"progress_bar":false, "log_level":"WARN"}, "imsc_writer": {"time_format":"clock_time_with_frames", "fps": "25/1"}}'
"stl_reader"
)"disable_fill_line_gap" : true | false
true
means that the STL reader does not fill gaps between lines
Default: false
"disable_line_padding" : true | false
true
means that the STL reader does not add padding at the begining/end of lines
Default: false
"program_start_tc" : "TCP" | "HH:MM:SS:FF"
Specifies a starting offset, either the TCP field of the GSI block or a user-specified timecode
Default: "00:00:00:00"
"font_stack" : [<font-families>](https://www.w3.org/TR/ttml2/#style-value-font-families)
Overrides the font stack
Default: "Verdana, Arial, Tiresias, sansSerif"
"max_row_count" : "MNR" | integer
Specifies a maximum number of rows for open subtitles, either the MNR field of the GSI block or a user-specified value
Default: 23
"srt_writer"
)"text_formatting" : true | false
false
means that the SRT writer does not output any text formatting tags
Default: true
"vtt_writer"
)"line_position" : true | false
true
means that the VTT writer outputs line and line alignment cue settings
Default: false
"text_align" : true | false
true
means that the VTT writer outputs text alignment cue settings
Default: false
"cue_id" : true | false
true
means that the VTT writer outputs cue identifiers
Default: true
"text_align" : "auto" | "left" | "center" | "right"
Specifies the text alignment. "auto"
means the reader will use heuristics to determine
text alignment.
Default: "auto"
"lcd"
)The LCD filter merges regions and removes all text formatting with the exception of color and text alignment.
"safe_area" : <integer between 0 and 30>
Specifies the safe area (as a percentage of the height and width of the root container)
Default: 10
"color" : <TTML color> | null
If not null
, overrides text color. The syntax of TTML color
is
specified at https://www.w3.org/TR/ttml2/#style-value-color.
Default: null
Examples: "#FFFFFF"
(white), "white"
"bg_color" : <TTML color>
If not null
, overrides the background color. The syntax of TTML color
is
specified at https://www.w3.org/TR/ttml2/#style-value-color.
Default: null
Examples: "#FF0000"
(red), "transparent"
, "black"
"preserve_text_align" : true | false
If true
, text alignment is preserved, otherwise text is centered.
Default: false
The overall architecture of the library is as follows:
ttconv.imsc.reader.to_model()
for
example);Processing shared across multiple reader and writer modules is factored out in common modules whenever possible. For example, several output formats require an instance of the canonical data model to be transformed into a sequence of discrete temporal snapshots – a process called ISD generation.
The library uses the Python logging
module to report non-fatal events.
Unit tests illustrate the use of the library, e.g. ReaderWriterTest.test_imsc_1_test_suite
at
src/test/python/test_imsc_writer.py
.
Detailed documentation including reference documents is under doc
.
The project uses pipenv to manage dependencies.
pipenv install --dev
PYTHONPATH
environment variable to src/main/python
, e.g. export PYTHONPATH=src/main/python
pipenv run
can then be useddocker build --rm -f Dockerfile -t ttconv:latest .
docker run -it --rm ttconv:latest bash
From the root directory of the project:
mkdir build
pipenv install --dev
export PYTHONPATH=src/main/python
python src/main/python/ttconv/tt.py convert -i src/test/resources/scc/mix-rows-roll-up.scc -o build/mix-rows-roll-up.ttml
Unit test code coverage is provided by the script at scripts/coverage.sh
Automated testing is provided by the script at scripts/ci.sh
Run PYTHONPATH=src/main/python ./scripts/ci.sh
See .github/workflows/main.yml
Run docker run -it --rm ttconv:latest /bin/sh scripts/ci.sh