imageio-ffmpeg 0.8.0__py3-none-win_arm64.whl

imageio_ffmpeg/__init__.py

@@ -0,0 +1,7 @@
+"""imageio_ffmpeg, FFMPEG wrapper for Python."""
+
+# flake8: noqa
+
+from ._definitions import __version__
+from ._io import count_frames_and_secs, read_frames, write_frames
+from ._utils import get_ffmpeg_exe, get_ffmpeg_version

imageio_ffmpeg/_definitions.py

@@ -0,0 +1,69 @@
+import sys
+import platform
+
+__version__ = "0.8.0"
+
+
+def get_platform():
+    # get_os_string and get_arch are taken from wgpu-py
+    return _get_os_string() + "-" + _get_arch()
+
+
+def _get_os_string():
+    if sys.platform.startswith("win"):
+        return "windows"
+    elif sys.platform.startswith("darwin"):
+        return "macos"
+    elif sys.platform.startswith("linux"):
+        return "linux"
+    else:
+        return sys.platform
+
+
+def _get_arch():
+    # See e.g.: https://stackoverflow.com/questions/45124888
+    is_64_bit = sys.maxsize > 2**32
+    machine = platform.machine().lower()  # e.g. "ARM64" on Windows
+
+    if machine == "armv7l":
+        # Raspberry pi
+        detected_arch = "armv7"
+    elif is_64_bit and machine.startswith(("arm", "aarch64")):
+        # Includes MacOS M1, arm linux, ...
+        detected_arch = "aarch64"
+    elif is_64_bit:
+        detected_arch = "x86_64"
+    else:
+        detected_arch = "i686"
+    return detected_arch
+
+
+# The binaries are downloaded from the sources pinned in
+# tools/ffmpeg-sources.json (see tools/download_ffmpeg.py, which also updates
+# the file names below). The wheel tags must match the requirements of the
+# binaries, which `invoke check-binaries` verifies:
+# * Linux (BtbN): glibc 2.28+ (manylinux_2_28), kernel 4.18+.
+# * macOS x86_64 (evermeet.cx): macOS 10.13+; aarch64 (osxexperts): 12.0+.
+
+
+# Platform string -> ffmpeg filename
+FNAME_PER_PLATFORM = {
+    "macos-aarch64": "ffmpeg-macos-aarch64-v9.0",
+    "macos-x86_64": "ffmpeg-macos-x86_64-v9.0.2",
+    "windows-x86_64": "ffmpeg-win-x86_64-v9.0.2.exe",
+    "windows-aarch64": "ffmpeg-win-aarch64-v9.0.1.exe",
+    "windows-i686": "ffmpeg-win32-v4.2.2.exe",  # Windows 7+
+    "linux-aarch64": "ffmpeg-linux-aarch64-v9.0.2",
+    "linux-x86_64": "ffmpeg-linux-x86_64-v9.0.2",
+}
+
+# Wheel tag -> platform string
+WHEEL_BUILDS = {
+    "py3-none-manylinux_2_28_x86_64": "linux-x86_64",
+    "py3-none-manylinux_2_28_aarch64": "linux-aarch64",
+    "py3-none-macosx_10_13_x86_64": "macos-x86_64",
+    "py3-none-macosx_12_0_arm64": "macos-aarch64",
+    "py3-none-win32": "windows-i686",
+    "py3-none-win_amd64": "windows-x86_64",
+    "py3-none-win_arm64": "windows-aarch64",
+}

imageio_ffmpeg/_io.py

@@ -0,0 +1,698 @@
+import pathlib
+import subprocess
+import sys
+import time
+from collections import defaultdict
+from fractions import Fraction
+from functools import lru_cache
+
+from ._parsing import LogCatcher, cvsecs, parse_ffmpeg_header
+from ._utils import _popen_kwargs, get_ffmpeg_exe, logger
+
+ISWIN = sys.platform.startswith("win")
+
+h264_encoder_preference = defaultdict(lambda: -1)
+# The libx264 was the default encoder for a longe time with imageio
+h264_encoder_preference["libx264"] = 100
+
+# Encoder with the nvidia graphics card dedicated hardware
+h264_encoder_preference["h264_nvenc"] = 90
+# Deprecated names for the same encoder
+h264_encoder_preference["nvenc_h264"] = 90
+h264_encoder_preference["nvenc"] = 90
+
+# vaapi provides hardware encoding with intel integrated graphics chipsets
+h264_encoder_preference["h264_vaapi"] = 80
+
+# openh264 is cisco's open source encoder
+h264_encoder_preference["libopenh264"] = 70
+
+h264_encoder_preference["libx264rgb"] = 50
+
+
+def ffmpeg_test_encoder(encoder):
+    # Use the null streams to validate if we can encode anything
+    # https://trac.ffmpeg.org/wiki/Null
+    cmd = [
+        get_ffmpeg_exe(),
+        "-hide_banner",
+        "-f",
+        "lavfi",
+        "-i",
+        "nullsrc=s=256x256:d=8",
+        "-vcodec",
+        encoder,
+        "-f",
+        "null",
+        "-",
+    ]
+    p = subprocess.run(
+        cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    return p.returncode == 0
+
+
+def get_compiled_h264_encoders():
+    cmd = [get_ffmpeg_exe(), "-hide_banner", "-encoders"]
+    p = subprocess.run(
+        cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    stdout = p.stdout.decode().replace("\r", "")
+    # 2022/04/08: hmaarrfk
+    # I couldn't find a good way to get the list of available encoders from
+    # the ffmpeg command
+    # The ffmpeg command return a table that looks like
+    # Notice the leading space at the very beginning
+    # On ubuntu with libffmpeg-nvenc-dev we get
+    # $ ffmpeg -hide_banner -encoders | grep -i h.264
+    #
+    # Encoders:
+    #  V..... = Video
+    #  A..... = Audio
+    #  S..... = Subtitle
+    #  .F.... = Frame-level multithreading
+    #  ..S... = Slice-level multithreading
+    #  ...X.. = Codec is experimental
+    #  ....B. = Supports draw_horiz_band
+    #  .....D = Supports direct rendering method 1
+    #  ------
+    #  V..... libx264              libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (codec h264)
+    #  V..... libx264rgb           libx264 H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 RGB (codec h264)
+    #  V....D h264_nvenc           NVIDIA NVENC H.264 encoder (codec h264)
+    #  V..... h264_omx             OpenMAX IL H.264 video encoder (codec h264)
+    #  V..... h264_qsv             H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (Intel Quick Sync Video acceleration) (codec h264)
+    #  V..... h264_v4l2m2m         V4L2 mem2mem H.264 encoder wrapper (codec h264)
+    #  V....D h264_vaapi           H.264/AVC (VAAPI) (codec h264)
+    #  V..... nvenc                NVIDIA NVENC H.264 encoder (codec h264)
+    #  V..... nvenc_h264           NVIDIA NVENC H.264 encoder (codec h264)
+    #
+    # However, just because ffmpeg was compiled with the options enabled
+    # it doesn't mean that it will be successful
+    header_footer = stdout.split("------")
+    footer = header_footer[1].strip("\n")
+    encoders = []
+    for line in footer.split("\n"):
+        # Strip to remove any leading spaces
+        line = line.strip()
+        encoder = line.split(" ")[1]
+
+        if encoder in h264_encoder_preference:
+            # These encoders are known to support H.264
+            # We forcibly include them in case their description changes to
+            # not include the string "H.264"
+            encoders.append(encoder)
+        elif (line[0] == "V") and ("H.264" in line):
+            encoders.append(encoder)
+
+    encoders.sort(reverse=True, key=lambda x: h264_encoder_preference[x])
+    if "h264_nvenc" in encoders:
+        # Remove deprecated names for the same encoder
+        for encoder in ["nvenc", "nvenc_h264"]:
+            if encoder in encoders:
+                encoders.remove(encoder)
+    # Return an immutable tuple to avoid users corrupting the lru_cache
+    return tuple(encoders)
+
+
+@lru_cache()
+def get_first_available_h264_encoder():
+    compiled_encoders = get_compiled_h264_encoders()
+    for encoder in compiled_encoders:
+        if ffmpeg_test_encoder(encoder):
+            return encoder
+    else:
+        raise RuntimeError(
+            "No valid H.264 encoder was found with the ffmpeg installation"
+        )
+
+
+def count_frames_and_secs(path):
+    """
+    Get the number of frames and number of seconds for the given video
+    file. Note that this operation can be quite slow for large files.
+
+    Disclaimer: I've seen this produce different results from actually reading
+    the frames with older versions of ffmpeg (2.x). Therefore I cannot say
+    with 100% certainty that the returned values are always exact.
+    """
+    # https://stackoverflow.com/questions/2017843/fetch-frame-count-with-ffmpeg
+
+    if isinstance(path, pathlib.PurePath):
+        path = str(path)
+    if not isinstance(path, str):
+        raise TypeError("Video path must be a string or pathlib.Path.")
+
+    cmd = [
+        get_ffmpeg_exe(),
+        "-i",
+        path,
+        "-map",
+        "0:v:0",
+        "-vf",
+        "null",
+        "-f",
+        "null",
+        "-",
+    ]
+    try:
+        out = subprocess.check_output(cmd, stderr=subprocess.STDOUT, **_popen_kwargs())
+    except subprocess.CalledProcessError as err:
+        out = err.output.decode(errors="ignore")
+        raise RuntimeError(
+            "FFMPEG call failed with {}:\n{}".format(err.returncode, out)
+        )
+
+    # Note that other than with the subprocess calls below, ffmpeg wont hang here.
+    # Worst case Python will stop/crash and ffmpeg will continue running until done.
+
+    nframes = nsecs = None
+    for line in reversed(out.splitlines()):
+        if line.startswith(b"frame="):
+            line = line.decode(errors="ignore")
+            i = line.find("frame=")
+            if i >= 0:
+                s = line[i:].split("=", 1)[-1].lstrip().split(" ", 1)[0].strip()
+                nframes = int(s)
+            i = line.find("time=")
+            if i >= 0:
+                s = line[i:].split("=", 1)[-1].lstrip().split(" ", 1)[0].strip()
+                nsecs = cvsecs(*s.split(":"))
+            return nframes, nsecs
+
+    raise RuntimeError("Could not get number of frames")  # pragma: no cover
+
+
+def read_frames(
+    path,
+    pix_fmt="rgb24",
+    bpp=None,
+    input_params=None,
+    output_params=None,
+    bits_per_pixel=None,
+):
+    """
+    Create a generator to iterate over the frames in a video file.
+
+    It first yields a small metadata dictionary that contains:
+
+    * ffmpeg_version: the ffmpeg version in use (as a string).
+    * codec: a hint about the codec used to encode the video, e.g. "h264".
+    * source_size: the width and height of the encoded video frames.
+    * size: the width and height of the frames that will be produced.
+    * fps: the frames per second. Can be zero if it could not be detected.
+    * duration: duration in seconds. Can be zero if it could not be detected.
+
+    After that, it yields frames until the end of the video is reached. Each
+    frame is a bytes object.
+
+    This function makes no assumptions about the number of frames in
+    the data. For one because this is hard to predict exactly, but also
+    because it may depend on the provided output_params. If you want
+    to know the number of frames in a video file, use count_frames_and_secs().
+    It is also possible to estimate the number of frames from the fps and
+    duration, but note that even if both numbers are present, the resulting
+    value is not always correct.
+
+    Example:
+
+        gen = read_frames(path)
+        meta = gen.__next__()
+        for frame in gen:
+            print(len(frame))
+
+    Parameters:
+        path (str): the filename of the file to read from.
+        pix_fmt (str): the pixel format of the frames to be read.
+            The default is "rgb24" (frames are uint8 RGB images).
+        input_params (list): Additional ffmpeg input command line parameters.
+        output_params (list): Additional ffmpeg output command line parameters.
+        bits_per_pixel (int): The number of bits per pixel in the output frames.
+            This depends on the given pix_fmt. Default is 24 (RGB)
+        bpp (int): DEPRECATED, USE bits_per_pixel INSTEAD. The number of bytes per pixel in the output frames.
+            This depends on the given pix_fmt. Some pixel formats like yuv420p have 12 bits per pixel
+            and cannot be set in bytes as integer. For this reason the bpp argument is deprecated.
+    """
+
+    # ----- Input args
+
+    if isinstance(path, pathlib.PurePath):
+        path = str(path)
+    if not isinstance(path, str):
+        raise TypeError("Video path must be a string or pathlib.Path.")
+    # Note: Dont check whether it exists. The source could be e.g. a camera.
+
+    pix_fmt = pix_fmt or "rgb24"
+    bpp = bpp or 3
+    bits_per_pixel = bits_per_pixel or bpp * 8
+    input_params = input_params or []
+    output_params = output_params or []
+
+    assert isinstance(pix_fmt, str), "pix_fmt must be a string"
+    assert isinstance(bits_per_pixel, int), "bpp and bits_per_pixel must be an int"
+    assert isinstance(input_params, list), "input_params must be a list"
+    assert isinstance(output_params, list), "output_params must be a list"
+
+    # ----- Prepare
+
+    pre_output_params = ["-pix_fmt", pix_fmt, "-vcodec", "rawvideo", "-f", "image2pipe"]
+
+    cmd = [get_ffmpeg_exe()]
+    cmd += input_params + ["-i", path]
+    cmd += pre_output_params + output_params + ["-"]
+
+    process = subprocess.Popen(
+        cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        **_popen_kwargs(prevent_sigint=True)
+    )
+
+    log_catcher = LogCatcher(process.stderr)
+
+    # Init policy by which to terminate ffmpeg. May be set to "kill" later.
+    stop_policy = "timeout"  # not wait; ffmpeg should be able to quit quickly
+
+    # Enter try block directly after opening the process.
+    # We terminate ffmpeg in the finally clause.
+    # Generators are automatically closed when they get deleted,
+    # so the finally block is guaranteed to run.
+    try:
+        # ----- Load meta data
+
+        # Wait for the log catcher to get the meta information
+        etime = time.time() + 10.0
+        while log_catcher.is_alive() and not log_catcher.header and time.time() < etime:
+            time.sleep(0.01)
+
+        # Check whether we have the information
+        if not log_catcher.header:
+            err2 = log_catcher.get_text(0.2)
+            fmt = "Could not load meta information\n=== stderr ===\n{}"
+            raise IOError(fmt.format(err2))
+        elif "No such file or directory" in log_catcher.header:
+            raise IOError("{} not found! Wrong path?".format(path))
+
+        meta = parse_ffmpeg_header(log_catcher.header)
+        yield meta
+
+        # ----- Read frames
+
+        width, height = meta["size"]
+        framesize_bits = width * height * bits_per_pixel
+        framesize_bytes = framesize_bits / 8
+        assert (
+            framesize_bytes.is_integer()
+        ), "incorrect bits_per_pixel, framesize in bytes must be an int"
+        framesize_bytes = int(framesize_bytes)
+        framenr = 0
+
+        while True:
+            framenr += 1
+            try:
+                bb = bytes()
+                while len(bb) < framesize_bytes:
+                    extra_bytes = process.stdout.read(framesize_bytes - len(bb))
+                    if not extra_bytes:
+                        if len(bb) == 0:
+                            return
+                        else:
+                            raise RuntimeError(
+                                "End of file reached before full frame could be read."
+                            )
+                    bb += extra_bytes
+                yield bb
+            except Exception as err:
+                err1 = str(err)
+                err2 = log_catcher.get_text(0.4)
+                fmt = "Could not read frame {}:\n{}\n=== stderr ===\n{}"
+                raise RuntimeError(fmt.format(framenr, err1, err2))
+
+    except GeneratorExit:
+        # Note that GeneratorExit does not inherit from Exception but BaseException
+        pass
+
+    except Exception:
+        # Normal exceptions fall through
+        raise
+
+    except BaseException:
+        # Detect KeyboardInterrupt / SystemExit: don't wait for ffmpeg to quit
+        stop_policy = "kill"
+        raise
+
+    finally:
+        # Stop the LogCatcher thread, which reads from stderr.
+        log_catcher.stop_me()
+
+        # Make sure that ffmpeg is terminated.
+        if process.poll() is None:
+            # Ask ffmpeg to quit
+            try:
+                # I read somewhere that modern ffmpeg on Linux prefers a
+                # "ctrl-c", but tests so far suggests sending q is more robust.
+                # > p.send_signal(signal.SIGINT)
+                # Sending q via communicate works, but can hang (see #17)
+                # > p.communicate(b"q")
+                # So let's do similar to what communicate does, but without
+                # reading stdout (which may block). It looks like only closing
+                # stdout is enough (tried Windows+Linux), but let's play safe.
+                # Found that writing to stdin can cause "Invalid argument" on
+                # Windows # and "Broken Pipe" on Unix.
+                # p.stdin.write(b"q")  # commented out in v0.4.1
+                process.stdout.close()
+                process.stdin.close()
+                # p.stderr.close() -> not here, the log_catcher closes it
+            except Exception as err:  # pragma: no cover
+                logger.warning("Error while attempting stop ffmpeg (r): " + str(err))
+
+            if stop_policy == "timeout":
+                # Wait until timeout, produce a warning and kill if it still exists
+                try:
+                    etime = time.time() + 1.5
+                    while time.time() < etime and process.poll() is None:
+                        time.sleep(0.01)
+                finally:
+                    if process.poll() is None:  # pragma: no cover
+                        logger.warning("We had to kill ffmpeg to stop it.")
+                        process.kill()
+
+            else:  # stop_policy == "kill"
+                # Just kill it
+                process.kill()
+
+
+def write_frames(
+    path,
+    size,
+    pix_fmt_in="rgb24",
+    pix_fmt_out="yuv420p",
+    fps=16,
+    quality=5,
+    bitrate=None,
+    codec=None,
+    macro_block_size=16,
+    ffmpeg_log_level="warning",
+    ffmpeg_timeout=None,
+    input_params=None,
+    output_params=None,
+    audio_path=None,
+    audio_codec=None,
+):
+    """
+    Create a generator to write frames (bytes objects) into a video file.
+
+    The frames are written by using the generator's `send()` method. Frames
+    can be anything that can be written to a file. Typically these are
+    bytes objects, but c-contiguous Numpy arrays also work.
+
+    Example:
+
+        gen = write_frames(path, size)
+        gen.send(None)  # seed the generator
+        for frame in frames:
+            gen.send(frame)
+        gen.close()  # don't forget this
+
+    Parameters:
+        path (str): the filename to write to.
+        size (tuple): the width and height of the frames.
+        pix_fmt_in (str): the pixel format of incoming frames.
+            E.g. "gray", "gray8a", "rgb24", or "rgba". Default "rgb24".
+        pix_fmt_out (str): the pixel format to store frames. Default yuv420p".
+        fps (float or Fraction): The frames per second. Default 16.
+        quality (float): A measure for quality between 0 and 10. Default 5.
+            Ignored if bitrate is given.
+        bitrate (str): The bitrate, e.g. "192k". The defaults are pretty good.
+        codec (str): The codec. Default "libx264" for .mp4 (if available from
+            the ffmpeg executable) or "msmpeg4" for .wmv.
+        macro_block_size (int): You probably want to align the size of frames
+            to this value to avoid image resizing. Default 16. Can be set
+            to 1 to avoid block alignment, though this is not recommended.
+        ffmpeg_log_level (str): The ffmpeg logging level. Default "warning".
+        ffmpeg_timeout (float): Timeout in seconds to wait for ffmpeg process
+            to finish. Value of 0 or None will wait forever (default). The time that
+            ffmpeg needs depends on CPU speed, compression, and frame size.
+        input_params (list): Additional ffmpeg input command line parameters.
+        output_params (list): Additional ffmpeg output command line parameters.
+        audio_path (str): A input file path for encoding with an audio stream.
+            Default None, no audio.
+        audio_codec (str): The audio codec to use if audio_path is provided.
+            "copy" will try to use audio_path's audio codec without re-encoding.
+            Default None, but some formats must have certain codecs specified.
+    """
+
+    # ----- Input args
+
+    if isinstance(path, pathlib.PurePath):
+        path = str(path)
+    if not isinstance(path, str):
+        raise TypeError("Video path must be a string or pathlib.Path.")
+
+    # The pix_fmt_out yuv420p is the best for the outpur to work in
+    # QuickTime and most other players. These players only support
+    # the YUV planar color space with 4:2:0 chroma subsampling for
+    # H.264 video. Otherwise, depending on the source, ffmpeg may
+    # output to a pixel format that may be incompatible with these
+    # players. See https://trac.ffmpeg.org/wiki/Encode/H.264#Encodingfordumbplayers
+
+    pix_fmt_in = pix_fmt_in or "rgb24"
+    pix_fmt_out = pix_fmt_out or "yuv420p"
+    fps = fps or 16
+    # bitrate, codec, macro_block_size can all be None or ...
+    macro_block_size = macro_block_size or 16
+    ffmpeg_log_level = ffmpeg_log_level or "warning"
+    input_params = input_params or []
+    output_params = output_params or []
+    ffmpeg_timeout = ffmpeg_timeout or 0
+
+    floatish = float, int
+    if isinstance(size, (tuple, list)):
+        assert len(size) == 2, "size must be a 2-tuple"
+        assert isinstance(size[0], int) and isinstance(
+            size[1], int
+        ), "size must be ints"
+        sizestr = "{:d}x{:d}".format(*size)
+    # elif isinstance(size, str):
+    #     assert "x" in size, "size as string must have format NxM"
+    #     sizestr = size
+    else:
+        assert False, "size must be str or tuple"
+    assert isinstance(pix_fmt_in, str), "pix_fmt_in must be str"
+    assert isinstance(pix_fmt_out, str), "pix_fmt_out must be str"
+    assert isinstance(fps, (*floatish, Fraction)), "fps must be float or Fraction"
+    if quality is not None:
+        assert isinstance(quality, floatish), "quality must be float"
+        assert 1 <= quality <= 10, "quality must be between 1 and 10 inclusive"
+    assert isinstance(macro_block_size, int), "macro_block_size must be int"
+    assert isinstance(ffmpeg_log_level, str), "ffmpeg_log_level must be str"
+    assert isinstance(ffmpeg_timeout, floatish), "ffmpeg_timeout must be float"
+    assert isinstance(input_params, list), "input_params must be a list"
+    assert isinstance(output_params, list), "output_params must be a list"
+
+    # ----- Prepare
+
+    # Get parameters
+    if not codec:
+        if path.lower().endswith(".wmv"):
+            # This is a safer default codec on windows to get videos that
+            # will play in powerpoint and other apps. H264 is not always
+            # available on windows.
+            codec = "msmpeg4"
+        else:
+            codec = get_first_available_h264_encoder()
+
+    audio_params = ["-an"]
+    if audio_path is not None and not path.lower().endswith(".gif"):
+        audio_params = ["-i", audio_path]
+        if audio_codec is not None:
+            output_params += ["-acodec", audio_codec]
+        output_params += ["-map", "0:v:0", "-map", "1:a:0"]
+
+    # Get command
+    cmd = [
+        get_ffmpeg_exe(),
+        "-y",
+        "-f",
+        "rawvideo",
+        "-vcodec",
+        "rawvideo",
+        "-s",
+        sizestr,
+    ]
+    # Pass fps as a rational so values like 24000/1001 are not rounded (#116).
+    if not isinstance(fps, Fraction):
+        fps = Fraction(fps).limit_denominator()
+    fps_arg = str(fps)
+    cmd += ["-pix_fmt", pix_fmt_in, "-r", fps_arg] + input_params
+    cmd += ["-i", "-"] + audio_params
+    cmd += ["-vcodec", codec, "-pix_fmt", pix_fmt_out]
+
+    # Add fixed bitrate or variable bitrate compression flags
+    if bitrate is not None:
+        cmd += ["-b:v", str(bitrate)]
+    elif quality is not None:  # If None, then we don't add anything
+        quality = 1 - quality / 10.0
+        if codec == "libx264":
+            # crf ranges 0 to 51, 51 being worst.
+            quality = int(quality * 51)
+            cmd += ["-crf", str(quality)]  # for h264
+        else:  # Many codecs accept q:v
+            # q:v range can vary, 1-31, 31 being worst
+            # But q:v does not always have the same range.
+            # May need a way to find range for any codec.
+            quality = int(quality * 30) + 1
+            cmd += ["-qscale:v", str(quality)]  # for others
+
+    # Note, for most codecs, the image dimensions must be divisible by
+    # 16 the default for the macro_block_size is 16. Check if image is
+    # divisible, if not have ffmpeg upsize to nearest size and warn
+    # user they should correct input image if this is not desired.
+    if macro_block_size > 1:
+        if size[0] % macro_block_size > 0 or size[1] % macro_block_size > 0:
+            out_w = size[0]
+            out_h = size[1]
+            if size[0] % macro_block_size > 0:
+                out_w += macro_block_size - (size[0] % macro_block_size)
+            if size[1] % macro_block_size > 0:
+                out_h += macro_block_size - (size[1] % macro_block_size)
+            cmd += ["-vf", "scale={}:{}".format(out_w, out_h)]
+            logger.warning(
+                "IMAGEIO FFMPEG_WRITER WARNING: input image is not"
+                " divisible by macro_block_size={}, resizing from {} "
+                "to {} to ensure video compatibility with most codecs "
+                "and players. To prevent resizing, make your input "
+                "image divisible by the macro_block_size or set the "
+                "macro_block_size to 1 (risking incompatibility).".format(
+                    macro_block_size, size[:2], (out_w, out_h)
+                )
+            )
+
+    # Rather than redirect stderr to a pipe, just set minimal
+    # output from ffmpeg by default. That way if there are warnings
+    # the user will see them.
+    cmd += ["-v", ffmpeg_log_level]
+    cmd += output_params
+    cmd.append(path)
+    cmd_str = " ".join(cmd)
+    if any(
+        [level in ffmpeg_log_level for level in ("info", "verbose", "debug", "trace")]
+    ):
+        logger.info("RUNNING FFMPEG COMMAND: " + cmd_str)
+
+    # Launch process
+    p = subprocess.Popen(
+        cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=None,
+        **_popen_kwargs(prevent_sigint=True)
+    )
+
+    # Note that directing stderr to a pipe on windows will cause ffmpeg
+    # to hang if the buffer is not periodically cleared using
+    # StreamCatcher or other means.
+    # Setting bufsize to 0 or a small value does not seem to have much effect
+    # (tried on Windows and Linux). I suspect that ffmpeg buffers
+    # multiple frames (before encoding in a batch).
+
+    # Init policy by which to terminate ffmpeg. May be set to "kill" later.
+    stop_policy = "timeout"
+    if not ffmpeg_timeout:
+        stop_policy = "wait"
+
+    # ----- Write frames
+
+    # Enter try block directly after opening the process.
+    # We terminate ffmpeg in the finally clause.
+    # Generators are automatically closed when they get deleted,
+    # so the finally block is guaranteed to run.
+    try:
+        # Just keep going until the generator.close() is called (raises GeneratorExit).
+        # This could also happen when the generator is deleted somehow.
+        nframes = 0
+        while True:
+            # Get frame
+            bb = yield
+
+            # framesize = size[0] * size[1] * depth * bpp
+            # assert isinstance(bb, bytes), "Frame must be send as bytes"
+            # assert len(bb) == framesize, "Frame must have width*height*depth*bpp bytes"
+            # Actually, we accept anything that can be written to file.
+            # This e.g. allows writing numpy arrays without having to make a copy ...
+
+            # Write
+            try:
+                p.stdin.write(bb)
+            except Exception as err:
+                # Show the command and stderr from pipe
+                msg = (
+                    "{0:}\n\nFFMPEG COMMAND:\n{1:}\n\nFFMPEG STDERR "
+                    "OUTPUT:\n".format(err, cmd_str)
+                )
+                raise IOError(msg)
+
+            nframes += 1
+
+    except GeneratorExit:
+        # Note that GeneratorExit does not inherit from Exception but BaseException
+        # Detect premature closing
+        if nframes == 0:
+            logger.warning("No frames have been written; the written video is invalid.")
+
+    except Exception:
+        # Normal exceptions fall through
+        raise
+
+    except BaseException:
+        # Detect KeyboardInterrupt / SystemExit: don't wait for ffmpeg to quit
+        stop_policy = "kill"
+        raise
+
+    finally:
+        # Make sure that ffmpeg is terminated.
+        if p.poll() is None:
+            # Tell ffmpeg that we're done
+            try:
+                p.stdin.close()
+            except Exception as err:  # pragma: no cover
+                logger.warning("Error while attempting stop ffmpeg (w): " + str(err))
+
+            if stop_policy == "timeout":
+                # Wait until timeout, produce a warning and kill if it still exists
+                try:
+                    etime = time.time() + ffmpeg_timeout
+                    while (time.time() < etime) and p.poll() is None:
+                        time.sleep(0.01)
+                finally:
+                    if p.poll() is None:  # pragma: no cover
+                        logger.warning(
+                            "We had to kill ffmpeg to stop it. "
+                            + "Consider increasing ffmpeg_timeout, "
+                            + "or setting it to zero (no timeout)."
+                        )
+                        p.kill()
+
+            elif stop_policy == "wait":
+                # Wait forever, kill if it if we're interrupted
+                try:
+                    while p.poll() is None:
+                        time.sleep(0.01)
+                finally:  # the above can raise e.g. by ctrl-c or systemexit
+                    if p.poll() is None:  # pragma: no cover
+                        p.kill()
+
+            else:  #  stop_policy == "kill":
+                # Just kill it
+                p.kill()
+        # Just to be safe, wrap in try/except
+        try:
+            p.stdout.close()
+        except Exception:
+            pass

imageio_ffmpeg/_parsing.py

@@ -0,0 +1,208 @@
+import re
+import threading
+import time
+
+from ._utils import logger
+
+
+class LogCatcher(threading.Thread):
+    """Thread to keep reading from stderr so that the buffer does not
+    fill up and stalls the ffmpeg process. On stderr a message is send
+    on every few frames with some meta information. We only keep the
+    last ones.
+    """
+
+    def __init__(self, file):
+        self._file = file
+        self._header = ""
+        self._lines = []
+        self._remainder = b""
+        threading.Thread.__init__(self)
+        self.daemon = True  # do not let this thread hold up Python shutdown
+        self._should_stop = False
+        self.start()
+
+    def stop_me(self):
+        self._should_stop = True
+
+    @property
+    def header(self):
+        """Get header text. Empty string if the header is not yet parsed."""
+        return self._header
+
+    def get_text(self, timeout=0):
+        """Get the whole text written to stderr so far. To preserve
+        memory, only the last 50 to 100 frames are kept.
+
+        If a timeout is given, wait for this thread to finish. When
+        something goes wrong, we stop ffmpeg and want a full report of
+        stderr, but this thread might need a tiny bit more time.
+        """
+
+        # Wait?
+        if timeout > 0:
+            etime = time.time() + timeout
+            while self.is_alive() and time.time() < etime:  # pragma: no cover
+                time.sleep(0.01)
+        # Return str
+        lines = b"\n".join(self._lines)
+        return self._header + "\n" + lines.decode("utf-8", "ignore")
+
+    def run(self):
+        # Create ref here so it still exists even if Py is shutting down
+        limit_lines_local = limit_lines
+
+        while not self._should_stop:
+            time.sleep(0)
+            # Read one line. Detect when closed, and exit
+            try:
+                line = self._file.read(20)
+            except ValueError:  # pragma: no cover
+                break
+            if not line:
+                break
+            # Process to divide in lines
+            line = line.replace(b"\r", b"\n").replace(b"\n\n", b"\n")
+            lines = line.split(b"\n")
+            lines[0] = self._remainder + lines[0]
+            self._remainder = lines.pop(-1)
+            # Process each line
+            self._lines.extend(lines)
+            if not self._header:
+                if get_output_video_line(self._lines):
+                    header = b"\n".join(self._lines)
+                    self._header += header.decode("utf-8", "ignore")
+            elif self._lines:
+                self._lines = limit_lines_local(self._lines)
+
+        # Close the file when we're done
+        # See #61 and #69
+        try:
+            self._file.close()
+        except Exception:
+            pass
+
+
+def get_output_video_line(lines):
+    """Get the line that defines the video stream that ffmpeg outputs,
+    and which we read.
+    """
+    in_output = False
+    for line in lines:
+        sline = line.lstrip()
+        if sline.startswith(b"Output "):
+            in_output = True
+        elif in_output:
+            if sline.startswith(b"Stream ") and b" Video:" in sline:
+                return line
+
+
+def limit_lines(lines, N=32):
+    """When number of lines > 2*N, reduce to N."""
+    if len(lines) > 2 * N:
+        lines = [b"... showing only last few lines ..."] + lines[-N:]
+    return lines
+
+
+def cvsecs(*args):
+    """converts a time to second. Either cvsecs(min, secs) or
+    cvsecs(hours, mins, secs).
+    """
+    if len(args) == 1:
+        return float(args[0])
+    elif len(args) == 2:
+        return 60 * float(args[0]) + float(args[1])
+    elif len(args) == 3:
+        return 3600 * float(args[0]) + 60 * float(args[1]) + float(args[2])
+
+
+def parse_ffmpeg_header(text):
+    lines = text.splitlines()
+    meta = {}
+
+    # meta["header"] = text  # Can enable this for debugging
+
+    # Get version
+    ver = lines[0].split("version", 1)[-1].split("Copyright")[0]
+    meta["ffmpeg_version"] = ver.strip() + " " + lines[1].strip()
+
+    # get the output line that speaks about video
+    videolines = [
+        l for l in lines if l.lstrip().startswith("Stream ") and " Video: " in l
+    ]
+
+    # Codec and pix_fmt hint
+    line = videolines[0]
+    meta["codec"] = line.split("Video: ", 1)[-1].lstrip().split(" ", 1)[0].strip()
+    meta["pix_fmt"] = re.split(
+        # use a negative lookahead regexp to ignore commas that are contained
+        # within a parenthesis
+        # this helps consider a pix_fmt of the kind
+        #     yuv420p(tv, progressive)
+        # as what it is, instead of erroneously reporting as
+        #     yuv420p(tv
+        r",\s*(?![^()]*\))",
+        line.split("Video: ", 1)[-1],
+    )[1].strip()
+
+    # get the output line that speaks about audio
+    audiolines = [
+        l for l in lines if l.lstrip().startswith("Stream ") and " Audio: " in l
+    ]
+
+    if len(audiolines) > 0:
+        audio_line = audiolines[0]
+        meta["audio_codec"] = (
+            audio_line.split("Audio: ", 1)[-1].lstrip().split(" ", 1)[0].strip()
+        )
+
+    # get the frame rate.
+    # matches can be empty, see #171, assume nframes = inf
+    # the regexp omits values of "1k tbr" which seems a specific edge-case #262
+    # it seems that tbr is generally to be preferred #262
+    fps = 0
+    for line in [videolines[0]]:
+        matches = re.findall(r" ([0-9]+\.?[0-9]*) (fps)", line)
+        if matches:
+            fps = float(matches[0][0].strip())
+    meta["fps"] = fps
+
+    # get the size of the original stream, of the form 460x320 (w x h)
+    line = videolines[0]
+    match = re.search(" [0-9]*x[0-9]*(,| )", line)
+    parts = line[match.start() : match.end() - 1].split("x")
+    meta["source_size"] = tuple(map(int, parts))
+
+    # get the size of what we receive, of the form 460x320 (w x h)
+    line = videolines[-1]  # Pipe output
+    match = re.search(" [0-9]*x[0-9]*(,| )", line)
+    parts = line[match.start() : match.end() - 1].split("x")
+    meta["size"] = tuple(map(int, parts))
+
+    # Check the two sizes
+    if meta["source_size"] != meta["size"]:
+        logger.warning(
+            "The frame size for reading {} is "
+            "different from the source frame size {}.".format(
+                meta["size"], meta["source_size"]
+            )
+        )
+
+    # get the rotate metadata
+    reo_rotate = re.compile(r"rotate\s+:\s([0-9]+)")
+    match = reo_rotate.search(text)
+    rotate = 0
+    if match is not None:
+        rotate = match.groups()[0]
+    meta["rotate"] = int(rotate)
+
+    # get duration (in seconds)
+    line = [l for l in lines if "Duration: " in l][0]
+    match = re.search(" [0-9][0-9]:[0-9][0-9]:[0-9][0-9].[0-9][0-9]", line)
+    duration = 0
+    if match is not None:
+        hms = line[match.start() + 1 : match.end()].split(":")
+        duration = cvsecs(*hms)
+    meta["duration"] = duration
+
+    return meta

imageio_ffmpeg/_utils.py

@@ -0,0 +1,127 @@
+import logging
+import os
+import subprocess
+import sys
+from functools import lru_cache
+import importlib.resources
+
+from ._definitions import FNAME_PER_PLATFORM, get_platform
+
+logger = logging.getLogger("imageio_ffmpeg")
+
+
+def get_ffmpeg_exe():
+    """
+    Get the ffmpeg executable file. This can be the binary defined by
+    the IMAGEIO_FFMPEG_EXE environment variable, the binary distributed
+    with imageio-ffmpeg, an ffmpeg binary installed with conda, or the
+    system ffmpeg (in that order). A RuntimeError is raised if no valid
+    ffmpeg could be found.
+    """
+
+    # 1. Try environment variable. - Dont test it: the user is explicit here!
+    exe = os.getenv("IMAGEIO_FFMPEG_EXE", None)
+    if exe:
+        return exe
+
+    # Auto-detect
+    exe = _get_ffmpeg_exe()
+    if exe:
+        return exe
+
+    # Nothing was found
+    raise RuntimeError(
+        "No ffmpeg exe could be found. Install ffmpeg on your system, "
+        "or set the IMAGEIO_FFMPEG_EXE environment variable."
+    )
+
+
+@lru_cache()
+def _get_ffmpeg_exe():
+    plat = get_platform()
+
+    # 2. Try from here
+    exe = os.path.join(_get_bin_dir(), FNAME_PER_PLATFORM.get(plat, ""))
+    if exe and os.path.isfile(exe) and _is_valid_exe(exe):
+        return exe
+
+    # 3. Try binary from conda package
+    # (installed e.g. via `conda install ffmpeg -c conda-forge`)
+    if plat.startswith("win"):
+        exe = os.path.join(sys.prefix, "Library", "bin", "ffmpeg.exe")
+    else:
+        exe = os.path.join(sys.prefix, "bin", "ffmpeg")
+    if exe and os.path.isfile(exe) and _is_valid_exe(exe):
+        return exe
+
+    # 4. Try system ffmpeg command
+    exe = "ffmpeg"
+    if _is_valid_exe(exe):
+        return exe
+
+    return None
+
+
+def _get_bin_dir():
+    if sys.version_info < (3, 9):
+        context = importlib.resources.path("imageio_ffmpeg.binaries", "__init__.py")
+    else:
+        ref = importlib.resources.files("imageio_ffmpeg.binaries") / "__init__.py"
+        context = importlib.resources.as_file(ref)
+    with context as path:
+        pass
+    # Return the dir. We assume that the data files are on a normal dir on the fs.
+    return str(path.parent)
+
+
+def _popen_kwargs(prevent_sigint=False):
+    startupinfo = None
+    preexec_fn = None
+    creationflags = 0
+    if sys.platform.startswith("win"):
+        # Stops executable from flashing on Windows (see #22)
+        startupinfo = subprocess.STARTUPINFO()
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+    if prevent_sigint:
+        # Prevent propagation of sigint (see #4)
+        # https://stackoverflow.com/questions/5045771
+        if sys.platform.startswith("win"):
+            creationflags = 0x00000200
+        else:
+            preexec_fn = os.setpgrp  # the _pre_exec does not seem to work
+
+    falsy = ("", "0", "false", "no")
+    if os.getenv("IMAGEIO_FFMPEG_NO_PREVENT_SIGINT", "").lower() not in falsy:
+        # Unset preexec_fn to work around a strange hang on fork() (see #58)
+        preexec_fn = None
+
+    return {
+        "startupinfo": startupinfo,
+        "creationflags": creationflags,
+        "preexec_fn": preexec_fn,
+    }
+
+
+def _is_valid_exe(exe):
+    cmd = [exe, "-version"]
+    try:
+        with open(os.devnull, "w") as null:
+            subprocess.check_call(
+                cmd, stdout=null, stderr=subprocess.STDOUT, **_popen_kwargs()
+            )
+        return True
+    except (OSError, ValueError, subprocess.CalledProcessError):
+        return False
+
+
+def get_ffmpeg_version():
+    """
+    Get the version of the used ffmpeg executable (as a string).
+    """
+    exe = get_ffmpeg_exe()
+    line = subprocess.check_output([exe, "-version"], **_popen_kwargs()).split(
+        b"\n", 1
+    )[0]
+    line = line.decode(errors="ignore").strip()
+    version = line.split("version", 1)[-1].lstrip().split(" ", 1)[0].strip()
+    return version

imageio_ffmpeg/binaries/README.md

@@ -0,0 +1,2 @@
+Exes are dropped here by `invoke get-ffmpeg-binary` and the release script
+(see `tools/download_ffmpeg.py`).

imageio_ffmpeg/binaries/__init__.py

@@ -0,0 +1 @@
+# Just here to make importlib.resources work

imageio_ffmpeg/binaries/ffmpeg-win-aarch64-v9.0.1.exe

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: imageio_ffmpeg/binaries/ffmpeg-win-aarch64-v9.0.1.exe
+size: 78507008 bytes
+sha256: a169b9d26b2380be66211022525c9ac16affc923ba05b561024e57c5ed4281f9

imageio_ffmpeg-0.8.0.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: imageio-ffmpeg
+Version: 0.8.0
+Summary: FFMPEG wrapper for Python
+Home-page: https://github.com/imageio/imageio-ffmpeg
+Download-URL: http://pypi.python.org/pypi/imageio-ffmpeg
+Author: imageio contributors
+Author-email: almar.klein@gmail.com
+License: BSD-2-Clause
+Keywords: video ffmpeg
+Platform: any
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Provides: imageio_ffmpeg
+Requires-Python: >=3.10
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: provides
+Dynamic: requires-python
+Dynamic: summary
+
+FFMPEG wrapper for Python.
+
+Note that the platform-specific wheels contain the binary executable
+of ffmpeg, which makes this package around 60 MiB in size.
+I guess that's the cost for being able to read/write video files.
+
+For Linux users: the above is not the case when installing via your
+Linux package manager (if that is possible), because this package would
+simply depend on ffmpeg in that case.

imageio_ffmpeg-0.8.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+imageio_ffmpeg/__init__.py,sha256=up19VQbBji1XMFotEd96oazT3u17Dq-GMzHYHbFqOFI,225
+imageio_ffmpeg/_definitions.py,sha256=4DADH1EdLc9AA98RYf0dWxfIEMxtFl80Q21J4sEXJ2s,2192
+imageio_ffmpeg/_io.py,sha256=XdqDqEjnMT-kJijRt1dZ5-TkFFS_uh2eD9zsE6238-M,27290
+imageio_ffmpeg/_parsing.py,sha256=UUtYPybzv9vQ4sKPwYlRTyaP_k9koKXfl-zI6Rm4Qpo,6840
+imageio_ffmpeg/_utils.py,sha256=eVF4ny9zP3jPfeYIwl6VfV9T1v34S6yURWC_RiGUNF8,3833
+imageio_ffmpeg/binaries/README.md,sha256=nwMe1zGsWei5WruCZKFAeUuUj4Ud9Air6uNVObFdlt0,109
+imageio_ffmpeg/binaries/__init__.py,sha256=zjnRZoM6bQUBYOI30HpzIp4ck07bOy4oxXB-bwN3NW8,45
+imageio_ffmpeg/binaries/ffmpeg-win-aarch64-v9.0.1.exe,sha256=oWm50msjgL5mIRAiUlyawWr_ySO6BbVhAk5Xxe1Cgfk,78507008
+imageio_ffmpeg-0.8.0.dist-info/licenses/LICENSE,sha256=7Kc0IdDJBakulSpVPU1YkZxaUHwsLHbjwM-bpAjCmeQ,1317
+imageio_ffmpeg-0.8.0.dist-info/METADATA,sha256=x4s48LRsmfavQIkgJFk3z-kZ2BazBDmhqScuhdC-YQo,1530
+imageio_ffmpeg-0.8.0.dist-info/WHEEL,sha256=lTfaOYr-DH5rklomOvgFCC9CuI2mD5X71wfmwV8y5wQ,96
+imageio_ffmpeg-0.8.0.dist-info/top_level.txt,sha256=ODQYUYYbtj9I1SjASEMY7h8Q8haLrmMNURSCn0FEB18,15
+imageio_ffmpeg-0.8.0.dist-info/RECORD,,

imageio_ffmpeg-0.8.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-win_arm64

imageio_ffmpeg-0.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2019-2025, imageio
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

imageio_ffmpeg-0.8.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+imageio_ffmpeg