{"id":1302,"library":"imageio-ffmpeg","title":"FFMPEG wrapper for Python","description":"imageio-ffmpeg is a Python library that provides a convenient wrapper around the FFMPEG executable, enabling Python applications to easily read and write video files. It bundles pre-compiled FFMPEG binaries for various platforms, simplifying deployment. The current version is 0.6.0, and it generally follows a release cadence tied to bug fixes, dependency updates, and new platform support.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/imageio/imageio-ffmpeg","tags":["video","ffmpeg","multimedia","codec","wrapper"],"install":[{"cmd":"pip install imageio-ffmpeg","lang":"bash","label":"Install imageio-ffmpeg"}],"dependencies":[],"imports":[{"symbol":"imageio_ffmpeg","correct":"import imageio_ffmpeg as iio_ffmpeg"}],"quickstart":{"code":"import imageio_ffmpeg as iio_ffmpeg\nimport numpy as np\n\n# Define video parameters\nfilename = 'my_video_output.mp4'\nwidth, height = 640, 480\nfps = 30\nnum_frames = 100\n\nprint(f\"Using FFMPEG executable: {iio_ffmpeg.get_ffmpeg_exe()}\")\n\ntry:\n    # Initialize the writer\n    writer = iio_ffmpeg.write_frames(filename, (width, height), fps=fps)\n    writer.send(None)  # Start the pipe\n\n    for i in range(num_frames):\n        # Create a simple frame: black background with a moving red square\n        frame = np.zeros((height, width, 3), dtype=np.uint8)\n        x_offset = (i * 5) % (width - 100) # Move square across width\n        frame[50:150, x_offset : x_offset + 100] = [255, 0, 0] # Red square\n        writer.send(frame)\n    \n    writer.close()\n    print(f\"Video saved to {filename}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure FFMPEG is correctly configured or its bundled binary is accessible.\")","lang":"python","description":"This quickstart demonstrates how to use `imageio-ffmpeg` to write a simple video file (e.g., an MP4 with a moving red square). It initializes a video writer, generates a series of NumPy arrays representing frames, and sends them to the FFMPEG process. It also shows how to check the FFMPEG executable path being used."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or a later version.","message":"Starting from version 0.5.0, imageio-ffmpeg requires Python 3.9 or newer. Users on older Python versions (e.g., Python 3.8 or earlier) will encounter installation failures or runtime errors.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"You can explicitly set the FFMPEG executable path using `imageio_ffmpeg.set_ffmpeg_exe('/path/to/your/ffmpeg')` or ensure that `ffmpeg` is available in your system's PATH. The path used can be checked with `imageio_ffmpeg.get_ffmpeg_exe()`.","message":"Although imageio-ffmpeg bundles pre-compiled FFMPEG binaries, sometimes these might not be compatible with specific system configurations or users may prefer to use a system-wide or custom FFMPEG installation. If you encounter issues like 'ffmpeg not found' or unexpected encoding failures, verify the FFMPEG executable path.","severity":"gotcha","affected_versions":"All"},{"fix":"Understand your use-case: use `imageio` for general image/video I/O if `imageio-ffmpeg` is configured as its backend, or directly use `imageio_ffmpeg` when you need explicit control over FFMPEG processes and arguments.","message":"imageio-ffmpeg can be used as a standalone wrapper for FFMPEG, but it's primarily designed to be a backend for the `imageio` library for video I/O. Users sometimes confuse when to import `imageio` vs. `imageio_ffmpeg`. For higher-level, more abstract video operations integrated with image processing, `imageio` is often sufficient. For direct, lower-level control over FFMPEG parameters, `imageio_ffmpeg` is the correct choice.","severity":"gotcha","affected_versions":"All"},{"fix":"Review any custom code that interacts with internal resource paths or loaders; adapt it to use `importlib.resources` patterns if necessary. For most users, no action is required.","message":"In version 0.5.0, imageio-ffmpeg migrated from using `pkg_resources` to `importlib.resources` for internal resource management. While this generally doesn't affect standard API usage, any advanced users who relied on direct interaction with `imageio-ffmpeg`'s internal resource loading mechanisms via `pkg_resources` might experience breaking changes.","severity":"deprecated","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-08T00:00:00.000Z","next_check":"2026-07-07T00:00:00.000Z"}