Data track schema metadata

CMakeLists.txt

@@ -376,6 +376,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,90 @@
+/*
+ * 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>
+
+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.
+ */
+enum class DataTrackSchemaEncoding {
+  /** 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 encoding not known to this client version. */
+  Other,
+};
+
+/**
+ * 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).
+ */
+enum class DataTrackFrameEncoding {
+  /** 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 encoding not known to this client version. */
+  Other,
+};
+
+/**
+ * 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(DataTrackSchemaEncoding in);
+DataTrackSchemaEncoding fromProto(proto::DataTrackSchemaEncoding in);
+
+proto::DataTrackFrameEncoding toProto(DataTrackFrameEncoding in);
+DataTrackFrameEncoding fromProto(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