{"record":{"id":"a95184cd92c5ec39","repo":"microsoft/markitdown","slug":"unsupported-audio-format-audio-format","errorCode":null,"errorMessage":"Unsupported audio format: {audio_format}","messagePattern":"Unsupported audio format: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"packages/markitdown/src/markitdown/converters/_transcribe_audio.py","lineNumber":46,"sourceCode":"            \"[audio-transcription] optional dependencies. E.g., \"\n            \"`pip install 'markitdown[audio-transcription]'` or \"\n            \"`pip install 'markitdown[all]'`\"\n        ) from _dependency_exc_info[\n            1\n        ].with_traceback(  # type: ignore[union-attr]\n            _dependency_exc_info[2]\n        )\n\n    if audio_format in [\"wav\", \"aiff\", \"flac\"]:\n        audio_source = file_stream\n    elif audio_format in [\"mp3\", \"mp4\"]:\n        audio_segment = pydub.AudioSegment.from_file(file_stream, format=audio_format)\n\n        audio_source = io.BytesIO()\n        audio_segment.export(audio_source, format=\"wav\")\n        audio_source.seek(0)\n    else:\n        raise ValueError(f\"Unsupported audio format: {audio_format}\")\n\n    recognizer = sr.Recognizer()\n    with sr.AudioFile(audio_source) as source:\n        audio = recognizer.record(source)\n        transcript = recognizer.recognize_google(audio).strip()\n        return \"[No speech detected]\" if transcript == \"\" else transcript\n","sourceCodeStart":28,"sourceCodeEnd":53,"githubUrl":"https://github.com/microsoft/markitdown/blob/fd239d5d2be43d9b68329730206b9312c7d5a388/packages/markitdown/src/markitdown/converters/_transcribe_audio.py#L28-L53","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pre-convert the audio to a supported format (wav or mp3) with ffmpeg before passing it to markitdown","If calling transcribe_audio directly, pass only one of: wav, aiff, flac, mp3, mp4","Filter or reject .ogg/.aac/.wma/.opus inputs upstream with a clear message instead of letting conversion fail","Check the extension-to-format mapping used by the audio converter and normalize extensions before conversion"],"exampleFix":"# before\nMarkItDown().convert('voice.ogg')  # ValueError: Unsupported audio format: ogg\n\n# after: transcode to wav first\nimport subprocess, io\nwav = subprocess.run(['ffmpeg','-i','voice.ogg','-f','wav','-'], capture_output=True, check=True).stdout\nMarkItDown().convert_stream(io.BytesIO(wav), StreamInfo(extension='.wav', mimetype='audio/wav'))","handlingStrategy":"validation","validationCode":"SUPPORTED_AUDIO_FORMATS = {\"wav\", \"aiff\", \"flac\", \"mp3\", \"mp4\"}\n\ndef audio_format_supported(fmt: str) -> bool:\n    return fmt.lower() in SUPPORTED_AUDIO_FORMATS","typeGuard":"from typing_extensions import Literal\nAudioFormat = Literal[\"wav\", \"aiff\", \"flac\", \"mp3\", \"mp4\"]\n\ndef is_supported_format(fmt: str) -> bool:\n    \"\"\"Type-guard the audio_format argument accepted by transcribe_audio.\"\"\"\n    return fmt in (\"wav\", \"aiff\", \"flac\", \"mp3\", \"mp4\")","tryCatchPattern":"try:\n    result = MarkItDown().convert(\"voice.ogg\")\nexcept ValueError as e:\n    if str(e).startswith(\"Unsupported audio format\"):\n        # transcode with ffmpeg to wav, then retry\n        ...","preventionTips":["Restrict uploads to wav/mp3/mp4 (or transcode with ffmpeg to wav on receipt)","When calling transcribe_audio directly, pass only wav|aiff|flac|mp3|mp4","Map extensions to supported formats before invoking conversion; reject .ogg/.aac/.opus/.wma early with a clear message"],"tags":["audio","format-validation","transcription","unsupported-format"],"backgroundTag":null,"analyzedSha":"fd239d5d2be43d9b68329730206b9312c7d5a388","analyzedAt":"2026-08-14T15:47:51.745Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}