xtekky/gpt4free · error · MissingDependencyException

Speech transcription requires installing MarkItdown with the

Error message

Speech transcription requires installing MarkItdown with the [audio-transcription] optional dependencies. E.g., `pip install markitdown[audio-transcription]` or `pip install markitdown[all]`

What it means

Thrown by g4f's vendored markitdown transcribe_audio() as MissingDependencyException when the import of speech_recognition or pydub failed at module load; the original ImportError is captured in _dependency_exc_info and re-raised with a pip hint chained to it. It means the [audio-transcription] optional extras are absent in the current environment.

Source

Thrown at g4f/integration/markitdown/_transcribe_audio.py:28

    # Suppress some warnings on library import
    import warnings

    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        warnings.filterwarnings("ignore", category=SyntaxWarning)
        import speech_recognition as sr
        import pydub
except ImportError:
    # Preserve the error and stack trace for later
    _dependency_exc_info = sys.exc_info()


def transcribe_audio(
    file_stream: BinaryIO, *, audio_format: str = "wav", language: str = None
) -> str:
    # Check for installed dependencies
    if _dependency_exc_info is not None:
        raise MissingDependencyException(
            "Speech transcription requires installing MarkItdown with the [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", "webm"]:
        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}")

View on GitHub (pinned to 973504e177)

Solutions

pip install 'markitdown[audio-transcription]' (or 'markitdown[all]') into the same interpreter that runs the code.
Verify with python -c 'import speech_recognition, pydub' — exit code 0 means the error will not fire.
In Dockerfiles add the extra to the RUN pip install line.
Note ffmpeg must also be on PATH for pydub to decode mp3/mp4/webm.

Example fix

// before
# deps missing, transcribe_audio raises MissingDependencyException
result = md.convert("meeting.mp3")

// after
# pip install 'markitdown[audio-transcription]'
result = md.convert("meeting.mp3")

Defensive patterns

Strategy: validation

Validate before calling

def audio_transcription_available() -> bool:
    try:
        import speech_recognition  # noqa
        import pydub  # noqa
        return True
    except ImportError:
        return False

Try / catch

try:
    result = md.convert("note.mp3")
except Exception as e:
    if "audio-transcription" in str(e):
        raise RuntimeError("install markitdown[audio-transcription] to handle audio") from e
    raise

Prevention

Declare 'markitdown[audio-transcription]' in requirements for audio flows.
Feature-detect the imports and disable audio upload paths when missing.
Ensure ffmpeg is installed for non-wav input.

When it happens

Trigger: md.convert('note.mp3') or any audio conversion when SpeechRecognition or pydub is not installed. The check fires before any audio processing, so even valid wav files raise immediately.

Common situations: Installing g4f/markitdown without extras (pip install markitdown instead of markitdown[audio-transcription]); slim Docker images that strip optional deps; a venv activated after installing into another interpreter.

Related errors

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/c45aa99489fc12f0. Report an issue: GitHub.