Package: ttconv
ttconv (Timed Text Conversion)$$\     $$\                                             
  $$ |    $$ |                                            
$$$$$$\ $$$$$$\    $$$$$$$\  $$$$$$\  $$$$$$$\ $$\    $$\ 
\_$$  _|\_$$  _|  $$  _____|$$  __$$\ $$  __$$\\$$\  $$  |
  $$ |    $$ |    $$ /      $$ /  $$ |$$ |  $$ |\$$\$$  / 
  $$ |$$\ $$ |$$\ $$ |      $$ |  $$ |$$ |  $$ | \$$$  /  
  \$$$$  |\$$$$  |\$$$$$$$\ \$$$$$$  |$$ |  $$ |  \$  /   
   \____/  \____/  \_______| \______/ \__|  \__|   \_/Introductionttconvis 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 ----- Canonical Model -------- WebVTT
                /                     \
EBU STL -------                         --- SRT
              /
SRT ---------
            /
WebVTT ----ttconvworks by mapping the input document, whatever its format, into an internal canonical model, which is then mapped to the
format of the output document is derived. The canonical model closely follows theTTML 2data model,
as constrained by theIMSC 1.1 Text Profilespecification.Online demohttps://ttconv.sandflow.com/Format supportttconvcurrently supports the following input and output formats. Additional input and output formats are planned, and
suggestions/contributions are welcome.Input FormatsCEA 608/.sccIMSC 1.1 Text Profile/.ttmlEBU STLSubRip/.srtWebVTTOutput FormatsSubRip/.srtIMSC 1.1 Text Profile/.ttmlWebVTTQuick startTo install the latest version ofttconv, including pre-releases:pipinstall--prettconv

ttconvert-i<input.sccfile>-o<output.ttmlfile>DocumentationCommand linett 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)--configand--config_file: JSON dictionaries with the following members:"general": JSON object: General configuration options (see below)"imsc_writer": JSON object: IMSC Writer configuration options (see below)"stl_reader": JSON object: STL Reader configuration options (see below)"vtt_writer": JSON object: WebVTT Writer configuration options (see below)"srt_writer": JSON object: SRT Writer configuration options (see below)"scc_reader": JSON object: SCC Reader configuration options (see below)Example:tt convert -i <.scc file> -o <.ttml file> --itype SCC --otype TTML --config '{"general": {"progress_bar":false, "log_level":"WARN"}}'General configurationprogress_bar"progress_bar": true | falseA progress bar is displayed ifprogress_baristrueandlog_levelis"INFO".Default:truelog_level"log_level": "INFO" | "WARN" | "ERROR"Logging verbosityDefault:"INFO"document_lang"document_lang": <RFC 5646 language tag>Overrides the top-level language of the input document.Example:"document_lang": "es-419"Default:NoneIMSC Writer configurationtime_format"time_format": "frames" | "clock_time" | "clock_time_with_frames"Specifies whether the TTML time expressions are in frames (f),HH:MM:SS.mmmorHH:MM:SS:FFDefault:"frames"if"fps"is specified,"clock_time"otherwisefps"fps": "<num>/<denom>"Specifies thettp:frameRateandttp:frameRateMultiplierof the output document.Required whentime_formatisframesorclock_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 configurationdisable_fill_line_gap"disable_fill_line_gap" : true | falsetruemeans that the STL reader does not fill gaps between linesDefault:falsedisable_line_padding"disable_line_padding" : true | falsetruemeans that the STL reader does not add padding at the begining/end of linesDefault:falseprogram_start_tc"program_start_tc" : "TCP" | "HH:MM:SS:FF"Specifies a starting offset, either the TCP field of the GSI block or a user-specified timecodeDefault:"00:00:00:00"font_stack"font_stack" : [<font-families>](https://www.w3.org/TR/ttml2/#style-value-font-families)Overrides the font stackDefault:"Verdana, Arial, Tiresias, sansSerif"max_row_count"max_row_count" : "MNR" | integerSpecifies a maximum number of rows for open subtitles, either the MNR field of the GSI block or a user-specified valueDefault:23SRT Writer configurationtext_formatting"text_formatting" : true | falsefalsemeans that the SRT writer does not output any text formatting tagsDefault:trueVTT Writer configurationline_position"line_position" : true | falsetruemeans that the VTT writer outputs line and line alignment cue settingsDefault:falsetext_align"text_align" : true | falsetruemeans that the VTT writer outputs text alignment cue settingsDefault:falsecue_id"cue_id" : true | falsetruemeans that the VTT writer outputs cue identifiersDefault:trueSCC Reader configurationtext_align"text_align" : "auto" | "left" | "center" | "right"Specifies the text alignment."auto"means the reader will use heuristics to determine
text alignment.Default:"auto"LibraryThe overall architecture of the library is as follows:Reader modules validate and convert input files into instances of the canonical model (seettconv.imsc.reader.to_model()for
example);Filter modules transform instances of the canonical data model, e.g. all text styling and positioning might be removed from an
instance of the canonical model to match the limited capabilities of downstream devices; andWriter modules convert instances of the canonical data model into output files.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 Pythonloggingmodule to report non-fatal events.Unit tests illustrate the use of the library, e.g.ReaderWriterTest.test_imsc_1_test_suiteatsrc/test/python/test_imsc_writer.py.Detailed documentation including reference documents is underdoc.DependenciesRuntimepython >= 3.7DevelopmentThe project usespipenvto manage dependencies.pylintcoverageDevelopmentSetupLocalrunpipenv install --devset thePYTHONPATHenvironment variable tosrc/main/python, e.g.export PYTHONPATH=src/main/pythonpipenv runcan then be usedDockerdockerbuild--rm-fDockerfile-tttconv:latest.
dockerrun-it--rmttconv:latestbashExampleFrom the root directory of the project:mkdirbuild
pipenvinstall--devexportPYTHONPATH=src/main/python
pythonsrc/main/python/ttconv/tt.pyconvert-isrc/test/resources/scc/mix-rows-roll-up.scc-obuild/mix-rows-roll-up.ttmlCode coverageUnit test code coverage is provided by the script atscripts/coverage.shContinuous integrationOverviewAutomated testing is provided by the script atscripts/ci.shLocalRunPYTHONPATH=src/main/python ./scripts/ci.shGitHub actionsSee.github/workflows/main.ymlDockerRundocker run -it --rm  ttconv:latest /bin/sh scripts/ci.sh