High severity intermediate · Fix: 5-15 min

RuntimeError or FileFormatError

RuntimeError: Audio file format not supported

What this error means
Whisper cannot process the audio file format because it's either unsupported, corrupted, or the required ffmpeg codec is missing from your system.

Stack trace

traceback
RuntimeError: Audio file format not supported or corrupted
  File "/usr/local/lib/python3.11/site-packages/whisper/audio.py", line 28, in load_audio
    audio = ffmpeg.input(file, threads=0).output("pipe:", format="s16", acodec="pcm_s16le", ac=1, ar=sample_rate).run(capture_stdout=True, capture_stderr=True, quiet=True)
RuntimeError: ffmpeg error (see stderr for details)
QUICK FIX
Install ffmpeg with codec support (`brew install ffmpeg` on macOS, `sudo apt-get install ffmpeg` on Linux), then convert your audio to WAV with `ffmpeg -i input.mp3 -acodec pcm_s16le -ac 1 -ar 16000 output.wav` before transcription.

Why it happens

Whisper relies on ffmpeg to decode audio files into PCM s16 format. If ffmpeg isn't installed, the audio codec isn't available, the file extension doesn't match the actual format, or the file is corrupted, Whisper's load_audio() function fails silently and raises a RuntimeError. MP3 requires the libmp3lame codec, AAC requires the aac codec, and many formats require ffmpeg to be properly compiled with those libraries enabled.

Detection

Check ffmpeg availability with `ffmpeg -version` before processing audio. Log the file size, MIME type, and ffmpeg stderr output to identify codec gaps. Validate audio files with `ffprobe -show_format filename.mp3` before passing to Whisper.

Causes & fixes

1

ffmpeg is not installed on the system

✓ Fix

Install ffmpeg: Ubuntu/Debian: `sudo apt-get install ffmpeg` | macOS: `brew install ffmpeg` | Windows: `choco install ffmpeg` or download from https://ffmpeg.org/download.html. Verify with `ffmpeg -version`.

2

ffmpeg is installed but lacks MP3/AAC codec support (libmp3lame or aac not compiled in)

✓ Fix

Rebuild ffmpeg with codec support: `brew reinstall ffmpeg --with-libmp3lame --with-libvorbis` (macOS) or compile from source with `./configure --enable-libmp3lame --enable-libvorbis`. Or use Conda: `conda install -c conda-forge ffmpeg=7.0` which includes all codecs.

3

File extension doesn't match actual audio format (e.g., renamed MP3 file with .wav extension)

✓ Fix

Convert the file to match its extension using ffmpeg: `ffmpeg -i corrupted.wav -acodec libmp3lame -ab 192k output.mp3`. Or use ffprobe to detect actual format: `ffprobe -v error -select_streams a:0 -show_entries stream=codec_name -of csv=p=0 file.wav`

4

Audio file is corrupted or truncated (incomplete download or write failure)

✓ Fix

Re-download or re-record the file. Verify integrity with `ffprobe -v error -show_format -show_streams file.mp3`. If partially downloaded, resume with `curl -C - -o file.mp3 URL`. Test with `ffplay file.mp3` to ensure it plays.

5

Using deprecated OpenAI Whisper CLI instead of Python SDK with proper error handling

✓ Fix

Use the OpenAI Python API with response format control: `client.audio.transcriptions.create(model='whisper-1', file=open('audio.mp3', 'rb'), response_format='json')` which includes better error messages.

Code: broken vs fixed

Broken - triggers the error
python
import whisper
import os

# This breaks when ffmpeg is missing or file format unsupported
audio_file = 'podcast.mp3'
model = whisper.load_model('base')
result = model.transcribe(audio_file)  # ❌ RuntimeError: Audio file format not supported
print(result['text'])
Fixed - works correctly
python
import whisper
import os
import subprocess
import json
from pathlib import Path

def transcribe_with_fallback(audio_path: str) -> str:
    """Transcribe audio with format validation and conversion fallback."""
    # Step 1: Verify ffmpeg is installed
    try:
        subprocess.run(['ffmpeg', '-version'], capture_output=True, check=True, timeout=5)
    except (FileNotFoundError, subprocess.TimeoutExpired):
        raise RuntimeError('ffmpeg not installed. Install with: brew install ffmpeg (macOS) or apt-get install ffmpeg (Linux)')
    
    # Step 2: Validate audio file format with ffprobe
    try:
        result = subprocess.run(
            ['ffprobe', '-v', 'error', '-show_format', '-show_streams', '-of', 'json', audio_path],
            capture_output=True,
            text=True,
            timeout=10
        )
        if result.returncode != 0:
            raise RuntimeError(f'ffprobe failed: {result.stderr}')
        probe_data = json.loads(result.stdout)
        if not probe_data.get('streams'):
            raise RuntimeError(f'No audio stream found in {audio_path} - file may be corrupted')
    except json.JSONDecodeError as e:
        raise RuntimeError(f'Failed to read audio file metadata: {e}')
    
    # Step 3: Convert to PCM s16 WAV if needed
    audio_path = Path(audio_path)
    wav_path = audio_path.with_suffix('.wav')
    
    if audio_path.suffix.lower() != '.wav':
        print(f'Converting {audio_path.suffix} to WAV...')
        subprocess.run(
            ['ffmpeg', '-i', str(audio_path), '-acodec', 'pcm_s16le', '-ac', '1', '-ar', '16000', '-y', str(wav_path)],
            capture_output=True,
            check=True
        )
        audio_path = wav_path
    
    # Step 4: Load and transcribe with error handling
    try:
        model = whisper.load_model('large-v3')  # Use latest model for best accuracy
        result = model.transcribe(str(audio_path))
        return result['text']
    except RuntimeError as e:
        raise RuntimeError(f'Whisper transcription failed on {audio_path}: {e}')

# Usage
try:
    text = transcribe_with_fallback('podcast.mp3')  # ✅ Now handles format conversion automatically
    print(f'Transcription: {text}')
except RuntimeError as e:
    print(f'Error: {e}')
Added ffmpeg validation, audio format detection via ffprobe, automatic WAV conversion for unsupported formats (MP3, M4A, etc.), and proper error messages that identify the exact failure point.

Workaround

If you cannot install ffmpeg on your system, use the OpenAI Whisper API instead of the local model: `from openai import OpenAI; client = OpenAI(api_key=os.environ['OPENAI_API_KEY']); transcript = client.audio.transcriptions.create(model='whisper-1', file=open('audio.mp3', 'rb')).text`. This offloads format handling to OpenAI's servers which support all formats natively.

Prevention

In production, containerize your app with ffmpeg pre-installed (base Docker image with ffmpeg layer), validate audio files before transcription with ffprobe metadata checks, convert all ingested audio to canonical PCM s16 16kHz WAV at upload time, and monitor ffmpeg availability in health checks. Use OpenAI's Whisper API for formats you don't control, and the local whisper-large-v3 model only for validated, converted WAV files.

Python 3.9+ · openai-whisper >=20231117 · tested on 20240314+
Verified 2026-04 · whisper-1, whisper-large-v3
Verify ↗

Community Notes

No notes yetBe the first to share a version-specific fix or tip.