FFGear API Advanced Usage¶

# import required libraries
from vidgear.gears import FFGear
import cv2

# stream with "/dev/video0" source for BGR24 output
stream = FFGear(
    source="/dev/video0", source_demuxer="v4l2", frame_format="bgr24", logging=True
).start()

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    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()

# safely close video stream
stream.stop()

# import required libraries
from vidgear.gears import FFGear
import cv2

# use H.264 CUVID hardware decoder; enable OpenCV patch for YUV frames
options = {
    "-vcodec": "h264_cuvid",    # NVIDIA CUVID hardware decoder
    "-enforce_cv_patch": True,  # auto-convert YUV420p → OpenCV Compatible in FFGear
}

stream = FFGear(
    source="myvideo.mp4",
    frame_format="yuv420p",
    logging=True,
    **options
).start()

# loop over
while True:

    # read BGR frames (auto-converted from YUV420p)
    frame = stream.read()

    # check for frame if Nonetype
    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()

# safely close video stream
stream.stop()

# import required libraries
from vidgear.gears import FFGear
import cv2

# CUDA hwaccel: decode in GPU memory, scale & fps in GPU, download as NV12
options = {
    "-vcodec": None,               # skip source decoder, let FFmpeg choose
    "-enforce_cv_patch": True,     # auto-convert NV12 → OpenCV Compatible in FFGear
    "-ffprefixes": [
        "-vsync", "0",             # prevent duplicate frames
        "-hwaccel", "cuda",        # use CUDA accelerator
        "-hwaccel_output_format", "cuda",  # keep frames in GPU memory
    ],
    "-custom_resolution": "null",  # discard source resolution param
    "-framerate": "null",          # discard source framerate param
    "-vf": (
        "scale_cuda=1280:720,"     # GPU-side scale to 1280x720
        "fps=60.0,"                # GPU-side framerate
        "hwdownload,"              # download to system memory
        "format=nv12"             # convert to NV12 pixel format
    ),
}

stream = FFGear(
    source=VIDEO,
    frame_format="null",           # discard source pixel format
    logging=True,
    **options
).start()

# loop over
while True:

    # read NV12 frames
    frame = stream.read()

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

    # {do something with the frame here}

    # convert it to OpenCV compatible frame
    frame = cv2.cvtColor(frame, cv2.COLOR_YUV2BGR_NV12)

    # {do something with the BGR 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()

# safely close video stream
stream.stop()

# import the necessary packages
from vidgear.gears import FFGear
import cv2, json

# CUDA hwaccel: decode in GPU memory, scale & crop in GPU, download as NV12
options = {
    "-vcodec": None,               # skip source decoder, let FFmpeg choose
    "-enforce_cv_patch": True,     # auto-convert NV12 → OpenCV Compatible in FFGear
    "-ffprefixes": [
        "-vsync", "0",             # prevent duplicate frames
        "-hwaccel", "cuda",        # use CUDA accelerator
        "-hwaccel_output_format", "cuda",  # keep frames in GPU memory
    ],
    "-custom_resolution": "null",  # discard source resolution param
    "-framerate": "null",          # discard source framerate param
    "-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 to system memory
        "format=nv12"              # convert to NV12 pixel format
    ),
}

stream = FFGear(
    source="foo.mp4",
    frame_format="null",           # discard source pixel format
    logging=True,
    **options
).start()

# retrieve JSON Metadata and convert it to dict
metadata_dict = json.loads(stream.stream.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)

# loop over
while True:

    # read NV12 frames (auto-converted from NV12)
    frame = stream.read()

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

# safely close video stream
stream.stop()

# safely close writer
writer.release()

# import required libraries
from vidgear.gears import FFGear

# enable per-frame metadata extraction
options = {"-extract_metadata": True}

stream = FFGear(
    source="myvideo.mp4",
    frame_format="bgr24",
    logging=True,
    **options
).start()

# loop over
while True:

    # returns (frame, metadata) tuple when `-extract_metadata` is enabled
    output = stream.read()

    # check if output is None (end of stream)
    if output is None:
        break

    # Unpacking tuple
    frame, meta = output

    # [OPTIMIZATION]: skip non-keyframes entirely
    if meta and not meta["is_keyframe"]: 
        continue # <-- Skips Non-key frames (P, B-frames)

    # Run Heavy AI model inference/Prediction on keyframes (I-frames) only 
    # results = my_heavy_ai_model.predict(frame)
    print(f"Keyframe #{meta['frame_num']} at {meta['pts_time']:.3f}s")

# safely close video stream
stream.stop()

# import required libraries
from vidgear.gears import FFGear

# enable per-frame metadata extraction
options = {"-extract_metadata": True}

stream = FFGear(
    source="screen_recording.mp4",
    frame_format="bgr24",
    **options
).start()

prev_pts = None

# loop over
while True:

    # read returns (frame, metadata) tuple
    output = stream.read()

    if output is None:
        break

    frame, meta = output

    # exact presentation timestamp in seconds
    pts = meta["pts_time"]

    # compute the real inter-frame delta (not the nominal 1/fps value)
    delta_ms = None if prev_pts is None else (pts - prev_pts) * 1000.0
    prev_pts = pts

    # use real delta for per-frame motion/velocity calculations
    # e.g. velocity = displacement_px / delta_ms
    if delta_ms is not None:
        print(f"Frame #{meta['frame_num']} | PTS: {pts:.3f}s | Δt: {delta_ms:.1f}ms")

# safely close video stream
stream.stop()

# import the necessary packages
from vidgear.gears import FFGear
from vidgear.gears import WriteGear
import json, cv2

# define the Complex Video Filter with additional `watermark.png` image input
options = {
    "-ffprefixes": ["-t", "10"],  # playback time of 10 seconds
    "-clones": [
        "-i",
        "watermark.png",  # !!! [WARNING] define your absolute `watermark.png` path here.
    ],
    "-filter_complex": "[1]scale=256:-1,format=rgba,"  # change 2nd(image) input to 256 pixels wide and yuv444p format
    + "colorchannelmixer=aa=0.7[logo];"  # apply colorchannelmixer to image for controlling alpha [logo]
    + "[0][logo]overlay=W-w-{pixel}:H-h-{pixel}:format=auto,".format(  # apply overlay to 1st(video) with [logo]
        pixel=5  # at 5 pixels from the bottom right corner of the input video
    )
    + "format=bgr24",  # change output format to `bgr24`
}

# open source with FFGear and BGR frames with given params
stream = FFGear(source="myvideo.mp4", frame_format="bgr24", logging=True, **options).start()

# retrieve framerate from source JSON Metadata and pass it as `-input_framerate`
# parameter for controlled framerate
output_params = {
    "-input_framerate": json.loads(stream.stream.metadata)["source_video_framerate"]
}

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

# loop over
while True:

    # read frames from stream
    frame = stream.read()

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

    # {do something with the frame here}

    # write frame to output
    writer.write(frame)

# safely close stream
stream.stop()

# safely close writer
writer.close()

# import required libraries
from vidgear.gears import FFGear
from vidgear.gears import WriteGear
import json

# define parameters
options = {
    "-ffprefixes": ["-t", "10"],  # playback time of 10 seconds
    "-vf": "format=yuv444p," # change input format to yuv444p
    + "split=4[a][b][c][d]," # split input into 4 identical outputs.
    + "[a]waveform[aa],"  # apply waveform on first output
    + "[b][aa]vstack[V],"  # vertical stack 2nd output with waveform [V]
    + "[c]waveform=m=0[cc],"  # apply waveform on 3rd output
    + "[d]vectorscope=color4[dd],"  # apply vectorscope on 4th output
    + "[cc][dd]vstack[V2],"  # vertical stack waveform and vectorscope [V2]
    + "[V][V2]hstack",  # horizontal stack [V] and [V2] vertical stacks
}

# stream with "mandelbrot" source of
# `1280x720` frame size and `30` framerate for BGR24 output
stream = FFGear(
    source="mandelbrot=size=1280x720:rate=30",
    source_demuxer="lavfi",
    frame_format="bgr24",
    logging=True,
    **options
).start()

# retrieve framerate from source JSON Metadata and pass it as `-input_framerate`
# parameter for controlled framerate
output_params = {
    "-input_framerate": json.loads(stream.stream.metadata)["source_video_framerate"]
}

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

# loop over
while True:

    # read frames from stream
    frame = stream.read()

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

    # write frame to output
    writer.write(frame)

# safely close stream
stream.stop()

# safely close writer
writer.close()