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 Polling interval (in seconds) for queue get() calls, and grace period for the producer thread to exit on stop() (1 second when None), after which FFmpeg is killed to unblock a stalled source. To bound how long read() waits for a frame, use read(timeout=...) instead.
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"]).
-capture_stderr bool Captures the last 50 lines of FFmpeg's stderr, retained as FFGear's stderr_tail after stop() (requires DeFFcode with -capture_stderr support).

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)

Â