whisply

<img src="assets/whisply.png" width="25%">

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 (November 2025)
• 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

# --- 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 (November 2025)

<details> <summary><i>Could not load library libcudnn_ops.so.9</i> (<b>click to expand</b>)</summary> <br>If you use <b>whisply</b> with a Nvidia GPU and encounter this error:<br><br>

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

<b>Use the following steps to fix the issue</b>:

1. In your activated python environment run pip list and check that torch==2.8.0 and torchaudio==2.8.0 are installed.
2. If yes, run pip install ctranslate2==4.6.0.
3. Export the following environment variable to your shell:

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}"

4. To make the change permanent, run this bash command while your python environment is activated:

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"

Finally, deactivate the environment and reactivate it to apply the changes.

Find additional information at <a href="https://github.com/SYSTRAN/faster-whisper" target="_blank">faster-whisper</a>'s GitHub page.

</details>

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.                                  │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯