{"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":"en","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,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}