deFFcode

Performant ⚡️ Pythonic FFmpeg Decoder with easy to adapt flexible API 🐍.

deffcode is a Performant and Robust FFmpeg Pythonic Wrapper that aimed at decoding any stream that you throw at it. Requiring minimal efforts, deffcode provides an easy-to-adapt flexible API to read a wide range of streams, and can ingest video using any decoder(even hardware ones) into any pixel format ffmpeg supports. It also provides pin-point accurate seeking for extracting only a specific part of your input as required.

It is cross-platform, runs on Python 3.7+, and is easy to install.

Examples

Basic Example

# import the necessary packages
from deffcode import FFdecoder

# initialize and formulate the decoder
decoder = FFdecoder("foo.mp4").formulate()

# grab the RGB24(default) frame from 
# the decoder(generator)
for frame in decoder.generateFrame():
	print(frame.shape)

# terminate the decoder
decoder.terminate()

The output:

(720, 1280, 3)
(720, 1280, 3)
     ...
     ...
     ...
(720, 1280, 3)

Basic OpenCV Example

# import the necessary packages
from deffcode import FFdecoder
import cv2

# initialize and formulate the decoder for BGR24 output
decoder = FFdecoder("foo.mp4", frame_format="bgr24").formulate()

# loop over frames
while True:
    # grab the BGR24 frame from the decoder
    frame = next(decoder.generateFrame(), None)

    # check if frame is None
    if frame is None:
        break
    
    # Show output window
    cv2.imshow("Output", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()
# terminate the decoder
decoder.terminate()

Basic PIL Example

# import the necessary packages
from deffcode import FFdecoder
from PIL import Image

# define the FFmpeg parameter to seek 
# to 00:00:01 in time and get one single frame
extraparams = {"-ss": "00:00:01", "-frames:v":1}

# initialize and formulate the decode
decoder = FFdecoder("foo.mp4", **extraparams).formulate()

# grab the RGB24(default) frame from the decoder
frame = next(decoder.generateFrame(), None)

# check if frame is None
if not(frame is None)
    # Convert and Show output window
    im = Image.fromarray(frame)
    im.show()

# terminate the decoder
decoder.terminate()

Basic Matplotlib Example

# import the necessary packages
from deffcode import FFdecoder
import matplotlib.pyplot as plt

# define the FFmpeg parameter to seek 
# to 00:00:02.01 in time and get one single frame
extraparams = {"-ss": "00:00:02.01", "-frames:v":1}

# initialize and formulate the decode for Grayscale output
decoder = FFdecoder("foo.mp4", frame_format="gray", **extraparams).formulate()

# grab single Grayscale frame from the decoder
frame = next(decoder.generateFrame(), None)

# Show output window
plt.imshow(frame, cmap='gray', vmin=0, vmax=255)
plt.show()

# terminate the decoder
decoder.terminate()

Dependencies

Minimal requirements:

• Python 3.7+
• FFmpeg (See this for its installation)
• NumPy >=1.20.0
• requests
• colorlog
• tqdm

:bulb: These requirements are installed automatically(except FFmpeg).

Installation

# Install latest stable release
pip install -U deffcode

And if you prefer to install deffcode directly from the repository:

# Install latest stable release
pip install git+git://github.com/abhiTronix/deffcode@master#egg=deffcode

Or you can also download its wheel (.whl) package from our repository's releases section, and thereby can be installed as follows:

# Install latest stable release
pip install deffcode-0.1.0-py3-none-any.whl

deffcode is Apache 2.0 Licensed code.
Designed & crafted with care.
⭐️