Guide: Transcribing Audio with Whisper via OpenAI and Groq (SAPAT)

[Spaceben123]

/claim #13

What this covers

A long-form, step-by-step guide to SAPAT (nkkko/sapat), the multi-provider Whisper transcription CLI referenced in #13, written for an AI-engineer audience.

Everything technical in the guide is grounded in a direct read of the SAPAT source (commit ba900b7, the feat/provider-plugin-architecture merge, package v0.3.0) — not the project's README, which documents an older CLI shape (the README's --api openai/--api groq flags and GROQCLOUD_API_KEY no longer exist in the current code; the guide calls this drift out explicitly rather than repeating the stale README).

Structure:

• How Whisper actually works — a real deep-dive per the issue's ask: the log-mel spectrogram, 30-second fixed windows, encoder-decoder architecture, multitask training, why --prompt and --language behave the way they do, and why silence causes hallucination.
• Same weights, different hosts — explains that OpenAI's API, Azure OpenAI, Groq, and local whisper.cpp/whisperx all run the same Whisper weights on different infrastructure, while several other "compatible" providers (Mistral/Voxtral, ElevenLabs/Scribe, NVIDIA/Parakeet, Vosk/Kaldi) are not Whisper at all despite sharing the API shape.
• Step-by-step Azure OpenAI and Groq walkthroughs (the two APIs named in the issue), with exact env vars and flags read from azure.py/groq.py.
• A genuine extension: the current release has no plain openai (api.openai.com) provider — only azure — so the guide adds one, using the existing OpenAICompatProvider mixin the codebase already uses for Together/Venice/Lemonfox. This directly answers the issue's "extend it to cover additional supported APIs" ask.
• A source-verified gotcha nobody should be publishing without checking: azure.py calls Whisper's /audio/translations endpoint, not /audio/transcriptions — meaning non-English audio through the Azure provider comes back translated into English, not transcribed in its original language, regardless of --language.
• A full survey table of all 25+ registered providers, correctly noting which ones are actually Whisper under the hood and which aren't (verified by reading every provider file).
• The automatic large-file chunking pipeline (audio_splitter.py), full CLI flag reference, troubleshooting, and real-world use cases.

Also includes a new speech-to-text definition and a first-time author profile, per CONTRIBUTING.md.

Disclosure

This guide was researched and drafted with AI assistance (Claude/Fable). The technical claims about SAPAT's architecture, providers, and CLI behavior are based on directly reading the source files cited throughout (not invented or copied from the README). I do not have API keys for the paid providers, so I did not execute a live end-to-end transcription — the guide is explicit that the code-level walkthroughs (architecture, request construction, provider registry, chunking math) were verified by reading the source, while running the commands against a live API key is left to the reader, as the guide states outright rather than implying it was tested live.

Why this over the existing attempts

I checked the issue's history before writing — it explicitly calls out that prior submissions under-explained Whisper itself. This guide treats that as the core ask rather than a footnote, and adds one piece of genuinely new technical content (the direct-OpenAI provider extension, plus the translations-vs-transcriptions endpoint finding) that isn't just a restatement of the README.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MQvd9avZenwbcumQHWuusX