Make SAP tracks opt-in

Author: mondain

README.md

@@ -12,6 +12,7 @@ It packages MP4 input into CMSF-style publishable objects, supports MOQT draft-s
 - Builds a publish plan with catalog, SAP event timeline, and media objects
 - Emits generated objects and catalog metadata to disk for inspection
 - Supports a configurable track namespace, optional paced publication, and draft-aware MOQT control/object encoding
+- Can optionally add per-track SAP event timeline metadata with a CLI flag
 - Includes packaging, CLI, and MOQT session tests through CTest
 
 ## Design overview
@@ -102,6 +103,34 @@ Useful CMake options:
 - `-DOPENMOQ_PICOQUIC_SOURCE_DIR=/path/to/picoquic`
 - `-DOPENMOQ_RUN_PICOQUIC_SMOKE_TESTS=ON|OFF`
 
+## Quick Start
+
+If you already have a sample MP4 and just want to see what the publisher does, these are the most useful first commands:
+
+Inspect the publish plan with the default settings:
+
+```bash
+./build/openmoq-publisher --input sample.mp4 --dump-plan
+```
+
+Inspect the same input with SAP event timeline metadata enabled:
+
+```bash
+./build/openmoq-publisher --input sample.mp4 --sap --dump-plan
+```
+
+Emit the catalog and media objects to disk:
+
+```bash
+./build/openmoq-publisher --input sample.mp4 --emit-dir out/
+```
+
+Stream the input over stdin instead of reading it from a file path:
+
+```bash
+cat sample.mp4 | ./build/openmoq-publisher --input - --dump-plan
+```
+
 ## How To Test
 
 ### Packaging and session tests
@@ -130,6 +159,7 @@ Publish-plan numbering note:
 - `group_id` is allocated per track, not across all tracks, so interleaved audio and video fragments can both use `0, 1, 2, ...`
 - by default, `object_id` advances within a group when CMAF content is split into multiple MOQT objects for lower latency
 - `--coalesce-cmaf-chunks` forces `object_id = 0` for the current one-object-per-group fallback
+- SAP event timeline tracks are disabled by default; add `--sap` when you want catalog and metadata objects for `*_sap` tracks
 
 If you want the packaging and transport tests without the CLI target, use the secondary build tree:
 
@@ -162,13 +192,26 @@ Input source note:
 - `--input <path>` reads an MP4 from a regular file
 - `--input -` reads the MP4 byte stream from standard input, which allows `cat`, `ffmpeg`, or other producer pipelines to feed the publisher directly
 - fragmented and progressive MP4 inputs are both supported through either source type
+- SAP event timeline tracks are disabled by default; add `--sap` to include `*_sap` metadata tracks and objects in the publish plan
 
 Use `--dump-plan` to inspect the generated publish plan without touching the network:
 
 ```bash
 ./build/openmoq-publisher --input sample.mp4 --draft 14 --dump-plan
 ```
 
+Include SAP event timeline output explicitly:
+
+```bash
+./build/openmoq-publisher --input sample.mp4 --draft 14 --sap --dump-plan
+```
+
+The difference is:
+
+- default output includes the `catalog` object plus media objects
+- `--sap` additionally creates `*_sap` metadata tracks and objects
+- this affects both `--dump-plan` output and emitted files under `--emit-dir`
+
 Use stdin when the source is already being produced by another command:
 
 ```bash
@@ -192,15 +235,24 @@ Use `--emit-dir` to inspect the emitted catalog and media objects on disk:
 ./build/openmoq-publisher --input sample.mp4 --draft 14 --emit-dir out/
 ```
 
+Emit the same plan with SAP metadata enabled:
+
+```bash
+./build/openmoq-publisher --input sample.mp4 --draft 14 --sap --emit-dir out/
+```
+
 The output directory should contain:
 
 - `catalog.json`
-- one `*_sap_g*_o*.json` file per emitted SAP event timeline object
 - one `*_init.mp4` file per media track
 - one `*_media.mp4` file per emitted media object
 - one `*_probe.mp4` file per emitted media object for direct `ffprobe` use
 - `publish-plan.txt`
 
+When `--sap` is enabled, the output directory also contains:
+
+- one `*_sap_g*_o*.json` file per emitted SAP event timeline object
+
 The catalog format includes:
 
 - `role` with values such as `video` and `audio`
@@ -211,6 +263,13 @@ The catalog format includes:
 - `sampleRate` and `channelCount` for audio tracks
 - base64-encoded per-track CMAF initialization segment (`ftyp` + `moov`) in `initData`
 
+When `--sap` is enabled, `catalog.json` also includes:
+
+- one `*_sap` track per media track
+- `packaging: "eventtimeline"`
+- `eventType: "org.ietf.moq.cmsf.sap"`
+- `depends` pointing back to the corresponding media track
+
 ### Relay interoperability test
 
 To attempt a live publish against a relay:
@@ -226,6 +285,20 @@ OPENMOQ_PICOQUIC_TRACE=1 ./build/openmoq-publisher \
   --insecure
 ```
 
+Publish the same stream with SAP timeline tracks included:
+
+```bash
+OPENMOQ_PICOQUIC_TRACE=1 ./build/openmoq-publisher \
+  --input sample.mp4 \
+  --endpoint moqt://interop-relay.cloudflare.mediaoverquic.com:443/moq \
+  --namespace interop \
+  --forward 0 \
+  --timeout 10 \
+  --paced \
+  --sap \
+  --insecure
+```
+
 If you need to connect to a relay by IP while still presenting the relay hostname in TLS SNI:
 
 ```bash
@@ -244,6 +317,7 @@ Behavior notes:
 - `--forward 0` waits for inbound `SUBSCRIBE` requests before sending matching media objects
 - with `--forward 0`, subscribers are still expected to request tracks explicitly; by default that includes subscribing to `catalog` if they need track discovery
 - `--publish-catalog` keeps `--forward 0` for media tracks but proactively publishes the `catalog` track through the normal `PUBLISH` / `PUBLISH_OK` path so downstream consumers can discover available tracks without first subscribing to `catalog`
+- `--sap` adds per-track `*_sap` event timeline tracks and metadata objects; by default those tracks are not created
 - media packaging defaults to lower-latency split MOQT objects per group when chunk/sample boundaries are available
 - `--coalesce-cmaf-chunks` disables that split and falls back to one media object per group
 - when multiple tracks are subscribed, matching objects are served in publish-plan order so time-aligned audio/video stay interleaved instead of draining one track before the next
@@ -272,12 +346,24 @@ Inspect the publish plan for an already fragmented MP4:
 ./build/openmoq-publisher --input sample-fragmented.mp4 --draft 14 --dump-plan
 ```
 
+Inspect the same fragmented MP4 with SAP metadata enabled:
+
+```bash
+./build/openmoq-publisher --input sample-fragmented.mp4 --draft 14 --sap --dump-plan
+```
+
 Emit object payloads for a progressive MP4 after remux:
 
 ```bash
 ./build/openmoq-publisher --input sample-progressive.mp4 --draft 14 --emit-dir out/
 ```
 
+Emit a progressive MP4 after remux with SAP metadata enabled:
+
+```bash
+./build/openmoq-publisher --input sample-progressive.mp4 --draft 14 --sap --emit-dir out/
+```
+
 Try the draft-16 compatibility profile:
 
 ```bash
@@ -297,6 +383,20 @@ Transport-oriented CLI flags are also present now:
   --insecure
 ```
 
+If you want subscribers or downstream tools to see SAP event timeline tracks, add `--sap`:
+
+```bash
+./build/openmoq-publisher \
+  --input sample.mp4 \
+  --endpoint localhost:4433 \
+  --namespace media \
+  --forward 0 \
+  --timeout 3 \
+  --paced \
+  --sap \
+  --insecure
+```
+
 The same CLI accepts stdin for transport publishing as well:
 
 ```bash
@@ -315,6 +415,11 @@ Chunk/object mapping:
 - default behavior is lower-latency split publication, which emits multiple MOQT objects in the same group when CMAF chunk/sample boundaries are available
 - `--coalesce-cmaf-chunks` restores one media object per group
 
+SAP metadata:
+
+- by default the catalog only includes media tracks plus the top-level `catalog` object
+- `--sap` adds per-track `*_sap` event timeline entries to the catalog and emits matching metadata objects
+
 ALPN selection:
 
 - draft-14 defaults to `moq-00`
@@ -324,7 +429,7 @@ ALPN selection:
 Catalog note:
 
 - `catalog.json` uses the CMSF-style `role` field such as `video` and `audio`
-- `catalog.json` also advertises per-track SAP event timeline tracks using CMSF `eventtimeline` metadata
+- with `--sap`, `catalog.json` also advertises per-track SAP event timeline tracks using CMSF `eventtimeline` metadata
 - `publish-plan.txt` and `--dump-plan` still print an internal debug `kind=` label for object type (`catalog`, `metadata`, or `media`); that debug label is not part of the catalog spec
 
 ## Creating Fragmented MP4 with FFmpeg

include/openmoq/publisher/cli_options.h

@@ -30,6 +30,7 @@ struct CliOptions {
     bool endpoint_alpn_overridden = false;
     bool forward = false;
     bool publish_catalog = false;
+    bool include_sap = false;
     bool split_cmaf_chunks = true;
     bool paced = false;
     bool dump_plan = false;

include/openmoq/publisher/cmsf_packager.h

@@ -40,7 +40,7 @@ struct PublishPlan {
     std::vector<CmsfObject> objects;
 };
 
-PublishPlan build_publish_plan(const SegmentedMp4& segmented_mp4, DraftVersion version);
+PublishPlan build_publish_plan(const SegmentedMp4& segmented_mp4, DraftVersion version, bool include_sap = false);
 std::string render_publish_plan(const PublishPlan& plan);
 PublishPlan materialize_publish_plan(const PublishPlan& plan, std::span<const std::uint8_t> bytes);
 void emit_plan_objects(const PublishPlan& plan,

src/cli_options.cpp

@@ -121,6 +121,8 @@ CliOptions parse_cli_options(int argc, char** argv) {
             options.forward = parse_forward_flag(require_value("--forward"));
         } else if (argument == "--publish-catalog") {
             options.publish_catalog = true;
+        } else if (argument == "--sap") {
+            options.include_sap = true;
         } else if (argument == "--coalesce-cmaf-chunks" || argument == "--coalesce-cmaf-chunk") {
             options.split_cmaf_chunks = false;
         } else if (argument == "--timeout") {
@@ -155,7 +157,7 @@ CliOptions parse_cli_options(int argc, char** argv) {
 std::string build_usage(const char* argv0) {
     return std::string("Usage: ") + argv0 +
            " --input <mp4|-> [--draft 14|16] [--namespace <value>] [--forward 0|1] [--timeout <seconds>]"
-           " [--publish-catalog] [--coalesce-cmaf-chunks|--coalesce-cmaf-chunk] [--paced] [--dump-plan] [--emit-dir <dir>]"
+           " [--publish-catalog] [--sap] [--coalesce-cmaf-chunks|--coalesce-cmaf-chunk] [--paced] [--dump-plan] [--emit-dir <dir>]"
            " [--endpoint host:port|moqt://host:port/path] [--alpn value] [--sni value]"
            " [--cert file] [--key file] [--ca file] [--insecure]";
 }

src/cmsf_packager.cpp

@@ -420,21 +420,23 @@ std::vector<std::uint8_t> build_track_codec_init_data(std::span<const std::uint8
 
 }  // namespace
 
-PublishPlan build_publish_plan(const SegmentedMp4& segmented_mp4, DraftVersion version) {
+PublishPlan build_publish_plan(const SegmentedMp4& segmented_mp4, DraftVersion version, bool include_sap) {
     std::vector<TrackDescription> tracks = segmented_mp4.tracks;
-    std::uint32_t synthetic_track_id = next_synthetic_track_id(tracks);
-    for (const auto& media_track : segmented_mp4.tracks) {
-        tracks.push_back(TrackDescription{
-            .track_id = synthetic_track_id++,
-            .handler_type = "meta",
-            .codec = {},
-            .sample_entry_type = "eventtimeline",
-            .track_name = sap_track_name(media_track.track_name),
-            .packaging = "eventtimeline",
-            .event_type = "org.ietf.moq.cmsf.sap",
-            .mime_type = "application/json",
-            .depends = {media_track.track_name},
-        });
+    if (include_sap) {
+        std::uint32_t synthetic_track_id = next_synthetic_track_id(tracks);
+        for (const auto& media_track : segmented_mp4.tracks) {
+            tracks.push_back(TrackDescription{
+                .track_id = synthetic_track_id++,
+                .handler_type = "meta",
+                .codec = {},
+                .sample_entry_type = "eventtimeline",
+                .track_name = sap_track_name(media_track.track_name),
+                .packaging = "eventtimeline",
+                .event_type = "org.ietf.moq.cmsf.sap",
+                .mime_type = "application/json",
+                .depends = {media_track.track_name},
+            });
+        }
     }
     tracks.insert(tracks.begin(), TrackDescription{
                                     .track_id = 0,
@@ -511,18 +513,20 @@ PublishPlan build_publish_plan(const SegmentedMp4& segmented_mp4, DraftVersion v
         });
     }
 
-    for (const auto& media_track : segmented_mp4.tracks) {
-        if (find_track_by_name(plan.tracks, sap_track_name(media_track.track_name)) == nullptr) {
-            continue;
+    if (include_sap) {
+        for (const auto& media_track : segmented_mp4.tracks) {
+            if (find_track_by_name(plan.tracks, sap_track_name(media_track.track_name)) == nullptr) {
+                continue;
+            }
+            plan.objects.push_back({
+                .kind = CmsfObjectKind::kMetadata,
+                .track_name = sap_track_name(media_track.track_name),
+                .group_id = 0,
+                .object_id = 0,
+                .payload = {},
+                .owned_payload = build_sap_timeline_payload(segmented_mp4, media_track),
+            });
         }
-        plan.objects.push_back({
-            .kind = CmsfObjectKind::kMetadata,
-            .track_name = sap_track_name(media_track.track_name),
-            .group_id = 0,
-            .object_id = 0,
-            .payload = {},
-            .owned_payload = build_sap_timeline_payload(segmented_mp4, media_track),
-        });
     }
 
     return plan;

src/main.cpp

@@ -19,7 +19,7 @@ int main(int argc, char** argv) {
         const SegmentedMp4 segmented_mp4 = segment_for_cmaf(parsed_mp4,
                                                             options.split_cmaf_chunks ? CmafObjectMode::kSplit
                                                                                       : CmafObjectMode::kCoalesced);
-        const PublishPlan plan = build_publish_plan(segmented_mp4, options.draft_version);
+        const PublishPlan plan = build_publish_plan(segmented_mp4, options.draft_version, options.include_sap);
 
         if (options.dump_plan || !options.emit_dir.has_value()) {
             std::cout << render_publish_plan(plan);

tests/cli_options_test.cpp

@@ -42,6 +42,7 @@ int main() {
                      "expected file input to remain the default input source kind");
         ok &= expect(options.input_source.path == "sample.mp4",
                      "expected file input path to be preserved");
+        ok &= expect(!options.include_sap, "expected SAP track creation to be disabled by default");
     }
 
     {
@@ -74,6 +75,12 @@ int main() {
         ok &= expect(options.publish_catalog, "expected --publish-catalog to enable proactive catalog publish");
     }
 
+    {
+        const CliOptions options =
+            parse({"openmoq-publisher", "--input", "sample.mp4", "--sap"});
+        ok &= expect(options.include_sap, "expected --sap to enable SAP track creation");
+    }
+
     {
         const CliOptions options =
             parse({"openmoq-publisher", "--input", "sample.mp4", "--coalesce-cmaf-chunks"});