---

name: asr-python-api description: "Use WhisperX's Python API for ASR model loading, audio arrays, VAD-batched transcription, progress callbacks, local cache use, and device/memory tuning." disable-model-invocation: true metadata: disco-role: operating license: BSD 2-Clause

WhisperX ASR Python API

Use this sub-skill when a task needs WhisperX through Python code rather than the whisperx command line: importing the package, loading ASR models, representing audio as paths or NumPy arrays, running VAD-batched transcription, reporting progress, using local model caches, or choosing device/compute/memory settings.

Do not use this sub-skill for:

• CLI flag catalogs or command construction; route to ../transcription-cli/.
• Forced alignment, word/character timestamps, or alignment models; route to ../alignment-timestamps/ after ASR segments exist.
• Diarization or speaker labels; route to ../diarization-speakers/ after ASR or alignment results exist.
• Rendering JSON/SRT/VTT/TXT/TSV/Audacity files; route to ../outputs-subtitles/ after result dictionaries exist.

Read first

• references/api-reference.md — use when you need verified Python signatures, return schemas, TranscriptionResult fields, audio constants, or ASR/VAD option names.
• references/workflows.md — use when you need self-contained Python recipes for path audio, cached NumPy-array transcription, progress callbacks, and memory-conscious runs.
• references/model-and-backend-notes.md — use before choosing device, compute_type, batch_size, download_root, local_files_only, VAD method, language, or cache behavior.
• references/troubleshooting.md — use when imports, ffmpeg audio loading, model cache/downloads, CUDA/compute type, low memory, CPU slowness, language detection, suppress_numerals, or cache-only operation fails.

Safe bundled helpers

• scripts/inspect_whisperx_api.py — run for a no-download import/signature report, public lazy API presence, package version, and torch CUDA availability. It intentionally does not call load_model or transcribe.
• scripts/check_audio_loading.py — run for a tiny generated-WAV whisperx.load_audio smoke check. It writes only to a temporary directory and catches missing ffmpeg.

Operating facts

• Distribution/package version covered by this skill: whisperx 3.8.7rc1; import name: whisperx.
• Supported Python range from package metadata: >=3.10,<3.14.
• Public top-level functions such as whisperx.load_model and whisperx.load_audio are lazy wrappers; use the source signatures in the API reference for real arguments.
• Full ASR execution may download model weights unless the caller intentionally uses local_files_only=True with a populated cache. The bundled helpers are safe by default and do not run model inference.

Minimal routing pattern

1. Inspect the runtime surface with python scripts/inspect_whisperx_api.py if the environment is unknown.
2. For path audio, confirm ffmpeg or run python scripts/check_audio_loading.py; for already-decoded audio, provide a mono float32 NumPy array sampled at 16 kHz.
3. Load ASR with whisperx.load_model(...), choosing cache and backend settings from model-and-backend-notes.md.
4. Call model.transcribe(audio, ...) and treat the returned object as TranscriptionResult: {"segments": [...], "language": "..."}.
5. Route any post-ASR alignment, diarization, or file rendering to the sibling sub-skills above.