# ttconv (Timed Text Conversion)
$$\ $$\
$$ | $$ |
$$$$$$\ $$$$$$\ $$$$$$$\ $$$$$$\ $$$$$$$\ $$\ $$\
\_$$ _|\_$$ _| $$ _____|$$ __$$\ $$ __$$\\$$\ $$ |
$$ | $$ | $$ / $$ / $$ |$$ | $$ |\$$\$$ /
$$ |$$\ $$ |$$\ $$ | $$ | $$ |$$ | $$ | \$$$ /
\$$$$ |\$$$$ |\$$$$$$$\ \$$$$$$ |$$ | $$ | \$ /
\____/ \____/ \_______| \______/ \__| \__| \_/
## Introduction
_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 ----- Canonical Model -------- WebVTT
/ \
EBU STL ------- --- SRT
/
SRT ---------
/
WebVTT ----
_ttconv_ works 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 the [TTML 2](https://www.w3.org/TR/ttml2) data model,
as constrained by the [IMSC 1.1 Text Profile](https://www.w3.org/TR/ttml-imsc1.1/#text-profile) specification.
## Online demo
[https://ttconv.sandflow.com/](https://ttconv.sandflow.com/)
## Format support
_ttconv_ currently supports the following input and output formats. Additional input and output formats are planned, and
suggestions/contributions are welcome.
### Input Formats
* [CEA 608/.scc](https://en.wikipedia.org/wiki/EIA-608)
* [IMSC 1.1 Text Profile/.ttml](https://www.w3.org/TR/ttml-imsc1.1/#text-profile)
* [EBU STL](https://tech.ebu.ch/docs/tech/tech3264.pdf)
* [SubRip/.srt](https://en.wikipedia.org/wiki/SubRip)
* [WebVTT](https://www.w3.org/TR/webvtt1/)
### Output Formats
* [SubRip/.srt](https://en.wikipedia.org/wiki/SubRip)
* [IMSC 1.1 Text Profile/.ttml](https://www.w3.org/TR/ttml-imsc1.1/#text-profile)
* [WebVTT](https://www.w3.org/TR/webvtt1/)
## Quick start
To install the latest version of `ttconv`, including pre-releases:
```sh
pip install --pre ttconv
tt convert -i <input .scc file> -o <output .ttml file>
```
## Documentation
### Command line
`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)
* `--config` and `--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 configuration
#### progress_bar
`"progress_bar": true | false`
A progress bar is displayed if `progress_bar` is `true` and `log_level` is `"INFO"`.
Default: `true`
### log_level
`"log_level": "INFO" | "WARN" | "ERROR"`
Logging verbosity
Default: `"INFO"`
### document_lang
`"document_lang": <RFC 5646 language tag>`
Overrides the top-level language of the input document.
Example: `"document_lang": "es-419"`
Default: `None`
### IMSC Writer configuration
### time_format
`"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
`"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 configuration
#### disable_fill_line_gap
`"disable_fill_line_gap" : true | false`
`true` means that the STL reader does not fill gaps between lines
Default: `false`
#### disable_line_padding
`"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
`"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_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
`"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 configuration
#### text_formatting
`"text_formatting" : true | false`
`false` means that the SRT writer does not output any text formatting tags
Default: `true`
### VTT Writer configuration
#### line_position
`"line_position" : true | false`
`true` means that the VTT writer outputs line and line alignment cue settings
Default: `false`
#### text_align
`"text_align" : true | false`
`true` means that the VTT writer outputs text alignment cue settings
Default: `false`
#### cue_id
`"cue_id" : true | false`
`true` means that the VTT writer outputs cue identifiers
Default: `true`
### SCC Reader configuration
#### text_align
`"text_align" : "auto" | "left" | "center" | "right"`
Specifies the text alignment. `"auto"` means the reader will use heuristics to determine
text alignment.
Default: `"auto"`
### Library
The overall architecture of the library is as follows:
* Reader modules validate and convert input files into instances of the canonical model (see `ttconv.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; and
* Writer 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 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`](./doc).
## Dependencies
### Runtime
* [python >= 3.7](https://python.org)
### Development
The project uses [pipenv](https://pypi.org/project/pipenv/) to manage dependencies.
* [pylint](https://pypi.org/project/pylint/)
* [coverage](https://pypi.org/project/coverage/)
## Development
### Setup
#### Local
* run `pipenv install --dev`
* set the `PYTHONPATH` environment variable to `src/main/python`, e.g. `export PYTHONPATH=src/main/python`
* `pipenv run` can then be used
#### Docker
```sh
docker build --rm -f Dockerfile -t ttconv:latest .
docker run -it --rm ttconv:latest bash
```
### Example
From the root directory of the project:
```sh
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
```
### Code coverage
Unit test code coverage is provided by the script at `scripts/coverage.sh`
### Continuous integration
#### Overview
Automated testing is provided by the script at `scripts/ci.sh`
#### Local
Run `PYTHONPATH=src/main/python ./scripts/ci.sh`
#### GitHub actions
See `.github/workflows/main.yml`
#### Docker
Run `docker run -it --rm ttconv:latest /bin/sh scripts/ci.sh`
Raw data
{
"_id": null,
"home_page": "https://github.com/sandflow/ttconv",
"name": "ttconv",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7, <4",
"maintainer_email": "",
"keywords": "ttml,timed text,caption,subtitle,imsc,scc,srt,stl,smpte-tt,conversion,vtt,webvtt,608",
"author": "Sandflow Consulting LLC",
"author_email": "info@sandflow.com",
"download_url": "https://files.pythonhosted.org/packages/cc/a0/3708520c508da0656caf77ac75a74cc839cb47e1d556f9e52fd00debf7ef/ttconv-1.0.8.tar.gz",
"platform": null,
"description": "# ttconv (Timed Text Conversion)\r\n\r\n $$\\ $$\\ \r\n $$ | $$ | \r\n $$$$$$\\ $$$$$$\\ $$$$$$$\\ $$$$$$\\ $$$$$$$\\ $$\\ $$\\ \r\n \\_$$ _|\\_$$ _| $$ _____|$$ __$$\\ $$ __$$\\\\$$\\ $$ |\r\n $$ | $$ | $$ / $$ / $$ |$$ | $$ |\\$$\\$$ / \r\n $$ |$$\\ $$ |$$\\ $$ | $$ | $$ |$$ | $$ | \\$$$ / \r\n \\$$$$ |\\$$$$ |\\$$$$$$$\\ \\$$$$$$ |$$ | $$ | \\$ / \r\n \\____/ \\____/ \\_______| \\______/ \\__| \\__| \\_/ \r\n\r\n## Introduction\r\n\r\n_ttconv_ is a library and command line application written in pure Python for converting between timed text\r\nformats used in the presentations of captions, subtitles, karaoke, etc.\r\n\r\n TTML / IMSC --- --- IMSC / TTML\r\n \\ /\r\n SCC / CEA 608 ----- Canonical Model -------- WebVTT\r\n / \\\r\n EBU STL ------- --- SRT\r\n /\r\n SRT ---------\r\n /\r\n WebVTT ----\r\n\r\n_ttconv_ works by mapping the input document, whatever its format, into an internal canonical model, which is then mapped to the\r\nformat of the output document is derived. The canonical model closely follows the [TTML 2](https://www.w3.org/TR/ttml2) data model,\r\nas constrained by the [IMSC 1.1 Text Profile](https://www.w3.org/TR/ttml-imsc1.1/#text-profile) specification.\r\n\r\n## Online demo\r\n\r\n[https://ttconv.sandflow.com/](https://ttconv.sandflow.com/)\r\n\r\n## Format support\r\n\r\n_ttconv_ currently supports the following input and output formats. Additional input and output formats are planned, and\r\nsuggestions/contributions are welcome.\r\n\r\n### Input Formats\r\n\r\n* [CEA 608/.scc](https://en.wikipedia.org/wiki/EIA-608)\r\n* [IMSC 1.1 Text Profile/.ttml](https://www.w3.org/TR/ttml-imsc1.1/#text-profile)\r\n* [EBU STL](https://tech.ebu.ch/docs/tech/tech3264.pdf)\r\n* [SubRip/.srt](https://en.wikipedia.org/wiki/SubRip)\r\n* [WebVTT](https://www.w3.org/TR/webvtt1/)\r\n\r\n### Output Formats\r\n\r\n* [SubRip/.srt](https://en.wikipedia.org/wiki/SubRip)\r\n* [IMSC 1.1 Text Profile/.ttml](https://www.w3.org/TR/ttml-imsc1.1/#text-profile)\r\n* [WebVTT](https://www.w3.org/TR/webvtt1/)\r\n\r\n## Quick start\r\n\r\nTo install the latest version of `ttconv`, including pre-releases:\r\n\r\n```sh\r\npip install --pre ttconv\r\n\r\ntt convert -i <input .scc file> -o <output .ttml file>\r\n```\r\n\r\n## Documentation\r\n\r\n### Command line\r\n\r\n`tt convert [-h] -i INPUT -o OUTPUT [--itype ITYPE] [--otype OTYPE] [--config CONFIG] [--config_file CONFIG_FILE]`\r\n\r\n* `--itype`: `TTML` | `SCC` | `STL` | `SRT` (extrapolated from the filename, if omitted)\r\n* `--otype`: `TTML` | `SRT` | `VTT` (extrapolated from the filename, if omitted)\r\n* `--config` and `--config_file`: JSON dictionaries with the following members:\r\n * `\"general\": JSON object`: General configuration options (see below)\r\n * `\"imsc_writer\": JSON object`: IMSC Writer configuration options (see below)\r\n * `\"stl_reader\": JSON object`: STL Reader configuration options (see below)\r\n * `\"vtt_writer\": JSON object`: WebVTT Writer configuration options (see below)\r\n * `\"srt_writer\": JSON object`: SRT Writer configuration options (see below)\r\n * `\"scc_reader\": JSON object`: SCC Reader configuration options (see below)\r\n\r\nExample:\r\n\r\n`tt convert -i <.scc file> -o <.ttml file> --itype SCC --otype TTML --config '{\"general\": {\"progress_bar\":false, \"log_level\":\"WARN\"}}'`\r\n\r\n### General configuration\r\n\r\n#### progress_bar\r\n\r\n`\"progress_bar\": true | false`\r\n\r\nA progress bar is displayed if `progress_bar` is `true` and `log_level` is `\"INFO\"`.\r\n\r\nDefault: `true`\r\n\r\n### log_level\r\n\r\n`\"log_level\": \"INFO\" | \"WARN\" | \"ERROR\"`\r\n\r\nLogging verbosity\r\n\r\nDefault: `\"INFO\"`\r\n\r\n### document_lang\r\n\r\n`\"document_lang\": <RFC 5646 language tag>`\r\n\r\nOverrides the top-level language of the input document.\r\n\r\nExample: `\"document_lang\": \"es-419\"`\r\n\r\nDefault: `None`\r\n\r\n### IMSC Writer configuration\r\n\r\n### time_format\r\n\r\n`\"time_format\": \"frames\" | \"clock_time\" | \"clock_time_with_frames\"`\r\n\r\nSpecifies whether the TTML time expressions are in frames (`f`), `HH:MM:SS.mmm` or `HH:MM:SS:FF`\r\n\r\nDefault: `\"frames\"` if `\"fps\"` is specified, `\"clock_time\"` otherwise\r\n\r\n### fps\r\n\r\n`\"fps\": \"<num>/<denom>\"`\r\n\r\nSpecifies the `ttp:frameRate` and `ttp:frameRateMultiplier` of the output document.\r\n\r\nRequired when `time_format` is `frames` or `clock_time_with_frames`. No effect otherwise.\r\n\r\nExample:\r\n\r\n`--config '{\"general\": {\"progress_bar\":false, \"log_level\":\"WARN\"}, \"imsc_writer\": {\"time_format\":\"clock_time_with_frames\", \"fps\": \"25/1\"}}'`\r\n\r\n### STL Reader configuration\r\n\r\n#### disable_fill_line_gap\r\n\r\n`\"disable_fill_line_gap\" : true | false`\r\n\r\n`true` means that the STL reader does not fill gaps between lines\r\n\r\nDefault: `false`\r\n\r\n#### disable_line_padding\r\n\r\n`\"disable_line_padding\" : true | false`\r\n\r\n`true` means that the STL reader does not add padding at the begining/end of lines\r\n\r\nDefault: `false`\r\n\r\n#### program_start_tc\r\n\r\n`\"program_start_tc\" : \"TCP\" | \"HH:MM:SS:FF\"`\r\n\r\nSpecifies a starting offset, either the TCP field of the GSI block or a user-specified timecode\r\n\r\nDefault: `\"00:00:00:00\"`\r\n\r\n#### font_stack\r\n\r\n`\"font_stack\" : [<font-families>](https://www.w3.org/TR/ttml2/#style-value-font-families)`\r\n\r\nOverrides the font stack\r\n\r\nDefault: `\"Verdana, Arial, Tiresias, sansSerif\"`\r\n\r\n#### max_row_count\r\n\r\n`\"max_row_count\" : \"MNR\" | integer`\r\n\r\nSpecifies a maximum number of rows for open subtitles, either the MNR field of the GSI block or a user-specified value\r\n\r\nDefault: `23`\r\n\r\n### SRT Writer configuration\r\n\r\n#### text_formatting\r\n\r\n`\"text_formatting\" : true | false`\r\n\r\n`false` means that the SRT writer does not output any text formatting tags\r\n\r\nDefault: `true`\r\n\r\n### VTT Writer configuration\r\n\r\n#### line_position\r\n\r\n`\"line_position\" : true | false`\r\n\r\n`true` means that the VTT writer outputs line and line alignment cue settings\r\n\r\nDefault: `false`\r\n\r\n#### text_align\r\n\r\n`\"text_align\" : true | false`\r\n\r\n`true` means that the VTT writer outputs text alignment cue settings\r\n\r\nDefault: `false`\r\n\r\n#### cue_id\r\n\r\n`\"cue_id\" : true | false`\r\n\r\n`true` means that the VTT writer outputs cue identifiers\r\n\r\nDefault: `true`\r\n\r\n### SCC Reader configuration\r\n\r\n#### text_align\r\n\r\n`\"text_align\" : \"auto\" | \"left\" | \"center\" | \"right\"`\r\n\r\nSpecifies the text alignment. `\"auto\"` means the reader will use heuristics to determine\r\ntext alignment.\r\n\r\nDefault: `\"auto\"`\r\n\r\n### Library\r\n\r\nThe overall architecture of the library is as follows:\r\n\r\n* Reader modules validate and convert input files into instances of the canonical model (see `ttconv.imsc.reader.to_model()` for\r\n example);\r\n* Filter modules transform instances of the canonical data model, e.g. all text styling and positioning might be removed from an\r\n instance of the canonical model to match the limited capabilities of downstream devices; and\r\n* Writer modules convert instances of the canonical data model into output files.\r\n\r\nProcessing shared across multiple reader and writer modules is factored out in common modules whenever possible. For example,\r\nseveral output formats require an instance of the canonical data model to be transformed into a sequence of discrete temporal\r\nsnapshots \u2013 a process called ISD generation.\r\n\r\nThe library uses the Python `logging` module to report non-fatal events.\r\n\r\nUnit tests illustrate the use of the library, e.g. `ReaderWriterTest.test_imsc_1_test_suite` at\r\n`src/test/python/test_imsc_writer.py`.\r\n\r\nDetailed documentation including reference documents is under [`doc`](./doc).\r\n\r\n## Dependencies\r\n\r\n### Runtime\r\n\r\n* [python >= 3.7](https://python.org)\r\n\r\n### Development\r\n\r\nThe project uses [pipenv](https://pypi.org/project/pipenv/) to manage dependencies.\r\n\r\n* [pylint](https://pypi.org/project/pylint/)\r\n* [coverage](https://pypi.org/project/coverage/)\r\n\r\n## Development\r\n\r\n### Setup\r\n\r\n#### Local\r\n\r\n* run `pipenv install --dev`\r\n* set the `PYTHONPATH` environment variable to `src/main/python`, e.g. `export PYTHONPATH=src/main/python`\r\n* `pipenv run` can then be used\r\n\r\n#### Docker\r\n\r\n```sh\r\ndocker build --rm -f Dockerfile -t ttconv:latest .\r\ndocker run -it --rm ttconv:latest bash\r\n```\r\n\r\n### Example\r\n\r\nFrom the root directory of the project:\r\n\r\n```sh\r\nmkdir build\r\npipenv install --dev\r\nexport PYTHONPATH=src/main/python\r\npython src/main/python/ttconv/tt.py convert -i src/test/resources/scc/mix-rows-roll-up.scc -o build/mix-rows-roll-up.ttml\r\n```\r\n\r\n### Code coverage\r\n\r\nUnit test code coverage is provided by the script at `scripts/coverage.sh`\r\n\r\n### Continuous integration\r\n\r\n#### Overview\r\n\r\nAutomated testing is provided by the script at `scripts/ci.sh`\r\n\r\n#### Local\r\n\r\nRun `PYTHONPATH=src/main/python ./scripts/ci.sh`\r\n\r\n#### GitHub actions\r\n\r\nSee `.github/workflows/main.yml`\r\n\r\n#### Docker\r\n\r\nRun `docker run -it --rm ttconv:latest /bin/sh scripts/ci.sh`\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Library for conversion of common timed text formats",
"version": "1.0.8",
"project_urls": {
"Bug Reports": "https://github.com/sandflow/ttconv/issues",
"Homepage": "https://github.com/sandflow/ttconv",
"Source": "https://github.com/sandflow/ttconv"
},
"split_keywords": [
"ttml",
"timed text",
"caption",
"subtitle",
"imsc",
"scc",
"srt",
"stl",
"smpte-tt",
"conversion",
"vtt",
"webvtt",
"608"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a341989b7b5bc6e4342c6bbc127bfc176fd929170a1acef01a6d5e8bf1bc95d",
"md5": "c9a42d870b962a11bd6b79f4e6caee43",
"sha256": "340ca3413703f689764c764f56c92c7a647c18ecafb7aab857de49c3a49cfac2"
},
"downloads": -1,
"filename": "ttconv-1.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9a42d870b962a11bd6b79f4e6caee43",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7, <4",
"size": 152362,
"upload_time": "2023-11-27T06:23:09",
"upload_time_iso_8601": "2023-11-27T06:23:09.907786Z",
"url": "https://files.pythonhosted.org/packages/7a/34/1989b7b5bc6e4342c6bbc127bfc176fd929170a1acef01a6d5e8bf1bc95d/ttconv-1.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cca03708520c508da0656caf77ac75a74cc839cb47e1d556f9e52fd00debf7ef",
"md5": "1616d37cae657438e3f7e3992e5ef4c1",
"sha256": "9dc7e68b0c80f8c1cd4c2eff624ccef7399953cf8620630ce5f89727c5d529e4"
},
"downloads": -1,
"filename": "ttconv-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "1616d37cae657438e3f7e3992e5ef4c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7, <4",
"size": 101023,
"upload_time": "2023-11-27T06:23:12",
"upload_time_iso_8601": "2023-11-27T06:23:12.104614Z",
"url": "https://files.pythonhosted.org/packages/cc/a0/3708520c508da0656caf77ac75a74cc839cb47e1d556f9e52fd00debf7ef/ttconv-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-27 06:23:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sandflow",
"github_project": "ttconv",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ttconv"
}
JSON
