# `pyffstream` A Python library to ease processing of video frames. `pyffstream` is mostly a wrapper around external [FFmpeg][] processes (via [`ffmpeg-python`][]) intended to be used with [OpenCV][]. [FFmpeg]: https://ffmpeg.org [`ffmpeg-python`]: https://github.com/kkroening/ffmpeg-python [OpenCV]: https://opencv.org ## Usage `pyffstream` provides your application with a command line interface (CLI) and handles reading and writing video files (with the original audio intact), filtering the frames through a callback that you define. The API consists mainly of the single function ```python run(description, process, init=None, args_pre=None, args_post=None) ``` that takes the application description to present in the CLI and some callbacks, all but one being optional: - `process(args, state, frame, frame_num)`: Takes: - `args`: [`argparse.Namespace`][] containing parsed command line arguments. - `state`: arbitrary object returned by `init` (see below). - `frame`: [`numpy.array`][] with shape `(args.working_width, args.working_height, 3)` containing RGB data to be processed. - `frame_num`: integer in the range [`args.frame_start`, `args.frame_end`) representing the number of the current frame. Returns: - `output_frame`: [`numpy.array`][] with shape `(args.output_width, args.output_height, 3)` containing RGB output. - `debug_frame`: [`numpy.array`][] with shape `(args.working_width, args.working_height, 3)` containing RGB debug output. - `init(args)`: Takes: - `args`: [`argparse.Namespace`][] containing parsed command line arguments. Returns: - `state`: arbitrary object passed to `process` (see above). - `args_pre(parser)`, `args_post(parser)`: Takes: - `args`: [`argparse.ArgumentParser`][] before (for `args_pre`) or after (for `args_post`) being filled with `pyffstream` arguments. Returns nothing. A number of hepler functions are also supplied: - `resize(image, width, height, resample)`: wrapper around [`PIL.Image.resize`][]. - `text(image, text, x, y, thickness, font=cv2.FONT_HERSHEY_SIMPLEX)`: wrapper around [`cv2.putText`][] that automatically adjusts text placement and scaling. - `fix_rect(args, x, y, w, h)`: forces a rectangle to aspect ratio `args.output_aspect` and to be inside `(0, 0, args.working_width, args.working_height)`. [`argparse.Namespace`]: https://docs.python.org/3/library/argparse.html#argparse.Namespace [`argparse.ArgumentParser`]: https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser [`numpy.array`]: https://numpy.org/doc/stable/reference/generated/numpy.array.html [`PIL.Image.resize`]: https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.resize [`cv2.putText`]: https://docs.opencv.org/master/d6/d6e/group__imgproc__draw.html#ga5126f47f883d730f633d74f07456c576 ### Examples Projects using `pyffstream`: - [`autozoom`][]: Automatically zoom in on video content of interest. [`autozoom`]: https://git.rcrnstn.net/rcrnstn/autozoom ## Installation ### With `pip` ```sh python3 -m pip install git+https://git.rcrnstn.net/rcrnstn/pyffstream ``` ### In `setuptools` `setup.py` ```python from setuptools import setup setup( # ... install_requires=[ 'pyffstream @ git+https://git.rcrnstn.net/rcrnstn/pyffstream', ], # ... ) ``` ## License Licensed under the [ISC license][], see the [`LICENSE`](LICENSE) file. [ISC license]: https://en.wikipedia.org/wiki/ISC_license