{"id":21421,"library":"ha-ffmpeg","title":"HA-FFmpeg","description":"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.","status":"active","version":"3.2.2","language":"python","source_language":"en","source_url":"https://github.com/pvizeli/ha-ffmpeg","tags":["ffmpeg","home-assistant","async","media","wrapper"],"install":[{"cmd":"pip install ha-ffmpeg","lang":"bash","label":"latest"}],"dependencies":[{"reason":"Used for timeout handling in async operations.","package":"async-timeout","optional":false}],"imports":[{"note":"The package name uses underscore, but the correct module import is 'haffmpeg' (no hyphen).","wrong":"from ha_ffmpeg import FFmpeg","symbol":"FFmpeg","correct":"from haffmpeg import FFmpeg"},{"note":"FFprobe is part of ha-ffmpeg, not an independent library.","wrong":"from ffmpeg import FFprobe","symbol":"FFprobe","correct":"from haffmpeg import FFprobe"}],"quickstart":{"code":"import asyncio\nfrom haffmpeg import FFmpeg, FFprobe\n\nasync def main():\n    ffmpeg = FFmpeg()\n    await ffmpeg.set_options(\n        input=\"input.mp4\",\n        output=\"output.mp3\",\n        output_global_options=[\"-vn\", \"-acodec\", \"libmp3lame\"]\n    )\n    await ffmpeg.open()\n    await ffmpeg.start()\n    await ffmpeg.close()\n\n    # Probe a file\n    ffprobe = FFprobe()\n    probe = await ffprobe.get_media_info(\"input.mp4\")\n    print(probe)\n\nasyncio.run(main())","lang":"python","description":"Basic usage: convert a video to audio and probe file info."},"warnings":[{"fix":"Remove the `loop` parameter. Ensure creation is done within an async context (e.g., inside an async function).","message":"In version 3.0.0, the constructor dropped the `loop` argument. You must no longer pass an event loop to FFmpeg or FFprobe constructors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install FFmpeg on your system (e.g., `sudo apt install ffmpeg` on Debian/Ubuntu).","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always use a try/finally or async context manager, or explicitly call await ffmpeg.close() after start().","message":"After calling `start()`, you must `close()` the process to release resources. Not doing so can lead to zombie FFmpeg processes.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Replace `import ha_ffmpeg` with `from haffmpeg import FFmpeg`.","cause":"Incorrect import path. The correct import uses 'haffmpeg' (no hyphen, no underscore).","error":"ModuleNotFoundError: No module named 'ha_ffmpeg'"},{"fix":"Remove the loop argument. The library now automatically gets the running event loop.","cause":"You're passing the deprecated 'loop' argument to FFmpeg() or FFprobe() constructor.","error":"TypeError: __init__() got an unexpected keyword argument 'loop'"},{"fix":"Install FFmpeg (e.g., `sudo apt install ffmpeg`) and ensure it's in your system PATH.","cause":"FFmpeg executable not installed or not in PATH.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}