Video Support
DeGirum Tools API Reference Guide. Read, stream, display and save video or RTSP sources.
Video Support Module Overview
This module provides comprehensive video stream handling capabilities, including capturing from various sources, saving to files, and managing video clips. It supports local cameras, IP cameras, video files, and YouTube videos. Key Features:
Multi-Source Support: Capture from local cameras, IP cameras, video files, and YouTube
Video Writing: Save video streams with configurable quality and format
Frame Extraction: Convert video files to JPEG sequences
Clip Management: Save video clips triggered by events with pre/post buffers
FPS Control: Frame rate management for both capture and writing
Stream Properties: Query video stream dimensions and frame rate Typical Usage:
Open video streams with
open_video_stream()Process frames using
video_source()generatorSave videos with
VideoWriteroropen_video_writer()Extract frames using
video2jpegs()Save event-triggered clips with
ClipSaverIntegration Notes:
Works with OpenCV's VideoCapture and VideoWriter
Supports YouTube videos through pafy
Handles both real-time and file-based video sources
Provides context managers for safe resource handling
Thread-safe for concurrent video operations Key Classes:
VideoWriter: Main class for saving video streamsClipSaver: Manages saving video clips with pre/post buffers Configuration Options:Video quality and format settings
Frame rate control
Clip duration and buffer size
Output file naming and paths
Functions
create_video_stream(video_source=None, ...)
create_video_stream(video_source=None, *, max_yt_quality=0, use_gstreamer=False)
Create a video stream from various sources.
This function creates and returns video stream object working from different sources, including local cameras, IP cameras, video files, and YouTube videos.
Parameters:
video_source
Union[int, str, Path, None, VideoCapture, VideoCaptureGst]
Video source specification: - int: 0-based index for local cameras - str: IP camera URL (rtsp://user:password@hostname) - str: Local video file path - str: URL to mp4 video file - str: YouTube video URL - None: Use environment variable or default camera - cv2.VideoCapture or VideoCaptureGst: Pass through existing capture
None
max_yt_quality
int
Maximum video quality for YouTube videos in pixels (height). If 0, use best quality. Defaults to 0.
0
use_gstreamer
bool
If True, use GStreamer backend for video files. Only applies to .mp4 files. Defaults to False.
False
Returns:
Union[VideoCapture, VideoCaptureGst]
cv2.VideoCapture or VideoCaptureGst: Video capture object.
Raises:
Exception
If the video stream cannot be opened.
detect_rtsp_cameras(subnet_cidr, ...)
detect_rtsp_cameras(subnet_cidr, *, timeout_s=0.5, port=554, max_workers=16)
Scan given subnet for RTSP cameras by probing given port with OPTIONS request. Args: subnet_cidr (str): Subnet in CIDR notation (e.g., '192.168.0.0/24'). timeout_s (float): Timeout for each connection attempt in seconds. port (int): Port to probe for RTSP cameras (default is 554). max_workers (int): Maximum number of concurrent threads for scanning (default is 16). Returns: dict: Dictionary with IP addresses as keys and properties as values. Properties include 'require_auth' indicating if authentication is required.
open_video_stream(video_source=None, ...)
open_video_stream(video_source=None, *, max_yt_quality=0, use_gstreamer=False)
Open a video stream from various sources.
This function provides a context manager for opening video streams from different sources. The stream is automatically closed when the context is exited. Internally it calls create_video_stream to create the stream.
Parameters:
video_source
Union[int, str, Path, None, VideoCapture, VideoCaptureGst]
Video source specification (see create_video_stream)
None
max_yt_quality
int
Maximum video quality for YouTube videos
0
use_gstreamer
bool
If True, use GStreamer backend for video files
False
Yields:
Union[VideoCapture, VideoCaptureGst]
cv2.VideoCapture or VideoCaptureGst: Video capture object.
Raises:
Exception
If the video stream cannot be opened.
get_video_stream_properties(video_source)
get_video_stream_properties(video_source)
Return the dimensions and frame rate of a video source.
Parameters:
video_source
Union[int, str, Path, None, VideoCapture, VideoCaptureGst]
Video source identifier or an already opened capture object.
required
Returns:
tuple
(width, height, fps) describing the video stream.
video_source(stream, ...)
video_source(stream, fps=None, include_metadata=False)
Yield frames from a video stream.
Parameters:
stream
Union[VideoCapture, VideoCaptureGst]
Open video stream (cv2.VideoCapture or VideoCaptureGst).
required
fps
Optional[float]
Target frame rate cap.
None
include_metadata
bool
If True, yields (frame, metadata) tuples where metadata contains timestamp, frame_id, fps, frame dimensions. If False, yields only frames. Defaults to False.
False
Yields:
Union[ndarray, Tuple[ndarray, dict]]
If include_metadata is False: Frames from the stream (np.ndarray).
Union[ndarray, Tuple[ndarray, dict]]
If include_metadata is True: Tuples of (frame, metadata) where metadata is a dict containing 'timestamp', 'frame_id', 'fps', 'frame_width', 'frame_height'.
create_video_writer(fname, ...)
create_video_writer(fname, w=0, h=0, fps=30.0)
open_video_writer(fname, ...)
open_video_writer(fname, w=0, h=0, fps=30.0)
video2jpegs(video_file, ...)
video2jpegs(video_file, jpeg_path, *, jpeg_prefix='frame_', preprocessor=None)
Convert a video file into a sequence of JPEG images.
Parameters:
video_file
str
Path to the input video file.
required
jpeg_path
str
Directory where JPEG files will be stored.
required
jpeg_prefix
str
Prefix for generated image filenames. Defaults to "frame_".
'frame_'
preprocessor
Callable[[ndarray], ndarray]
Optional function applied to each frame before saving.
None
Returns:
int
int
Number of frames written to jpeg_path.
Classes
VideoSourceType
VideoSourceType
Bases: Enum
Enumeration of supported video source types for inference.
VideoSourceType Methods
from_string(value)
from_string(value)
classmethod
Convert string to enum, maintaining backward compatibility. Args: value: String value or VideoSourceType enum Returns: VideoSourceType enum value Raises: ValueError: If string value is not a valid VideoSourceType TypeError: If value is not str or VideoSourceType
VideoCaptureGst
VideoCaptureGst
GStreamer-based video capture class that mimics cv2.VideoCapture interface.
VideoCaptureGst Methods
__init__(pipeline_str)
__init__(pipeline_str)
Initialize GStreamer pipeline from string.
Parameters:
pipeline_str
GStreamer pipeline string
required
get(prop)
get(prop)
Get capture properties (mimics cv2.VideoCapture.get).
Parameters:
prop
int
OpenCV property constant (e.g., cv2.CAP_PROP_FRAME_WIDTH)
required
Returns:
Property value or None if not available
isOpened
isOpened()
Check if the capture is opened.
Returns:
bool
True if pipeline is running
read
read()
Read a frame from the GStreamer pipeline.
Returns:
(bool, ndarray)
Success flag and frame data
release
release()
Release the GStreamer pipeline.
set(prop, ...)
set(prop, value)
Set capture properties (mimics cv2.VideoCapture.set).
Note: GStreamer pipelines are typically configured at creation time. Most properties cannot be changed dynamically after the pipeline is created. This method provides limited support for interface compatibility.
Parameters:
prop
int
OpenCV property constant (e.g., cv2.CAP_PROP_FPS)
required
value
float
Property value to set
required
Returns:
bool
bool
True if property was acknowledged, False if not supported
VideoWriter
VideoWriter
Video stream writer with configurable quality and format.
ClipSaver
ClipSaver
Video clip saver with pre/post trigger buffering.
This class provides functionality to save video clips triggered by events, with configurable pre-trigger and post-trigger buffers. It maintains a circular buffer of frames and saves clips when triggers occur.
This class is primarily used by two other components in DeGirum Tools.
ClipSavingAnalyzer wraps ClipSaver and triggers clips from event names found in EventNotifier or EventDetector results.
EventNotifier can instantiate and use ClipSaver to record clips when a notification fires, optionally uploading those clips through NotificationServer.
Attributes:
clip_duration
int
Total length of output clips in frames.
file_prefix
str
Base path for saved clip files.
pre_trigger_delay
int
Frames to include before trigger.
embed_ai_annotations
bool
Whether to include AI annotations in clips.
save_ai_result_json
bool
Whether to save AI results as JSON.
target_fps
float
Frame rate for saved clips.
ClipSaver Methods
__init__(clip_duration, ...)
__init__(clip_duration, file_prefix, *, pre_trigger_delay=0, embed_ai_annotations=True, save_ai_result_json=True, target_fps=30.0)
Initialize the clip saver.
Parameters:
clip_duration
int
Total length of output clips in frames (pre-buffer + post-buffer).
required
file_prefix
str
Base path for saved clip files. Frame number and extension are appended automatically.
required
pre_trigger_delay
int
Frames to include before trigger. Defaults to 0.
0
embed_ai_annotations
bool
If True, use InferenceResults.image_overlay to include bounding boxes/labels in the clip. Defaults to True.
True
save_ai_result_json
bool
If True, save a JSON file with raw inference results alongside the video. Defaults to True.
True
target_fps
float
Frame rate for saved clips. Defaults to 30.0.
30.0
Raises:
ValueError
If clip_duration is not positive.
ValueError
If pre_trigger_delay is negative or exceeds clip_duration.
forward(result, ...)
forward(result, triggers=[])
Process a frame and save clips if triggers occur.
This method adds the current frame to the buffer and saves clips if any triggers are present. The saved clips include pre-trigger frames from the buffer.
Parameters:
triggers
List[str]
List of trigger names that occurred in this frame. Defaults to [].
[]
Returns:
Tuple[List[str], bool]
List of saved clip filenames and whether any clips were saved.
Raises:
Exception
If the frame cannot be saved.
join_all_saver_threads
join_all_saver_threads()
Wait for all clip saving threads to complete.
This method blocks until all background clip saving threads have finished. It's useful to call this before exiting to ensure all clips are properly saved.
Returns:
int
Number of threads that were joined.
MediaServer
MediaServer
Manages the MediaMTX media server as a subprocess.
Starts MediaMTX using a provided config file path. If no config path is given, it runs from the MediaMTX binary's directory.
MediaMTX binary must be installed and available in the system path. Refer to https://github.com/bluenviron/mediamtx for installation instructions.
MediaServer Methods
__del__
__del__()
Destructor to ensure the media server is stopped.
__enter__
__enter__()
Enables use with context manager.
__exit__(exc_type, ...)
__exit__(exc_type, exc_val, exc_tb)
Stops server when context exits.
__init__(*, ...)
__init__(*, config_path=None, verbose=False)
Initializes and starts the server.
Parameters:
config_path
Optional[str]
Path to an existing MediaMTX YAML config file. If not provided, runs with config file from binary directory.
None
verbose
bool
If True, shows media server output in the console.
False
stop
stop()
Stops the media server process.
VideoStreamer
VideoStreamer
Streams video frames to an RTMP or RTSP server using FFmpeg. This class uses FFmpeg to stream video frames to an RTSP server. FFmpeg must be installed and available in the system path.
VideoStreamer Methods
__del__
__del__()
Destructor to ensure the streamer is stopped.
__enter__
__enter__()
Enables use with context manager.
__exit__(exc_type, ...)
__exit__(exc_type, exc_value, traceback)
Stops streamer when context exits.
__init__(stream_url, ...)
__init__(stream_url, width, height, *, fps=30.0, pix_fmt='bgr24', gop_size=50, verbose=False)
Initializes the video streamer.
Parameters:
stream_url
str
RTMP/RTSP URL to stream to (e.g., 'rtsp://user:password@hostname:port/stream'). Typically you use MediaServer class to start media server and then use its RTMP/RTSP URL like rtsp://localhost:8554/mystream
required
width
int
Width of the video frames in pixels.
required
height
int
Height of the video frames in pixels.
required
fps
float
Frames per second for the stream. Defaults to 30.
30.0
pix_fmt
str
Pixel format for the input frames. Defaults to 'bgr24'. Can be 'rgb24'.
'bgr24'
gop_size
int
GOP size for the video stream. Defaults to 50.
50
verbose
bool
If True, shows FFmpeg output in the console. Defaults to False.
False
stop
stop()
Stops the streamer process.
write(img)
write(img)
Writes a frame to the RTSP stream. Args: img (ImageType): Frame to write. Can be:
OpenCV image (np.ndarray)
PIL Image
Last updated
Was this helpful?