{"library":"ffmpeg-python","title":"FFmpeg Python Bindings","description":"ffmpeg-python is a Python wrapper for the powerful FFmpeg multimedia framework, enabling developers to programmatically build and execute FFmpeg command-line arguments. It simplifies complex media manipulation tasks such as format conversion, video editing, and audio extraction within Python applications. The library's current PyPI version is 0.2.0, and while its own releases are infrequent, it remains actively used and functional due to its reliance on the externally maintained FFmpeg binary. Users should ensure their underlying FFmpeg installation is up-to-date.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/kkroening/ffmpeg-python","tags":["video processing","audio processing","multimedia","ffmpeg","wrapper","media conversion"],"install":[{"cmd":"pip install ffmpeg-python","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"ffmpeg-python is a wrapper around the FFmpeg command-line utility. The FFmpeg binary must be installed separately on your system and accessible via the system's PATH environment variable for ffmpeg-python to function.","package":"FFmpeg","optional":false}],"imports":[{"symbol":"ffmpeg","correct":"import ffmpeg"},{"note":"Installing 'ffmpeg' or 'python-ffmpeg' from PyPI will install a different, unrelated library. Ensure you install 'ffmpeg-python' for these bindings and use 'import ffmpeg' in your code.","wrong":"pip install ffmpeg","symbol":"ffmpeg","correct":"pip install ffmpeg-python"}],"quickstart":{"code":"import ffmpeg\nimport os\n\n# Create dummy input file for demonstration\n# In a real scenario, 'input.mp4' would be an existing video file.\n# For a runnable example without actual FFmpeg, this part would be mocked or use a very small, pre-existing file.\n# For this example, we assume 'input.mp4' exists.\n# To make it runnable for demonstration, let's create a placeholder.\n# WARNING: This part is for demonstration. FFmpeg needs a valid input file.\n# In a production environment, ensure 'input.mp4' is a real video file.\n\ninput_filename = 'input.mp4'\noutput_filename = 'output.avi'\n\n# This block is a placeholder to ensure the file exists for a 'runnable' check, \n# but FFmpeg still requires a proper media file.\nif not os.path.exists(input_filename):\n    print(f\"Please create a dummy video file named '{input_filename}' for this example to fully run with FFmpeg.\")\n    print(\"Example will proceed by trying to convert, but might fail if FFmpeg can't find/process the file.\")\n    # Example of how you might generate a minimal dummy file if FFmpeg was installed and functional:\n    # import subprocess\n    # try:\n    #     subprocess.run(['ffmpeg', '-f', 'lavfi', '-i', 'testsrc=duration=1:size=128x72:rate=10', input_filename], check=True)\n    # except FileNotFoundError:\n    #     print(\"FFmpeg command-line tool not found. Please install FFmpeg.\")\n    # except subprocess.CalledProcessError as e:\n    #     print(f\"Error creating dummy input file: {e}\")\n\n\n\ntry:\n    stream = ffmpeg.input(input_filename)\n    stream = ffmpeg.output(stream, output_filename)\n    ffmpeg.run(stream, overwrite_output=True)\n    print(f\"Successfully converted {input_filename} to {output_filename}\")\nexcept ffmpeg.Error as e:\n    print(f\"FFmpeg error: {e.stderr.decode('utf8')}\")\nexcept FileNotFoundError:\n    print(\"FFmpeg command not found. Please ensure FFmpeg is installed and in your system's PATH.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to convert a video file from one format (e.g., MP4) to another (e.g., AVI) using `ffmpeg-python`. It creates a stream from an input file, specifies an output file, and then executes the FFmpeg command. For this example to function correctly, an `input.mp4` file must exist, and the FFmpeg binary must be installed and accessible on your system."},"warnings":[{"fix":"Install FFmpeg for your operating system (e.g., `sudo apt install ffmpeg` on Debian/Ubuntu, `brew install ffmpeg` on macOS, or download from the official FFmpeg website for Windows and add to PATH).","message":"The `ffmpeg-python` library is a wrapper for the external FFmpeg binary. You *must* install FFmpeg separately on your system and ensure its executables are available in your system's PATH environment variable for `ffmpeg-python` to work. `ffmpeg-python` does not install FFmpeg for you.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `stream.audio` and `stream.video` to reference and process audio/video portions separately, then use `ffmpeg.concat()` or similar to re-combine them if needed. Refer to FFmpeg's official documentation for specific filter behaviors.","message":"Some FFmpeg filters inherently drop audio or video streams if not explicitly handled. If you encounter missing audio or video in your output, you may need to explicitly select and re-combine streams using `.audio` and `.video` operators.","severity":"gotcha","affected_versions":"All versions (intrinsic FFmpeg behavior)"},{"fix":"Implement graceful termination by sending a signal to the FFmpeg process (e.g., `process.terminate()`) and allowing a short sleep period for FFmpeg to finalize the output file. Avoid `taskkill` or similar abrupt methods.","message":"Abruptly terminating the underlying FFmpeg process (e.g., by killing the Python process) can lead to corrupted output files.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly update your system's FFmpeg binary to benefit from the latest features, bug fixes, and security patches. Check the FFmpeg project's official news for new releases. This library's lack of recent updates does not imply it is broken or incompatible with newer FFmpeg binaries, though very recent, significant breaking changes in FFmpeg's CLI syntax *could* potentially affect it.","message":"While `ffmpeg-python` (version 0.2.0) has not been updated since 2019, it remains widely used and functional because it acts as a thin wrapper around the underlying FFmpeg command-line tool. The core FFmpeg binary itself is actively maintained and frequently updated (e.g., FFmpeg 8.1 released March 2026). The stability of your media processing largely depends on keeping your *FFmpeg binary* up-to-date, not necessarily the `ffmpeg-python` wrapper.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When encoding video, consider adding the `-pix_fmt yuv420p` option to your FFmpeg command via `ffmpeg-python`. Example: `ffmpeg.output(stream, output_filename, pix_fmt='yuv420p').run()`.","message":"Some media players or platforms require specific pixel formats (e.g., `yuv420p`) for maximum compatibility. Omitting this can lead to playback issues.","severity":"gotcha","affected_versions":"All versions (depends on target playback environment)"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}