ha-ffmpeg

What it is and what it does

ha-ffmpeg is a Python library that wraps ffmpeg for use in asyncio-based applications, particularly Home Assistant. It allows you to control ffmpeg processes asynchronously—emulating webcams from arbitrary video sources, analyzing streams for motion or noise, and extracting still images. The library depends only on async-timeout and is designed to integrate with Home Assistant's async architecture.

The package is actively maintained and carries a permissive BSD license. It has been in production use since 2016 and remains stable. The main design consideration is that function calls should be protected with asyncio.shield to ensure proper cancellation handling in async contexts.

Use it for:

• Integrate video streams into Home Assistant as virtual webcams for automation and monitoring
• Detect motion or noise in surveillance feeds to trigger home automation routines
• Extract snapshots from live video streams for display in dashboards or notifications
• Wrap ffmpeg process management in async code without blocking the event loop
• Build Home Assistant add-ons that process multiple video sources concurrently

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides an asyncio-based Python interface to control ffmpeg for Home Assistant, enabling webcam emulation, stream analysis, and image capture from video/audio sources.

Yes, if you are building Home Assistant integrations or async applications that need to control ffmpeg. The library is actively maintained, has low install friction, carries a permissive license, and has no known vulnerabilities. The main prerequisite is that ffmpeg itself must be installed on the system, and you should follow the asyncio.shield guidance in the documentation.

Install

ha-ffmpeg on PyPI

pip install ha-ffmpeg

uv add ha-ffmpeg

poetry add ha-ffmpeg

Installing ha-ffmpeg

Before you install

Low install friction with a single lightweight runtime dependency (async-timeout). Actively maintained with recent commits; last release was 644 days ago and the repository remains active.

License in practice

Licensed under BSD License (permissive), allowing use in most commercial and open-source projects without significant restrictions.

Quickstart

import asyncio
from ha_ffmpeg import FFMpegManager

async def main():
    manager = FFMpegManager()
    # Use asyncio.shield to protect calls
    await asyncio.shield(manager.start_process(...))

asyncio.run(main())

ffmpeg must be installed and available on the system PATH; asyncio.shield should wrap function calls per the documentation.

Verify before relying

• Whether ffmpeg must be installed separately on the system for this library to function
• Specific Python version requirements, as classifiers list 3.5–3.7 but requires_python is unspecified
• Whether asyncio.shield protection is mandatory for all use cases or only certain operations

Package facts

Evidence: ha_ffmpeg-3.2.2-py3-none-any.whl

Keywords: ffmpeg, homeassistant, wrapper, api

Tags

More Python Modules packages