HA-FFmpeg

3.2.2 verified Mon Apr 27 auth: no python

An asynchronous Python wrapper around FFmpeg for Home Assistant, providing tools to probe media, convert streams, and manage FFmpeg processes. As of version 3.2.2, it is fully async and no longer accepts a loop parameter in constructors. Maintained by the Home Assistant core team with a moderate release cadence.

pip install ha-ffmpeg

Common errors

error ModuleNotFoundError: No module named 'ha_ffmpeg' ↓

cause Incorrect import path. The correct import uses 'haffmpeg' (no hyphen, no underscore).

fix

Replace import ha_ffmpeg with from haffmpeg import FFmpeg.

error TypeError: __init__() got an unexpected keyword argument 'loop' ↓

cause You're passing the deprecated 'loop' argument to FFmpeg() or FFprobe() constructor.

fix

Remove the loop argument. The library now automatically gets the running event loop.

error FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg' ↓

cause FFmpeg executable not installed or not in PATH.

fix

Install FFmpeg (e.g., sudo apt install ffmpeg) and ensure it's in your system PATH.

Warnings

breaking In version 3.0.0, the constructor dropped the `loop` argument. You must no longer pass an event loop to FFmpeg or FFprobe constructors. ↓

fix Remove the `loop` parameter. Ensure creation is done within an async context (e.g., inside an async function).

gotcha The library expects FFmpeg to be installed on the system and accessible via PATH. If FFmpeg is not found, operations will silently fail or raise cryptic errors. ↓

fix Install FFmpeg on your system (e.g., `sudo apt install ffmpeg` on Debian/Ubuntu).

gotcha After calling `start()`, you must `close()` the process to release resources. Not doing so can lead to zombie FFmpeg processes. ↓

fix Always use a try/finally or async context manager, or explicitly call await ffmpeg.close() after start().

Imports

FFmpeg
wrong
```
from ha_ffmpeg import FFmpeg
```
correct
```
from haffmpeg import FFmpeg
```
The package name uses underscore, but the correct module import is 'haffmpeg' (no hyphen).
FFprobe
wrong
```
from ffmpeg import FFprobe
```
correct
```
from haffmpeg import FFprobe
```
FFprobe is part of ha-ffmpeg, not an independent library.

Quickstart

Basic usage: convert a video to audio and probe file info.

import asyncio
from haffmpeg import FFmpeg, FFprobe

async def main():
    ffmpeg = FFmpeg()
    await ffmpeg.set_options(
        input="input.mp4",
        output="output.mp3",
        output_global_options=["-vn", "-acodec", "libmp3lame"]
    )
    await ffmpeg.open()
    await ffmpeg.start()
    await ffmpeg.close()

    # Probe a file
    ffprobe = FFprobe()
    probe = await ffprobe.get_media_info("input.mp4")
    print(probe)

asyncio.run(main())