Library for conversion of common timed text formats
Project description
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.
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 data model, as constrained by the IMSC 1.1 Text Profile specification.
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
Output Formats
Quick start
pip install ttconv
tt.py convert -i <input .scc file> -o <output .ttml file>
Documentation
Command line
tt.py convert [-h] -i INPUT -o OUTPUT [--itype ITYPE] [--otype OTYPE] [--config CONFIG] [--config_file CONFIG_FILE]
-
--itype
:TTML
orSCC
(extrapolated from the filename, if omitted) -
--otype
:TTML
orSRT
(extrapolated from the filename, if omitted) -
--config
and--config_file
: JSON dictionaries with the following members:"general"."progress_bar": "true" | "false"
: whether a progress bar is displayed"general"."log_level": "INFO" | "WARN" | "ERROR"
: logging level"imsc_writer"."time_format": "frames" | "clock_time"
: output TTML expressions in seconds or in frames"imsc_writer"."fps": "<num>/<denom>"
: specifies the frame rate num/denom when output TTML expressions in frames
Example:
tt.py convert -i <.scc file> -o <.ttml file> --itype SCC --otype TTML --config '{"general": {"progress_bar":false, "log_level":"WARN"}}'
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
.
Dependencies
Runtime
Development
The project uses pipenv to manage dependencies.
Development
Setup
Local
- run
pipenv install --dev
- set the
PYTHONPATH
environment variable tosrc/main/python
, e.g.export PYTHONPATH=src/main/python
pipenv run
can then be used
Docker
docker build --rm -f Dockerfile -t ttconv:latest .
docker run -it --rm ttconv:latest bash
Example
From the root directory of the project:
mkdir build
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 ./scripts/ci.sh
GitHub actions
See .github/workflows/main.yml
Docker
Run docker run -it --rm ttconv:latest /bin/sh scripts/ci.sh
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ttconv-1.0.1rc2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | eab5659f0f2d1af879dd4036579d9e7fb39aefffb8277fe324ac965ccc12b262 |
|
MD5 | 43d5ccc5bf33b2a2093e1ef68de9c568 |
|
BLAKE2b-256 | c6f33b38fb277d91e011d7c0d7b9ca42ebf1faf7bae5639992f1f6a872abfc68 |