Data track schema metadata

.github/workflows/make-release.yml

@@ -445,11 +445,13 @@
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-  # ---------- Publish Docs Job ----------
-  publish-docs:
-    name: Publish Documentation
+  # Build docs for validation and retain them as a workflow artifact. Publishing
+  # is triggered separately by the GitHub release's authoritative state.
+  generate-docs:
+    name: Generate Documentation
     needs: release
-    uses: ./.github/workflows/publish-docs.yml
+    uses: ./.github/workflows/generate-docs.yml
     with:
       version: ${{ needs.release.outputs.version }}
-    secrets: inherit
+      upload_artifact: true
+      artifact_name: livekit-cpp-docs-${{ github.run_id }}

.github/workflows/publish-docs.yml

@@ -1,18 +1,10 @@
 name: Publish docs
 
 on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Documentation version (e.g. v0.1.0)'
-        required: false
-        type: string
-  workflow_call:
-    inputs:
-      version:
-        description: 'Documentation version (e.g. v0.1.0)'
-        required: false
-        type: string
+  release:
+    # "published" covers newly published stable releases and prereleases.
+    # "released" also catches promotion of an existing prerelease to stable.
+    types: [published, released]
 
 permissions:
   contents: read
@@ -23,7 +15,7 @@ jobs:
     name: Validate (build docs)
     uses: ./.github/workflows/generate-docs.yml
     with:
-      version: ${{ inputs.version || github.event.inputs.version || '' }}
+      version: ${{ github.event.release.tag_name }}
       upload_artifact: true
       # Suffix with run_id so concurrent publish runs cannot collide on the
       # artifact namespace within the same repository.
@@ -32,6 +24,9 @@ jobs:
   publish:
     name: Publish (S3 + CloudFront)
     needs: validate
+    # The GitHub release is the source of truth. Drafts do not emit these
+    # events until published; prereleases validate docs but never deploy them.
+    if: github.event.release.draft == false && github.event.release.prerelease == false
     runs-on: ubuntu-latest
     steps:
       - name: Download docs artifact

.github/workflows/tests.yml

@@ -219,9 +219,12 @@ 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: v1.13.3
+          config: |
+            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,23 +16,32 @@
 
 #pragma once
 
+#include <optional>
 #include <string>
 
+#include "livekit/data_track_schema.h"
+
 namespace livekit {
 
 /// Metadata about a published data track.
 ///
 /// Unlike audio/video tracks, data tracks are not part of the Track class
 /// hierarchy. They carry their own lightweight info struct.
 struct DataTrackInfo {
-  /// Publisher-assigned track name (unique per publisher).
+  /// @brief Publisher-assigned track name, unique per publisher.
   std::string name;
 
   /// SFU-assigned track identifier.
   std::string sid;
 
   /// 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,43 @@
+/*
+ * 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,206 @@
+/*
+ * 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 (for
+/// example, 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,
+  };
+
+  /// Construct a well-known encoding.
+  ///
+  /// The constructor is intentionally implicit for the common well-known case.
+  DataTrackSchemaEncoding(WellKnown wellKnown) : well_known_(wellKnown) {}
+
+  /// Construct 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.
+  ///
+  /// @param identifier Custom encoding identifier.
+  /// @return Custom schema encoding.
+  static DataTrackSchemaEncoding custom(std::string identifier) {
+    DataTrackSchemaEncoding encoding;
+    encoding.custom_ = std::move(identifier);
+    return encoding;
+  }
+
+  /// Check whether this is a custom encoding.
+  ///
+  /// @return true if this is a custom encoding rather than a well-known one.
+  bool isCustom() const { return !custom_.empty(); }
+
+  /// Get the well-known encoding.
+  ///
+  /// @return The well-known encoding. Only meaningful when @ref isCustom is false.
+  WellKnown wellKnown() const { return well_known_; }
+
+  /// Get the custom identifier.
+  ///
+  /// @return 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 (for example,
+/// @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,
+  };
+
+  /// Construct a well-known encoding.
+  ///
+  /// The constructor is intentionally implicit for the common well-known case.
+  DataTrackFrameEncoding(WellKnown wellKnown) : well_known_(wellKnown) {}
+
+  /// Construct 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.
+  ///
+  /// @param identifier Custom encoding identifier.
+  /// @return Custom frame encoding.
+  static DataTrackFrameEncoding custom(std::string identifier) {
+    DataTrackFrameEncoding encoding;
+    encoding.custom_ = std::move(identifier);
+    return encoding;
+  }
+
+  /// Check whether this is a custom encoding.
+  ///
+  /// @return true if this is a custom encoding rather than a well-known one.
+  bool isCustom() const { return !custom_.empty(); }
+
+  /// Get the well-known encoding.
+  ///
+  /// @return The well-known encoding. Only meaningful when @ref isCustom is false.
+  WellKnown wellKnown() const { return well_known_; }
+
+  /// Get the custom identifier.
+  ///
+  /// @return 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;
+};
+
+inline bool operator==(const DataTrackSchemaId& a, const DataTrackSchemaId& b) {
+  return a.name == b.name && a.encoding == b.encoding;
+}
+inline bool operator!=(const DataTrackSchemaId& a, const DataTrackSchemaId& b) { return !(a == b); }
+
+} // namespace livekit