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.mdindex 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 filediff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.mdindex 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 uploadAlready-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.mdindex 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 transcriptiFor 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 IssuesFor [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.