Environment:Elevenlabs Elevenlabs python FFmpeg Mpv

Knowledge Sources	elevenlabs-python FFmpeg mpv
Domains	Infrastructure, Audio_Playback
Last Updated	2026-02-15 12:00 GMT

Overview

System environment with ffplay (FFmpeg), mpv, and optionally ffmpeg for audio playback and streaming in the ElevenLabs SDK.

Description

This environment provides external system binaries used by the ElevenLabs SDK for audio playback and audio stream conversion. The `play()` function uses ffplay (from FFmpeg) to play audio buffers via subprocess piping. The `stream()` function uses mpv to play streaming audio in real-time as chunks arrive. The `ScribeRealtime` URL-based mode uses ffmpeg to convert audio streams from arbitrary formats to PCM for WebSocket transmission.

Usage

Use this environment when calling `play()` to play generated audio, `stream()` to stream audio in real-time, or `ScribeRealtime.connect()` with a URL source. These are the primary audio output utilities in the SDK. An alternative `play(use_ffmpeg=False)` path exists using `sounddevice` and `soundfile` instead.

System Requirements

Category	Requirement	Notes
OS	Any (Windows, macOS, Linux)	FFmpeg and mpv available on all major platforms
System Binary	`ffplay` (from FFmpeg)	Required for `play()` function
System Binary	`mpv`	Required for `stream()` function
System Binary	`ffmpeg`	Required for `ScribeRealtime` URL-based audio streaming
Hardware	Audio output device	Required for playback

Dependencies

System Packages

`ffmpeg` (includes `ffplay`):
- macOS: `brew install ffmpeg`
- Linux (Debian/Ubuntu): `apt install ffmpeg`
- Windows: Download from https://ffmpeg.org/
`mpv`:
- macOS: `brew install mpv`
- Linux (Debian/Ubuntu): `apt install mpv`
- Windows: Download from https://mpv.io/

Python Packages (alternative path)

`sounddevice` (optional, for `play(use_ffmpeg=False)`)
`soundfile` (optional, for `play(use_ffmpeg=False)`)
`ipython` (optional, for `play(notebook=True)`)

Credentials

No additional credentials required.

Quick Install

# macOS
brew install ffmpeg mpv

# Linux (Debian/Ubuntu)
sudo apt install ffmpeg mpv

# Alternative: use sounddevice instead of ffplay
pip install sounddevice soundfile

# For Jupyter notebook playback
pip install ipython

Code Evidence

ffplay availability check in `play.py:31-37`:

if not is_installed("ffplay"):
    message = (
        "ffplay from ffmpeg not found, necessary to play audio. "
        "On mac you can install it with 'brew install ffmpeg'. "
        "On linux and windows you can install it from https://ffmpeg.org/"
    )
    raise ValueError(message)

ffplay invocation in `play.py:38-45`:

args = ["ffplay", "-autoexit", "-", "-nodisp"]
proc = subprocess.Popen(
    args=args,
    stdout=subprocess.PIPE,
    stdin=subprocess.PIPE,
    stderr=subprocess.PIPE,
)
out, err = proc.communicate(input=audio)

mpv availability check in `play.py:70-76`:

if not is_installed("mpv"):
    message = (
        "mpv not found, necessary to stream audio. "
        "On mac you can install it with 'brew install mpv'. "
        "On linux and windows you can install it from https://mpv.io/"
    )
    raise ValueError(message)

mpv streaming command in `play.py:78-84`:

mpv_command = ["mpv", "--no-cache", "--no-terminal", "--", "fd://0"]
mpv_process = subprocess.Popen(
    mpv_command,
    stdin=subprocess.PIPE,
    stdout=subprocess.DEVNULL,
    stderr=subprocess.DEVNULL,
)

ffmpeg for URL streaming in `realtime/scribe.py:275-287`:

ffmpeg_process = subprocess.Popen(
    [
        "ffmpeg",
        "-i", url,
        "-f", "s16le",
        "-ar", str(sample_rate),
        "-ac", "1",
        "-"
    ],
    stdout=subprocess.PIPE,
    stderr=subprocess.DEVNULL,
    bufsize=0
)

ffmpeg not found error in `realtime/scribe.py:288-293`:

except FileNotFoundError:
    await websocket.close(1011, "ffmpeg not found")
    raise RuntimeError(
        "ffmpeg is required for URL-based audio streaming. "
        "Please install ffmpeg: https://ffmpeg.org/download.html"
    )

Common Errors

Error Message	Cause	Solution
`ffplay from ffmpeg not found, necessary to play audio`	FFmpeg not installed or not in PATH	Install FFmpeg: `brew install ffmpeg` (macOS) or `apt install ffmpeg` (Linux)
`mpv not found, necessary to stream audio`	mpv not installed or not in PATH	Install mpv: `brew install mpv` (macOS) or `apt install mpv` (Linux)
`RuntimeError: ffmpeg is required for URL-based audio streaming`	ffmpeg not installed (ScribeRealtime URL mode)	Install ffmpeg: `apt install ffmpeg` or download from https://ffmpeg.org/
`pip install sounddevice soundfile required when use_ffmpeg=False`	Alternative playback dependencies missing	`pip install sounddevice soundfile`
`pip install ipython required when notebook=False`	IPython not installed for notebook playback	`pip install ipython`

Compatibility Notes

Three playback paths: `play()` supports ffplay (default), sounddevice/soundfile (`use_ffmpeg=False`), and IPython Audio (`notebook=True`).
Streaming requires mpv: The `stream()` function has no alternative path; mpv is the only supported streaming player.
ffmpeg for Scribe URL mode: Only required when using `ScribeRealtime.connect()` with a `url` parameter. Manual audio chunk mode does not need ffmpeg.
PATH requirement: All system binaries are located via `shutil.which()`, so they must be in the system PATH.
mpv flags: Uses `--no-cache --no-terminal` for minimal latency real-time streaming.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment