User Metadata Publisher

The MetadataPublisher module in Air SDK enables the attachment and real-time transmission of user-defined metadata to video streams and recordings. This is especially useful when adding contextual data such as inference results, annotations, telemetry, or visual overlays to a live stream or recorded video.

Overview

The MetadataPublisher handles metadata as compact binary blobs — typically serialized using Protocol Buffers — and manages their association with stream or record sources. It also supports callbacks to notify the application logic of incoming metadata, enabling real-time processing and reaction within the mission code (see Metadata Listener for details).

There are two main types of user-defined metadata:

  • Stream metadata: Attached to a live video stream (e.g., “front” stream).

  • Record metadata: Attached to a recording video track (e.g., “DefaultVideo”).

Initialization

You must create a MetadataPublisher instance by passing a unique mission UID (e.g., a string or UUID) and optionally a pomp::Loop object to integrate with an existing event loop. If no loop is provided, the MetadataPublisher will start an internal thread to manage event processing automatically.

airsdk::metadata_publisher::MetadataPublisher publisher(
    "my_mission_uid", myMetadataListener);

Metadata Listener

To receive updates on metadata changes, implement the MetadataPublisherListener interface:

class MyListener : public MetadataPublisherListener {
public:
    void onStreamUserMetadataList(
        std::string resource_path,
        std::vector<StreamUserMetadata> user_metadata) override;

    void onRecordUserMetadataList(
        uint64_t camera_id,
        std::string track_name,
        std::vector<RecordUserMetadata> user_metadata) override;
};

Adding Metadata Descriptors

Before pushing metadata, you must declare it using one of the following:

  • addStreamUserMetadata: Registers a metadata UID for a stream source.

  • addRecordUserMetadata: Registers a metadata UID for a recording source.

Each registration requires specifying a maximum payload size for the metadata type, ensuring proper memory allocation.

publisher.addStreamUserMetadata("boxes", 256, "front");
publisher.addRecordUserMetadata("boxes", 256, 0, "DefaultVideo");

Pushing Metadata

Once registered, you can push data using push().

std::vector<uint8_t> data = ...;
publisher.push("boxes", data.data(), data.size());

This data will be transmitted to the stream/record subscribers (e.g., FreeFlight, Olympe or PDrAW).

Removing Metadata

To remove a previously declared metadata descriptor:

publisher.removeStreamUserMetadata("boxes", "front");
publisher.removeRecordUserMetadata("boxes", 0, "DefaultVideo");

Stopping the Publisher

To properly stop the Publisher:

publisher.stopMetadataPublisher();

This stops the event loop, unregisters all services, and disconnects from the internal message hub.

Thread and Loop Management

  • If you provide your own pomp::Loop, you are responsible for regularly calling loop.waitAndProcess() to process events.

  • If not, the publisher runs an internal event loop on a dedicated thread.

Use Cases

Typical use cases for MetadataPublisher include:

  • Sending neural network detections (e.g., bounding boxes, class IDs, confidence scores).

  • Injecting telemetry data (e.g., altitude, orientation) into a stream.

  • Adding visual overlays or annotations synchronized with stream and/or video recording.

Limitations

  • The maximum payload size for each metadata type is specified at the time of registration to ensure appropriate memory allocation.

  • Each metadata UID must be unique within its associated stream or recording track to prevent conflicts and ensure correct identification.

  • Metadata is transient: it must be refreshed regularly if meant to persist visually.

  • Warning: User metadata adds traffic on the video stream, so it should be kept as lightweight as possible to avoid decreasing stream quality (this applies only to streaming, not recording).

Reference

See airsdk/metadata_publisher/metadata_publisher.hpp for complete API documentation.