Video Support
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
VideoWriter
oropen_video_writer()
Extract frames using
video2jpegs()
Save event-triggered clips with
ClipSaver
Integration 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
Classes
VideoWriter
VideoWriter
Video stream writer with configurable quality and format.
This class provides functionality to save video streams to files with configurable dimensions, frame rate, and format. It supports both OpenCV and PIL image formats as input.
Use open_video_writer()
to create a video writer instance with proper cleanup.
Attributes:
filename
str
Output video file path.
width
int
Video width in pixels.
height
int
Video height in pixels.
fps
float
Target frame rate.
int
Number of frames written.
Attributes
count
count
property
Get the number of frames written.
Returns:
int
Number of frames written to the video file.
Functions
__exit__(exc_type, ...)
__exit__(exc_type, exc_val, exc_tb)
Exit the context manager.
This method ensures the video writer is properly released when exiting the context.
__init__(fname, ...)
__init__(fname, w=0, h=0, fps=30.0)
Initialize the video writer.
Parameters:
fname
str
Output video file path.
required
w
int
Video width in pixels. If 0, use input frame width. Defaults to 0.
0
h
int
Video height in pixels. If 0, use input frame height. Defaults to 0.
0
fps
float
Target frame rate. Defaults to 30.0.
30.0
Raises:
Exception
If the video writer cannot be created.
release
release()
Release the video writer resources.
This method should be called when finished writing to ensure all resources are properly released.
write(img)
write(img)
Write a frame to the video file.
This method writes a single frame to the video file. The frame can be in either OpenCV (BGR) or PIL format.
Parameters:
img
ImageType
Frame to write. Can be: - OpenCV image (np.ndarray) - PIL Image
required
Raises:
Exception
If the frame cannot be written.
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.
Functions
__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
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.
_save_clip
_save_clip()
Save a video clip with pre-trigger frames.
This method creates a new thread to save the clip, including frames from the buffer before the trigger and the current frame.
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.
Functions
open_video_stream(video_source=None, ...)
open_video_stream(video_source=None, max_yt_quality=0)
Open a video stream from various sources.
This function provides a context manager for opening video streams from different sources, including local cameras, IP cameras, video files, and YouTube videos. The stream is automatically closed when the context is exited.
Parameters:
video_source
Union[int, str, Path, None]
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
None
max_yt_quality
int
Maximum video quality for YouTube videos in pixels (height). If 0, use best quality. Defaults to 0.
0
Yields:
VideoCapture
cv2.VideoCapture: OpenCV 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]
Video source identifier or an already opened VideoCapture
object.
required
Returns:
tuple
(width, height, fps)
describing the video stream.
video_source(stream, ...)
video_source(stream, fps=None)
Yield frames from a video stream.
Parameters:
stream
VideoCapture
Open video stream.
required
fps
Optional[float]
Target frame rate cap.
None
Yields:
ndarray
Frames from the stream.
create_video_writer(fname, ...)
create_video_writer(fname, w=0, h=0, fps=30.0)
Create and return a video writer.
Parameters:
fname
str
Output filename for the video file.
required
w
int
Frame width in pixels. 0
uses the width of the first frame. Defaults to 0
.
0
h
int
Frame height in pixels. 0
uses the height of the first frame. Defaults to 0
.
0
fps
float
Target frames per second. Defaults to 30.0
.
30.0
Returns:
VideoWriter
Open video writer instance.
open_video_writer(fname, ...)
open_video_writer(fname, w=0, h=0, fps=30.0)
Context manager for VideoWriter
.
This function creates a video writer, yields it for use inside the context, and releases it automatically on exit.
Parameters:
fname
str
Output filename for the video file.
required
w
int
Frame width in pixels. 0
uses the width of the first frame. Defaults to 0
.
0
h
int
Frame height in pixels. 0
uses the height of the first frame. Defaults to 0
.
0
fps
float
Target frames per second. Defaults to 30.0
.
30.0
Yields:
VideoWriter
Open video writer instance ready for use.
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
.
Last updated
Was this helpful?