microsoft/markitdown · error · ValueError

Unsupported audio format: {audio_format}

Error message

Unsupported audio format: {audio_format}

What it means

transcribe_audio() branches on the audio_format parameter: 'wav'/'aiff'/'flac' pass the stream straight to SpeechRecognition, 'mp3'/'mp4' are re-encoded to wav via pydub, and any other string raises ValueError with the offending format. The format is normally derived from the file extension by the calling converter, so unknown extensions mapping to a non-empty format string, or direct callers passing e.g. 'ogg' or 'm4a', hit this guard.

Source

Thrown at packages/markitdown/src/markitdown/converters/_transcribe_audio.py:46

            "[audio-transcription] optional dependencies. E.g., "
            "`pip install 'markitdown[audio-transcription]'` or "
            "`pip install 'markitdown[all]'`"
        ) from _dependency_exc_info[
            1
        ].with_traceback(  # type: ignore[union-attr]
            _dependency_exc_info[2]
        )

    if audio_format in ["wav", "aiff", "flac"]:
        audio_source = file_stream
    elif audio_format in ["mp3", "mp4"]:
        audio_segment = pydub.AudioSegment.from_file(file_stream, format=audio_format)

        audio_source = io.BytesIO()
        audio_segment.export(audio_source, format="wav")
        audio_source.seek(0)
    else:
        raise ValueError(f"Unsupported audio format: {audio_format}")

    recognizer = sr.Recognizer()
    with sr.AudioFile(audio_source) as source:
        audio = recognizer.record(source)
        transcript = recognizer.recognize_google(audio).strip()
        return "[No speech detected]" if transcript == "" else transcript

View on GitHub (pinned to fd239d5d2b)

Solutions

1. Pre-convert the audio to a supported format (wav or mp3) with ffmpeg before passing it to markitdown
2. If calling transcribe_audio directly, pass only one of: wav, aiff, flac, mp3, mp4
3. Filter or reject .ogg/.aac/.wma/.opus inputs upstream with a clear message instead of letting conversion fail
4. Check the extension-to-format mapping used by the audio converter and normalize extensions before conversion

Example fix

# before
MarkItDown().convert('voice.ogg')  # ValueError: Unsupported audio format: ogg

# after: transcode to wav first
import subprocess, io
wav = subprocess.run(['ffmpeg','-i','voice.ogg','-f','wav','-'], capture_output=True, check=True).stdout
MarkItDown().convert_stream(io.BytesIO(wav), StreamInfo(extension='.wav', mimetype='audio/wav'))

SUPPORTED_AUDIO_FORMATS = {"wav", "aiff", "flac", "mp3", "mp4"}

def audio_format_supported(fmt: str) -> bool:
    return fmt.lower() in SUPPORTED_AUDIO_FORMATS

from typing_extensions import Literal
AudioFormat = Literal["wav", "aiff", "flac", "mp3", "mp4"]

def is_supported_format(fmt: str) -> bool:
    """Type-guard the audio_format argument accepted by transcribe_audio."""
    return fmt in ("wav", "aiff", "flac", "mp3", "mp4")

try:
    result = MarkItDown().convert("voice.ogg")
except ValueError as e:
    if str(e).startswith("Unsupported audio format"):
        # transcode with ffmpeg to wav, then retry
        ...

When it happens

Trigger: Calling MarkItDown().convert() on a file whose extension maps to an unsupported audio format (e.g. .ogg, .opus, .aac, .wma) that the audio converter still accepts via mimetype; calling transcribe_audio(file, audio_format='m4a') directly; StreamInfo with mimetype audio/* and an unmapped extension.

Common situations: Voice-note ingestion pipelines receiving mobile formats (aac, ogg-opus from WhatsApp/Telegram); users assuming any audio type converts because accepts() matched the mimetype; direct API users guessing the format string.

Related errors

• Speech transcription requires installing MarkItDown with the
• Could not convert stream to Markdown. No converter attempted
• Unsupported file type for Content Understanding conversion.

AI-assisted analysis of microsoft/markitdown@fd239d5d2b (2026-08-14). Data as JSON: /api/errors/a95184cd92c5ec39. Report an issue: GitHub.