Metadata-Version: 2.4
Name: subtatix
Version: 0.2.1
Summary: CLI for generating and translating subtitles with WhisperX
Keywords: cli,subtitles,srt,vtt,whisperx,transcription,translation
Author: Chris Paganon
Author-email: Chris Paganon <info@chrispaganon.com>
License-Expression: BSD-2-Clause
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Dist: accelerate>=1.13.0
Requires-Dist: sentencepiece>=0.2.1
Requires-Dist: torch>=2.8.0
Requires-Dist: transformers>=4.57.6
Requires-Dist: typer>=0.25.1
Requires-Dist: whisperx>=3.8.5
Requires-Python: >=3.12
Project-URL: Homepage, https://codeberg.org/chris-paganon/subtatix
Project-URL: Repository, https://codeberg.org/chris-paganon/subtatix
Project-URL: Issues, https://codeberg.org/chris-paganon/subtatix/issues
Description-Content-Type: text/markdown

# 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):

```bash
subtatix transcribe my-video.mp4 --to es
```

It relies heavily on [WhisperX](https://github.com/m-bain/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:

```bash
uvx subtatix --help
```

Install as a tool with `uv`:

```bash
uv tool install subtatix
```

Install with `pip`:

```bash
pip install subtatix
```

or from my Forgejo PyPI instance:

```bash
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:

```bash
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:

```bash
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:

```bash
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 --list-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`.

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:

```bash
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.
