WhisperX standalone (optional reference recipe)¶

Use this when you want diarized WhisperX JSON, then import it into TranscriptX. These files are optional standalone examples. They are not part of the TranscriptX runtime — TranscriptX does not orchestrate WhisperX. Any tool that produces compatible transcript JSON is fine; WhisperX is one example.

What this is for¶

Generate transcript JSON with WhisperX (Docker, or the Transcribe Audio command generator).
In TranscriptX, Import Transcript and upload that JSON.
Run analysis in the web UI.

GUI path (recommended)¶

Open Transcribe Audio in TranscriptX.
Choose WhisperX Docker (external recipe), set input/output folders, model, language, device, and optional min/max speakers.
Copy the generated docker run command and execute it on a Linux/GPU host (not inside transcriptx-web).
Import the resulting WhisperX JSON via Import Transcript.

Configure WhisperX (compose / env)¶

Copy the env example and set your values:
```
cp whisperx.env.example whisperx.env
```
Edit whisperx.env: set HF_TOKEN for diarization and gated models.
Never commit whisperx.env.

Env-configurable settings live in whisperx.env.example in this directory. A historical map from the old in-app TranscriptionConfig fields to these env vars is in the archive migration table (not required for new setups; not in the hosted guide).

Run WhisperX¶

Using Compose (from this directory):

cd docs/recipes/whisperx
export HOST_RECORDINGS_DIR=/path/to/your/recordings   # host folder outside the git clone (required)
cp whisperx.env.example whisperx.env
# Edit whisperx.env and set HF_TOKEN
docker compose -f docker-compose.whisperx.yml up -d
# Run transcription via docker exec; see WhisperX docs for exact command.

Using a single docker run (snippet for reference):

Override the image entrypoint and run whisperx explicitly in a shell so the audio path and flags are passed correctly:

export HOST_RECORDINGS_DIR=/path/to/your/recordings   # outside the git clone
docker run --rm --entrypoint /bin/bash \
  -v "$HOST_RECORDINGS_DIR:/data/input:ro" -v "$(pwd)/data/transcripts:/data/output" \
  --env-file whisperx.env \
  ghcr.io/jim60105/whisperx:no_model \
  -c "whisperx /data/input/your_audio.wav --output_dir /data/output --language en --diarize"

Replace your_audio.wav with your file (e.g. 260225_cursor_presentation.mp3). With this image, passing arguments directly after the image name does not reach whisperx; use the --entrypoint /bin/bash form above.

Adjust paths and WhisperX CLI flags to match your setup. Output format: WhisperX JSON; then Import Transcript (or the Python import API in host-stt.md).

Python import (optional)¶

From the repo root with your environment active:

from pathlib import Path

from transcriptx.io.managed_import_workflow import run_managed_import_workflow

result = run_managed_import_workflow(
    Path("path/to/whisperx.json"),
    overwrite=False,
)
print(result.json_path)
print(result.sidecar_path)

Then analyse in the web UI or via run_analysis(AnalysisRequest(...)) (see host-stt.md).

Troubleshooting¶

403 / GatedRepoError when using `--diarize`¶

If you see:

No --hf_token provided, needs to be saved in environment variable
Could not download Pipeline from pyannote/speaker-diarization-community-1
GatedRepoError: 403 Client Error or “repository is private or gated”

the diarization model requires a Hugging Face token and acceptance of its terms:

Accept model terms: Open pyannote/speaker-diarization-community-1 and accept the user conditions.
Create a token: Go to Hugging Face → Settings → Access Tokens, create a token (read access is enough).
Pass the token: In whisperx.env set HF_TOKEN=hf_xxxxxxxx (your real token). Ensure your docker run or Compose command uses --env-file whisperx.env so the container receives HF_TOKEN. WhisperX reads it for diarization.

If you prefer not to use diarization, run without --diarize (no token needed).