Highly Adaptive - DeFFcode APIs implements a standalone highly-extensible wrapper around [FFmpeg][ffmpeg] multimedia framework. These APIs supports a wide-ranging media streams as input source such as [live USB/Virtual/IP camera feeds][capturing-and-previewing-frames-from-a-webcam], [regular multimedia files][decoding-video-files], [screen recordings][capturing-and-previewing-frames-from-your-desktop], [image sequences][decoding-image-sequences], [network URL schemes][decoding-network-streams] (such as HTTP(s), RTP/RSTP, etc.), so on and so forth.

Highly Flexible - DeFFcode APIs gains an edge over other FFmpeg Wrappers by providing complete control over the underline pipeline including access to almost any FFmpeg specification thinkable such as specifying framerate, resolution, hardware decoder(s), filtergraph(s), and pixel-format(s) that are readily supported by all well known Computer Vision libraries.

Highly Convenient - FFmpeg has a steep learning curve especially for users unfamiliar with a command line interface. DeFFcode helps users by providing similar to OpenCV, [Index based Camera Device Capturing][decoding-camera-devices-using-indexes] and the same standard OpenCV-Python (Python API for OpenCV) coding syntax for its APIs, thereby making it even easier to learn, create, and develop FFmpeg based apps in Python.

Key features of DeFFcode

Here are some key features that stand out:

• High-performance, low-overhead video frames decoding with robust error-handling.
• Flexible API with access to almost any FFmpeg specification thinkable.
• Supports a wide-range of media streams/devices/protocols as input source.
• Curated list of well-documented recipes ranging from [Basic][basic-recipes] to [Advanced][advanced-recipes] skill levels.
• Hands down the easiest [Index based Camera Device Capturing][decoding-camera-devices-using-indexes], similar to OpenCV.
• Easy to code Real-time [Simple][transcoding-live-simple-filtergraphs] & [Complex][transcoding-live-complex-filtergraphs] Filtergraphs. (Yes, You read it correctly "Real-time"!)
• Lightning fast dedicated GPU-Accelerated Video [Decoding][hardware-accelerated-video-decoding] & [Transcoding][hardware-accelerated-video-transcoding].
• Enables precise FFmpeg [Key-frame Seeking][extracting-key-frames-as-png-image] with pinpoint accuracy.
• Effortless [Metadata Extraction][extracting-video-metadata] from all streams available in the source.
• Maintains the standard easy to learn OpenCV-Python coding syntax.
• Out-of-the-box support for all prominent Computer Vision libraries.
• Cross-platform, runs on Python 3.7+, and easy to install.

Getting Started

📚 Documentation: https://abhitronix.github.io/deffcode

Installation:

If this is your first time using DeFFcode, head straight to the [Installation Notes][installation-notes] to install DeFFcode on your machine.

Recipes a.k.a Examples:

Once you have DeFFcode installed, checkout our Well-Documented [Recipes 🍱][basic-recipes] for usage examples:

Note In case you're run into any problems, consult our [Help section][help].

A. [Basic Recipes 🍰][basic-recipes]: Recipes for beginners of any skill level to get started.

_{Big Buck Bunny Reversed using Live Simple Filtergraph}

B. [Advanced Recipes 🥐][advanced-recipes]: Recipes to take your skills to the next level.

_{Live Mandelbrot pattern with a Vectorscope & two Waveforms}

API in a nutshell:

As a user, you just have to remember only two DeFFcode APIs, namely:

A. FFdecoder API

The primary function of [FFdecoder API][ffdecoder-api] is to decode 24-bit RGB video frames from the given source:

Note See [API Reference][ffdecoder-api] for more in-depth information.

# import the necessary packages
from deffcode import FFdecoder

# formulate the decoder with suitable source
decoder = FFdecoder("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4").formulate()

# grab RGB24(default) 3D frames from decoder
for frame in decoder.generateFrame():

    # lets print its shape
    print(frame.shape) # (1080, 1920, 3)

# terminate the decoder
decoder.terminate()

B. Sourcer API

The primary function of [Sourcer API][sourcer-api] is to gather metadata information from all multimedia streams available in the given source:

# import the necessary packages
from deffcode import Sourcer

# initialize and formulate the decoder using suitable source
sourcer = Sourcer("https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4").probe_stream()

# print metadata as `json.dump`
print(sourcer.retrieve_metadata(pretty_json=True))

{
  "ffmpeg_binary_path": "C:\\Users\\foo\\AppData\\Local\\Temp\\ffmpeg-static-win64-gpl/bin/ffmpeg.exe",
  "source": "https://abhitronix.github.io/html/Big_Buck_Bunny_1080_10s_1MB.mp4",
  "source_extension": ".mp4",
  "source_video_resolution": [1920, 1080],
  "source_video_framerate": 60.0,
  "source_video_pixfmt": "yuv420p",
  "source_video_decoder": "h264",
  "source_duration_sec": 10.0,
  "approx_video_nframes": 600,
  "source_video_bitrate": "832k",
  "source_audio_bitrate": "",
  "source_audio_samplerate": "",
  "source_has_video": true,
  "source_has_audio": false,
  "source_has_image_sequence": false
}

Contributions

We're happy to meet new contributors💗

We welcome your contributions to help us improve and extend this project. If you want to get involved with DeFFcode development, checkout the [Contribution Guidelines ▶️][contribute]

We're offering support for DeFFcode on [Gitter Community Channel][gitter]. Come and join the conversation over there!

Donations

DeFFcode is free and open source and will always remain so. ❤️

It is something I am doing with my own free time. But so much more needs to be done, and I need your help to do this. For just the price of a cup of coffee, you can make a difference 🙂

Citation

Here is a Bibtex entry you can use to cite this project in a publication:

@software{deffcode,
  author       = {Abhishek Thakur},
  title        = {abhiTronix/deffcode: v0.2.5},
  month        = jan,
  year         = 2023,
  publisher    = {Zenodo},
  version      = {v0.2.5},
  doi          = {10.5281/zenodo.7523792},
  url          = {https://doi.org/10.5281/zenodo.7523792}
}

Copyright

Copyright © abhiTronix 2021

This library is released under the [Apache 2.0 License][license].

[appveyor]: