Skip to content
openmoqPublic

About

Origin Publisher for OpenMOQ

Resources

Code of conduct

Contributing

Stars

8 stars

Watchers

0 watching

Forks

Repository files navigation

OpenMOQ Publisher

English | Español | Français | Italiano | 日本語 | Português | 中文

moqxr is a C++20 OpenMOQ publisher for Linux, macOS, and Windows.

It packages file and live media for Media over QUIC Transport (MOQT), builds MSF/CMSF catalogs and publish plans, and publishes through picoquic-backed Raw QUIC or WebTransport connections.

Capabilities

  • Parses fragmented MP4 (ftyp + moov + moof/mdat) and remuxes progressive MP4 into fragmented media objects.
  • Extracts track metadata and RFC 6381 codec identifiers, including HEVC signaling and hev1 to hvc1 normalization.
  • Builds MSF/CMSF version 1 catalogs, initialization data, optional media timelines, and SAP event timelines.
  • Detects and signals existing CMAF CENC content protection for batch input, live fragmented MP4 on stdin, and CTE LL-DASH ingest. It does not encrypt or decrypt media.
  • Emits catalog, initialization, media, probe, and publish-plan files for local inspection.
  • Publishes with the main CLI's supported MOQT draft profiles: draft 16, draft 18, draft 21, draft 22 (default), and draft 23.
  • Publishes over Raw QUIC or WebTransport when picoquic and picotls are available.
  • Accepts live fragmented MP4 from stdin, MPEG-TS over SRT when libsrt is available, and CMAF over HTTP/1.1 CTE LL-DASH ingest (chunked or fixed-length requests).
  • Parses MSF URLs with --url and prints the catalog discovery URL with --print-msf-urls.
  • Supports ordered relay failover with repeated --endpoint options and configurable same-endpoint retries with --retry.
  • Provides C++ Publisher API examples for FFmpeg-generated live media, CAT4MOQ authorization, and MPEG-2 TS/M2TS packaging.
  • Optionally routes publishing through the moq5 C11 Media-over-QUIC library for drafts 16, 18 and 22. Drafts 21 and 23, which moq5 does not implement, publish through the native backend even in moq5 builds.

Quick Start

Build and test:

cmake -S . -B build -DOPENMOQ_RUN_PICOQUIC_SMOKE_TESTS=OFF
cmake --build build
ctest --test-dir build --output-on-failure

The default build creates the openmoq-publisher executable and the static Publisher library: build/libopenmoq_publisher.a on Linux/macOS, or build\<config>\openmoq_publisher.lib with Visual Studio generators on Windows.

Check which build you are running:

./build/openmoq-publisher --version

This prints openmoq-publisher <version> (commit <hash>). The version is project(VERSION) from CMakeLists.txt; a build made from the matching v<version> release tag reports it as-is, while any other build appends -dev+g<commit> (plus .dirty when there are uncommitted changes) so a bug report identifies the exact source. --help prints the same banner. Embedders get the same values from openmoq/publisher/version.h (version(), version_full(), git_commit()).

Inspect a publish plan:

./build/openmoq-publisher --input sample.mp4 --dump-plan

Emit the catalog and packaged media objects:

./build/openmoq-publisher --input sample.mp4 --emit-dir out/

CMAF remains the default. Add --packaging locmaf to opt into LOCMAF-01, packaging version 0.3, for file, live stdin, SRT, or CTE LL-DASH publishing on the default backend. The publisher retains CMAF initialization and encoded sample bytes, signals LOCMAF in the catalog, and emits full headers so late joins and queue drops do not depend on earlier delta objects. File input retains original CMAF chunks, including encryption and auxiliary boxes; source constraints can keep an entire track on CMAF. A live track that becomes ineligible fails instead of changing its advertised packaging. --stream-per-object, --coalesce-cmaf-chunks, and the libmoq publishing backend are currently incompatible with LOCMAF. Multiplexed fragments must be demuxed first (for FFmpeg, use separate_moof).

--emit-dir writes LOCMAF media as .locmafobj alongside the usual catalog and initialization segments. For a playback equivalence check against a moq-playa checkout with LOCMAF support, run bun scripts/test-locmaf-playa.mjs build/openmoq-publisher ../moq-playa (requires FFmpeg and ffprobe). See the LOCMAF quickstart, C++ API configuration, and validation coverage.

Catalogs follow draft-ietf-moq-msf-02 by default; --msf-version 01 keeps the earlier draft-ietf-moq-msf-01 form (see protocol-mapping).

LOC-05 publishing is available with --packaging loc --draft 18 (or --draft 21 / --draft 22 / --draft 23) on the native backend. It sends individual H.264, HEVC, AV1, VP9, AAC-LC or Opus frames with timestamp, timescale, and codec configuration properties; CMAF remains the default. See the LOC quickstart for scope and constraints.

Publish to a relay with the default draft-22 profile:

OPENMOQ_PICOQUIC_TRACE=1 ./build/openmoq-publisher \
  --input sample.mp4 \
  --endpoint moqt://relay.example.com:443/moq \
  --namespace media \
  --draft 22 \
  --forward 0 \
  --timeout 30 \
  --paced

For file input, --forward 0 announces the namespace and waits for inbound SUBSCRIBE requests for catalog and media tracks. The catalog is available without --publish-catalog; that option proactively sends catalog PUBLISH and requires the relay to accept it. --forward 1 proactively publishes both catalog and media tracks and sends objects when the relay permits forwarding. If the relay reports PUBLISH is not supported, use --forward 0 without --publish-catalog. See publishing modes and troubleshooting.

A printed connection_id= confirms transport and MOQT setup only; it does not confirm namespace acceptance or a downstream subscription.

Add endpoints in preferred order and use --retry N to retry each current endpoint N times before advancing. For example, --endpoint primary:4433 --endpoint backup:4433 --retry 2 makes up to three attempts at the primary, then up to three attempts at the backup. See the CLI quick start for failure handling and live-source details.

On Windows, replace ./build/openmoq-publisher with build\Release\openmoq-publisher.exe or the path for the selected build configuration.

Live Ingest

The CLI exposes one live source at a time:

Source CLI selection Input Notes
Fragmented MP4 --live-source stdin --input - CMAF/fMP4 on standard input Available on all supported platforms
SRT --live-source srt --srt-config FILE MPEG-TS over SRT Requires libsrt; CENC metadata is unavailable in this path
CTE LL-DASH --live-source dash --dash-listen HOST:PORT CMAF POST or PUT requests, chunked or with Content-Length Listener currently requires a Unix-like platform

Fragmented MP4 ingest

The publisher reads fragmented MP4 from standard input. The input must contain ftyp + moov + moof/mdat fragments, and the publisher will emit MSF/CMSF catalogs and media objects.

ffmpeg -hide_banner -stream_loop -1 -re \
 -i fragmented.mp4 \
 -map 0:v:0 -map 0:a:0 \
 -c:v libx264 -preset veryfast \
 -r 30 -g 60 -keyint_min 60 -sc_threshold 0 -bf 0 \
 -c:a aac -b:a 128k -ar 48000 -ac 2 \
 -movflags +frag_keyframe+empty_moov+default_base_moof+separate_moof \
 -f mp4 pipe:1 | ./build/openmoq-publisher \
 --transport webtransport \
 --endpoint https://127.0.0.1:4433/moq \
 --namespace live/stdin \
 --draft 16 \
 --publish-catalog \
 --live-source stdin \
 --input -

Multiple video renditions

Every track in the input is published, named in trak order (vide_1, vide_2, soun_3, ...). When the video tracks are renditions of one picture, --video-alt-group <N> puts each of them in MSF alternate group N ("altGroup":N in the catalog, MSF section 5.2.12), so a subscriber knows to pick one. Audio tracks are not grouped, and an input with a single video track gets no altGroup. Without the option the catalog has no altGroup, because the publisher cannot tell renditions from, for example, two camera angles.

MSF requires the tracks of an alternate group to be time-aligned, so encode them with the same frame rate and keyframe interval and without scene-cut keyframes:

ffmpeg -hide_banner -re -i input.mp4 \
 -filter_complex "[0:v]split=2[high][low_in];[low_in]scale=-2:360[low]" \
 -map "[high]" -map "[low]" -map 0:a:0 \
 -c:v libx264 -preset veryfast \
 -r 30 -g 60 -keyint_min 60 -sc_threshold 0 -bf 0 \
 -b:v:0 3000k -b:v:1 800k \
 -c:a aac -b:a 128k -ar 48000 -ac 2 \
 -movflags +frag_keyframe+empty_moov+default_base_moof+separate_moof \
 -f mp4 pipe:1 | ./build/openmoq-publisher \
 --transport webtransport \
 --endpoint https://127.0.0.1:4433/moq \
 --namespace live/stdin \
 --publish-catalog \
 --input - \
 --video-alt-group 1

The option applies to live stdin publishing on the native backend. It is rejected for file, SRT and LL-DASH input; the LL-DASH ingest already sets altGroup 1 on its video tracks when there are two or more. The moq5 backend builds its own catalog and refuses the option.

SRT ingest

The publisher is an SRT caller. Create /tmp/srt_callers.json with the SRT listener address and MPEG-TS/CMAF settings:

{
  "srt_callers": [
    {
      "id": "cam1",
      "srt": {
        "mode": "caller",
        "host": "127.0.0.1",
        "port": 9000,
        "latency_ms": 120
      },
      "mpegts": {
        "auto_detect_program": true,
        "program_number": null,
        "video_pid": null,
        "audio_pid": null
      },
      "cmaf": {
        "fragment_on_keyframe": true,
        "empty_moov": true,
        "default_base_moof": true,
        "separate_moof_per_track": true,
        "target_fragment_duration_ms": 1000
      }
    }
  ]
}

In the first terminal, start an FFmpeg SRT listener that sends MPEG-TS after the publisher connects:

ffmpeg -hide_banner -stream_loop -1 -re \
  -i input.mp4 \
  -map 0:v:0 -map 0:a:0 \
  -c:v libx264 -preset veryfast -r 30 -g 60 -keyint_min 60 -sc_threshold 0 -bf 0 \
  -c:a aac -b:a 128k -ar 48000 -ac 2 \
  -f mpegts "srt://0.0.0.0:9000?mode=listener&pkt_size=1316"

In the second terminal, start the SRT caller and MoQ publisher:

./build/openmoq-publisher \
  --live-source srt \
  --srt-config /tmp/srt_callers.json \
  --endpoint 127.0.0.1:4443 \
  --transport raw \
  --namespace live/srt \
  --draft 16 \
  --timeout 120 \
  --forward 0

Set srt.mode to caller to connect to an existing SRT listener, or to listener to bind the configured host and port and accept an incoming SRT source. Listener mode accepts one connection per configured entry and uses the same MPEG-TS ingest pipeline. Use --forward 1 for an immediate relay smoke test, or keep --forward 0 to wait for subscriber interest.

CTE LL-DASH ingest

Start the publisher with an HTTP/1.1 CMAF listener and a MoQ relay target:

./build/openmoq-publisher \
  --live-source dash \
  --dash-listen 0.0.0.0:8080 \
  --dash-path /ingest \
  --endpoint https://127.0.0.1:4433/moq \
  --transport webtransport \
  --namespace live/dash \
  --draft 18 \
  --publish-catalog \
  --forward 1 \
  --insecure

Send an existing CMAF/fMP4 stream with HTTP/1.1 chunked transfer encoding:

curl -X PUT \
  -H 'Transfer-Encoding: chunked' \
  -H 'Content-Type: video/iso.segment' \
  --data-binary @live-video.cmaf \
  http://127.0.0.1:8080/ingest/video

Requests that carry a Content-Length instead of chunked transfer encoding are accepted too, as the DASH-IF ingest specification only recommends chunking for low latency. This is how livesim2 pushes init segments, so its CMAF ingest output can be pointed straight at the listener:

curl -X PUT \
  -H 'Content-Type: video/mp4' \
  --data-binary @init.cmfv \
  http://127.0.0.1:8080/ingest/video/init.cmfv

When the final path segment has a file extension, such as /ingest/video/init.cmfv followed by /ingest/video/1.cmfv, the enclosing directory (/ingest/video) is the representation path, so media segments find the init segment that preceded them. Paths without an extension, like the FFmpeg recipe below, are used as-is. A request with neither framing header is refused with 411 Length Required, and a declared length above the configured cap (256 MiB by default) with 413 Content Too Large.

FFmpeg can instead create two video representations plus audio and push them directly to the ingest prefix:

ffmpeg -re \
  -f lavfi -i "testsrc2=size=1280x720:rate=25" \
  -f lavfi -i "anullsrc=r=48000:cl=stereo" \
  -filter_complex "[0:v]split=2[v1][v2];[v1]scale=1280:720[v720];[v2]scale=640:360[v360]" \
  -map "[v720]" -c:v:0 libx264 -b:v:0 1500k -g 50 -keyint_min 50 -sc_threshold 0 \
  -map "[v360]" -c:v:1 libx264 -b:v:1 500k -g 50 -keyint_min 50 -sc_threshold 0 \
  -map 1:a -c:a aac -b:a 128k \
  -f dash -seg_duration 2 -use_template 1 -use_timeline 0 \
  -init_seg_name 'video$RepresentationID$' \
  -media_seg_name 'video$RepresentationID$' \
  -adaptation_sets "id=0,streams=v id=1,streams=a" \
  -multiple_requests 1 -streaming 1 -remove_at_exit 0 \
  -window_size 20 -extra_window_size 20 \
  http://127.0.0.1:8080/ingest/

Each representation path below /ingest maintains independent parser state and produces path-prefixed MoQ track names. Use --forward 1 to send objects immediately, or --forward 0 to wait for subscriber interest. The DASH listener currently requires a Unix-like platform.

See the CLI quick start, FFmpeg recipes, and SRT technical note for additional details.

Restarting a live publisher

Each live publisher process numbers its Group IDs from 0. If the process restarts and publishes the same namespace and track names again, its new groups reuse Group IDs that the previous run already published, so two different objects share one Location. MoqTransport section 2.5 suggests that a resuming publisher set its initial Group ID to a value larger than every group it used before, for example one based on the current time. Use --initial-group-id to do that:

./build/openmoq-publisher --input - --initial-group-id time ...
  • --initial-group-id time reads the system clock once at startup and starts at the number of milliseconds since the Unix epoch. This is safe if the previous run published fewer groups than the milliseconds that passed between its start and the restart, and the system clock did not step backwards in between.
  • --initial-group-id N starts at the unsigned integer N, which must not exceed 2^62-1.
  • The default is 0. The option applies to the media tracks and the catalog of the live sources (stdin, SRT, and CTE LL-DASH) on every draft; it is rejected for file input. On drafts 22 and 23, a GOAWAY migration still resumes above the groups the previous session sent. The moq5 publishing backend numbers Group IDs itself and rejects a non-zero value.
  • The value is fixed for the process. For stdin and SRT input, a --retry or endpoint failover reconnect inside the same process continues above the Group IDs the failed session sent instead of starting again from it, and stdin input resumes from its init segment. The moq5 publishing backend does not take part in this: it ignores the resume state, so a retry there restarts from Group 0 and a stdin input cannot be replayed.

Track priorities

By default every track has the MOQT default Publisher Priority, 128, and moqxr sends no priority signal. To let a relay serve some tracks first, set a priority per kind of track; lower is more urgent:

./build/openmoq-publisher --input - --draft 22 --publisher-priority audio=64,video=128,catalog=64 ...
  • The kinds are audio, video, catalog, and other (tracks that are none of these, such as timeline or event tracks). A kind not named stays 128.
  • Each track's value goes out as the DEFAULT_PUBLISHER_PRIORITY Track Property (0x0E) in its PUBLISH and SUBSCRIBE_OK, and its subgroups inherit it, so the subgroup headers keep their default-priority form. Catalog FETCH objects carry the catalog's value.
  • A track's priority is fixed for the session, so it never changes within a subgroup.
  • The publisher also schedules its own streams with these values. That scheduling maps subscriber and publisher priority onto one byte of QUIC stream priority, where the publisher priority moves a stream by at most one step, so on the publisher's own connection the effect is small.
  • Requires --draft 18 or later and --endpoint. The libmoq backend refuses it. With publish_live_objects, a track's kind comes from LiveTrack::media_type; a track without one counts as other.

Publishing via moq5

The opt-in moq5 backend routes batch, live stdin, live SRT, and live-object publishing through moq5's service tier. The service tier handles catalog publication, CMSF/CMAF validation, subscriber-demand gating, bounded backpressure, and graceful transport draining.

CMake fetches current openmoq/moq5 main when this backend is enabled. Set OPENMOQ_LIBMOQ_SOURCE_DIR only to use a local or offline source override:

cmake -S . -B build-libmoq \
  -DOPENMOQ_USE_LIBMOQ_PUBLISHER=ON
cmake --build build-libmoq
ctest --test-dir build-libmoq --output-on-failure

The default build keeps the built-in transport path. See docs/build.md for backend status, dependency discovery, and configuration details.

CAT4MoQ on this backend requires moq5's MOQ_SERVICE_AUTH_API_VERSION >= 1. Use -DOPENMOQ_LIBMOQ_SOURCE_DIR=../moq5 with the corresponding feature/cat4moq checkout while testing the coordinated change. Older moq5 dependencies reject configured credentials before connecting. See the auth design for backend limits and compatibility profiles.

Examples

Enable examples explicitly with cmake -S . -B build -DOPENMOQ_BUILD_EXAMPLES=ON, then build them with cmake --build build.

Example Target Purpose
Psychedelic live publisher openmoq-publisher-psychedelic-example Runs one FFmpeg audio/video pipeline through Publisher::publish_live(...)
CAT4MOQ authorization openmoq-publisher-auth-example Publishes deterministic live objects with token files or a Catapult token command
MSFTS publisher openmoq-publisher-msfts-example Publishes packet-aligned MPEG-2 TS or M2TS objects through Publisher::publish_live_objects(...)

The MSFTS example follows the local text draft in examples/msfts-publisher/docs/, discovers PAT/PMT data, selects one program, filters unrelated PIDs, and emits an MSF version 1 catalog with packaging: "m2ts".

This example discovers single-packet PAT/PMT sections within the first 4096 source packets. It uses fixed 10 ms object pacing rather than PCR-derived timing, publishes one group, and declares m2tsRandomAccess: false; it does not identify random-access boundaries or track program changes.

./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

Add --program NUMBER to select a program, --packets-per-object COUNT to change object sizing, or --insecure only when the relay certificate is intentionally untrusted.

Documentation

Topic Link
Build and dependencies docs/build.md
CLI and live-ingest quick start docs/quickstart.md
Testing docs/testing.md
Design overview docs/design.md
FFmpeg input recipes docs/ffmpeg.md
SRT ingest technical note docs/srt-ingest-technical-note.md
Relay interoperability docs/relay-interop.md
C++ Publisher API docs/publisher-api.md
CAT4MOQ auth example examples/auth/README.md
CAT4MoQ profiles and implementation status docs/cat4moq-design.md, docs/cat4moq-plan.md
MSFTS text draft examples/msfts-publisher/docs/draft-gregoire-moq-msfts.txt
Protocol mapping docs/protocol-mapping.md
WebTransport compliance docs/webtransport-compliance.md
Local MSF version 1 draft docs/draft-ietf-moq-msf-01.txt
Local CMSF version 1 draft docs/draft-ietf-moq-cmsf-01.txt
macOS DASH shutdown behavior docs/macos-accept-shutdown-quirk.txt
Project status and roadmap docs/status.md

Localized Publisher API guides are available in Spanish, French, Italian, Japanese, Portuguese, and Chinese.

Repository Layout

  • include/openmoq/publisher: public C++ headers
  • src: static library and CLI implementation
  • tests: CTest-based unit and integration coverage
  • docs: local draft text, protocol notes, integration guides, and design references
  • examples: Publisher API integrations
  • .github/workflows/ci.yml: Linux, macOS, and Windows CI
  • .github/workflows/release.yml: CLI, header, and static-library release artifacts

Current Status

The main openmoq-publisher CLI accepts drafts 16, 18, 21, 22, and 23; draft 22 is the default; draft 18 provides the newer request-stream profile, and draft 21 extends it (LOCATION_FILTER, INCLUDE_PROPERTIES, FILL_PARAMETERS). Draft 22 adds explicit LOCATION_FILTER types while retaining draft-21 publishing semantics. Draft 23 keeps those semantics with a varint control message Length, PAUSED in place of FORWARD, REQUEST_ERROR Error Details, overlapping namespace subscriptions, and its specific session termination codes; see docs/draft23-implementation-plan.md. Drafts 21 and 23 are published by the native backend. In moq5 builds drafts 16, 18, and 22 go through moq5 and the other drafts still publish through the native backend. Draft 22 through moq5 has been tested against a closed port and by the unit tests only; it has not been run against a draft 22 relay. Text for drafts 14, 17, 19, and 20 remains in docs/ for implementation history and protocol review, but those versions are not selectable in the main CLI. The separate MSFTS example retains draft 14/16/17/18 selection for draft-specific testing, and also accepts drafts 21, 22, and 23.

The default picoquic backend and the opt-in moq5 backend are both under active interoperability testing. For detailed feature coverage, limitations, and roadmap work, see docs/status.md and docs/protocol-mapping.md.

Attribution

Originally created by Paul Gregoire for OpenMOQ

About

Origin Publisher for OpenMOQ

Resources

Code of conduct

Contributing

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages