Skip to content

FFGear API Parameters

 

source

FFGear API will throw RuntimeError if source provided is invalid or unreadable.

This parameter defines the source for the input stream. FFGear passes it directly to FFdecoder API.

Data-Type: Any

Default Value: None

Its valid input can be one of the following:

  • Index (integer or string of integer): Valid index of the connected camera device, e.g. 0, 1, "0", "-1", etc.:

    FFGear(source=0)

  • Filepath (string): Valid path of the video file, for e.g. "myvideo.mp4":

    FFGear(source="myvideo.mp4")

  • Streaming Service URL (string): Valid streaming URL when stream_mode=True is enabled:

    FFGear(source="https://youtu.be/bvetuLwJIkA", stream_mode=True)

  • Network Stream Address (string): Valid http(s), rtsp, rtp, rtmp, etc. network address:

    FFGear(source="rtsp://192.168.1.10:554/stream")

  • Image Sequence (string with glob pattern): Valid image sequence glob, e.g. "frames/%04d.jpg":

    FFGear(source="frames/%04d.jpg")

 

stream_mode

This parameter enables Stream Mode for handling streaming URLs via the yt_dlp backend. When True, FFGear will interpret the given source as a streaming service URL.

Data-Type: Boolean

Default Value: False

Usage:

Supported Streaming Websites

The complete list of all supported Streaming Websites URLs can be found here ➶

FFGear(source="https://youtu.be/bvetuLwJIkA", stream_mode=True)

Its complete usage example is given here ➶.

 

source_demuxer

This parameter specifies the FFmpeg demuxer for the source, required when the source type cannot be auto-detected. Common values include "v4l2" (Linux), "dshow" (Windows), "avfoundation" (macOS).

Data-Type: String or None

Default Value: None

Usage:

# Linux: use v4l2 demuxer for webcam device
FFGear(source="/dev/video0", source_demuxer="v4l2")

Platform-specific demuxers

Platform Demuxer
Windows dshow
Linux v4l2 (or video4linux2)
macOS avfoundation

 

frame_format

This parameter specifies the pixel layout for decoding frames. It accepts any FFmpeg-supported pixel format string.

Data-Type: String

Default Value: "bgr24"

Usage:

Use ffmpeg -pix_fmts terminal command to list all FFmpeg-supported pixel formats.

# decode as BGR24 (default, OpenCV-compatible)
FFGear(source="myvideo.mp4", frame_format="bgr24")

# decode as grayscale
FFGear(source="myvideo.mp4", frame_format="gray")

# decode as YUV420p (fastest throughput; requires -enforce_cv_patch for OpenCV compatibility)
FFGear(source="myvideo.mp4", frame_format="yuv420p") # auto-convert YUV420p → OpenCV Compatible in FFGear

YUV420p + -enforce_cv_patch usage example is given here ➶.

 

custom_ffmpeg

This parameter specifies a custom path to the FFmpeg executable. Useful when FFmpeg is not on PATH or you want to use a specific version.

Data-Type: String

Default Value: "" (uses system FFmpeg)

Usage:

FFGear(source="myvideo.mp4", custom_ffmpeg="/opt/ffmpeg/bin/ffmpeg")

 

logging

This parameter enables logging (if True), essential for debugging.

Data-Type: Boolean

Default Value: False

Usage:

FFGear(source="myvideo.mp4", logging=True)

 

options

This parameter provides the ability to configure both FFdecoder-specific parameters (passed directly to FFdecoder API) and FFGear queue-tuning parameters.

Data-Type: Dictionary

Default Value: {}

 

A. FFGear-Exclusive Parameters

The following options keys are consumed by FFGear itself and are not forwarded to FFdecoder:

Parameter Type Default Description
THREADED_QUEUE_MODE bool True Enables producer-consumer threaded queue for zero-bottleneck frame delivery. Disable only for single-threaded pipelines.
QUEUE_SIZE int 96 Maximum number of frames buffered in the queue. Increase for smoother playback on high-latency sources.
THREAD_TIMEOUT float or None None Timeout (in seconds) for queue get() and thread join() calls. None means block indefinitely.
STREAM_RESOLUTION str "best" (Stream Mode only) Desired stream resolution, e.g. "720p", "1080p", "best".
STREAM_PARAMS dict {} (Stream Mode only) Extra yt_dlp parameters forwarded to the YT_backend.

Usage:

options = {
    "THREADED_QUEUE_MODE": True,
    "QUEUE_SIZE": 128,
    "THREAD_TIMEOUT": 5.0,
}
FFGear(source="myvideo.mp4", **options)

 

B. FFdecoder Parameters

All remaining keys in options are forwarded directly to FFdecoder's ffparams dictionary. This gives you full access to FFdecoder's exclusive parameters:

Parameter Type Description
-vcodec str or None Force a specific video decoder (e.g. "h264_cuvid").
-hwaccel str Hardware acceleration backend (e.g. "cuda", "vaapi").
-vf str Simple FFmpeg video filtergraph (e.g. "scale=1280:720,hflip").
-filter_complex str Complex FFmpeg filtergraph for multi-input routing.
-enforce_cv_patch bool Enables OpenCV-compatibility patch for YUV/NV pixel formats.
-extract_metadata bool Enables per-frame metadata extraction via showinfo filter. read() returns (frame, metadata) tuples.
-ffprefixes list Additional FFmpeg CLI prefixes (e.g. ["-stream_loop", "-1"]).

Full list of all FFdecoder parameters can be found here ➶

Usage:

options = {
    "-vcodec": "h264_cuvid",         # hardware decoder
    "-enforce_cv_patch": True,        # OpenCV YUV compatibility
    "-vf": "scale=1280:720",          # scale filter
    "QUEUE_SIZE": 64,                 # FFGear queue size
}
FFGear(source="myvideo.mp4", frame_format="yuv420p", **options)