Convert MSFTS example to Publisher API

Author: mondain

CMakeLists.txt

@@ -352,6 +352,8 @@ target_link_libraries(openmoq-publisher-auth-example PRIVATE openmoq_publisher_l
 
 include(CTest)
 
+add_subdirectory(examples/msfts-publisher)
+
 if(OPENMOQ_BUILD_TESTS)
     add_executable(openmoq-publisher-packaging-tests
         tests/cmaf_segmenter_test.cpp

README.md

@@ -79,6 +79,24 @@ OPENMOQ_PICOQUIC_TRACE=1 ./build/openmoq-publisher \
   --paced
 ```
 
+Publish a packet-aligned MPEG-2 TS or M2TS file with the MSFTS example:
+
+```bash
+./build/examples/msfts-publisher/openmoq-publisher-msfts-example \
+  --input sample.m2ts \
+  --endpoint https://relay.example.com:443/moq \
+  --namespace media.msfts \
+  --track transport \
+  --draft 17
+```
+
+The example uses the public `Publisher::publish_live_objects(...)` API. It
+discovers PAT/PMT data, selects one program, filters unrelated PIDs, and emits
+the caller-supplied `"m2ts"` catalog required by the text draft in
+`examples/msfts-publisher/docs/`. Add `--program NUMBER` to select a specific
+program, `--packets-per-object COUNT` to change object sizing, or `--insecure`
+only for a relay whose certificate is intentionally untrusted.
+
 Live ingest examples (choose one path):
 
 1. SRT ingest path (`--live-source srt`)

docs/build.md

@@ -29,6 +29,16 @@ The build also produces the reusable publisher API static library:
 
 The CMake target remains `openmoq_publisher_lib`, so projects that include this repository with `add_subdirectory(...)` should link that target. Projects that consume the raw archive directly should add `include/` to their include path and link the same transport dependencies used by the build, especially picoquic, picotls, OpenSSL, and platform socket libraries when picoquic transport support is enabled.
 
+The default build also compiles the MSFTS Publisher API example:
+
+```bash
+cmake --build build --target openmoq-publisher-msfts-example
+./build/examples/msfts-publisher/openmoq-publisher-msfts-example --help
+```
+
+Its CMake target links only `openmoq_publisher_lib`; it does not consume moq5
+or picoquic APIs directly.
+
 ## Build with Local Picoquic and Picotls
 
 By default, CMake looks for:
@@ -98,6 +108,10 @@ reviewed, the backend is selectable:
   is independent of which backend is *selected*.
 - **`-DOPENMOQ_USE_LIBMOQ_PUBLISHER=ON`** — the production `Publisher` routes
   batch, live stdin, live SRT, and `LiveObjectSource` publishing through libmoq.
+- **Caller-supplied catalog exception** — a `LiveObjectSource` using
+  `LiveCatalogMode::kSourceObject` is routed through `MoqtSession` in either
+  configuration. This preserves catalog formats such as MSFTS `"m2ts"` that
+  libmoq's current RAW/CMAF media sender cannot author.
 - **default (`OFF`)** — publishing stays on the legacy MoqtSession path.
 
 Configure-time output reports both, e.g.:

docs/publisher-api.md

@@ -256,6 +256,31 @@ the payload bytes to send. `object_id == 0` starts a group (and is treated as a
 sync point); `final_in_subgroup && subgroup_contains_group_largest` closes the
 group.
 
+### Caller-supplied catalogs
+
+Set `LiveCatalogMode::kSourceObject` when the source must provide a catalog
+whose format cannot be generated from `LiveTrack` media metadata:
+
+```cpp
+openmoq::publisher::LiveObjectSource source;
+source.tracks = {
+    openmoq::publisher::LiveTrack{.track_name = "catalog"},
+    openmoq::publisher::LiveTrack{.track_name = "transport"},
+};
+source.next_object = next_catalog_then_media_object;
+source.catalog_mode =
+    openmoq::publisher::LiveCatalogMode::kSourceObject;
+```
+
+This mode requires exactly one track named `catalog`, at least one non-catalog
+track, and a non-empty catalog as the first returned object. The Publisher uses
+the `MoqtSession` object path for such a source even when the libmoq backend is
+selected, because libmoq currently authors catalogs only for its RAW and CMAF
+media packaging. The MSFTS example under `examples/msfts-publisher` uses this
+mode for `"m2ts"` packaging and supplies packet-size, program/PID, PSI interval,
+random-access, timestamp-mode, and Base64 PAT/PMT `initData` fields from its
+local text draft.
+
 **Demand gating (lazy relays).** When the libmoq backend is selected, the publish
 path waits for at least one downstream media subscriber before producing media —
 a lazy relay forwards a SUBSCRIBE only when a player subscribes. Until then
@@ -270,9 +295,10 @@ interrupted, and the call returns success. For stdin specifically, cancellation
 observed once the current blocking read returns.
 
 > **Legacy note:** bare `LiveTrack{.track_name = ...}` entries with no media
-> metadata (a generic "events"-style object track) are **legacy-only**. They are
-> rejected on the libmoq path with a clear error; to publish such tracks you must
-> inject a custom `TransportFactory`, which forces the older MoqtSession transport.
+> metadata (a generic "events"-style object track) are rejected on the normal
+> libmoq-generated-catalog path. Inject a custom `TransportFactory` for generic
+> legacy object tracks, or use `LiveCatalogMode::kSourceObject` only when the
+> source genuinely supplies the required catalog object.
 
 The fragmented MP4 `publish_live(...)` API remains the default live publishing
 path for media ingest.

docs/testing.md

@@ -21,6 +21,10 @@ This covers:
 - draft-16 LL-DASH await-subscribe behavior with catalog plus multiple FFmpeg-style representation paths
 - multitrack subscribe serving in publish-plan/media-time order rather than draining one track at a time
 - paced send scheduling against fragment media timestamps
+- caller-supplied catalog declaration, ordering, and backend-routing validation
+- MSFTS 188-byte TS and 192-byte M2TS detection, program filtering, rewritten
+  PAT/PMT `initData`, catalog fields, whole-packet object payloads, and invalid
+  partial-packet rejection
 - QUIC varint boundary coverage
 
 Publish-plan numbering notes:
@@ -64,6 +68,23 @@ track/object translation, readiness and demand waits, bounded backpressure
 retries, cancellation, and live-object metadata validation. CMake also detects
 moq5 at `../libmoq`, `third_party/moq5`, and `thirdparty/moq5`.
 
+## MSFTS Example Tests
+
+Build and run the focused MSFTS Publisher API coverage with:
+
+```bash
+cmake --build build --target \
+  openmoq-publisher-msfts-example \
+  openmoq-publisher-msfts-tests
+ctest --test-dir build -R openmoq-publisher-msfts-tests --output-on-failure
+./build/examples/msfts-publisher/openmoq-publisher-msfts-example --help
+```
+
+The tests use synthetic transport streams for both supported source-packet
+sizes and do not require a relay. A live relay run is a separate
+interoperability check and should use a real subscriber before claiming media
+delivery.
+
 ## Picoquic Loopback Smoke Test
 
 When you want to exercise the live QUIC path locally, enable the smoke test target:

examples/msfts-publisher/CMakeLists.txt

@@ -0,0 +1,16 @@
+add_executable(openmoq-publisher-msfts-example
+    main.cpp
+    msfts_options.cpp
+    msfts_source.cpp
+)
+target_link_libraries(openmoq-publisher-msfts-example PRIVATE openmoq_publisher_lib)
+
+if(OPENMOQ_BUILD_TESTS)
+    add_executable(openmoq-publisher-msfts-tests
+        tests/msfts_source_test.cpp
+        msfts_options.cpp
+        msfts_source.cpp
+    )
+    target_link_libraries(openmoq-publisher-msfts-tests PRIVATE openmoq_publisher_lib)
+    add_test(NAME openmoq-publisher-msfts-tests COMMAND openmoq-publisher-msfts-tests)
+endif()