Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Add documentation for AUDIO_UNSUPPORTED_CODECS setting

Murtaza Nasir4c9aa380791b
diff --git a/docs/faq.md b/docs/faq.md
index 9d27fd4d..086159ec 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -236,6 +236,16 @@ The three codec options serve different needs:
For most users, the default **mp3 at 128k** provides excellent quality for speech while maximizing storage savings. If you're archiving important recordings and want to preserve full audio fidelity, use **flac**. The **opus** codec is efficient for speech but has slightly less universal compatibility than MP3.
+### What if my transcription service doesn't support certain codecs?
+
+Some self-hosted transcription services (like vLLM-hosted Whisper) don't support all audio codecs. If you're getting "format not recognised" errors, you can exclude specific codecs from Speakr's supported list:
+
+```bash
+AUDIO_UNSUPPORTED_CODECS=opus,vorbis
+```
+
+Files using these codecs will be automatically converted to your target format before transcription. See the [troubleshooting guide](troubleshooting.md#format-not-recognised-errors) for more details.
+
---
Return to [Home](index.md) →
\ No newline at end of file
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index b985d84a..acb1096f 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -216,6 +216,20 @@ When enabled (the default), lossless files are automatically converted on upload
Already-compressed formats (MP3, AAC, OGG, M4A, etc.) are never re-encoded to avoid quality degradation. Only truly lossless formats (WAV, AIFF) are compressed.
+**Excluding unsupported codecs:**
+
+Some transcription services don't support certain audio codecs. For example, vLLM-hosted Whisper instances may not support Opus. If you encounter "format not recognised" errors, you can exclude specific codecs from Speakr's supported list, forcing them to be converted before transcription:
+
+```bash
+# Exclude a single codec
+AUDIO_UNSUPPORTED_CODECS=opus
+
+# Exclude multiple codecs (comma-separated)
+AUDIO_UNSUPPORTED_CODECS=opus,vorbis
+```
+
+Supported codecs by default: `pcm_s16le`, `pcm_s24le`, `pcm_f32le`, `mp3`, `flac`, `opus`, `vorbis`, `aac`. Any codec listed in `AUDIO_UNSUPPORTED_CODECS` will be automatically converted to your target format (set by `AUDIO_CODEC`) before being sent to the transcription service.
+
!!! tip "Storage Savings Example"
A 500MB WAV recording compressed to MP3 at 128k becomes roughly 50MB - a 90% reduction. For lossless preservation, FLAC typically achieves 50-70% reduction while maintaining perfect audio quality.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index ef43fda8..8747a960 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -56,6 +56,27 @@ Language mismatches cause poor results too. If you've set a specific transcripti
For recordings with multiple speakers, using the [ASR endpoint with speaker diarization](features.md#speaker-diarization) dramatically improves usability. Learn how to [identify speakers](user-guide/transcripts.md#speaker-identification) after transcription, even if the raw transcription accuracy is similar.
+### "Format Not Recognised" Errors
+
+If your transcription service returns "format not recognised" or similar codec errors, your service may not support certain audio formats that Speakr considers supported by default.
+
+This commonly occurs with:
+- **vLLM-hosted Whisper instances** that don't support Opus codec
+- **Self-hosted ASR services** with limited codec support
+- **WebM recordings** (which typically use Opus audio)
+
+**Solution:** Add unsupported codecs to your `.env` file:
+
+```bash
+# Exclude codecs your service doesn't support
+AUDIO_UNSUPPORTED_CODECS=opus
+
+# Multiple codecs can be excluded
+AUDIO_UNSUPPORTED_CODECS=opus,vorbis
+```
+
+Files using these codecs will be automatically converted to your target format (MP3 by default) before transcription. See the [audio compression settings](getting-started/installation.md#audio-compression) for more details.
+
### Chinese Transcription Issues
For [Chinese language transcription](features.md#language-support), model selection is critical. See the [FAQ on language support](faq.md#can-speakr-transcribe-languages-other-than-english) for more details.