subtatix 0.2.4

CLI for generating and translating subtitles with WhisperX

Subtatix

Subtatix is a small CLI for generating .srt (or .vtt) subtitles with local AI from audio or video files with optional translation. Everything is processed on your machine.

Generate subtitles from my-video.mp4 into my-video.srt and my-video.es.srt (Spanish):

subtatix transcribe my-video.mp4 --to es

It relies heavily on WhisperX for transcription and subtitle timing alignment.

Requirements

• Python 3.12+
• ffmpeg installed separately and available on your PATH
• Enough disk space for model downloads and caching

The first run will be slower because WhisperX and translation models need to be downloaded. Subsequent runs reuse the cached models and do not need to download them again unless the cache is cleared.

ffmpeg is an external system dependency. It is not installed by pip, uvx, or uv tool install.

Installation

Run without installing:

uvx subtatix --help

Install as a tool with uv:

uv tool install subtatix

Install with pip:

pip install subtatix

or from my Forgejo PyPI instance:

uvx --index https://forgejo.chrispaganon.com/api/packages/chris-paganon/pypi/simple/ subtatix --help
uv tool install --index https://forgejo.chrispaganon.com/api/packages/chris-paganon/pypi/simple/ subtatix
pip install --index-url https://forgejo.chrispaganon.com/api/packages/chris-paganon/pypi/simple/ subtatix

Usage

transcribe creates subtitles from an audio or video file. It writes .srt by default:

subtatix transcribe input.mp4
subtatix transcribe input.mp4 --from en --to es --output translated/subtitles
subtatix transcribe input.mp4 --to es --discard-transcription

The first command writes input.srt. The second writes translated/subtitles.srt and translated/subtitles.es.srt. --discard-transcription writes only the translated output when used with --to.

translate translates an existing .srt or .vtt file without transcribing audio or video:

subtatix translate input.srt --from en --to es --output translated/subtitles
subtatix translate input.vtt --from en --to es

For translation-only mode, the input must be an .srt or .vtt file and --from is required. These commands write translated/subtitles.es.srt and input.es.vtt.

Common options and discovery commands:

subtatix transcribe input.mp4 --format vtt
subtatix translate input.srt --from en --to es --format vtt
subtatix transcribe input.mp4 --batch-size 4 --device cpu
subtatix translate input.srt --from en --to es --translation-batch-size 4
subtatix translate input.srt --from en --to es --translation-device cpu
subtatix list languages
subtatix list source-languages
subtatix list target-languages

Passing an --output value that ends in a subtitle suffix like .srt or .vtt is rejected. Use a base path such as --output subtitles instead.

Models

By default, transcription uses WhisperX with the Whisper model large-v2. This is a good general default when you want higher transcription quality and aligned subtitle timings, but it is heavier and slower than smaller Whisper models.

Translation uses facebook/nllb-200-1.3B. The CLI accepts simple target codes such as en, es, fr, de, pt, ja, ko, zh, and also raw NLLB codes such as spa_Latn.

On CUDA, translation loads the model in half precision and automatically retries with smaller translation batches if the GPU runs out of memory. If your GPU is still too small or busy, reduce --translation-batch-size or use --translation-device cpu.

Other model options can also be used:

• For transcription, you can pass another Whisper model with --model, such as small, medium, or large-v3, depending on your speed and accuracy needs.
• For translation, the code currently defaults to the NLLB model above, but the translation layer is built around Hugging Face seq2seq models and could be adapted to use a different multilingual translation model if needed.

Examples:

subtatix transcribe input.mp4 --model small
subtatix transcribe input.mp4 --model large-v3 --to spa_Latn
subtatix list target-languages

Limitations

• Translations are processed one subtitle cue at a time to preserve the original timing exactly. The tradeoff is that each cue is translated without the surrounding subtitle lines, so some lines may sound less natural when they depend on nearby context.
• Adding nearby cues as extra context is not reliable with regular translation models, because they cannot tell which text is only context and which text must actually be translated.
• Translating larger blocks and splitting them back into subtitle cues is also not a good fit. Translation can reorder or merge sentence parts across cue boundaries, making it impossible to split the result back without damaging the timing.
• A typical llm model could handle context more explicitly, but that would make translation much slower, heavier, and less predictable, especially with smaller local models.