{"id":13906825,"url":"https://github.com/imageio/imageio-ffmpeg","last_synced_at":"2025-05-14T11:10:19.904Z","repository":{"id":34077649,"uuid":"167969840","full_name":"imageio/imageio-ffmpeg","owner":"imageio","description":"FFMPEG wrapper for Python","archived":false,"fork":false,"pushed_at":"2025-01-16T21:36:01.000Z","size":144,"stargazers_count":253,"open_issues_count":18,"forks_count":54,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-15T00:38:06.549Z","etag":null,"topics":["ffmpeg","python","wrapper-library"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imageio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"imageio","tidelift":"pypi/imageio-ffmpeg"}},"created_at":"2019-01-28T13:49:20.000Z","updated_at":"2025-04-07T08:17:41.000Z","dependencies_parsed_at":"2025-03-10T14:01:41.189Z","dependency_job_id":"930fd74f-6d80-4bd8-b513-987f3225ead8","html_url":"https://github.com/imageio/imageio-ffmpeg","commit_stats":{"total_commits":93,"total_committers":24,"mean_commits":3.875,"dds":0.5268817204301075,"last_synced_commit":"2f3403a0c3d1a34b208c4a7d9396035479f90838"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imageio%2Fimageio-ffmpeg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imageio%2Fimageio-ffmpeg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imageio%2Fimageio-ffmpeg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imageio%2Fimageio-ffmpeg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imageio","download_url":"https://codeload.github.com/imageio/imageio-ffmpeg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129489,"owners_count":22019628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffmpeg","python","wrapper-library"],"created_at":"2024-08-06T23:01:43.132Z","updated_at":"2025-05-14T11:10:19.841Z","avatar_url":"https://github.com/imageio.png","language":"Python","readme":"# imageio-ffmpeg\n\n[![Build Status](https://github.com/imageio/imageio-ffmpeg/workflows/CI/badge.svg)](https://github.com/imageio/imageio-ffmpeg/actions)\n[![PyPI Version](https://img.shields.io/pypi/v/imageio-ffmpeg.svg)](https://pypi.python.org/pypi/imageio-ffmpeg/)\n\nFFMPEG wrapper for Python\n\n## Purpose\n\nThe purpose of this project is to provide a simple and reliable ffmpeg\nwrapper for working with video files. It implements two simple generator\nfunctions for reading and writing data from/to ffmpeg, which reliably\nterminate the ffmpeg process when done. It also takes care of publishing\nplatform-specific wheels that include the binary ffmpeg executables.\n\nThis library is used as the basis for the\n[imageio](https://github.com/imageio/imageio)\n[ffmpeg plugin](https://imageio.readthedocs.io/en/stable/format_ffmpeg.html),\nbut it can also be used by itself. Imageio provides a higher level API,\nand adds support for e.g. cameras and seeking.\n\nThis library was created before [PyAV](https://github.com/PyAV-Org/PyAV) was a thing. But now they have binary wheels for many platforms. You should probably use `PyAV` instead; it is faster and offers more features.\n\n\n## Installation\n\nThis library works with any version of Python 3.7+ (including Pypy).\nThere are no further dependencies. The wheels on Pypi include the ffmpeg\nexecutable for all common platforms (Windows 7+, Linux kernel 2.6.32+,\nOSX 10.9+). Install using:\n\n```\n$ pip install --upgrade imageio-ffmpeg\n```\n\n(On Linux you may want to first `pip install -U pip`, since pip 19 is needed to detect the `manylinux2010` wheels.)\n\nIf you're using a Conda environment: the conda package does not include\nthe ffmpeg executable, but instead depends on the `ffmpeg` package from\n`conda-forge`. Install using:\n\n```\n$ conda install imageio-ffmpeg -c conda-forge\n```\n\nIf you don't want to install the included ffmpeg, you can use pip with\n`--no-binary` or conda with `--no-deps`. Then use the\n`IMAGEIO_FFMPEG_EXE` environment variable if needed.\n\n\n## Example usage\n\nThe `imageio_ffmpeg` library provides low level functionality to read\nand write video data, using Python generators:\n\n\n```py\n\n# Read a video file\nreader = read_frames(path)\nmeta = reader.__next__()  # meta data, e.g. meta[\"size\"] -\u003e (width, height)\nfor frame in reader:\n    ... # each frame is a bytes object\n\n# Write a video file\nwriter = write_frames(path, size)  # size is (width, height)\nwriter.send(None)  # seed the generator\nfor frame in frames:\n    writer.send(frame)\nwriter.close()  # don't forget this\n```\n\n(Also see the API section further down.)\n\n\n## How it works\n\nThis library calls ffmpeg in a subprocess, and video frames are\ncommunicated over pipes. This is certainly not the fastest way to\nuse ffmpeg, but it makes it possible to wrap ffmpeg with pure Python,\nmaking distribution and installation *much* easier. And probably\nthe code itself too. In contrast, [PyAV](https://github.com/mikeboers/PyAV)\nwraps ffmpeg at the C level.\n\nNote that because of how `imageio-ffmpeg` works, `read_frames()` and\n`write_frames()` only accept file names, and not file (like) objects.\n\n\n\n## imageio-ffmpeg for enterprise\n\nAvailable as part of the Tidelift Subscription\n\nThe maintainers of imageio-ffmpeg and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/pypi-imageio-ffmpeg?utm_source=pypi-imageio-ffmpeg\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo)\n\n\n## Security contact information\n\nTo report a security vulnerability, please use the\n[Tidelift security contact](https://tidelift.com/security).\nTidelift will coordinate the fix and disclosure.\n\n\n## Environment variables\n\nThe library can be configured at runtime by setting the following environment\nvariables:\n* `IMAGEIO_FFMPEG_EXE=[file name]` -- override the ffmpeg executable;\n* `IMAGEIO_FFMPEG_NO_PREVENT_SIGINT=1` -- don't prevent propagation of SIGINT\n  to the ffmpeg process.\n\n## Developers\n\nDev deps:\n```\npip install invoke black flake8\n```\n\nWe use invoke:\n\n```\ninvoke autoformat\ninvoke lint\ninvoke -l  # to get a list of all tasks\ninvoke update-readme  # after changes to the docstrings\n```\n\n## API\n\n```py\ndef read_frames(\n    path,\n    pix_fmt=\"rgb24\",\n    bpp=None,\n    input_params=None,\n    output_params=None,\n    bits_per_pixel=None,\n):\n    \"\"\"\n    Create a generator to iterate over the frames in a video file.\n\n    It first yields a small metadata dictionary that contains:\n\n    * ffmpeg_version: the ffmpeg version in use (as a string).\n    * codec: a hint about the codec used to encode the video, e.g. \"h264\".\n    * source_size: the width and height of the encoded video frames.\n    * size: the width and height of the frames that will be produced.\n    * fps: the frames per second. Can be zero if it could not be detected.\n    * duration: duration in seconds. Can be zero if it could not be detected.\n\n    After that, it yields frames until the end of the video is reached. Each\n    frame is a bytes object.\n\n    This function makes no assumptions about the number of frames in\n    the data. For one because this is hard to predict exactly, but also\n    because it may depend on the provided output_params. If you want\n    to know the number of frames in a video file, use count_frames_and_secs().\n    It is also possible to estimate the number of frames from the fps and\n    duration, but note that even if both numbers are present, the resulting\n    value is not always correct.\n\n    Example:\n\n        gen = read_frames(path)\n        meta = gen.__next__()\n        for frame in gen:\n            print(len(frame))\n\n    Parameters:\n        path (str): the filename of the file to read from.\n        pix_fmt (str): the pixel format of the frames to be read.\n            The default is \"rgb24\" (frames are uint8 RGB images).\n        input_params (list): Additional ffmpeg input command line parameters.\n        output_params (list): Additional ffmpeg output command line parameters.\n        bits_per_pixel (int): The number of bits per pixel in the output frames.\n            This depends on the given pix_fmt. Default is 24 (RGB)\n        bpp (int): DEPRECATED, USE bits_per_pixel INSTEAD. The number of bytes per pixel in the output frames.\n            This depends on the given pix_fmt. Some pixel formats like yuv420p have 12 bits per pixel\n            and cannot be set in bytes as integer. For this reason the bpp argument is deprecated.\n    \"\"\"\n```\n\n```py\ndef write_frames(\n    path,\n    size,\n    pix_fmt_in=\"rgb24\",\n    pix_fmt_out=\"yuv420p\",\n    fps=16,\n    quality=5,\n    bitrate=None,\n    codec=None,\n    macro_block_size=16,\n    ffmpeg_log_level=\"warning\",\n    ffmpeg_timeout=None,\n    input_params=None,\n    output_params=None,\n    audio_path=None,\n    audio_codec=None,\n):\n    \"\"\"\n    Create a generator to write frames (bytes objects) into a video file.\n\n    The frames are written by using the generator's `send()` method. Frames\n    can be anything that can be written to a file. Typically these are\n    bytes objects, but c-contiguous Numpy arrays also work.\n\n    Example:\n\n        gen = write_frames(path, size)\n        gen.send(None)  # seed the generator\n        for frame in frames:\n            gen.send(frame)\n        gen.close()  # don't forget this\n\n    Parameters:\n        path (str): the filename to write to.\n        size (tuple): the width and height of the frames.\n        pix_fmt_in (str): the pixel format of incoming frames.\n            E.g. \"gray\", \"gray8a\", \"rgb24\", or \"rgba\". Default \"rgb24\".\n        pix_fmt_out (str): the pixel format to store frames. Default yuv420p\".\n        fps (float): The frames per second. Default 16.\n        quality (float): A measure for quality between 0 and 10. Default 5.\n            Ignored if bitrate is given.\n        bitrate (str): The bitrate, e.g. \"192k\". The defaults are pretty good.\n        codec (str): The codec. Default \"libx264\" for .mp4 (if available from\n            the ffmpeg executable) or \"msmpeg4\" for .wmv.\n        macro_block_size (int): You probably want to align the size of frames\n            to this value to avoid image resizing. Default 16. Can be set\n            to 1 to avoid block alignment, though this is not recommended.\n        ffmpeg_log_level (str): The ffmpeg logging level. Default \"warning\".\n        ffmpeg_timeout (float): Timeout in seconds to wait for ffmpeg process\n            to finish. Value of 0 or None will wait forever (default). The time that\n            ffmpeg needs depends on CPU speed, compression, and frame size.\n        input_params (list): Additional ffmpeg input command line parameters.\n        output_params (list): Additional ffmpeg output command line parameters.\n        audio_path (str): A input file path for encoding with an audio stream.\n            Default None, no audio.\n        audio_codec (str): The audio codec to use if audio_path is provided.\n            \"copy\" will try to use audio_path's audio codec without re-encoding.\n            Default None, but some formats must have certain codecs specified.\n    \"\"\"\n```\n\n```py\ndef count_frames_and_secs(path):\n    \"\"\"\n    Get the number of frames and number of seconds for the given video\n    file. Note that this operation can be quite slow for large files.\n\n    Disclaimer: I've seen this produce different results from actually reading\n    the frames with older versions of ffmpeg (2.x). Therefore I cannot say\n    with 100% certainty that the returned values are always exact.\n    \"\"\"\n```\n\n```py\ndef get_ffmpeg_exe():\n    \"\"\"\n    Get the ffmpeg executable file. This can be the binary defined by\n    the IMAGEIO_FFMPEG_EXE environment variable, the binary distributed\n    with imageio-ffmpeg, an ffmpeg binary installed with conda, or the\n    system ffmpeg (in that order). A RuntimeError is raised if no valid\n    ffmpeg could be found.\n    \"\"\"\n```\n\n```py\ndef get_ffmpeg_version():\n    \"\"\"\n    Get the version of the used ffmpeg executable (as a string).\n    \"\"\"\n```\n\n","funding_links":["https://github.com/sponsors/imageio","https://tidelift.com/funding/github/pypi/imageio-ffmpeg","https://tidelift.com/subscription/pkg/pypi-imageio-ffmpeg?utm_source=pypi-imageio-ffmpeg\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo","https://tidelift.com/security"],"categories":["HarmonyOS","Build Tools, Deployment \u0026 Utility Libraries"],"sub_categories":["Windows Manager","API Libraries \u0026 SDKs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimageio%2Fimageio-ffmpeg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimageio%2Fimageio-ffmpeg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimageio%2Fimageio-ffmpeg/lists"}