subaligner

Codecov

Supported Formats

Subtitle: SubRip, TTML, WebVTT, (Advanced) SubStation Alpha, MicroDVD, MPL2, TMP, EBU STL, SAMI, SCC and SBV.

Video/Audio: MP4, WebM, Ogg, 3GP, FLV, MOV, Matroska, MPEG TS, WAV, MP3, AAC, FLAC, etc.

:information_source: Subaligner relies on file extensions as default hints to process a wide range of audiovisual or subtitle formats. It is recommended to use extensions widely acceppted by the community to ensure compatibility.

Dependant package

Required by the basic installation: FFmpeg

Install FFmpeg

apt-get install ffmpeg

brew install ffmpeg

Basic Installation

Install from PyPI

pip install -U pip && pip install wheel

pip install subaligner

Install from source

git clone git@github.com:baxtree/subaligner.git && cd subaligner

pip install -U pip

pip install .

:information_source: It is highly recommended creating a virtual environment prior to installation.

Installation with Optional Packages Supporting Additional Features

Install dependencies for enabling translation and transcription

pip install 'subaligner[llm]'

Install dependencies for enabling forced alignment

pip install --no-build-isolation 'subaligner[stretch]'

Install dependencies for setting up the development environment

pip install --no-build-isolation 'subaligner[dev]'

Install all extra dependencies

pip install --no-build-isolation 'subaligner[harmony]'

Note that subaligner[stretch], subaligner[dev] and subaligner[harmony] require eSpeak to be pre-installed:

Install eSpeak

apt-get install espeak libespeak1 libespeak-dev espeak-data

brew install espeak

Also, if Python 3.12+ is used, you will need to install the following patch for those extras to fully function:

Install patched aeneas

pip install --no-build-isolation -r requirements-py312-patched.txt

Container Support

If you prefer using a containerised environment over installing everything locally:

Run subaligner with a container

docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner bash

For Windows users, you can use Windows Subsystem for Linux (WSL) to install Subaligner. Alternatively, you can use Docker Desktop to pull and run the image. Assuming your media assets are stored under d:\media, open built-in command prompt, PowerShell, or Windows Terminal:

Run the subaligner container on Windows

docker pull baxtree/subaligner

docker run -v "/d/media":/media -w "/media" -it baxtree/subaligner bash

Usage

Single-stage alignment (high-level shift with lower latency)

subaligner -m single -v video.mp4 -s subtitle.srt

subaligner -m single -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt

Dual-stage alignment (low-level shift with higher latency)

subaligner -m dual -v video.mp4 -s subtitle.srt

subaligner -m dual -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt

Generate subtitles by transcribing audiovisual files

subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf small -o subtitle_aligned.srt

subaligner -m transcribe -v video.mp4 -ml zho -mr whisper -mf medium -o subtitle_aligned.srt

Pass in a global prompt for the entire audio transcription

subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" -o subtitle_aligned.srt

Use the full subtitle content as a prompt

subaligner -m transcribe -v video.mp4 -s subtitle.srt -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt

Use the previous subtitle segment as the prompt when transcribing the following segment

subaligner -m transcribe -v video.mp4 -s subtitle.srt --use_prior_prompting -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt

(For details on the prompt crafting for transcription, please refer to Whisper prompting guide.)

Alignment on segmented plain texts (double newlines as the delimiter)

subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt

subaligner -m script -v https://example.com/video.mp4 -s https://example.com/subtitle.txt -o subtitle_aligned.srt

Generate JSON raw subtitle with per-word timings

subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" --word_time_codes -o raw_subtitle.json

subaligner -m script -v video.mp4 -s subtitle.txt --word_time_codes -o raw_subtitle.json

Alignment on multiple subtitles against the single media file

subaligner -m script -v video.mp4 -s subtitle_lang_1.txt -s subtitle_lang_2.txt

subaligner -m script -v video.mp4 -s subtitle_lang_1.txt subtitle_lang_2.txt

Alignment on embedded subtitles

subaligner -m single -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt

subaligner -m dual -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt

Translative alignment with the ISO 639-3 language code pair (src,tgt)

subaligner --languages

subaligner -m single -v video.mp4 -s subtitle.srt -t src,tgt

subaligner -m dual -v video.mp4 -s subtitle.srt -t src,tgt

subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt -t src,tgt

subaligner -m dual -v video.mp4 -s subtitle.srt -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt

subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-mbart -tf large -o subtitle_aligned.srt -t src,tgt

subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-m2m100 -tf small -o subtitle_aligned.srt -t src,tgt

subaligner -m dual -v video.mp4 -s subtitle.srt -tr whisper -tf small -o subtitle_aligned.srt -t src,tgt

Transcribe audiovisual files and generate translated subtitles

subaligner -m transcribe -v video.mp4 -ml src -mr whisper -mf small -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt

Shift subtitle manually by offset in seconds

subaligner -m shift --subtitle_path subtitle.srt -os 5.5

subaligner -m shift --subtitle_path subtitle.srt -os -5.5 -o subtitle_shifted.srt

Run batch alignment against directories

subaligner_batch -m single -vd videos/ -sd subtitles/ -od aligned_subtitles/

subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/

subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/ -of ttml

Run alignments with pipx

pipx run subaligner -m single -v video.mp4 -s subtitle.srt

pipx run subaligner -m dual -v video.mp4 -s subtitle.srt

Run the module as a script

python -m subaligner -m single -v video.mp4 -s subtitle.srt

python -m subaligner -m dual -v video.mp4 -s subtitle.srt

Run alignments with the docker image

docker pull baxtree/subaligner

docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m single -v video.mp4 -s subtitle.srt

docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m dual -v video.mp4 -s subtitle.srt

docker run -it baxtree/subaligner subaligner -m single -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt

docker run -it baxtree/subaligner subaligner -m dual -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt

The aligned subtitle will be saved at subtitle_aligned.srt. To obtain the subtitle in raw JSON format for downstream processing, replace the output file extension with .json. For details on CLIs, run subaligner -h or subaligner_batch -h, subaligner_convert -h, subaligner_train -h and subaligner_tune -h for additional utilities. subaligner_1pass and subaligner_2pass are shortcuts for running subaligner with -m single and -m dual options, respectively.

Advanced Usage

You can train a new model with your own audiovisual files and subtitle files,

Train a custom model

subaligner_train -vd VIDEO_DIRECTORY -sd SUBTITLE_DIRECTORY -tod TRAINING_OUTPUT_DIRECTORY

Then you can apply it to your subtitle synchronisation with the aforementioned commands. For more details on how to train and tune your own model, please refer to Subaligner Docs.

For larger media files taking longer to process, you can reconfigure various timeouts using the following:

Options for tuning timeouts

-mpt [Maximum waiting time in seconds when processing media files]
-sat [Maximum waiting time in seconds when aligning each segment]
-fet [Maximum waiting time in seconds when embedding features for training]

Anatomy

Subtitles can be out of sync with their companion audiovisual media files for a variety of causes including latency introduced by Speech-To-Text on live streams or calibration and rectification involving human intervention during post-production.

A model has been trained with synchronised video and subtitle pairs and later used for predicating shifting offsets and directions under the guidance of a dual-stage aligning approach.

First Stage (Global Alignment):

Second Stage (Parallelised Individual Alignment):

Acknowledgement

This tool wouldn't be possible without the following packages: librosa tensorflow scikit-learn pycaption pysrt pysubs2 aeneas transformers whisper.

Thanks to Alan Robinson and Nigel Megitt for their invaluable feedback.

Metadata

Release files for subaligner 0.3.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for subaligner 0.3.15
File	Size	Uploaded	Provenance	Actions
subaligner-0.3.15.tar.gz	44.5 MB	Jun 1, 2026	Without provenance	Details for subaligner-0.3.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for subaligner 0.3.15
File	Interpreter	ABI	Platform	Actions Reset
subaligner-0.3.15-py3-none-any.whl 3.4 MB Jun 1, 2026 Without provenance	Python 3	none	any	Details for subaligner-0.3.15-py3-none-any.whl

Total release size: 47.9 MB

Release files / subaligner-0.3.15.tar.gz

Download URL	subaligner-0.3.15.tar.gz
Size	44.5 MB
Tags	Source
SHA-256 checksum How to use checksums	`946f29ed7e0bc373a60997d1cdcd8577a2f73a6c3f9b1851d6b177a1219d260e`
BLAKE2b-256 checksum How to use checksums	`c95a215a7d4d3f3c28826844cd14f815a8c94906567bd2a8a9055886b4fc72c9`
Upload date	Jun 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/8.7.1 pkginfo/1.12.1.2 requests/2.33.1 requests-toolbelt/1.0.0 tqdm/4.67.1 CPython/3.10.14`

Release files / subaligner-0.3.15-py3-none-any.whl

Download URL	subaligner-0.3.15-py3-none-any.whl
Size	3.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`65919165f4888e2f12d864da8a1ff8f185ebe7786db2435056d344e5d41058c1`
BLAKE2b-256 checksum How to use checksums	`76777058dfe4a77f6c36c95367efb3034a40f2f1698fbc47c80e891550c4f806`
Upload date	Jun 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/8.7.1 pkginfo/1.12.1.2 requests/2.33.1 requests-toolbelt/1.0.0 tqdm/4.67.1 CPython/3.10.14`

Security for subaligner 0.3.15

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.15 This release

Jun 1, 2026 2 release files No provenance

subaligner 0.3.15