whispersub

Transcribe video files to ASS subtitle files using faster-whisper. Whisper detects the spoken language automatically and supports 99 languages, including English, Spanish, French, German, Japanese, Chinese, Arabic, Hindi, and many more.

  • NVIDIA GPU acceleration with automatic CPU fallback
  • Batch mode: pass multiple video files or directory trees
  • Surround-sound audio extraction (dialogue-channel aware)
  • Word-level timestamps with balanced line breaking
  • Per-word confidence colour coding in the terminal

Requirements

Python 3.10+. Works on Linux, Windows, and macOS. No system FFmpeg needed — PyAV bundles its own. Supports MKV, MP4, AVI, MOV, WebM, TS, and other common video formats.

Install

pip install whispersub

GPU acceleration (Linux/Windows — requires an NVIDIA GPU with CUDA 12):

pip install whispersub[gpu]

Without [gpu], whispersub falls back to CPU automatically if CUDA is unavailable.

On first run, whispersub downloads the Whisper large-v3-turbo model (~800 MB) from Hugging Face and caches it locally.

Usage

# Single file — writes movie.en.ass alongside the video
whispersub movie.mkv

# Explicit output directory
whispersub movie.mkv --output-dir ~/subs

# Whole directory, force overwrite
whispersub /media/shows --force

# File with multiple audio tracks — inspect, then pick one
whispersub series.mkv --list-audio-tracks
whispersub series.mkv --audio-track 2

Options

Option Default Description
--audio-track N — Audio track index (required if the file has multiple tracks)
--list-audio-tracks off Show audio tracks for all input videos, grouped by configuration, and exit
--colour-by probability Per-word terminal colour coding: probability or duration
--font-size N 48 Font size (1280×720 canvas; player scales to actual resolution)
--force off Overwrite existing subtitle files (keeps backups)
--keep N 3 Number of .bak copies to keep when overwriting
--limit N — Stop after N segments per video (useful for testing)
--max-line-count N 2 Maximum subtitle lines per card
--max-line-width N 36 Maximum characters per line
--max-threads N all cores CPU thread limit
--output-dir DIR alongside video Write all subtitle files to this directory

Output

Subtitle files are named <stem>.<language>.ass, e.g. movie.en.ass. The detected language comes from Whisper. Output is compatible with VLC, mpv, IINA, MPC-HC, and other players that support ASS/SSA subtitles.

We chose ASS over SRT for better-looking subtitles: font sizing scales correctly to any resolution, and line breaks are balanced for readability. It also allows us to preserve word-level timing, so the file can be post-processed or reformatted without re-transcribing.

Licence

MIT

Project links

Data verified by PyPI on Mar 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for zvea from gravatar.com zvea

GitHub Statistics

Data verified by PyPI on Mar 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

gpu dev

Tags

ASS audio automatic subtitles captions faster-whisper multilingual speech recognition speech-to-text SRT SSA subtitle subtitle generation subtitles transcription video whisper

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

whispersub-1.5.1.tar.gz (35.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

whispersub-1.5.1-py3-none-any.whl (18.1 kB view details)

Uploaded Python 3

File details

Details for the file whispersub-1.5.1.tar.gz.

File metadata

  • Download URL: whispersub-1.5.1.tar.gz
  • Upload date:
  • Size: 35.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for whispersub-1.5.1.tar.gz
Algorithm Hash digest
SHA256 95283a56fd9609a372166add7bce6d086a68424c8700a5d9caebe7d437554e8c
MD5 2e2f73c11340c5475b4b034949634a03
BLAKE2b-256 fca1c10b6b7c51972a9d6ec3ab2b08a31173e325ea16ce2b75b4ffa558362665

See more details on using hashes here.

Provenance

The following attestation bundles were made for whispersub-1.5.1.tar.gz:

Publisher: publish.yml on zvea/whispersub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file whispersub-1.5.1-py3-none-any.whl.

File metadata

  • Download URL: whispersub-1.5.1-py3-none-any.whl
  • Upload date:
  • Size: 18.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for whispersub-1.5.1-py3-none-any.whl
Algorithm Hash digest
SHA256 2988c4fdd86e83997b5fd0f72017dd54b51dd5e9a805de84b6212bcef2c01fec
MD5 e940bb4d2bcf9009067e4589f179de27
BLAKE2b-256 164eda4b937d2a78330e6eb2fab4d87a7bb08f21a5455c9ed0ff8f54a76d950b

See more details on using hashes here.

Provenance

The following attestation bundles were made for whispersub-1.5.1-py3-none-any.whl:

Publisher: publish.yml on zvea/whispersub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.5.1 This release

2 files

1.5.0

2 files

1.4.0

2 files

1.3.1

2 files

1.3.0

2 files

1.2.1

2 files

1.2.0

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.2

2 files

1.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page