### Standard `deffcode` Installation from Source

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Clones the `deffcode` repository and installs it using pip. This is the general method for installing the stable version of the project directly from its source.

```sh
# clone the repository and get inside
git clone https://github.com/abhiTronix/deffcode.git && cd deffcode

# Install it
pip install -U .
```

--------------------------------

### Install DeFFcode using pip (Recommended)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Command to install the latest stable release of the DeFFcode library using the pip package manager. This is the recommended and easiest option for getting DeFFcode installed.

```Shell
# Install latest stable release
pip install -U deffcode
```

--------------------------------

### Install DeFFcode from a local wheel file

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Command to install DeFFcode from a downloaded `.whl` package file. This method is useful for installing specific versions or for offline installations.

```Shell
# Install latest release
pip install deffcode-0.2.0-py3-none-any.whl
```

--------------------------------

### Install `deffcode` Development Branch from Source

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Clones the `deffcode` repository, checks out the `dev` beta branch, and installs it using pip. This branch may be unstable and is intended for trying latest work-in-progress enhancements or bug-fixes.

```sh
# clone the repository and get inside
git clone https://github.com/abhiTronix/deffcode.git && cd deffcode

# checkout the dev beta branch
git checkout dev

# Install it
pip install -U .
```

--------------------------------

### Install pip using get-pip.py script

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Instructions to install pip using the get-pip.py script, applicable for both Linux/MacOS and Windows systems. This method is a fallback if pip is not already present on the system.

```Shell
python get-pip.py
```

```Shell
py get-pip.py
```

--------------------------------

### Install `deffcode` on Windows with User Privileges

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Installs the `deffcode` package into the user's home directory on Windows when administrative privileges are not available, using the `--user` flag with `pip install`.

```sh
# Install latest beta branch
python -m pip install --upgrade --user .
```

--------------------------------

### Install `deffcode` on Windows using `python -m pip`

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Provides a solution for Windows users where direct `pip` commands might not work, by prefacing with `python -m` for installing the latest beta branch.

```sh
# Install latest beta branch
python -m pip install -U .
```

--------------------------------

### Install VidGear Core Library

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-hw-acceleration.md

Installs the `vidgear` library with its core functionalities, which is essential for lossless encoding of video frames into files or streams. This installation ensures all necessary components for VidGear's core operations are available.

```sh
pip install vidgear[core]
```

--------------------------------

### Complete FFdecoder Initialization Example

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-live-feed-devices.md

A comprehensive example demonstrating the import of necessary packages (`FFdecoder`, `cv2`) and the initialization of the decoder using a specified video device path for BGR24 output.

```python
# import the necessary packages
from deffcode import FFdecoder
import cv2

# initialize and formulate the decoder with "/dev/video0" source for BGR24 output
decoder = FFdecoder("/dev/video0", source_demuxer="v4l2", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Install `deffcode` on Windows using `py` alias

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Installs the `deffcode` package using the `py` alias for Python, typically used on Windows, with the `--user` flag for user-specific installation.

```sh
# Install latest beta branch
py -m pip install --upgrade --user .
```

--------------------------------

### DeFFcode API Parameters for FFmpeg Configuration

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/ffmpeg_install.md

This section outlines essential parameters within DeFFcode APIs that control FFmpeg binary detection, installation, and debugging. It includes parameters for specifying custom FFmpeg paths, enabling verbose output, and managing download locations for auto-installation.

```APIDOC
DeFFcode API Parameters:

1. custom_ffmpeg:
   Type: str
   Description: Path to the folder containing FFmpeg executables (e.g., 'ffmpeg/bin') or the path of the 'ffmpeg' executable itself.
   Usage: Used for manual configuration of FFmpeg binaries. If not provided, DeFFcode attempts auto-detection (Linux) or auto-installation (Windows).
   Note: If binaries are not found at the specified path, a RuntimeError will be thrown.

2. verbose:
   Type: bool
   Default: False
   Description: Enables verbose logging for debugging the FFmpeg validation process.
   Usage: Set to 'True' to get detailed output during FFmpeg detection and validation.

3. -ffmpeg_download_path (Sourcer API exclusive parameter):
   Type: str
   Description: Custom save path for auto-downloading FFmpeg Static Binaries on Windows.
   Usage: This parameter is exclusive to the Sourcer API. It can also be passed to the FFdecoder API via the '-custom_sourcer_params' attribute within its 'ffparams' dictionary parameter.
```

--------------------------------

### Decode Sequential Image Sequence with FFdecoder

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This snippet demonstrates decoding sequential image sequences (e.g., `img%03d.png`) using FFdecoder. It includes an example of starting from a specific image number using the `-start_number` FFmpeg parameter, passed via `ffparams`.

```python
# define `-start_number` such as `5`
ffparams = {"-ffprefixes":["-start_number", "5"]}

# initialize and formulate the decoder with define parameters
decoder = FFdecoder('img%03d.png', verbose=True, **ffparams).formulate()
```

```python
# initialize and formulate the decoder
decoder = FFdecoder('img%03d.png').formulate()
```

--------------------------------

### Install DeFFcode with pip on Windows

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Specific commands for installing the latest stable release of DeFFcode on Windows. These commands address common Windows-specific issues, such as needing to preface Python commands with `python -m` or using the `--user` flag for permission errors.

```Shell
# Install latest stable release
python -m pip install -U deffcode
```

```Shell
# Install latest stable release
python -m pip install --upgrade --user deffcode
```

```Shell
# Install latest stable release
py -m pip install --upgrade --user deffcode
```

--------------------------------

### Decoding and Processing Video with FFdecoder and OpenCV

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-hw-acceleration.md

This comprehensive example illustrates the end-to-end process of decoding a video file (`foo.mp4`) using `FFdecoder`, applying custom FFmpeg parameters for hardware acceleration, scaling, cropping, and format conversion. It then retrieves video metadata, initializes an OpenCV `VideoWriter`, processes each decoded frame (converting from NV12 to BGR), and writes it to an output AVI file. Finally, it ensures proper termination of the decoder and writer.

```python
# define suitable FFmpeg parameter
ffparams = {
    "-vcodec": None,  # skip source decoder and let FFmpeg chose
    "-enforce_cv_patch": True, # enable OpenCV patch for YUV(NV12) frames
    "-ffprefixes": [
        "-vsync",
        "0",  # prevent duplicate frames
        "-hwaccel",
        "cuda",  # accelerator
        "-hwaccel_output_format",
        "cuda"  # output accelerator
    ],
    "-custom_resolution": "null",  # discard source `-custom_resolution`
    "-framerate": "null",  # discard source `-framerate`
    "-vf": "scale_cuda=640:360," # scale to 640x360 in GPU memory
    + "crop=80:60:200:100," # crop a 80×60 section from position (200, 100) in GPU memory
    + "hwdownload,"  # download hardware frames to system memory
    + "format=nv12"  # convert downloaded frames to NV12 pixel format
}

# initialize and formulate the decoder with `foo.mp4` source
decoder = FFdecoder(
    "foo.mp4",
    frame_format="null",  # discard source frame pixel format
    verbose = False, # to avoid too much clutter
    **ffparams # apply various params and custom filters
).formulate()

# retrieve JSON Metadata and convert it to dict
metadata_dict = json.loads(decoder.metadata)

# prepare OpenCV parameters
FOURCC = cv2.VideoWriter_fourcc("M", "J", "P", "G")
FRAMERATE = metadata_dict["output_framerate"]
FRAMESIZE = tuple(metadata_dict["output_frames_resolution"])

# Define writer with parameters and suitable output filename for e.g. `output_foo_gray.avi`
writer = cv2.VideoWriter("output_foo.avi", FOURCC, FRAMERATE, FRAMESIZE)

# grab the NV12 frames from the decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # convert it to `BGR` pixel format,
    # since write() method only accepts `BGR` frames
    frame = cv2.cvtColor(frame, cv2.COLOR_YUV2BGR_NV12)

    # {do something with the BGR frame here}

    # writing BGR frame to writer
    writer.write(frame)

# close output window
cv2.destroyAllWindows()

# terminate the decoder
decoder.terminate()

# safely close writer
writer.close()
```

--------------------------------

### Install OpenCV Python Package

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/transcode-live-frames-simplegraphs.md

This command installs the `opencv-python` package, which is required for previewing and encoding video frames in the recipes discussed. It can be installed directly via pip.

```Shell
pip install opencv-python
```

--------------------------------

### Initialize Sourcer with Camera Device Index

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

Provides an example of initializing the `Sourcer` API with a camera device index (e.g., `"0"`) as the input source. For successful camera device capturing, the system must have appropriate FFmpeg binaries supporting platform-specific demuxers (`dshow` for Windows, `video4linux2` for Linux, `avfoundation` for Mac OS) and relevant video drivers installed. The `source` parameter value MUST be any Camera Device index (integer or string of integer type), and the `source_demuxer` parameter value MUST be either `None` or `"auto"`.

```Python
# initialize the sourcer with "0" index source and probe it
sourcer = Sourcer("0", verbose=True).probe_stream()
```

--------------------------------

### Install OpenCV Python Library

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-live-virtual-sources.md

This shell command installs the `opencv-python` package using pip, which is a required dependency for previewing video frames in DeFFcode recipes. Users should ensure they do not mix pip and source installations.

```sh
pip install opencv-python
```

--------------------------------

### Install VidGear Core Package

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/transcode-live-frames.md

This command installs the `vidgear[core]` package using pip, which is required for lossless encoding of video frames into files or streams.

```sh
pip install vidgear[core]
```

--------------------------------

### Install Python Dependencies for DeFFcode Testing

Source: https://github.com/abhitronix/deffcode/blob/master/docs/contribution/PR.md

Instructions to install necessary Python libraries like OpenCV, flake8, black, pytest, and vidgear[core] required for testing DeFFcode. These dependencies are installed via pip.

```sh
pip install opencv-python

pip install --upgrade flake8 black pytest vidgear[core]
```

--------------------------------

### Capture Linux Screen using Sourcer API with x11grab

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

This example demonstrates how to capture an X11 display on Linux using the `deffcode` Sourcer API. It specifies the display as ":0.0" and uses the `x11grab` demuxer, which is suitable for probing and recording the Linux desktop.

```python
# initialize the sourcer with ":0.0" desktop source and probe it
sourcer = Sourcer(":0.0", source_demuxer="x11grab", verbose=True).probe_stream()
```

--------------------------------

### Initialize FFdecoder for Camera Device by Index

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

Shows a basic initialization of the `FFdecoder` API to capture from a camera device using its 0-indexed integer identifier. The example configures the output frame format to BGR24 and enables verbose logging.

```python
# initialize and formulate the decoder with "0" index source for BGR24 output
decoder = FFdecoder("0", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Initialize Sourcer API with Windows DShow Camera

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

This example shows how to initialize the `deffcode` Sourcer API to connect to a specific camera device on Windows, such as a "USB2.0 Camera", using the `dshow` demuxer. This allows for probing and capturing from the specified camera.

```python
# initialize the sourcer with "USB2.0 Camera" source 
sourcer = Sourcer("USB2.0 Camera", source_demuxer="dshow", verbose=True).probe_stream()
```

--------------------------------

### Capture Entire Desktop with FFdecoder (X11)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This Python example demonstrates how to capture the entire desktop using the `FFdecoder` API on Linux with the `x11grab` demuxer. It initializes the decoder with a specified framerate and outputs frames in BGR24 format.

```python
# define framerate
ffparams = {"-framerate": "30"}

# initialize and formulate the decoder with ":0.0" desktop source for BGR24 output
decoder = FFdecoder(":0.0", source_demuxer="x11grab", frame_format="bgr24", verbose=True, **ffparams).formulate()
```

--------------------------------

### Install Imageio Library

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/save-keyframe-image.md

Imageio is a library for reading and writing a wide range of image, video, scientific, and volumetric data formats, also required for saving frames as images. This command installs the `imageio` package via pip.

```sh
pip install imageio
```

--------------------------------

### Install OpenCV Python Package

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/transcode-live-frames.md

This command installs the `opencv-python` package using pip, which is required for previewing and encoding video frames. Other binaries like `opencv-contrib-python` or headless versions can also be installed similarly.

```sh
pip install opencv-python
```

--------------------------------

### API Reference: validate_ffmpeg

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffhelper.md

API documentation for the `validate_ffmpeg` method within the `deffcode.ffhelper` module, used to validate the installation of FFmpeg binaries.

```APIDOC
deffcode.ffhelper.validate_ffmpeg
```

--------------------------------

### Install OpenCV Python Library

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/decode-network-streams.md

This command installs the `opencv-python` package using pip, which is a crucial dependency for previewing video frames in DeFFcode applications. Ensure you have pip installed and a stable internet connection.

```sh
pip install opencv-python
```

--------------------------------

### Capture Entire Desktop with FFdecoder (macOS)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This Python example shows how to capture the entire desktop on macOS using the `FFdecoder` API with the `avfoundation` demuxer. It initializes the decoder using the identified screen index and outputs frames in BGR24 format.

```python
# initialize and formulate the decoder with `0:` index desktop screen for BGR24 output
decoder = FFdecoder("0:", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Install OpenCV Python Dependency

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-live-feed-devices.md

This command installs the `opencv-python` package using pip, which is a required additional Python dependency for previewing video frames in DeFFcode recipes.

```Shell
pip install opencv-python
```

--------------------------------

### Install OpenCV Python Dependency

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/decode-camera-devices.md

Install the `opencv-python` package using pip, which is required for previewing video frames when working with DeFFcode APIs. This package provides the main OpenCV modules.

```Shell
pip install opencv-python
```

--------------------------------

### Initialize FFdecoder for Camera Device by Name on Windows

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

Demonstrates how to initialize the `FFdecoder` API to capture from a specific camera device by its name on Windows. This example utilizes the `dshow` source demuxer and configures the output frame format to BGR24 with verbose logging.

```python
# initialize and formulate the decoder with "USB2.0 Camera" source for BGR24 output
decoder = FFdecoder("USB2.0 Camera", source_demuxer="dshow", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Install OpenCV for Python

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/decode-video-files.md

This command installs the `opencv-python` package, which is a required Python dependency for previewing video frames in DeFFcode recipes. Other OpenCV binaries like `opencv-contrib-python` or headless versions can also be installed similarly.

```sh
pip install opencv-python
```

--------------------------------

### Install VidGear Core Dependency

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-live-frames-complexgraphs.md

Installs the `vidgear[core]` package, necessary for lossless encoding of video frames into files or streams using DeFFcode APIs. This command uses pip to install VidGear with its core functionalities.

```sh
pip install vidgear[core]
```

--------------------------------

### GPU-accelerated Decoding and Encoding to NV12 Frames (Python)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-hw-acceleration.md

This Python example illustrates GPU-accelerated video decoding using `FFdecoder` with Nvidia's CUDA. It performs scaling and cropping in GPU memory and downloads frames directly as NV12. The NV12 frames are then encoded directly with `WriteGear` using H.264 NVENC, showcasing an optimized workflow for direct NV12 processing without intermediate BGR conversion.

```Python
# import the necessary packages
from deffcode import FFdecoder
from vidgear.gears import WriteGear
import json
import cv2

# define suitable FFmpeg parameter
ffparams = {
    "-vcodec": None,  # skip source decoder and let FFmpeg chose
    "-ffprefixes": [
        "-vsync",
        "0",  # prevent duplicate frames
        "-hwaccel",
        "cuda",  # accelerator
        "-hwaccel_output_format",
        "cuda",  # output accelerator
    ],
    "-custom_resolution": "null",  # discard source `-custom_resolution`
    "-framerate": "null",  # discard source `-framerate`
    "-vf": "scale_cuda=640:360,"  # scale to 640x360 in GPU memory
    + "crop=80:60:200:100,"  # crop a 80×60 section from position (200, 100) in GPU memory
    + "hwdownload,"  # download hardware frames to system memory

```

--------------------------------

### Example DeFFcode Metadata JSON Output

Source: https://github.com/abhitronix/deffcode/blob/master/README.md

This JSON snippet illustrates the typical structure and content of metadata returned by DeFFcode's `sourcer.retrieve_metadata` function, as seen on a Windows machine. It includes details like FFmpeg path, source URL, video resolution, framerate, and other media properties.

```JSON
{
  "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
}
```

--------------------------------

### Generate and Decode Test Source Pattern with FFdecoder and OpenCV

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-live-virtual-sources.md

This example illustrates generating and decoding a `testsrc` video pattern for 10 seconds using `FFdecoder` with `lavfi` input. It configures the decoder for `1280x720` resolution and `30` framerate, and displays the decoded `BGR24` frames in real-time using OpenCV.

```python
# import the necessary packages
from deffcode import FFdecoder
import cv2

# define parameters
ffparams = {
    "-ffprefixes": ["-t", "10"],  # playback time of 10 seconds
}

# initialize and formulate the decoder with "testsrc" source of
# `1280x720` frame size and `30` framerate for BGR24 output
decoder = FFdecoder(
    "testsrc=size=1280x720:rate=30",
    source_demuxer="lavfi",
    frame_format="bgr24",
    **ffparams
).formulate()

# grab the BGR24 frame from the decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # {do something with the frame here}

    # 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()
```

--------------------------------

### Capture Entire Desktop on macOS with FFdecoder

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-live-feed-devices.md

Initialize `FFdecoder` to capture the entire desktop on macOS using the `avfoundation` demuxer. The example specifies the screen index '0:' and sets the output frame format to BGR24.

```python
# initialize and formulate the decoder with `0:` index desktop screen for BGR24 output
decoder = FFdecoder("0:", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Capture Entire Desktop on Linux with FFdecoder (X11grab)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-live-feed-devices.md

This Python example demonstrates capturing all displays as a single contiguous desktop on Linux using `FFdecoder` with the `x11grab` demuxer. It includes setting a framerate, processing frames with OpenCV, and proper resource termination.

```python
# import the necessary packages
from deffcode import FFdecoder
import cv2

# define framerate
ffparams = {"-framerate": "30"}

# initialize and formulate the decoder with ":0.0" desktop source for BGR24 output
decoder = FFdecoder(":0.0", source_demuxer="x11grab", frame_format="bgr24", verbose=True, **ffparams).formulate()

# grab the BGR24 frames from decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # {do something with the frame here}
    
    # 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()
```

--------------------------------

### Initialize FFdecoder for Device Name Capture (macOS)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This example shows how to capture video from a device by specifying its name or an abbreviation of its name, such as 'Integrated' for 'Integrated iSight-camera'. It uses the `avfoundation` demuxer for macOS, outputs BGR24 frames, and enables verbose logging.

```python
# initialize and formulate the decoder with "Integrated iSight-camera" source for BGR24 output
decoder = FFdecoder("Integrated", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### FFdecoder Camera Device Indexing Examples

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

Demonstrates how to use positive and negative integer or string indexes for camera devices with `FFdecoder.formulate()`. Camera device indexes are 0-indexed and can be negative to index from the end. Out-of-index values will raise a `ValueError`.

```python
FFdecoder("0").formulate()
```

```python
FFdecoder("-3").formulate()
```

```python
FFdecoder("1").formulate()
```

```python
FFdecoder("-2").formulate()
```

```python
FFdecoder("2").formulate()
```

```python
FFdecoder("-1").formulate()
```

--------------------------------

### Initialize Sourcer API with Lavfi Virtual Source

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

This Python example shows how to use the Sourcer API to generate and probe a virtual video source, specifically a Mandelbrot graph. It utilizes the `lavfi` demuxer, allowing specification of frame size and rate directly within the source string.

```python
# initialize the sourcer with "mandelbrot" source of
# `1280x720` frame size and `30` framerate and probe it
sourcer = Sourcer(
    "mandelbrot=size=1280x720:rate=30",
    source_demuxer="lavfi",
    frame_format="bgr24",
).probe_stream()
```

--------------------------------

### Check DeFFcode Library Version

Source: https://github.com/abhitronix/deffcode/blob/master/docs/contribution/issue.md

This command allows users to quickly retrieve the installed version of the DeFFcode library. Providing the exact version is crucial for debugging and reporting issues, as it helps maintainers reproduce bugs and understand the user's environment.

```Python
python -c "import deffcode; print(deffcode.__version__)"
```

--------------------------------

### Clone and Prepare Git Branch for DeFFcode Pull Request

Source: https://github.com/abhitronix/deffcode/blob/master/docs/contribution/PR.md

This snippet provides commands to clone a forked DeFFcode repository, pull the latest updates from the master branch, and create a new sub-branch for working on a pull request. It ensures the local repository is up-to-date before starting development.

```sh
git clone https://github.com/{YOUR USERNAME}/DeFFcode.git && cd DeFFcode

git pull

git checkout -b subbranch_of_master
```

--------------------------------

### Initialize FFdecoder for Specific USB Camera Capture (Windows)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This example demonstrates how to initialize FFdecoder to capture from a specific USB camera on Windows, identified by its full name like 'USB2.0 Camera'. It utilizes the `dshow` demuxer, sets the frame format to BGR24, and enables verbose output.

```python
# initialize and formulate the decoder with "USB2.0 Camera" source for BGR24 output
decoder = FFdecoder("USB2.0 Camera", source_demuxer="dshow", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Transcoding RGB Frames to Video using OpenCV VideoWriter

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/transcode-live-frames.md

This example illustrates how to decode RGB24 pixel format frames using DeFFcode's FFdecoder and then encode them with OpenCV's `cv2.VideoWriter()`. Since OpenCV's `cv2.write()` method expects BGR format, the RGB frames are converted to BGR using `cv2.cvtColor` before being written. Metadata retrieval and writer setup are similar to the BGR example.

```Python
# import the necessary packages
from deffcode import FFdecoder
import json, cv2

# initialize and formulate the decoder for RGB24 pixel format output
decoder = FFdecoder("foo.mp4").formulate()

# retrieve JSON Metadata and convert it to dict
metadata_dict = json.loads(decoder.metadata)

# prepare OpenCV parameters
FOURCC = cv2.VideoWriter_fourcc("M", "J", "P", "G")
FRAMERATE = metadata_dict["output_framerate"]
FRAMESIZE = tuple(metadata_dict["output_frames_resolution"])

# Define writer with parameters and suitable output filename for e.g. `output_foo.avi`
writer = cv2.VideoWriter("output_foo.avi", FOURCC, FRAMERATE, FRAMESIZE)

# grab the RGB24 frame from the decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # {do something with the frame here}

    # converting RGB24 to BGR24 frame
    frame_bgr = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)

    # writing BGR24 frame to writer
    writer.write(frame_bgr)

# terminate the decoder
decoder.terminate()

# safely close writer
writer.release()
```

--------------------------------

### Initialize FFdecoder for Desktop Region Capture (Windows)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This example demonstrates capturing a specific region of the desktop on Windows using `gdigrab`. It sets a framerate, defines offsets for the capture area (10,20), specifies the frame size (640x480), and enables showing the captured region. The output is BGR24 frames with verbose logging.

```python
# define suitable parameters
ffparams = {
    "-framerate": "30", # input framerate
    "-ffprefixes": [
        "-offset_x", "10", "-offset_y", "20", # grab at position 10,20
        "-video_size", "640x480", # frame size
        "-show_region", "1" # show only region
    ]
}

# initialize and formulate the decoder with "desktop" source for BGR24 output
decoder = FFdecoder("desktop", source_demuxer="gdigrab", frame_format="bgr24", verbose=True, **ffparams).formulate()
```

--------------------------------

### Initialize FFdecoder and Override Metadata in Python

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/update-metadata.md

This Python example demonstrates how to import `FFdecoder` and `cv2`, initialize the decoder with a source file, and then prepare to override source video metadata values before the decoding pipeline is formulated. The snippet is a starting point for further metadata manipulation.

```python
# import the necessary packages
from deffcode import FFdecoder
import cv2

# initialize and formulate the decoder using suitable source
decoder = FFdecoder("foo.mp4", verbose=True)

# override source metadata values
```

--------------------------------

### Download DeFFcode Test Dataset

Source: https://github.com/abhitronix/deffcode/blob/master/docs/contribution/PR.md

Commands to download the additional dataset required for running DeFFcode tests. This involves making the `prepare_dataset.sh` script executable and then running it, with separate instructions for Linux/MacOS and Windows.

```sh
chmod +x scripts/bash/prepare_dataset.sh
./scripts/bash/prepare_dataset.sh
```

```sh
sh scripts/bash/prepare_dataset.sh
```

--------------------------------

### Specify Video Device by Name and Index in Sourcer API (Windows)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

This Python example shows how to specify a video device by its name and an arbitrary index using the Sourcer API on Windows. The `-video_device_number` parameter is passed via `sourcer_params` to select a specific device when multiple devices share a similar name.

```python
# define video_device_number as 1 (numbering start from 0)
sourcer_params = {"-ffprefixes":["-video_device_number", "1"]}

# initialize the sourcer with "Camera" source and probe it
sourcer = Sourcer("Camera", source_demuxer="dshow", verbose=True, **sourcer_params).probe_stream()
```

--------------------------------

### Install OpenCV Python Library

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-hw-acceleration.md

Installs the `opencv-python` package, which provides the main OpenCV modules. Alternative distributions like `opencv-contrib-python` or headless versions (`opencv-python-headless`, `opencv-contrib-python-headless`) can be installed similarly to include additional or server-specific functionalities.

```sh
pip install opencv-python
```

--------------------------------

### API Reference: download_ffmpeg_binaries

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffhelper.md

API documentation for the `download_ffmpeg_binaries` method within the `deffcode.ffhelper` module, specifically for downloading FFmpeg binaries on Windows.

```APIDOC
deffcode.ffhelper.download_ffmpeg_binaries
```

--------------------------------

### Initialize Sourcer with `sourcer_params`

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

Demonstrates how to initialize the Sourcer API by unpacking a dictionary of `sourcer_params`, which can include exclusive parameters like `-ffmpeg_download_path` for custom configurations.

```python
# # define suitable parameter to download at "C:/User/foo/foo1"
sourcer_params = {"-ffmpeg_download_path": "C:/User/foo/foo1"}

# initialize the sourcer
Sourcer("foo.mp4", verbose=True, **sourcer_params).probe_stream()
```

--------------------------------

### Install OpenCV Python Library

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/save-keyframe-image.md

OpenCV is required for saving video frames. This command installs the `opencv-python` package via pip. Other OpenCV binaries like `opencv-contrib-python`, `opencv-python-headless`, and `opencv-contrib-python-headless` can also be installed similarly.

```sh
pip install opencv-python
```

--------------------------------

### Capture Windows Screen using Sourcer API with gdigrab

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

This snippet illustrates how to capture the entire Windows desktop screen using the `deffcode` Sourcer API. It utilizes the `gdigrab` demuxer and allows for specifying parameters like the desired framerate for the capture. Note that `dshow` is generally unreliable for screen grabbing on Windows.

```python
# define framerate
sourcer_params = {"-framerate": "30"}

# initialize the sourcer with "desktop" source and probe it
sourcer = Sourcer("desktop", source_demuxer="gdigrab", verbose=True, **sourcer_params).probe_stream()
```

--------------------------------

### Initialize Sourcer with Filepath Input

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

Demonstrates how to initialize the `Sourcer` API with a local video file path (e.g., `/home/foo.mp4`) as the input source and then probe the stream. This is the most straightforward way to use a local video file.

```Python
# initialize the sourcer and probe it
sourcer = Sourcer('/home/foo.mp4').probe_stream()
```

--------------------------------

### Install OpenCV Python dependency

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/decode-image-sequences.md

Installs the `opencv-python` package using pip. OpenCV is a required additional Python dependency for previewing video frames in DeFFcode recipes. Users should ensure they do not install both pip and source versions together.

```sh
pip install opencv-python
```

--------------------------------

### Initialize Sourcer API with AVFoundation Device Index

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

This Python snippet demonstrates how to initialize the Sourcer API to probe a specific video input device, such as a desktop screen, using its index (e.g., '0:') and specifying `avfoundation` as the source demuxer. The `probe_stream()` method then analyzes the stream.

```python
# initialize the sourcer with `0:` index desktop screen and probe it
sourcer = Sourcer("0:", source_demuxer="avfoundation", verbose=True).probe_stream()
```

--------------------------------

### Enumerate Camera Devices with Sourcer API in Python

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/decode-camera-devices.md

This Python example demonstrates how to use the `deffcode.Sourcer` API to enumerate all probed camera devices connected to the system. It initializes a Sourcer object, then prints the enumerated devices first as a Python dictionary and subsequently as a formatted JSON string using the `json` module. Proper FFmpeg binaries and drivers are required for this functionality.

```python
# import the necessary packages
from deffcode import Sourcer
import json

# initialize and formulate the decoder
sourcer = Sourcer("0").probe_stream()

# enumerate probed devices as Dictionary object(`dict`)
print(sourcer.enumerate_devices)

# enumerate probed devices as JSON string(`json.dump`)
print(json.dumps(sourcer.enumerate_devices,indent=2))
```

--------------------------------

### GPU-accelerated Decoding and Encoding to BGR Frames (Python)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-hw-acceleration.md

This Python example demonstrates GPU-accelerated video decoding using `FFdecoder` with Nvidia's CUDA. It includes scaling and cropping frames in GPU memory, downloading them as patched NV12, converting to BGR with OpenCV's `cvtColor`, and then encoding with `WriteGear` using H.264 NVENC. It also shows how to retrieve the source framerate from `FFdecoder.metadata` for controlled encoding.

```Python
# import the necessary packages
from deffcode import FFdecoder
from vidgear.gears import WriteGear
import json
import cv2

# define suitable FFmpeg parameter
ffparams = {
    "-vcodec": None,  # skip source decoder and let FFmpeg chose
    "-enforce_cv_patch": True # enable OpenCV patch for YUV(NV12) frames
    "-ffprefixes": [
        "-vsync",
        "0",  # prevent duplicate frames
        "-hwaccel",
        "cuda",  # accelerator
        "-hwaccel_output_format",
        "cuda",  # output accelerator
    ],
    "-custom_resolution": "null",  # discard source `-custom_resolution`
    "-framerate": "null",  # discard source `-framerate`
    "-vf": "scale_cuda=640:360,"  # scale to 640x360 in GPU memory
    + "crop=80:60:200:100," # crop a 80×60 section from position (200, 100) in GPU memory
    + "hwdownload,"  # download hardware frames to system memory
    + "format=nv12",  # convert downloaded frames to NV12 pixel format
}

# initialize and formulate the decoder with `foo.mp4` source
decoder = FFdecoder(
    "foo.mp4",
    frame_format="null",  # discard source frame pixel format
    verbose = False, # to avoid too much clutter
    **ffparams # apply various params and custom filters
).formulate()

# retrieve framerate from JSON Metadata and pass it as
# `-input_framerate` parameter for controlled framerate
output_params = {
    "-input_framerate": json.loads(decoder.metadata)["output_framerate"],
    "-vcodec": "h264_nvenc", # H.264 NVENC Video-encoder

}

# Define writer with default parameters and suitable
# output filename for e.g. `output_foo.mp4`
writer = WriteGear(output="output_foo.mp4", logging=True, **output_params)

# grab the NV12 frames from the decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # convert it to `BGR` pixel format
    frame = cv2.cvtColor(frame, cv2.COLOR_YUV2BGR_NV12)

    # {do something with the BGR frame here}

    # writing BGR frame to writer
    writer.write(frame)

# close output window
cv2.destroyAllWindows()

# terminate the decoder
decoder.terminate()

# safely close writer
writer.close()
```

--------------------------------

### Install OpenCV Python for Video Processing

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-art-filtergraphs.md

This shell command installs the `opencv-python` library via pip. OpenCV is a crucial dependency for DeFFcode, enabling the previewing and encoding of video frames. Users should ensure they do not mix pip installations with source builds to avoid conflicts.

```sh
pip install opencv-python
```

--------------------------------

### Initialize FFdecoder for Entire Desktop Capture (Windows)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This snippet shows how to capture the entire desktop on Windows using the `gdigrab` demuxer. It defines a framerate of 30 FPS and configures the FFdecoder to output BGR24 frames with verbose logging.

```python
# define framerate
ffparams = {"-framerate": "30"}

# initialize and formulate the decoder with "desktop" source for BGR24 output
decoder = FFdecoder("desktop", source_demuxer="gdigrab", frame_format="bgr24", verbose=True, **ffparams).formulate()
```

--------------------------------

### Install Pillow Imaging Library

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/save-keyframe-image.md

Pillow is an Imaging Library required for saving frames as images. This command installs the `Pillow` package via pip.

```sh
pip install Pillow
```

--------------------------------

### Initialize FFdecoder for Default Device Capture (macOS)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/ffdecoder/params.md

This snippet illustrates capturing video from the default device, typically the first device listed, by using 'default' as the source. It configures the FFdecoder with `avfoundation` for macOS, BGR24 frame output, and verbose logging.

```python
# initialize and formulate the decoder with "default" source for BGR24 output
decoder = FFdecoder("default", source_demuxer="avfoundation", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Install OpenCV Python Dependency

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-hw-acceleration.md

This command installs the `opencv-python` package using pip. OpenCV is a required additional Python dependency for previewing video frames in DeFFcode recipes.

```sh
pip install opencv-python
```

--------------------------------

### Upgrade pip using ensurepip module

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Command to upgrade or install pip using Python's built-in `ensurepip` module. This module can easily manage pip in any Python environment.

```Shell
python -m ensurepip --upgrade
```

```Shell
py -m ensurepip --upgrade
```

--------------------------------

### Install Matplotlib for Visualizations

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/basic/save-keyframe-image.md

Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations, also required for saving frames as images. This command installs the `matplotlib` package via pip.

```sh
pip install matplotlib
```

--------------------------------

### Initialize FFdecoder with Video Device Path (Linux)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/decode-live-feed-devices.md

Demonstrates how to initialize the FFdecoder API by specifying the path to a video device, such as "/dev/video0", for BGR24 output. It uses `v4l2` as the source demuxer.

```python
# initialize and formulate the decoder with "/dev/video0" source for BGR24 output
decoder = FFdecoder("/dev/video0", source_demuxer="v4l2", frame_format="bgr24", verbose=True).formulate()
```

--------------------------------

### Install OpenCV Python Dependency

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-live-frames-complexgraphs.md

Installs the `opencv-python` package, which is required for previewing and encoding video frames in DeFFcode recipes. This command uses pip to fetch the official OpenCV binary.

```sh
pip install opencv-python
```

--------------------------------

### Upgrade pip using pip command

Source: https://github.com/abhitronix/deffcode/blob/master/docs/installation/index.md

Command to upgrade the pip package manager to its latest version using pip's own upgrade mechanism. This is strongly advised to avoid any undesired installation errors.

```Shell
python -m pip install pip --upgrade
```

```Shell
py -m pip install pip --upgrade
```

--------------------------------

### Run DeFFcode Unit Tests with Pytest

Source: https://github.com/abhitronix/deffcode/blob/master/docs/contribution/PR.md

Command to execute all unit tests for the DeFFcode library using pytest. The `-sv` flag provides verbose output, showing more details about test execution.

```sh
pytest -sv
```

--------------------------------

### Initialize Sourcer API with MacOS Video Device (Index or Name)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/reference/sourcer/params.md

This snippet demonstrates how to initialize the `deffcode` Sourcer API to probe a specific video device on MacOS using the `avfoundation` demuxer. It provides two methods: specifying the device by its numerical index or by its name. When using the name, abbreviations are supported.

```python
# initialize the sourcer with `1` index source and probe it
sourcer = Sourcer("1", source_demuxer="avfoundation", verbose=True).probe_stream()
```

```python
# initialize the sourcer with "Integrated iSight-camera" source 
sourcer = Sourcer("Integrated", source_demuxer="avfoundation", verbose=True).probe_stream()
```

--------------------------------

### Install VidGear Core for Lossless Video Encoding

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-art-filtergraphs.md

This shell command installs the `vidgear[core]` package using pip. VidGear is required by DeFFcode for lossless encoding of processed video frames into files or streams. This dependency is essential for advanced video output functionalities.

```sh
pip install vidgear[core]
```

--------------------------------

### Example Output of Sourcer API Metadata

Source: https://github.com/abhitronix/deffcode/blob/master/docs/index.md

This JSON snippet illustrates the typical metadata output retrieved by the Sourcer API when probing a multimedia stream. It includes details such as ffmpeg binary path, source URL, video resolution, framerate, pixel format, decoder, duration, approximate frame count, and bitrate information, indicating whether video or audio streams are present.

```JSON
{
  "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
}
```

--------------------------------

### Configuring FFdecoder to Start from a Specific Image Number

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-live-frames-complexgraphs.md

This Python snippet illustrates how to configure `FFdecoder` to begin processing an image sequence from a specific starting number. By setting the `-start_number` FFmpeg parameter within the `ffparams` dictionary, users can control the initial frame decoded from a numerically ordered image series.

```python
# define `-start_number` such as `5`
ffparams = {"-ffprefixes":["-start_number", "5"]}

# initialize and formulate the decoder with define parameters
decoder = FFdecoder('/path/to/img%03d.png', verbose=True, **ffparams).formulate()
```

--------------------------------

### Verify FFmpeg CUDA and NVDEC Support

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/transcode-hw-acceleration.md

Checks if FFmpeg is compiled with CUDA pixel formats and GPU-accelerated filters (CUDA/NPP) by inspecting its output. This ensures that hardware decoding and filtering capabilities are available.

```sh
$ ffmpeg  -hide_banner -pix_fmts | grep cuda
..H.. cuda                   0              0      0
```

```sh
$ ffmpeg  -hide_banner -filters | egrep "cuda|npp"
... bilateral_cuda    V->V       GPU accelerated bilateral filter
... chromakey_cuda    V->V       GPU accelerated chromakey filter
... colorspace_cuda   V->V       CUDA accelerated video color converter
... hwupload_cuda     V->V       Upload a system memory frame to a CUDA device.
... overlay_cuda      VV->V      Overlay one video on top of another using CUDA
... scale_cuda        V->V       GPU accelerated video resizer
... scale_npp         V->V       NVIDIA Performance Primitives video scaling and format conversion
... scale2ref_npp     VV->VV     NVIDIA Performance Primitives video scaling and format conversion to the given reference.
... sharpen_npp       V->V       NVIDIA Performance Primitives video sharpening filter.
... thumbnail_cuda    V->V       Select the most representative frame in a given sequence of consecutive frames.
... transpose_npp     V->V       NVIDIA Performance Primitives video transpose
T.. yadif_cuda        V->V       Deinterlace CUDA frames
```

--------------------------------

### Example FFdecoder Terminal Output (Windows)

Source: https://github.com/abhitronix/deffcode/blob/master/docs/recipes/advanced/update-metadata.md

This JSON snippet illustrates the typical structured output generated by FFdecoder on a Windows machine after processing a video file, showcasing various detected and derived metadata properties.

```json
{
  "ffmpeg_binary_path": "C:\\Users\\foo\\AppData\\Local\\Temp\\ffmpeg-static-win64-gpl/bin/ffmpeg.exe",
  "source": "D:\\foo.mp4",
  "source_extension": ".mp4",
  "source_video_resolution": [
    1920,
    1080
  ],
  "source_video_framerate": 29.97,
  "source_video_pixfmt": "yuv420p",
  "source_video_decoder": "h264",
  "source_duration_sec": 21.03,
  "approx_video_nframes": 630,
  "source_video_bitrate": "4937k",
  "source_audio_bitrate": "256k",
  "source_audio_samplerate": "48000 Hz",
  "source_has_video": true,
  "source_has_audio": true,
  "source_has_image_sequence": false,
  "ffdecoder_operational_mode": "Video-Only",
  "output_frames_pixfmt": "rgb24",
  "mystring": "abcd",
  "myint": 1234,
  "mylist": [
    1,
    "Rohan",
    [
      "inner_list"
    ]
  ],
  "mytuple": [
    1,
    "John",
    "inner_tuple"
  ],
  "mydict": {
    "anotherstring": "hello"
  },
  "myjson": {
    "name": "John",
    "age": 30,
    "city": "New York"
  }
}
```