---
id: ha-ffmpeg
version: "3.2.2"
license: BSD License
license_treatment: permissive
maintenance: active
---

# ha-ffmpeg — A library that handling with ffmpeg for home-assistant

License: permissive · Maintenance: active · Downloads: 181.3K/mo

## 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 above — 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

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

- License: BSD License (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 181.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ffmpeg asyncio wrapper, home assistant video stream, motion detection ffmpeg, webcam emulation python, audio stream analysis, ffmpeg home automation, video capture asyncio, home-assistant, asyncio, multimedia

[View on SkillFed](https://skillfed.io/packages/ha-ffmpeg) · [View on PyPI](https://pypi.org/project/ha-ffmpeg/)