{"record":{"id":"02c0ecbfc57b7b0f","repo":"microsoft/markitdown","slug":"speech-transcription-requires-installing-markitdow","errorCode":null,"errorMessage":"Speech transcription requires installing MarkItDown with the [audio-transcription] optional dependencies. E.g., `pip install 'markitdown[audio-transcription]'` or `pip install 'markitdown[all]'`","messagePattern":"Speech transcription requires installing MarkItDown with the \\[audio-transcription\\] optional dependencies\\. E\\.g\\., `pip install 'markitdown\\[audio-transcription\\]'` or `pip install 'markitdown\\[all\\]'`","errorType":"exception","errorClass":"MissingDependencyException","httpStatus":null,"severity":"error","filePath":"packages/markitdown/src/markitdown/converters/_transcribe_audio.py","lineNumber":26,"sourceCode":"_dependency_exc_info = None\ntry:\n    # Suppress some warnings on library import\n    import warnings\n\n    with warnings.catch_warnings():\n        warnings.filterwarnings(\"ignore\", category=DeprecationWarning)\n        warnings.filterwarnings(\"ignore\", category=SyntaxWarning)\n        import speech_recognition as sr\n        import pydub\nexcept ImportError:\n    # Preserve the error and stack trace for later\n    _dependency_exc_info = sys.exc_info()\n\n\ndef transcribe_audio(file_stream: BinaryIO, *, audio_format: str = \"wav\") -> str:\n    # Check for installed dependencies\n    if _dependency_exc_info is not None:\n        raise MissingDependencyException(\n            \"Speech transcription requires installing MarkItDown with the \"\n            \"[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)","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/microsoft/markitdown/blob/fd239d5d2be43d9b68329730206b9312c7d5a388/packages/markitdown/src/markitdown/converters/_transcribe_audio.py#L8-L44","documentation":"Audio transcription in MarkItDown delegates to SpeechRecognition and pydub, imported inside a module-level try/except in _transcribe_audio.py. If that import fails, the exc info is cached and transcribe_audio() raises MissingDependencyException with instructions to install the [audio-transcription] extra. The converter path (audio files routed by extension/mimetype) reaches this helper, so converting any recognized audio format without the extra produces this error.","triggerScenarios":"Calling MarkItDown().convert() on .mp3/.wav/.m4a/.flac files (the audio converter accepts them) without the audio extra installed; or when speech_recognition/pydub are present but import fails (pydub needs audioop, removed in Python 3.13, or ffmpeg-related import errors).","commonSituations":"Python 3.13 environments where pydub breaks on the removed audioop module; base installs in document-processing services that later receive audio attachments; offline/air-gapped installs where the extra was skipped intentionally but audio files still arrive.","solutions":["Install the extra: pip install 'markitdown[audio-transcription]'","Or: pip install 'markitdown[all]'","On Python 3.13+, also install the audioop shim (pip install audioop-lts) since pydub depends on the removed stdlib audioop module","Ensure ffmpeg is on PATH: transcription of mp3/mp4 goes through pydub, which shells out to ffmpeg"],"exampleFix":"# before (Python 3.13, base install)\npip install markitdown\nMarkItDown().convert('clip.mp3')  # MissingDependencyException\n\n# after\npip install 'markitdown[audio-transcription]' audioop-lts\n# and ensure ffmpeg is available:\nsudo apt-get install -y ffmpeg","handlingStrategy":"try-catch","validationCode":"from markitdown.converters._transcribe_audio import _dependency_exc_info\n\ndef can_transcribe_audio() -> bool:\n    return _dependency_exc_info is None","typeGuard":null,"tryCatchPattern":"from markitdown import MarkItDown, MissingDependencyException\n\ntry:\n    result = MarkItDown().convert(\"note.mp3\")\nexcept MissingDependencyException:\n    logger.error(\"install markitdown[audio-transcription] (plus ffmpeg, and audioop-lts on Python 3.13)\")\n    raise","preventionTips":["Install markitdown[audio-transcription] and ffmpeg in environments accepting audio","On Python 3.13+, add the audioop-lts shim for pydub","Startup-probe the transcription dependency and disable audio upload paths when missing"],"tags":["dependencies","audio","transcription","optional-extras","python-3-13"],"backgroundTag":null,"analyzedSha":"fd239d5d2be43d9b68329730206b9312c7d5a388","analyzedAt":"2026-08-14T15:47:51.745Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}