Have any positive feedback?
Please share here!
Ctrlk
WebsiteAI HubVisit Community
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Release Notes

This page features release notes for releases of degirum-tools. You may download degirum-tools versions listed here from PyPI.org.

Version 1.4.0 (5/15/2026)

New Features and Modifications

  1. New gst subpackage providing a complete GStreamer-based video pipeline toolkit:

    • setup_gst_environment(*plugin_dirs) — initializes GStreamer and optionally registers custom plugin directories. Must be called before any gi import.

    • GstPipelineHandler — manages the full lifecycle of a GStreamer pipeline, with optional named appsink queues for Python frame consumption and throughput probing.

    • GstElementBase — mixin base class for implementing custom GStreamer Python elements with minimal boilerplate. Pad templates, worker threads, and state management are handled automatically.

    • GstAiElement — ready-to-use GStreamer filter element that accepts BGR/RGB video frames, runs AI inference via a DeGirum model, and pushes annotated frames and/or serialized JSON inference results downstream. Supports an optional secondary full-resolution input pad (sink_full) for high-quality overlay rendering at a different resolution than the model input.

    • map_gst_buffer(buf_or_sample, readonly) — context manager for safe Gst.Buffer memory mapping.

    • build_gst_pipeline(source) — builds a gst-launch-style pipeline string for camera devices (including Windows via mfvideosrc/ksvideosrc), RTSP streams, and video files.

    • VideoCaptureGst — cv2.VideoCapture-compatible class backed by a GStreamer pipeline.

  2. ObjectTracker analyzer now extends object trails with predicted positions during tracking timeouts, using the tracker's internal motion estimate for lost tracks. This preserves trail continuity when objects temporarily leave the frame.

  3. VideoSourceGizmo now accepts a pre-created VideoCaptureProtocol object (e.g., cv2.VideoCapture or VideoCaptureGst) as the video_source argument. Additional keyword arguments (**kwargs) are forwarded to the cv2.VideoCapture constructor when opening from a path or device index.

  4. VideoStreamerGizmo and VideoStreamer gain a vcodec parameter to configure the video codec (defaults to libx264).

  5. Stream.close() gains a force=True option that atomically clears the queue and inserts the poison pill without blocking, preventing deadlocks when a producer has filled the queue.

Bug Fixes

  1. VideoStreamerGizmo frame scheduling: duplicate frames were injected using an incorrect rate estimate that could cause a spin-loop. The logic is now based on an absolute deadline (next_frame_due_s) and stops duplicating when the encoder write time exceeds the target frame interval.

  2. VideoStreamer: pix_fmt was always passed to FFmpeg as bgr24 regardless of the configured pixel format. It now correctly uses the pix_fmt constructor argument.

  3. video_source(): CAP_PROP_FRAME_COUNT can return None for certain capture backends (e.g., VideoCaptureGst), causing a TypeError. The comparison now handles None correctly.

  4. MediaServer subprocess is now started with start_new_session=True, preventing signal propagation from the parent process to the media server process.

Version 1.3.1 (4/21/2026)

Bug Fixes

VideoStreamer class which uses ffmpeg for video streaming, now uses TCP protocol for RTSP streaming. Previous versions used UDP protocol, which had lower latency, but may result in corrupted video streams on certain systems.

Version 1.3.0 (4/3/2026)

New Features and Modifications

  1. Performance of ObjectTracker analyzer is greatly improved.

  2. frame_size parameter is added to ZoneCounter analyzer constructor. It specifies the frame size (width, height) when inference results do not have .image attribute.

  3. Added new ipc subpackage providing transparent inter-process communication: use ipc.spawn(MyClass, ...) to run any class instance in an isolated child process with all public methods automatically available as ZeroMQ RPC endpoints, with MsgPack serialization and InOut/Out wrappers for mutable argument writeback.

Version 1.2.2 (3/17/2026)

Bug Fixes

  1. EventDetector analyzer raises exception when result argument of analyze method has events_detected attribute of dict type.

  2. EventDetector analyzer incorrectly generates events when the event history is not fully accummulated yet.

Version 1.2.1 (3/13/2026)

New Features and Modifications

  1. ResultAnalyzerBase base class analyze and annotate methods are modified to ignore None results. This allows using analyzers with models in non_blocking_batch_predict mode.

Bug Fixes

  1. NoneType object has no attribute encoding exception is raised during import degirum_tools if the process has no stdout attached.

Version 1.2.0 (2/23/2026)

New Features and Modifications

  1. SceneCutDetector analyzer is implemented.

    SceneCutDetector analyzer detects scene cuts in video streams by comparing frame-to-frame differences using an adaptive thresholding approach.

    Key Features:

    • Adaptive Thresholding: Uses rolling average of previous frames to adapt to gradual changes

    • HSV Color Space: Analyzes differences in hue, saturation, and luminance channels

    • Configurable Parameters: Adjustable sensitivity, minimum scene length, and window size

    • Real-time Detection: Causal approach using only past frames for zero latency

    • Scene Cut Flag: Adds scene_cut boolean attribute to inference results

    Typical Usage:

    1. Create a SceneCutDetector instance with desired parameters

    2. Attach it to a model or inference pipeline

    3. Process video frames through the analyzer

    4. Check result.scene_cut flag to detect scene transitions

    5. Use scene cut information for downstream processing or triggering actions

    Put it before ObjectTracker in the analyzer pipeline to ensure cuts are detected before tracking is applied, allowing you to reset object tracker on scene changes.

    Integration Notes:

    • Works with any inference results that contain image data

    • Can be combined with other analyzers in a pipeline

    • Useful for video segmentation, activity detection, and content analysis

    • Maintains internal state to track frame history

    Configuration Options:

    • adaptive_threshold: Sensitivity ratio for detecting cuts (higher = less sensitive)

    • min_scene_len: Minimum frames between detected cuts to avoid false positives

    • window_width: Number of previous frames for rolling average calculation

    • min_content_val: Minimum absolute change threshold for scene cuts

    • luma_only: Use only brightness changes for faster processing

  2. reset_at_scene_cut parameter is added to the ObjectTracker analyzer. When True, all tracks are cleared when a scene cut is detected. Requires the result to have a scene_cut attribute (set by SceneCutDetector, see above). Use this feature to avoid tracking objects across scene transitions in videos with cuts or edits.

Version 1.1.0 (2/11/2026)

New Features and Modifications

  1. IteratorSourceGizmo: fps constructor parameter is added. This is optional parameter with default value 0.0. It specifies the FPS value to be included in the metadata.

Bug Fixes

  1. VideoStreamerGizmo: check for zero FPS is added to prevent division by zero in case of zero-FPS sources.

Version 1.0.0 (1/27/2026)

First official release of degirum-tools.

PreviousRemote Assets

Last updated

Was this helpful?