langchain-ai/deepagents · error · RuntimeError

ffmpeg not found on PATH; install ffmpeg to enable voice tra

Error message

ffmpeg not found on PATH; install ffmpeg to enable voice transcription.

What it means

Local transcription first converts input audio to 16 kHz mono WAV using the `ffmpeg` binary resolved from PATH. When `subprocess.run(['ffmpeg', ...])` raises FileNotFoundError, the binary is missing and `_convert_to_wav` re-raises as this RuntimeError.

Source

Thrown at libs/talon/deepagents_talon/speech.py:300

                "ffmpeg",
                "-y",
                "-i",
                str(path),
                "-ar",
                "16000",
                "-ac",
                "1",
                "-f",
                "wav",
                str(output),
            ],
            capture_output=True,
            timeout=120,
            check=False,
        )
    except FileNotFoundError as exc:
        msg = "ffmpeg not found on PATH; install ffmpeg to enable voice transcription."
        raise RuntimeError(msg) from exc
    except subprocess.TimeoutExpired as exc:
        msg = f"ffmpeg timed out while converting {path}"
        raise RuntimeError(msg) from exc

    if proc.returncode != 0:
        stderr = proc.stderr.decode("utf-8", errors="replace")
        msg = f"ffmpeg conversion failed with exit code {proc.returncode}: {stderr}"
        raise RuntimeError(msg)
    return output

View on GitHub (pinned to a1af029e6e)

Solutions

Install ffmpeg (`apt-get install ffmpeg`, `brew install ffmpeg`, or a conda/pip ffmpeg distribution)
Confirm `which ffmpeg` succeeds in the same shell/user that runs the app
If launching from an IDE or service manager, explicitly add ffmpeg's directory to PATH

Example fix

# before
Dockerfile: FROM python:3.12-slim
# after
Dockerfile: FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*

Defensive patterns

Strategy: validation

Validate before calling

import shutil
if shutil.which("ffmpeg") is None:
    raise SystemExit("ffmpeg not found on PATH; install it before enabling voice transcription")

Try / catch

try:
    text = transcribe_local(path)
except RuntimeError as exc:
    if "ffmpeg not found on PATH" in str(exc):
        text = ""  # or use a cloud transcription fallback
    else:
        raise

Prevention

Include ffmpeg in deployment images and check `shutil.which('ffmpeg')` at startup
Use feature detection before offering voice features in the UI
Keep the ffmpeg install step next to the media extra in setup docs

When it happens

Trigger: Calling local voice transcription on a machine where ffmpeg is not installed or is not on the PATH of the process running Talon.

Common situations: Minimal Docker images and CI runners without ffmpeg; virtualenv/IDE launches with a stripped PATH that omits /usr/local/bin or Homebrew paths; deploying to a server after developing on a machine that had ffmpeg.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/e1b484f2a82a09bd. Report an issue: GitHub.