FFMPEG wrapper for Python

Warnings

• breaking 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.
  Fix: Upgrade your Python environment to 3.9 or a later version.
• gotcha 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.
  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()`.
• gotcha 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.
  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.
• deprecated 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.
  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.

Install

• pip install imageio-ffmpeg Install imageio-ffmpeg

Imports

• imageio_ffmpeg

  import imageio_ffmpeg as iio_ffmpeg

Quickstart

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.

import imageio_ffmpeg as iio_ffmpeg
import numpy as np

# Define video parameters
filename = 'my_video_output.mp4'
width, height = 640, 480
fps = 30
num_frames = 100

print(f"Using FFMPEG executable: {iio_ffmpeg.get_ffmpeg_exe()}")

try:
    # Initialize the writer
    writer = iio_ffmpeg.write_frames(filename, (width, height), fps=fps)
    writer.send(None)  # Start the pipe

    for i in range(num_frames):
        # Create a simple frame: black background with a moving red square
        frame = np.zeros((height, width, 3), dtype=np.uint8)
        x_offset = (i * 5) % (width - 100) # Move square across width
        frame[50:150, x_offset : x_offset + 100] = [255, 0, 0] # Red square
        writer.send(frame)
    
    writer.close()
    print(f"Video saved to {filename}")
except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure FFMPEG is correctly configured or its bundled binary is accessible.")