Data track schema metadata

.github/workflows/tests.yml

@@ -219,9 +219,13 @@ jobs:
       - name: Start livekit-server
         if: matrix.e2e-testing
         id: livekit_server
-        uses: livekit/dev-server-action@61e2b4dcb170dd3591e0c9b0db3c3fe5db93b500
+        uses: livekit/dev-server-action@6562d7d9343e46c26ead1223151f64f00e4fc37f # v1.1.0
         with:
           github-token: ${{ github.token }}
+          version: a47e21b6cb945aabee88c98650366cef8cbf7a99
+          config: |
+            enable_data_tracks: true
+            enable_participant_data_blob: true
 
       # Needed by token helper script
       - name: Install livekit-cli

CMakeLists.txt

@@ -378,6 +378,7 @@ add_library(livekit SHARED
   src/data_track_frame.cpp
   src/data_stream.cpp
   src/data_track_error.cpp
+  src/data_track_schema.cpp
   src/data_track_stream.cpp
   src/e2ee.cpp
   src/ffi_handle.cpp

include/livekit/data_track_info.h

@@ -16,8 +16,11 @@
 
 #pragma once
 
+#include <optional>
 #include <string>
 
+#include "livekit/data_track_schema.h"
+
 namespace livekit {
 
 /// Metadata about a published data track.
@@ -33,6 +36,12 @@ struct DataTrackInfo {
 
   /// Whether frames on this track use end-to-end encryption.
   bool uses_e2ee = false;
+
+  /// Schema associated with frames sent on the track, if any.
+  std::optional<DataTrackSchemaId> schema;
+
+  /// Encoding of frames sent on the track, if specified.
+  std::optional<DataTrackFrameEncoding> frame_encoding;
 };
 
 } // namespace livekit

include/livekit/data_track_options.h

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <optional>
+#include <string>
+
+#include "livekit/data_track_schema.h"
+
+namespace livekit {
+
+/**
+ * Options for publishing a data track.
+ *
+ * The schema and frame encoding are optional metadata advertised to
+ * subscribers; they are surfaced on the subscriber side via DataTrackInfo.
+ */
+struct DataTrackPublishOptions {
+  /// Track name used to identify the track to other participants.
+  ///
+  /// Must not be empty and must be unique per publisher.
+  std::string name;
+
+  /// Schema describing frames sent on the track, if any.
+  std::optional<DataTrackSchemaId> schema;
+
+  /// Encoding of frames sent on the track, if any.
+  std::optional<DataTrackFrameEncoding> frame_encoding;
+};
+
+} // namespace livekit

include/livekit/data_track_schema.h

@@ -0,0 +1,189 @@
+/*
+ * Copyright 2026 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <string>
+#include <utility>
+
+namespace livekit {
+
+/**
+ * Encoding used to interpret a data track schema definition.
+ *
+ * Identifies the interface definition language the schema is written in (e.g. a
+ * `.proto` file for \ref DataTrackSchemaEncoding::Protobuf), which in turn
+ * dictates the wire format of the frames the schema describes.
+ *
+ * Almost all schemas use a well-known encoding, which converts implicitly:
+ * \code
+ *   DataTrackSchemaEncoding encoding = DataTrackSchemaEncoding::Protobuf;
+ * \endcode
+ * For the uncommon case of an encoding outside the well-known set, use
+ * \ref DataTrackSchemaEncoding::custom.
+ */
+class DataTrackSchemaEncoding {
+public:
+  /** Well-known schema encodings. */
+  enum WellKnown {
+    /** Protocol Buffer IDL. */
+    Protobuf,
+    /** FlatBuffer IDL. */
+    Flatbuffer,
+    /** ROS 1 Message. */
+    Ros1Msg,
+    /** ROS 2 Message. */
+    Ros2Msg,
+    /** ROS 2 IDL. */
+    Ros2Idl,
+    /** OMG IDL. */
+    OmgIdl,
+    /** JSON Schema. */
+    JsonSchema,
+    /** Another well-known encoding not known to this client version. */
+    Other,
+  };
+
+  /** Constructs a well-known encoding. Implicit by design, for the common case. */
+  DataTrackSchemaEncoding(WellKnown wellKnown) : well_known_(wellKnown) {}
+
+  /**
+   * Constructs a custom, application-defined encoding.
+   *
+   * Prefer a well-known encoding wherever one applies. The identifier must be
+   * non-empty and no longer than 25 characters.
+   */
+  static DataTrackSchemaEncoding custom(std::string identifier) {
+    DataTrackSchemaEncoding encoding;
+    encoding.custom_ = std::move(identifier);
+    return encoding;
+  }
+
+  /** Whether this is a custom encoding rather than a well-known one. */
+  bool isCustom() const { return !custom_.empty(); }
+
+  /** The well-known encoding. Only meaningful when \ref isCustom is false. */
+  WellKnown wellKnown() const { return well_known_; }
+
+  /** The custom identifier. Empty when \ref isCustom is false. */
+  const std::string& customIdentifier() const { return custom_; }
+
+private:
+  DataTrackSchemaEncoding() = default;
+
+  WellKnown well_known_ = Other;
+  std::string custom_;
+};
+
+inline bool operator==(const DataTrackSchemaEncoding& a, const DataTrackSchemaEncoding& b) {
+  if (a.isCustom() || b.isCustom()) {
+    return a.customIdentifier() == b.customIdentifier();
+  }
+  return a.wellKnown() == b.wellKnown();
+}
+inline bool operator!=(const DataTrackSchemaEncoding& a, const DataTrackSchemaEncoding& b) { return !(a == b); }
+
+/**
+ * Encoding used for frames sent on a data track.
+ *
+ * The serialization format of the frame bytes (e.g.
+ * \ref DataTrackFrameEncoding::Protobuf); the structure of those bytes is
+ * described by a schema (see \ref DataTrackSchemaEncoding).
+ *
+ * Almost all tracks use a well-known encoding, which converts implicitly:
+ * \code
+ *   options.frame_encoding = DataTrackFrameEncoding::Json;
+ * \endcode
+ * For the uncommon case of an encoding outside the well-known set, use
+ * \ref DataTrackFrameEncoding::custom.
+ */
+class DataTrackFrameEncoding {
+public:
+  /** Well-known frame encodings. */
+  enum WellKnown {
+    /** ROS 1, described by a Ros1Msg schema. */
+    Ros1,
+    /** CDR, described by a Ros2Msg, Ros2Idl, or OmgIdl schema. */
+    Cdr,
+    /** Protocol Buffer, described by a Protobuf schema. */
+    Protobuf,
+    /** FlatBuffer, described by a Flatbuffer schema. */
+    Flatbuffer,
+    /** CBOR, self-describing. */
+    Cbor,
+    /** MessagePack, self-describing. */
+    Msgpack,
+    /** JSON, self-describing or described by a JsonSchema schema. */
+    Json,
+    /** Another well-known encoding not known to this client version. */
+    Other,
+  };
+
+  /** Constructs a well-known encoding. Implicit by design, for the common case. */
+  DataTrackFrameEncoding(WellKnown wellKnown) : well_known_(wellKnown) {}
+
+  /**
+   * Constructs a custom, application-defined encoding.
+   *
+   * Prefer a well-known encoding wherever one applies. The identifier must be
+   * non-empty and no longer than 25 characters.
+   */
+  static DataTrackFrameEncoding custom(std::string identifier) {
+    DataTrackFrameEncoding encoding;
+    encoding.custom_ = std::move(identifier);
+    return encoding;
+  }
+
+  /** Whether this is a custom encoding rather than a well-known one. */
+  bool isCustom() const { return !custom_.empty(); }
+
+  /** The well-known encoding. Only meaningful when \ref isCustom is false. */
+  WellKnown wellKnown() const { return well_known_; }
+
+  /** The custom identifier. Empty when \ref isCustom is false. */
+  const std::string& customIdentifier() const { return custom_; }
+
+private:
+  DataTrackFrameEncoding() = default;
+
+  WellKnown well_known_ = Other;
+  std::string custom_;
+};
+
+inline bool operator==(const DataTrackFrameEncoding& a, const DataTrackFrameEncoding& b) {
+  if (a.isCustom() || b.isCustom()) {
+    return a.customIdentifier() == b.customIdentifier();
+  }
+  return a.wellKnown() == b.wellKnown();
+}
+inline bool operator!=(const DataTrackFrameEncoding& a, const DataTrackFrameEncoding& b) { return !(a == b); }
+
+/**
+ * Uniquely identifies a data track schema.
+ *
+ * A compound identifier with two components: a name and an encoding. Two IDs are
+ * equal only if both components match; the same name with a different encoding
+ * refers to a distinct schema.
+ */
+struct DataTrackSchemaId {
+  /** Name component of the schema identifier. */
+  std::string name;
+
+  /** Encoding of the schema definition. */
+  DataTrackSchemaEncoding encoding = DataTrackSchemaEncoding::Other;
+};
+
+} // namespace livekit

include/livekit/local_participant.h

@@ -26,6 +26,8 @@
 #include <unordered_map>
 #include <vector>
 
+#include "livekit/data_track_options.h"
+#include "livekit/data_track_schema.h"
 #include "livekit/ffi_handle.h"
 #include "livekit/local_audio_track.h"
 #include "livekit/local_data_track.h"
@@ -172,6 +174,18 @@ class LIVEKIT_API LocalParticipant : public Participant {
   ///         publication failed.
   Result<std::shared_ptr<LocalDataTrack>, PublishDataTrackError> publishDataTrack(const std::string& name);
 
+  /// Publish a data track to the room with explicit options.
+  ///
+  /// Like publishDataTrack(const std::string&), but also lets the publisher
+  /// advertise an optional schema and frame encoding as metadata. These are
+  /// surfaced to subscribers via the remote DataTrackInfo.
+  ///
+  /// @param options  Track name plus optional schema / frame encoding.
+  /// @return The published track on success, or a typed error describing why
+  ///         publication failed.
+  Result<std::shared_ptr<LocalDataTrack>, PublishDataTrackError> publishDataTrack(
+      const DataTrackPublishOptions& options);
+
   /// Unpublish a data track from the room.
   ///
   /// Delegates to LocalDataTrack::unpublishDataTrack(). After this call,
@@ -180,6 +194,39 @@ class LIVEKIT_API LocalParticipant : public Participant {
   /// @param track  The data track to unpublish. Null is ignored.
   void unpublishDataTrack(const std::shared_ptr<LocalDataTrack>& track);
 
+  /// Store the definition of a data track schema.
+  ///
+  /// Called by a publisher to make a schema available to subscribers, who can
+  /// later look up its definition via getSchema(). Define a schema before
+  /// publishing any data track that references it, so subscribers can resolve
+  /// the schema by its ID.
+  ///
+  /// A schema can only be defined once. Attempting to redefine an existing
+  /// schema fails.
+  ///
+  /// @param id          Identifies the schema (name and encoding).
+  /// @param definition  The schema definition, stored as-is. It is neither
+  ///                    parsed nor validated against its encoding, so the
+  ///                    caller is responsible for ensuring it is well-formed.
+  ///
+  /// @throws std::runtime_error If the schema could not be defined or the FFI
+  ///                            call fails.
+  void defineSchema(const DataTrackSchemaId& id, const std::string& definition);
+
+  /// Retrieve the definition for a data track schema.
+  ///
+  /// Called by a subscriber that wants to inspect the schema a participant
+  /// defined (see defineSchema()) for a data track it is publishing.
+  ///
+  /// @param id                    Identifies the schema to retrieve.
+  /// @param participant_identity  Identity of the participant that defined the
+  ///                              schema.
+  /// @return The schema definition.
+  ///
+  /// @throws std::runtime_error If the participant has not defined a schema
+  ///                            with this ID or the FFI call fails.
+  std::string getSchema(const DataTrackSchemaId& id, const std::string& participant_identity);
+
   /// Initiate an RPC call to a remote participant.
   ///
   /// @param destination_identity  Identity of the destination participant.

src/data_track_proto_converter.h

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "data_track.pb.h"
+#include "livekit/data_track_info.h"
+#include "livekit/data_track_schema.h"
+
+namespace livekit {
+
+proto::DataTrackSchemaEncoding toProto(const DataTrackSchemaEncoding& in);
+DataTrackSchemaEncoding fromProto(const proto::DataTrackSchemaEncoding& in);
+
+proto::DataTrackFrameEncoding toProto(const DataTrackFrameEncoding& in);
+DataTrackFrameEncoding fromProto(const proto::DataTrackFrameEncoding& in);
+
+proto::DataTrackSchemaId toProto(const DataTrackSchemaId& in);
+DataTrackSchemaId fromProto(const proto::DataTrackSchemaId& in);
+
+// Converts an FFI data track info message into the public DataTrackInfo struct.
+DataTrackInfo fromProto(const proto::DataTrackInfo& in);
+
+} // namespace livekit