FFGear FAQs¶
What is FFGear API and what does it do?¶
Answer: FFGear is a multi-threaded, high-performance wrapper around DeFFcode's FFdecoder API that compiles and executes an FFmpeg pipeline inside a subprocess pipe for generating real-time, low-overhead, lightning-fast decoded video frames in Python. It supports hardware-accelerated decoding, flexible pixel formats, per-frame metadata extraction, complex filtergraphs, and wide source support (cameras, files, network streams, streaming services). For more info. see FFGear doc ➶.
What are the requirements for FFGear API?¶
Answer: FFGear requires the deffcode library and a valid FFmpeg executable on your system. Install deffcode via pip:
For FFmpeg installation, follow the dedicated FFmpeg Installation guide ➶.
How is FFGear different from CamGear?¶
Answer: Both CamGear and FFGear follow the same .start() → .read() → .stop() coding pattern and support streaming URLs via yt_dlp. The key differences are:
- CamGear is built on top of OpenCV's
VideoCaptureand is ideal for general-purpose camera/file/network stream reading. - FFGear is built on top of DeFFcode's FFdecoder, which drives FFmpeg directly via subprocess pipes, giving you hardware-accelerated decoding, any FFmpeg pixel format, live filtergraphs, per-frame metadata, and multi-input pipelines — none of which are available in CamGear.
Use FFGear when you need GPU decoding, advanced FFmpeg pipelines, or YUV pixel formats for throughput-sensitive workloads.
I'm only familiar with OpenCV, how do I get started with FFGear?¶
Answer: FFGear maintains the same OpenCV-like coding syntax as CamGear. First, refer to the Switching from OpenCV guide, then go through FFGear documentation ➶. If you still have doubts, ask us on Gitter ➶ Community channel.
How to change the pixel format of decoded frames in FFGear?¶
Answer: Use the frame_format parameter. It accepts any FFmpeg-supported pixel format string (e.g. "bgr24", "rgb24", "gray", "yuv420p"). The default is "bgr24" for direct OpenCV compatibility. See Usage Examples ➶.
How to use a hardware decoder (GPU) in FFGear?¶
Answer: Pass the -vcodec FFmpeg parameter via the options dictionary to specify a hardware decoder like h264_cuvid (NVIDIA CUVID) or use -hwaccel cuda via -ffprefixes. See the Hardware-Accelerated Decoding ➶ advanced examples.
What is -enforce_cv_patch and when do I need it?¶
Answer: -enforce_cv_patch is an exclusive FFdecoder parameter that makes YUV/NV pixel-format frames (e.g. yuv420p, nv12) directly compatible with OpenCV. When enabled, FFGear automatically converts these frames to BGR colorspace internally — so read() returns standard BGR frames ready for cv2.imshow() or cv2.imwrite(). Enable it whenever you use frame_format="yuv420p" or similar YUV formats. See params ➶.
What is -extract_metadata and what does read() return when it's enabled?¶
Answer: -extract_metadata enables asynchronous per-frame metadata extraction via FFmpeg's showinfo filter. When enabled, FFGear's read() returns (frame, metadata) tuples instead of bare frames. The metadata dict contains frame_num, pts_time, is_keyframe, and frame_type. This is useful for keyframe-only AI inference, VFR synchronization, and timestamped pipelines. See advanced examples ➶.
-extract_metadata is incompatible with -filter_complex. Both cannot be active simultaneously.
How to apply FFmpeg filters in FFGear?¶
Answer: Pass the -vf FFmpeg parameter (for simple filtergraphs) or -filter_complex (for multi-input graphs) via the options dictionary. See Usage Examples ➶ and Advanced Usage ➶.
How to open RTSP/RTP network streams with FFGear?¶
Answer: Simply provide the RTSP/RTP URL as the source parameter. You can also pass FFmpeg transport parameters via options (e.g. {"-rtsp_transport": "tcp"}). See Usage Examples ➶.
How to change quality and parameters of YouTube Streams with FFGear?¶
Answer: FFGear provides exclusive STREAM_RESOLUTION (for specifying stream resolution) and STREAM_PARAMS (for specifying underlying yt_dlp parameters) attributes with its options dictionary parameter. See this Bonus Example ➶.
How to loop a video indefinitely with FFGear?¶
Answer: Use the -stream_loop FFmpeg prefix via the -ffprefixes option. Set it to -1 for infinite looping:
See Usage Examples ➶.
Can I use FFGear with multiple camera devices at the same time?¶
Answer: Yes. Simply create separate FFGear instances for each device. See this Bonus Example ➶.
How to use FFGear with WriteGear?¶
Answer: FFGear follows the same read-loop pattern as CamGear, so it integrates directly with WriteGear. See this Bonus Example ➶.
How to use FFGear with NetGear for network streaming?¶
Answer: Use FFGear on the server side to decode frames and send them via NetGear. See this Bonus Example ➶.
How to configure the internal queue in FFGear?¶
Answer: Use QUEUE_SIZE (int, default 96), THREADED_QUEUE_MODE (bool, default True), and THREAD_TIMEOUT (float or None, default None) in the options dictionary. See params ➶.
Can FFGear decode 4K/8K video?¶
Answer: Yes, FFGear can decode up to 4K/8K video if your system hardware and FFmpeg build support it. Hardware-accelerated decoding (e.g. via CUVID or VAAPI) is strongly recommended for high-resolution sources to avoid CPU bottlenecks.
Why is FFGear throwing RuntimeError: Source is invalid or unreadable!?¶
Answer: FFGear will throw RuntimeError if it cannot read even a single frame from the given source. Common causes include: - Invalid or non-existent file path. - Unsupported codec without the right hardware decoder or FFmpeg build. - Network stream not available at the given URL.
Enable logging=True to get detailed FFmpeg output for diagnosing the issue.
Why is FFGear throwing ImportError about deffcode?¶
Answer: FFGear requires the deffcode library. Install it via:
Why is FFGear throwing warning that Threaded Queue Mode is disabled?¶
Answer: That's normal behavior when THREADED_QUEUE_MODE=False is set in options. Please read about Threaded Queue Mode ➶ to understand its implications.