{"id":6626,"library":"ffmpeg","title":"ffmpeg-python","description":"The `ffmpeg` Python package (often referred to as `ffmpeg-python`) provides a lightweight, fluent Python wrapper for the `ffmpeg` command-line tool. It enables programmatic construction of `ffmpeg` commands, management of audio/video streams, application of filters, and format conversions. It currently stands at version 1.4, with its release cadence tied to upstream `ffmpeg` tool features and community contributions.","status":"active","version":"1.4","language":"python","source_language":"en","source_url":"https://github.com/jiashaokun/ffmpeg","tags":["video","audio","media","ffmpeg","wrapper"],"install":[{"cmd":"pip install ffmpeg","lang":"bash","label":"Install `ffmpeg` Python package"}],"dependencies":[],"imports":[{"symbol":"ffmpeg","correct":"import ffmpeg"}],"quickstart":{"code":"import ffmpeg\nimport os\n\n# This quickstart demonstrates compiling an ffmpeg command.\n# To actually run it, you would need 'input.mp4' to exist\n# and the ffmpeg CLI tool to be installed and in your PATH.\n# For full execution, replace 'input.mp4' with an actual file\n# and remove the '.compile()' to use '.run()'.\n\n# Example: Generate an ffmpeg command to re-encode a video\n# without actually running it, useful for inspection.\ncommand_list = (\n    ffmpeg.input('input.mp4')\n    .output('output_resized.mp4', vf='scale=1280:-1')\n    .compile()\n)\n\nprint(f\"Generated ffmpeg command: {' '.join(command_list)}\")\n\n# Example: Probe a (potentially non-existent) file to get its metadata\n# For this to run successfully, 'input.mp4' would need to exist\n# and the ffmpeg CLI tool must be installed.\n# try:\n#     probe_info = ffmpeg.probe('input.mp4')\n#     print(\"Probe information:\")\n#     print(probe_info)\n# except ffmpeg.Error as e:\n#     print(f\"Error probing file: {e.stderr.decode()}\")\n","lang":"python","description":"This quickstart demonstrates how to construct and compile an `ffmpeg` command using the Python wrapper. To execute the command (e.g., `ffmpeg.run()`), the `ffmpeg` command-line tool must be installed separately on your system, and input files like `input.mp4` must exist."},"warnings":[{"fix":"Install the `ffmpeg` CLI tool. On macOS: `brew install ffmpeg`. On Debian/Ubuntu: `sudo apt update && sudo apt install ffmpeg`. On Windows, download from `ffmpeg.org` and add to PATH.","message":"The Python `ffmpeg` package is merely a wrapper. The actual `ffmpeg` command-line executable must be installed separately on your system (e.g., via `apt`, `brew`, `choco`, or by downloading binaries) and be available in your system's PATH for the Python library to function.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `try: ffmpeg.run(...) except ffmpeg.Error as e: print(f\"Error: {e.stderr.decode()}\")` to handle errors gracefully and get feedback from the underlying process.","message":"Operations involving the `ffmpeg` CLI tool can fail for various reasons (e.g., invalid input, missing codecs, file permissions). Always wrap `ffmpeg.run()` calls in a `try-except` block to catch `ffmpeg.Error` and inspect `e.stderr` for detailed diagnostic information.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For input from memory: `ffmpeg.input('pipe:', format='rawvideo', ... , pix_fmt='rgb24', s='640x480', pipe_input=True)`. For output to memory: `.output('pipe:', format='rawvideo', ... , pipe_output=True).run(capture_stdout=True)`.","message":"By default, `ffmpeg` processes files on disk. For handling raw byte data in memory (e.g., from NumPy arrays, OpenCV), you must explicitly use `pipe_input=True` and/or `pipe_output=True` in your input/output nodes, and pass `capture_stdout=True`, `capture_stderr=True` (or `stdout=subprocess.PIPE` directly) to `ffmpeg.run()` to manage data streams.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `process = ffmpeg.run_async(...)` to get a `subprocess.Popen` object, then manage it (e.g., `process.wait()`, `process.poll()`) or integrate with `asyncio`.","message":"The `ffmpeg.run()` function is blocking, meaning your Python script will pause until the `ffmpeg` process completes. For long-running video processing tasks in applications that need to remain responsive, consider executing `ffmpeg.run_async()` for non-blocking execution or offloading the operation to a separate thread or background process.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.4':50 'applic':39 'audio':65 'audio/video':37 'cadenc':54 'command':25,34 'command-lin':24 'communiti':62 'construct':31 'contribut':63 'convers':44 'current':46 'enabl':29 'featur':60 'ffmpeg':2,5,13,23,33,58,67 'ffmpeg-python':1,12 'filter':41 'fluent':18 'format':43 'lightweight':17 'line':26 'manag':35 'media':66 'often':8 'packag':7 'programmat':30 'provid':15 'python':3,6,14,19 'refer':9 'releas':53 'stand':47 'stream':38 'tie':55 'tool':27,59 'upstream':57 'version':49 'video':64 'wrapper':20,68","created_at":"2026-04-15T18:35:59.580063+00:00","updated_at":"2026-04-16T15:00:18.587272+00:00","problems":[{"fix":"Ensure `ffmpeg-python` is installed using `pip install ffmpeg-python` or `conda install -c conda-forge ffmpeg-python`.","cause":"The Python package `ffmpeg-python` is not installed in the active Python environment, or an incorrect package like `python-ffmpeg` was installed instead.","error":"ModuleNotFoundError: No module named 'ffmpeg'"},{"fix":"Install the `ffmpeg` command-line tool for your operating system (e.g., via Homebrew on macOS, apt-get on Linux, or by downloading binaries and adding to PATH on Windows).","cause":"The underlying `ffmpeg` command-line tool (the binary executable) is not installed on the system, or its executable path is not included in the system's PATH environment variable, which `ffmpeg-python` needs to locate it.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'"},{"fix":"Rename any local file named `ffmpeg.py` to something else (e.g., `my_ffmpeg_script.py`) to avoid conflicts, and ensure `ffmpeg-python` is installed and correctly imported.","cause":"This usually happens when there is a Python file named `ffmpeg.py` in your project directory, which shadows the actual `ffmpeg-python` library, preventing it from being imported correctly, or an incompatible `ffmpeg` Python package was installed.","error":"AttributeError: module 'ffmpeg' has no attribute 'input'"},{"fix":"Carefully review the `ffmpeg-python` command arguments to ensure they are valid for the `ffmpeg` binary, check for proper handling of input/output pipes, and ensure that the `ffmpeg` process completes successfully with the given parameters.","cause":"This error occurs when the `ffmpeg` subprocess terminates unexpectedly, often due to invalid arguments passed to `ffmpeg`, issues with input/output streams, or if a process writing to `ffmpeg`'s stdin closes prematurely.","error":"BrokenPipeError: [Errno 32] Broken pipe"},{"fix":"Verify that the output file extension is appropriate for the desired format and codec, and ensure all codec and format-related arguments (e.g., `vcodec`, `acodec`, `f`) are correct and compatible with the `ffmpeg` tool version being used.","cause":"The `ffmpeg` command-line tool, invoked by `ffmpeg-python`, cannot determine a suitable output format or codec based on the provided arguments and the output file extension, or the arguments themselves are incorrectly specified.","error":"Unable to find a suitable output format for"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jiashaokun/ffmpeg","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ffmpeg/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}