whisply

Transcribe, translate, annotate and subtitle audio and video files with OpenAI's Whisper ... fast!

whisply combines faster-whisper and mlx-whisper to offer an easy-to-use solution for batch processing files on Windows, Linux and Mac. It also enables word-level speaker annotation by integrating whisperX and pyannote.

Table of contents

• Features
• Requirements
• Installation
  • Install ffmpeg
  • Installation with pip
  • Installation from source
  • Nvidia GPU fix for Linux users
• Usage
  • CLI
  • App
  • Speaker annotation and diarization
    • Requirements
    • How speaker annotation works
  • Post correction
  • Batch processing
    • Using config files for batch processing
• Citation

Features

• 🚴‍♂️ Performance: whisply selects the fastest Whisper implementation based on your hardware:

  • CPU/GPU (Nvidia CUDA): faster-whisper or whisperX
  • MLX (Apple M1-M5): mlx-whisper

• ⏩ large-v3-turbo Ready: Support for whisper-large-v3-turbo on all devices. Note: Subtitling and annotations on CPU/GPU use whisperX for accurate timestamps, but whisper-large-v3-turbo isn’t currently available for whisperX.

• ✅ Auto Device Selection: whisply automatically chooses faster-whisper (CPU, Nvidia GPU) or whisper-MLX (Apple M1-M5) for transcription and translation unless a specific --device option is passed.

• 🗣️ Word-level Annotations: Enabling --subtitle or --annotate uses whisperX and pyannote for word segmentation and speaker annotations. whisply approximates missing timestamps for numeric words.

• 💬 Customizable Subtitles: Specify words per subtitle block (e.g., "5") to generate .srt, .vtt and .webvtt files with fixed word counts and timestamps.

• 📦 Batch Processing: Handle single files, folders, URLs, or lists via .list documents. See the Batch processing section for details.

• 👩‍💻 CLI / App: whisply can be run directly from CLI or as a browser app.

• ⚙️ Export Formats:

  • Structured: .json, .rttm
  • Unstructured: .txt, .txt (annotated)
  • Markup: .html (compatible with noScribe's editor)
  • Subtitles: .srt, .webvtt, .vtt

Requirements

• FFmpeg
• >= Python3.10 <Python3.14
• GPU processing requires:
  • Nvidia GPU (CUDA: cuBLAS and cuDNN for CUDA 12)
  • Apple Silicon (Mac M1-M5)
• Speaker annotation requires a HuggingFace Access Token

Installation

Install ffmpeg

# --- macOS ---
brew install ffmpeg@7

# --- Linux ---
sudo apt-get update
sudo apt-get install ffmpeg

# --- Windows ---
winget install Gyan.FFmpeg

For more information you can visit the FFmpeg website.

Installation with pip

pip install whisply installs CPU + annotation dependencies (torch, torchaudio, pyannote) out of the box. Add one of the extras below if you want MLX acceleration or the whisply browser app.

1. Create a Python virtual environment

python3 -m venv venv

2. Activate the environment

# --- Linux & macOS ---
source venv/bin/activate

# --- Windows ---
venv\Scripts\activate

3. Install whisply

pip install whisply

4. (Optional) Install extras if you need them

pip install ".[app]"  # For running the whisply browser app
pip install ".[mlx]"  # For running whisply-MLX on Apple M1-M5

Installation from source

1. Clone this repository

git clone https://github.com/tsmdt/whisply.git

2. Change to project folder

cd whisply

3. Create a Python virtual environment

python3 -m venv venv

4. Activate the Python virtual environment

# --- Linux & macOS ---
source venv/bin/activate

# --- Windows ---
venv\Scripts\activate

5. Install whisply

pip install .

6. (Optional) Install whisply extras

pip install -e ".[mlx,app]"

Nvidia GPU fix

Unable to load any of {libcudnn_ops.so.9.1.0, libcudnn_ops.so.9.1, libcudnn_ops.so.9, libcudnn_ops.so}

export LD_LIBRARY_PATH="$(
python - <<'PY'
import importlib.util, pathlib

spec = importlib.util.find_spec("nvidia.cudnn")
if not spec or not spec.submodule_search_locations:
    raise SystemExit("Could not locate nvidia.cudnn package")

pkg_dir = pathlib.Path(spec.submodule_search_locations[0])
lib_dir = pkg_dir / "lib"
print(lib_dir)
PY
):${LD_LIBRARY_PATH}"

printf '\n# --- add cuDNN wheel dir ---\nexport LD_LIBRARY_PATH="$(python - <<'"'"'PY'"'"'\nimport importlib.util, pathlib\nspec = importlib.util.find_spec("nvidia.cudnn")\npkg_dir = pathlib.Path(spec.submodule_search_locations[0])\nprint(pkg_dir / "lib")\nPY\n):${LD_LIBRARY_PATH}"\n' >> "$VIRTUAL_ENV/bin/activate"

Usage

CLI

Three CLI commands are available:

1. whisply run: Running a transcription task
2. whisply app: Starting the whisply browser app
3. whisply list: Listing available models

$ whisply run

 Usage: whisply run [OPTIONS]

 Transcribe files with whisply

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --files              -f               TEXT                                     Path to file, folder, URL or .list to process.               │
│ --output_dir         -o               DIRECTORY                                Output folder [default: transcriptions]                      │
│ --device             -d               [auto|cpu|gpu|mlx]                       CPU, GPU (NVIDIA), MLX (Mac M1-M5) [default: auto]           │
│ --model              -m               TEXT                                     Whisper model (run "whisply list" to see options)            │
│                                                                                [default: large-v3-turbo]                                    │
│ --language           -l               TEXT                                     Language of your file(s) ("en", "de") (Default: auto-detect) │
│ --annotate           -a                                                        Enable speaker annotation (Default: False)                   │
│ --num_speakers       -num             INTEGER                                  Number of speakers to annotate (Default: auto-detect)        │
│ --hf_token           -hf              TEXT                                     HuggingFace Access token required for speaker annotation     │
│ --subtitle           -s                                                        Create subtitles (Default: False)                            │
│ --subtitle_length    -sub_length      INTEGER                                  Subtitle segment length in words [default: 5]                │
│ --translate          -t                                                        Translate transcription to English (Default: False)          │
│ --export             -e               [all|json|txt|rttm|vtt|webvtt|srt|html]  Choose the export format [default: all]                      │
│ --del_originals      -del                                                      Delete input files after file conversion. (Default: False)   │
│ --download_language  -dl              TEXT                                     Specify a language code ("en", "de" ...) to transcribe a     │
│                                                                                specific audio track of a URL. (Default: auto-detect)        │
│ --config             -c               PATH                                     Path to configuration file                                   │
│ --post_correction    -post            PATH                                     Path to YAML file for post-correction                        │
│ --verbose            -v                                                        Print text chunks during transcription (Default: False)      │
│ --help                                                                         Show this message and exit.                                  │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

App

Instead of running whisply from the CLI you can start the browser app instead:

$ whisply app

Open the local URL in your browser after starting the app (Note: The URL might differ from system to system):

* Running on local URL: http://127.0.0.1:7860

Speaker annotation and diarization

Requirements

In order to annotate speakers using --annotate you need to provide a valid HuggingFace access token using the --hf_token option. Additionally, you must accept the terms and conditions for the pyannote/speaker-diarization-community-1 pipeline.

For detailed instructions, refer to the Requirements section on the pyannote model page on HuggingFace and make sure that you accept the "pyannote/speaker-diarization-community-1 user conditions" and create an access token at hf.co/settings/tokens.

How speaker annotation works

whisply uses whisperX for speaker diarization and annotation. Instead of returning chunk-level timestamps like the standard Whisper implementation whisperX is able to return word-level timestamps as well as annotating speakers word by word, thus returning much more precise annotations.

Out of the box whisperX will not provide timestamps for words containing only numbers (e.g. "1.5" or "2024"): whisply fixes those instances through timestamp approximation. Other known limitations of whisperX include:

• inaccurate speaker diarization if multiple speakers talk at the same time
• to provide word-level timestamps and annotations whisperX uses language specific alignment models; out of the box whisperX supports these languages: en, fr, de, es, it, ja, zh, nl, uk, pt.

Refer to the whisperX GitHub page for more information.

Post correction

The --post_correction option allows you to correct various transcription errors that you may find in your files. The option takes as argument a .yaml file with the following structure:

# Single word corrections
Gardamer: Gadamer

# Pattern-based corrections
patterns:
  - pattern: 'Klaus-(Cira|Cyra|Tira)-Stiftung'
    replacement: 'Klaus Tschira Stiftung'

• Single word corrections: matches single words → wrong word: correct word
• Pattern-based corrections: matches patterns → (Cira|Cyra|Tira) will look for Klaus-Cira-Stiftung, Klaus-Cyra-Stiftung and / or Klaus-Tira-Stiftung and replaces it with Klaus-Tschirra-Stiftung

Post correction will be applied to all export file formats you choose.

Batch processing

Instead of providing a file, folder or URL by using the --files option you can pass a .list with a mix of files, folders and URLs for processing.

Example:

$ cat my_files.list

video_01.mp4
video_02.mp4
./my_files/
https://youtu.be/KtOayYXEsN4?si=-0MS6KXbEWXA7dqo

Using config files for batch processing

You can provide a .json config file by using the --config option which makes batch processing easy. An example config looks like this:

{
    "files": "./files/my_files.list",          # Path to your files
    "output_dir": "./transcriptions",          # Output folder where transcriptions are saved
    "device": "auto",                          # AUTO, CPU, GPU, MLX or MPS
    "model": "large-v3-turbo",                 # Whisper model to use
    "language": null,                          # Null for auto-detection or language codes ("en", "de", ...)
    "download_language": null,                 # If transcribing a video with multiple audio tracks from a URL you can choose a specific audio track by passing a language code ("de", "fr", "en" ...)
    "annotate": false,                         # Annotate speakers 
    "num_speakers": null,                      # Number of speakers of the input file (null: auto-detection)
    "hf_token": "HuggingFace Access Token",    # Your HuggingFace Access Token (needed for annotations)
    "subtitle": false,                         # Subtitle file(s)
    "subtitle_length": 10,                     # Length of each subtitle block in number of words
    "translate": false,                        # Translate to English
    "export": "txt",                           # Export .txts only
    "verbose": false,                          # Print transcription segments while processing 
    "delete_originals": false,                 # Delete original input files after file conversion
    "post_correction": "my_corrections.yaml"   # Apply post correction with specified patterns in .yaml
}

Citation

Schmidt, T. (2026). whisply: Cross-Platform Python App for Batch Transcription, Translation, Speaker Annotation and Subtitle Generation of Video and Audio Content (v0.15.0). Zenodo. https://doi.org/10.5281/zenodo.19437856