ha-ffmpeg

library3.2.2pypypiunverified

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.

data http-networking observability devops

pip install ha-ffmpeg

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HA-FFMPEG

ha-ffmpeg

datapythonv3.2.2

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FFmpeg

✓ from haffmpeg import FFmpeg

✗ from haffmpeg import FFmpeg

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())

Debug

Known issues

breakingIn 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).

affects: >=3.0.0

gotchaThe 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).

affects: all

gotchaAfter 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().

affects: all

Upgrade

Version history

3.2.2latest on PyPI · released Nov 8, 2024

Audit

Dependencies

async-timeoutrequiredUsed for timeout handling in async operations.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pvizeli/ha-ffmpeg ↗

packagehttps://pypi.org/project/ha-ffmpeg/ ↗

homepagehttps://www.home-assistant.io ↗