gvaeventrecorder#

Caches pre/event/post video frames, triggers on detected classes with a per-class cooldown, writes full event clips to disk, and forwards PRE/EVENT/POST buffers downstream after a trigger. Pair it with gvaframeselect and gvaroiscale to prepare frames for a VLM.

Overview#

The gvaeventrecorder element is a GstBaseTransform that sits between an object-detection element (e.g. gvadetect) and a downstream consumer such as gvagenai. It reads GstAnalyticsODMtd detections already attached to each buffer and acts as a valve:

  • Pre-event ring buffer: a single, continuously fed, fixed-size window of the last pre-event-frames frames is always kept, independent of any trigger. It is never reset by a trigger. If a trigger occurs before the ring fills (for example, at the start of a stream), the clip includes all pre-event frames available at that moment; later triggers include the full configured PRE window.

  • Trigger: when a detection matches one of target-classes with confidence at or above confidence-threshold, and that class is not in cooldown, a new recording session starts. The session snapshots the current pre-event ring and keeps collecting frames for the full time the class remains detected. After the event ends, it collects post-event-frames more frames before finalizing the clip.

  • Detection gaps: up to event-gap-frames consecutive frames without a matching detection are tolerated as part of the same event. This helps prevent detector flicker from splitting one event into several clips.

  • Cooldown: each class has its own independent cooldown window of cooldown-value frames, restarted from the first qualifying detection in the window, to avoid a burst of repeat triggers for the same ongoing event.

  • Filtering to downstream: nothing is forwarded until an event is accepted. At that moment, buffered PRE frames are replayed oldest first, followed immediately by the trigger frame. Subsequent EVENT and POST frames are forwarded as they arrive. Overlapping windows share a single chronological stream: a buffer already forwarded is never replayed again.

  • Disk write: each session is encoded and muxed to its own MP4 file by a background worker thread through an internal appsrc ! videoconvert ! encoder ! h264parse ! mp4mux ! filesink pipeline. This never blocks the main streaming thread. With the default flush-interval-ms, the clip is written incrementally while the event is being recorded. See Incremental clip writing.

  • Metadata: forwarded frames get frame-level GstAnalyticsClsMtd entries describing the event state and, on start frames, the triggering class(es). See Metadata.

Properties#

Property

Type

Range

Default

Description

target-classes

String

—

person,vehicle

Comma-separated detection labels that can trigger a recording.

confidence-threshold

Double

[0.0, 1.0]

0.5

Minimum detection confidence required to trigger.

pre-event-frames

Unsigned Integer

[0, 4294967295]

30

Number of frames preceding a trigger kept in the shared ring buffer.

post-event-frames

Unsigned Integer

[0, 4294967295]

30

Number of frames to keep capturing after the detected event ends.

event-gap-frames

Unsigned Integer

[0, 4294967295]

3

Consecutive frames without a matching detection tolerated before the event is considered ended.

cooldown-value

Unsigned Integer64

[0, 18446744073709551615]

150

Per-class cooldown duration in frames.

max-concurrent-events

Unsigned Integer

[1, 4294967295]

4

Maximum number of recording sessions active at the same time. New triggers beyond this limit are dropped and throttle-logged.

event-clip-output-dir

String

—

.

Directory where full PRE/EVENT/POST clips are written.

encoder-mode

Enum

software / vaapi / auto

software

Video encoder backend used to write triggered clips. See Encoder Modes.

drop-log-interval-ms

Unsigned Integer

[0, 4294967295]

1500

Minimum interval between aggregated “events dropped” log messages.

flush-interval-ms

Unsigned Integer

[0, 4294967295]

3000

Maximum stream time between partial writes of a clip that is still being recorded. 0 writes the whole clip when the event ends. Applies to sessions started after the change. See Incremental clip writing.

All properties are readable, writable and can be changed at runtime (e.g. from a Python application via element.set_property(...)), not just from the command line.

Configuration#

Trigger rule and cooldown#

Each target class has its own independent cooldown state. When a qualifying detection for a class arrives and that class is not currently in cooldown, a new trigger fires: the class enters cooldown starting from that frame, and cooldown is not restarted by any further detections of the same class until cooldown-value frames have elapsed since the first detection that started the window.

frame:       0        10       150       200
person:   trigger   (in cooldown, ignored)  trigger   (in cooldown, ignored)

With cooldown-value=100, a trigger at frame 0 suppresses further “person” triggers until frame 100; a detection at frame 150 fires a new trigger and restarts the window from 150, so a detection at frame 200 is suppressed again.

Pre/event/post-event window#

The frames written to disk for one session are, in order: exactly pre-event-frames preceding frames, the triggering frame, all frames while the target class is detected, and post-event-frames after the event ends. A matching detection resets the event-gap counter; the event ends only after more than event-gap-frames consecutive frames lack a qualifying detection. Those tolerated gap frames remain part of the clip, and POST starts on the first frame beyond the gap allowance.

The element does not wait for the pre-event ring to fill. If a target is detected during startup, it is recorded immediately with a partial (possibly empty) PRE section. Once the ring is full, subsequent sessions include the complete configured PRE window.

The shared ring buffer keeps sliding throughout, so overlapping sessions for different classes are supported and do not interfere with each other.

Downstream event stream#

The recorder starts forwarding as soon as a trigger is accepted, without waiting for the event or POST to finish. It first replays the available PRE frames, then forwards the trigger frame and subsequent EVENT and POST frames. It drops unrelated input frames after POST ends. There is no one-frame forwarding delay.

A DISCONT flag marks the first forwarded buffer of a new window, including PRE, so gvaframeselect resets its sub-stream sampling window. Original buffer timestamps and durations are preserved. For clock-synchronized downstream sinks, account for the PRE delay in the application; sync=false is suitable for offline consumers.

If recording sessions overlap, each disk clip still contains its own complete PRE/EVENT/POST sequence. Downstream receives their chronological union, without duplicate buffers or timestamp rewinds. PRE frames already sent for an earlier window are not sent again. The recorder writes no separate EVENT-only files; downstream-output-dir has been removed.

... ! gvadetect ... ! gvaeventrecorder target-classes=person ! \
  gvaframeselect sub-stream-frames=900 frame-budget=8 ! \
  videoconvert ! video/x-raw,format=RGB ! \
  gvaroiscale out-width=448 out-height=448 ! gvagenai ...

Clip filenames#

Each clip is an MP4 file whose name contains the triggering class, the UTC session start time, and a six-digit per-element counter. For example, the full clip of a person event is written to event-clip-output-dir as:

event_person_20261015T142301Z_000003.mp4

Encoder modes#

Value

Behavior

software (default)

Uses a software encoder (x264enc). Keeps the GPU completely free, useful when the GPU is dedicated to a downstream VLM.

vaapi

Uses the hardware VA-API encoder (vah264enc), which runs on the GPU’s fixed-function media engine rather than its compute/EU array.

auto

Uses vaapi if the vah264enc factory is available, falls back to software otherwise.

Metadata#

Forwarded PRE/EVENT/POST buffers carry frame-level GstAnalyticsClsMtd entries in their GstAnalyticsRelationMeta. They are not related to any GstAnalyticsODMtd and are identified by their semantic tag:

Semantic tag

Labels

Present on

event

start, continue or stop (confidence 1.0)

every forwarded PRE/EVENT/POST buffer

event_trigger

class(es) that started a recording session, with their confidence

frames that start one or more sessions

start marks the first forwarded frame of a window (normally its oldest PRE frame), continue the frames after it, and stop the final POST frame when no other session remains active. Trigger metadata remains on the actual detection frame, not the first PRE frame. If a window has only one frame, that frame gets stop. Buffers are sent immediately; if EOS interrupts an active window, its already-forwarded last buffer cannot be relabeled stop. The EOS event terminates downstream in that case, and the partial clip is saved on stop.

Place gvametaconvert after the recorder to serialize the entries to JSON; each frame then contains a full-frame object such as:

{
  "x": 0, "y": 0, "w": 1920, "h": 1080,
  "classification/event": { "label": "start", "confidence": 1.0 },
  "classification/event_trigger": { "label": "person", "confidence": 0.87 }
}

If one frame triggers several classes (e.g. person and vehicle), the event_trigger entry holds all of them; gvametaconvert joins their labels and reports the highest confidence.

Pipeline Examples#

Detection on NPU, event recording, VLM on GPU#

gst-launch-1.0 -v \
    filesrc location=input.mp4 ! decodebin3 ! videoconvert ! \
    gvadetect model=d-fine-int8.xml device=NPU ! queue ! \
    gvaeventrecorder target-classes=person,vehicle confidence-threshold=0.6 \
             pre-event-frames=30 post-event-frames=30 event-gap-frames=3 \
                     cooldown-value=150 \
                     event-clip-output-dir=./events ! \
    gvagenai model-path=$mVLM device=GPU prompt="Describe what is happening." ! \
    gvametaconvert format=json ! gvametapublish file-format=2 file-path=results.json ! \
    fakesink

Inspecting dropped vs. forwarded frames#

gst-launch-1.0 -v \
    filesrc location=input.mp4 ! decodebin3 ! videoconvert ! \
    gvadetect model=$mDetect device=GPU ! queue ! \
    gvaeventrecorder target-classes=person max-concurrent-events=2 ! \
    fakesink

For a runnable command-line example, see the gvaeventrecorder sample.

Logging#

To write debug messages from gvaeventrecorder to a file, prefix your pipeline command with:

GST_DEBUG=gvaeventrecorder:5 \
GST_DEBUG_FILE="/path/to/gvaeventrecorder.log" \
gst-launch-1.0 ...

Replace /path/to/gvaeventrecorder.log with the desired log file path and ... with your pipeline. The parent directory must already exist and be writable.

  • GST_DEBUG=gvaeventrecorder:5 enables messages up to DEBUG level for the gvaeventrecorder category.

  • GST_DEBUG_FILE sends GStreamer debug messages to the specified file instead of standard error. It does not redirect regular gst-launch-1.0 output.

Notes#

  • The pre-event ring is never reset by a trigger. A trigger only takes a snapshot of it; the ring keeps accumulating frames so the element is ready for the next event. A trigger during startup uses the frames available so far; later triggers get all pre-event-frames.

  • GPU stays free by default. encoder-mode defaults to software so clip encoding does not compete with a GPU-resident VLM; switch to vaapi deliberately if that trade-off is acceptable for your deployment.

  • Disk writes never block the streaming thread. A single background worker opens, feeds, and finalizes the clip pipelines in order; the number of simultaneously recorded sessions is bounded by max-concurrent-events, not by one thread per session.

  • Overflow policy: once max-concurrent-events is reached, new triggers are dropped (not queued) and aggregated into a single throttled GST_WARNING log line at most every drop-log-interval-ms, with a final flush when the element stops.

  • On EOS/stop, sessions still in their post-event window are finalized and written with whatever frames they collected so far, rather than discarded.

Element Details (gst-inspect-1.0)#

Pad Templates:
  SINK template: 'sink'
    Availability: Always
    Capabilities:
      video/x-raw
                 format: { (string)BGRx, (string)BGRA, (string)BGR, (string)NV12, (string)I420 }
      video/x-raw(memory:DMABuf)
                 format: { (string)DMA_DRM }
      video/x-raw(memory:VASurface)
                 format: { (string)NV12 }
      video/x-raw(memory:VAMemory)
                 format: { (string)NV12 }

  SRC template: 'src'
    Availability: Always
    Capabilities:
      video/x-raw
                 format: { (string)BGRx, (string)BGRA, (string)BGR, (string)NV12, (string)I420 }
      video/x-raw(memory:DMABuf)
                 format: { (string)DMA_DRM }
      video/x-raw(memory:VASurface)
                 format: { (string)NV12 }
      video/x-raw(memory:VAMemory)
                 format: { (string)NV12 }

Element has no clocking capabilities.
Element has no URI handling capabilities.

Pads:
  SINK: 'sink'
    Pad Template: 'sink'
  SRC: 'src'
    Pad Template: 'src'

Element Properties:

  confidence-threshold: Minimum detection confidence required to trigger
                        flags: readable, writable
                        Double. Range:               0 -               1 Default:             0.5
  cooldown-value      : Per-class cooldown duration in frames, counted from the frame that started the window
                        flags: readable, writable
                        Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 150
  drop-log-interval-ms: Minimum interval between aggregated 'events dropped' log messages
                        flags: readable, writable
                        Unsigned Integer. Range: 0 - 4294967295 Default: 1500
  event-gap-frames    : Consecutive frames without a matching detection tolerated before the event is considered ended
                        flags: readable, writable
                        Unsigned Integer. Range: 0 - 4294967295 Default: 3
  encoder-mode        : Video encoder backend used to write triggered clips
                        flags: readable, writable
                        Enum "GstGvaEventRecorderEncoderMode" Default: 0, "software"
                           (0): software          - Software encoder (x264), keeps the GPU free
                           (1): vaapi             - Hardware VA-API encoder (GPU media engine)
                           (2): auto              - VA-API if available, software fallback otherwise
  flush-interval-ms   : Write event clips incrementally as fragmented MP4: PRE frames are flushed to disk at the
                        trigger, then the clip is flushed at least every this many milliseconds of stream time
                        while recording. 0 = write the whole clip as a regular MP4 when the event ends.
                        Applies to sessions started after the change
                        flags: readable, writable
                        Unsigned Integer. Range: 0 - 4294967295 Default: 3000
  max-concurrent-events: Maximum number of recording sessions active at the same time; new triggers
                        beyond this limit are dropped (and throttle-logged)
                        flags: readable, writable
                        Unsigned Integer. Range: 1 - 4294967295 Default: 4
  event-clip-output-dir: Directory where full PRE/EVENT/POST clips are written
                        flags: readable, writable
                        String. Default: "."
  post-event-frames   : Number of frames to keep capturing after the detected event has ended
                        flags: readable, writable
                        Unsigned Integer. Range: 0 - 4294967295 Default: 30
  pre-event-frames    : Number of frames preceding a trigger to keep in the shared ring buffer
                        flags: readable, writable
                        Unsigned Integer. Range: 0 - 4294967295 Default: 30
  target-classes      : Comma-separated detection labels that trigger a recording (e.g. "person,vehicle")
                        flags: readable, writable
                        String. Default: "person,vehicle"
  name                : The name of the object
                        flags: readable, writable
                        String. Default: "gvaeventrecorder0"
  parent              : The parent of the object
                        flags: readable, writable
                        Object of type "GstObject"
  qos                 : Handle Quality-of-Service events
                        flags: readable, writable
                        Boolean. Default: false