RidgeRun Metadata/RidgeRun Metadata Catalog/OBU
 | The RidgeRun Metadata documentation from RidgeRun is presently being developed. |
Introduction
GstOBUMetadata is a GStreamer plugin developed by RidgeRun to handle the insertion and extraction of metadata in AV1 video streams. At a higher level, AV1 video data is organized into Open Bitstream Units (OBUs), and these units can carry metadata. The plugin injects and extracts user-defined metadata into these OBUs, enabling frame-level synchronization without affecting standard decoding or playback.
The main elements of the plugin are obuinject (for injecting metadata) and obuextract (for extracting it). Additional elements act as helpers for testing or for specific use cases, complementing the core functionality.
The plugin provides elements to manage both injection and extraction of metadata:
- ObuInject: Inserts metadata into the AV1 bitstream. Metadata can be provided as a string (via the
metadataproperty, inserted once each time the property is set), as binary data (via themetadata-binaryproperty), or as aGstMetabuffer attachment. TheObuMetaTesterelement can be used to generateGstMetamessages, which are then injected into the AV1 buffer byObuInject. - ObuExtract: Extracts metadata from the AV1 bitstream and attaches it as
GstObuMetato the output buffer. It also includes a signal property to emit metadata messages for external handling.
This design allows developers to embed telemetry, timecodes, annotations, or any custom data directly in AV1 streams and later recover them reliably.
Supported Protocols and Containers
Like SEI-based metadata, GstOBUMetadata is container- and protocol-agnostic, since metadata is embedded inside AV1 OBUs themselves. This means it can be used in a wide range of storage and streaming scenarios, including:
- MP4 / ISOBMFF – the most common container for AV1 storage and playback.
- Matroska / WebM – widely used in browsers and web streaming applications. WebM is a natural fit for AV1 + OBU workflows.
This flexibility ensures smooth metadata handling across different delivery methods without requiring special adaptations, as long as the underlying container or protocol supports AV1 within GStreamer.
Benefits and Limitations
| Category | Item | Description |
|---|---|---|
| Benefits | Precise synchronization | Metadata is embedded directly in OBUs, ensuring one-to-one correspondence with video frames. |
| Portable | Works with any container or protocol that supports AV1, without extra layers. | |
| Standards-compliant | Decoders or players that ignore metadata will continue normal playback. | |
| Flexible | Metadata remains intact when recording, retransmitting, or storing the video in different formats. | |
| Advanced use cases | Ideal for telemetry, closed captions, annotations, timecodes, and analytics in AV1-based applications (e.g., web streaming, video conferencing). | |
| Non-intrusive | Provides great flexibility since the video can be recorded or streamed without loss of information. | |
| Limitations | Limited player support | While metadata persists, not all players (e.g., browsers, commercial video players) expose it. |
| Pipeline control required | Extraction requires the ObuExtract element; not transparent outside GStreamer.
| |
| Codec-specific | Applicable only to AV1 streams; not usable with H.264, H.265, VP9, or older AV1 profiles without extended OBU support. |
Examples
- ObuInject – UDP streaming with metadata insertion
gst-launch-1.0 videotestsrc is-live=true num-buffers=15 ! "video/x-raw, width=320, height=240" ! av1enc cpu-used=8 ! obuinject metadata="Hello World" ! qtmux ! udpsink host=127.0.0.1 port=5000 -v
- ObuExtract – extracting metadata on client side
GST_DEBUG=*obu*:MEMDUMP gst-launch-1.0 udpsrc port=5000 ! qtdemux ! obuextract ! fakesink silent=false -v
- ObuMetaTester + ObuInject – testing metadata injection
gst-launch-1.0 videotestsrc is-live=true num-buffers=10 ! "video/x-raw, width=320, height=240" ! av1enc cpu-used=8 ! obumetatester ! obuinject ! qtmux ! udpsink host=127.0.0.1 port=5000 -v
Documentation
