Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
0dcea4f
feat(cli): add moq play
kixelated Aug 6, 2026
3c93420
fix(cli): keep moq play alive when one track ends
kixelated Aug 6, 2026
854bc5a
fix(cli): make moq play degrade instead of exiting
kixelated Aug 6, 2026
07b97e0
fix(cli): wait for the announcement before moq play resolves
kixelated Aug 6, 2026
c6b5baf
fix(cli): play out the tail and report an unplayable catalog
kixelated Aug 6, 2026
1f2ef05
fix(cli): rebuild a lost play surface, and pin the announce race
kixelated Aug 6, 2026
c224cda
fix(cli): chunk audio writes so a long PCM frame isn't truncated
kixelated Aug 6, 2026
55fafa5
fix(cli): back-pressure video instead of dropping frames ahead of the…
kixelated Aug 6, 2026
51623e7
fix(cli): retry a present that timed out
kixelated Aug 6, 2026
17c51d2
fix(video, audio): decode the container the catalog declares
kixelated Aug 6, 2026
2018f7a
Merge remote-tracking branch 'origin/main' into codex/moq-play
kixelated Aug 7, 2026
da2fec3
Merge remote-tracking branch 'origin/main' into codex/moq-play
kixelated Aug 7, 2026
38ae429
fix(rs): compile moq play in the Windows gate (#2712)
kixelated Aug 7, 2026
ad6643a
test(moq-audio): pin CMAF framing in the decode consumer
kixelated Aug 7, 2026
e03495c
chore(py): relock after the moq-rs version bump
kixelated Aug 7, 2026
b9456d0
docs(cli): list the ALSA headers a Linux play build needs
kixelated Aug 7, 2026
00081e8
docs(cli): drop defaults in the checkout play commands too
kixelated Aug 7, 2026
bcded72
test(media): cover CMAF consumer playback
kixelated Aug 7, 2026
0fd7a06
Merge remote-tracking branch 'origin/main' into codex/moq-play
kixelated Aug 7, 2026
2018241
Merge remote-tracking branch 'origin/codex/moq-play' into codex/moq-play
kixelated Aug 7, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
876 changes: 800 additions & 76 deletions Cargo.lock

Large diffs are not rendered by default.

7 changes: 7 additions & 0 deletions deny.toml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@ ignore = [
# needs Rust 1.92, above the 1.91 workspace MSRV. Build-time only.
"RUSTSEC-2024-0436",

# ttf-parser is unmaintained, with no upgrade available. Reachable only via
# winit -> sctk-adwaita -> ab_glyph, which parses the system font used to
# draw Wayland client-side decorations for `moq play`. Dropping winit's
# `wayland-csd-adwaita` feature would remove it, at the cost of a titlebar
# on GNOME. Awaits sctk-adwaita migrating to skrifa.
"RUSTSEC-2026-0192",

]

[licenses]
Expand Down
76 changes: 71 additions & 5 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ description: Command-line tools for MoQ media
# FFmpeg / moq-cli

`moq-cli` is a media router: it wires one endpoint onto a shared MoQ Origin. It
moves media into MoQ from a source, or out of MoQ to a sink, bridging stdin/stdout
(via FFmpeg), HLS, RTMP, SRT, and WebRTC.
moves media into MoQ from a source, out of MoQ to a sink, or plays a broadcast
locally, bridging stdin/stdout (via FFmpeg), HLS, RTMP, SRT, and WebRTC.

## Installation

Expand Down Expand Up @@ -74,6 +74,7 @@ Each signal writes a numbered `/tmp/moq.heap.*.heap` profile for analysis with

```
moq <MoQ side> <import|export> <endpoint> [endpoint options]
moq <MoQ side> play [playback options]
```

- **MoQ side** attaches the Origin to the network, and comes before the verb. At
Expand All @@ -90,6 +91,7 @@ moq <MoQ side> <import|export> <endpoint> [endpoint options]
run); see [Redundant Publishers](#redundant-publishers-11).
- **`import`** routes media INTO MoQ (a source fills the Origin); **`export`**
routes it OUT (a sink drains the Origin). The verb fixes the data direction.
- **`play`** subscribes to a broadcast and plays its audio and video locally.
- **endpoint** is one subcommand: a container format (`avc3`, `fmp4`, `ts`, `flv`
read from stdin on import; `fmp4`, `mkv`, `ts`, `flv` written to stdout on
export), or a gateway (`hls`, `rtmp`, `srt`, `rtc`). For the bidirectional
Expand All @@ -109,6 +111,69 @@ side and reject one if given.
`moq <MoQ side> import <format>` reads a container from stdin;
`moq <MoQ side> export <format>` writes one to stdout.

### Play a Broadcast

Native playback is gated behind the `play` feature, which adds the platform
window, graphics, decoder, and speaker dependencies:

```bash
cargo install moq-cli --no-default-features --features "iroh,quinn,websocket,play"
# or build from a checkout:
cargo build --release -p moq-cli --no-default-features --features "iroh,quinn,websocket,play"
# or run straight from that checkout:
cargo run -p moq-cli --no-default-features --features "iroh,quinn,websocket,play" -- \
--client-connect https://relay.example.com/anon --broadcast my-stream.hang play
```

Drop the defaults on Linux, as above: the default `pipewire` feature links
libpipewire-0.3 at build time to give `import capture` a display source that
playback never uses.

A Linux build still needs three system packages, whichever features are picked.
The speaker goes through cpal, which links ALSA, and `play` pulls in moq-video,
whose V4L2 camera capture is not behind a feature and whose bindgen wants
libclang. On Debian and Ubuntu:

```bash
sudo apt install libasound2-dev libclang-dev libv4l-dev
```

macOS and Windows need nothing extra, so plain `--features play` is enough
there.

Once built, play a broadcast with:

```bash
moq --client-connect https://relay.example.com/anon --broadcast my-stream.hang play
```

`play` starts each media role as soon as the catalog offers a rendition it can
decode, independently of the other, and keeps following catalog updates until
both have started. Audio-only and video-only broadcasts play fine; playback ends
once every track it started has ended. It doesn't switch renditions afterwards,
so a publisher that replaces the one being played ends that role.

Within a role it takes the first rendition it can decode, in track-name order,
which is arbitrary as a quality choice. Pass `--video-name` / `--audio-name` to
pick a specific rung of a ladder. Audio drives the video clock when both are
present. The window preserves the video's aspect ratio and can be closed with
Escape, the close button, or Ctrl-C.

Playback decodes h264, h265, and av1 video, and opus and pcm audio, so
`--video-codec` / `--audio-codec` are rejected up front for anything else.
`--latency-max` controls how far a stalled media group may lag before it is
skipped and defaults to `500ms`. These flags all follow the `play` verb:

```bash
moq --client-connect https://relay.example.com/anon --broadcast conference.hang \
play --video-name hd --audio-name en --latency-max 250ms
```

Video decoding prefers the platform hardware backend and falls back to the
built-in software H.264 decoder. Rendering picks the best graphics API the
machine offers: Metal on macOS, and Vulkan ahead of D3D12 or OpenGL elsewhere.
Audio uses the system default output device through CoreAudio, WASAPI, or ALSA.

### Publish a Video File

Remux a file to MPEG-TS and pipe it in (`-c copy` avoids re-encoding):
Expand Down Expand Up @@ -389,8 +454,9 @@ discovery. When omitted, it's auto-detected from the broadcast name suffix
- `hangz` - the DEFLATE-compressed `catalog.json.z` catalog (opt-in; shares the `.hang` suffix and is never auto-detected)
- `msf` - the MSF `catalog` track

Stdout exports can also select one rendition per media role before the sink
subcommand:
Stdout exports can also select one rendition per media role. The flags go before
the sink subcommand here; `play` takes the same four after its own verb (see
[Play a Broadcast](#play-a-broadcast)):

```bash
moq --client-connect https://relay.example.com/anon --broadcast my-stream.hang \
Expand All @@ -400,7 +466,7 @@ moq --client-connect https://relay.example.com/anon --broadcast my-stream.hang \
- `--video-name <name>` picks the video rendition with that exact catalog name.
- `--video-codec <h264|h265|vp8|vp9|av1>` keeps only matching video renditions.
- `--audio-name <name>` picks the audio rendition with that exact catalog name.
- `--audio-codec <aac|opus>` keeps only matching audio renditions.
- `--audio-codec <aac|opus|pcm>` keeps only matching audio renditions.

With no selection flags, every matching rendition is kept. The `h264` and `h265`
export sinks force the matching video codec, so use `export h264` / `export h265`
Expand Down
2 changes: 1 addition & 1 deletion rs/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ Then `Config::load()?` (initializes tracing), build clients/servers via `.init()

- **Local checks only compile the host's platform and target, and PR CI is Linux-only.** `#[cfg(target_os = "...")]` code for other platforms is invisible to them, and `cargo fmt` skips those modules too. Windows and Mac runners cost too much for a per-PR gate, so those platforms are manual:

- Windows (moq-video's Media Foundation and D3D11 backends): `just rs windows`, which must run ON Windows. You can't reproduce it elsewhere, since cross-compiling dies in openh264-sys2's vendored C++.
- Windows (moq-video's Media Foundation and D3D11 backends): `just rs windows`, which must run ON Windows. You can't reproduce it elsewhere, since cross-compiling dies in openh264-sys2's vendored C++. It names `moq-cli/play` explicitly, since that feature is what pulls in moq-video's wgpu renderer and moq-audio's cpal output; a default-feature build compiles neither.
- macOS (moq-video's VideoToolbox and ScreenCaptureKit, moq-audio's system audio): `just rs macos`, which must run ON macOS. Scoped to moq-video + moq-audio, and needs `--all-features` because moq-audio's capture backend is off by default.
- Linux: covered. `just rs ci` already runs `--all-features` in a dev shell carrying PipeWire and ALSA. VAAPI loads libva dynamically, so nvenc/nvdec/vaapi/pipewire all compile without libva installed.
- wasm32 (moq-wasm): `just rs wasm`. The crate root is `#![cfg(target_arch = "wasm32")]`, so a host-target `cargo check --workspace` compiles it down to nothing and sees no errors at all. This one needs no special host (the Nix shell carries the target), so `just rs ci` and `just check-all` both run it, and `just check` adds it when the diff touches `rs/moq-wasm/`. It's a compile gate, distinct from the root `just wasm`, which builds the shippable `@moq/wasm` package.
Expand Down
6 changes: 5 additions & 1 deletion rs/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -142,10 +142,14 @@ fix-changed $FILES:
# backend don't build on MSVC, while moq-video's Linux-only nvenc/nvdec defaults
# are already no-ops off Linux. moq-gst is excluded because it links
# GStreamer via pkg-config, which the Windows runner doesn't have.
#
# `moq-cli/play` is named explicitly because it's off by default and is what
# turns on moq-video's wgpu renderer and moq-audio's cpal output, neither of
# which any default-feature build compiles.

# Compile the whole workspace on a Windows host. Must run ON Windows.
windows *args:
cargo check --workspace --exclude moq-gst --all-targets {{ args }}
cargo check --workspace --exclude moq-gst --all-targets --features moq-cli/play {{ args }}

# Runs the `#[cfg(target_os = "macos")]` code past the compiler: moq-video's
# VideoToolbox encode/decode and its ScreenCaptureKit / AVFoundation capture,
Expand Down
102 changes: 100 additions & 2 deletions rs/moq-audio/src/decode/consumer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ use crate::{Error, Frame};
/// [`read`](Self::read) returns plain [`Frame`]s.
pub struct Consumer {
decoder: Decoder,
track: moq_mux::container::Consumer<moq_mux::container::legacy::Wire>,
track: moq_mux::container::Consumer<moq_mux::catalog::hang::Container>,
resampler: Option<Resampler>,
config: Config,
resolved_sample_rate: u32,
Expand Down Expand Up @@ -52,7 +52,11 @@ impl Consumer {
.track(&name)?
.subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio))
.await?;
let mut track = moq_mux::container::Consumer::new(track, moq_mux::container::legacy::Wire);
// The catalog says how the track is framed, and it is not always the legacy
// wire: `moq import fmp4` publishes CMAF. Reading a moof+mdat fragment as a
// varint timestamp plus a payload decodes to garbage rather than failing.
let container = moq_mux::catalog::hang::Container::try_from(&catalog.container)?;
let mut track = moq_mux::container::Consumer::new(track, container);
Comment thread
kixelated marked this conversation as resolved.
Resolved
if let Some(latency) = config.latency_max {
track = track.with_latency(latency);
}
Expand Down Expand Up @@ -164,4 +168,98 @@ mod tests {
assert_eq!(pair[0], pair[1]);
}
}

#[tokio::test]
async fn reads_the_container_the_catalog_declares() {
let mut broadcast = moq_net::broadcast::Info::new().produce();
let track = broadcast.create_track("audio", hang::container::track_info()).unwrap();
let subscriber = broadcast.consume();

let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 1);
catalog.container = hang::catalog::Container::Loc;

let mut producer = moq_mux::container::Producer::new(track, moq_mux::catalog::hang::Container::Loc);
let mut consumer = Consumer::new(
&subscriber,
&catalog,
"audio",
Config {
format: Format::F32,
..Config::new()
},
)
.await
.unwrap();

let samples = [0.25f32, -0.5, 0.75, -1.0];
let payload: Vec<u8> = samples.iter().flat_map(|sample| sample.to_le_bytes()).collect();
producer
.write(moq_mux::container::Frame {
timestamp: Timestamp::ZERO,
duration: None,
payload: payload.into(),
keyframe: true,
})
.unwrap();

let frame = consumer.read().await.unwrap().expect("decoded frame");
assert_eq!(
Format::F32.as_interleaved_f32(&frame.data, 1).unwrap().as_ref(),
samples
);
}

/// The catalog picks the framing, not this crate. Hardcoding the legacy wire
/// read a CMAF fragment as a varint timestamp plus a payload, which handed the
/// codec garbage instead of failing, so anything published by `moq import
/// fmp4` was undecodable.
#[tokio::test]
async fn decodes_a_cmaf_framed_track() {
let input = Input {
format: Format::F32,
sample_rate: 48_000,
channels: 2,
};

// One real Opus packet, so a mis-framed read can't accidentally decode.
let mut encoder = Encoder::new(&crate::encode::Config::new(input.clone())).unwrap();
let mut catalog = encoder.catalog();
let pcm = vec![0.0f32; encoder.frame_size() * encoder.codec_channels() as usize];
let packet = encoder.encode(&pcm).unwrap();

// Re-describe the same rendition as CMAF and publish it that way.
let muxer = moq_mux::container::fmp4::Muxer::audio(&catalog).unwrap();
let init = muxer.init().unwrap().expect("an out-of-band codec has an init segment");
catalog.container = hang::catalog::Container::Cmaf { init };

let mut broadcast = moq_net::broadcast::Info::new().produce();
let subscriber = broadcast.consume();
let track = broadcast.create_track("audio", hang::container::track_info()).unwrap();
let container = moq_mux::catalog::hang::Container::try_from(&catalog.container).unwrap();
let mut producer = moq_mux::container::Producer::new(track, container);

let mut consumer = Consumer::new(&subscriber, &catalog, "audio", Config::new())
.await
.unwrap();

producer
.write(moq_mux::container::Frame {
timestamp: Timestamp::ZERO,
payload: packet,
keyframe: true,
duration: None,
})
.unwrap();
producer.cut(None).unwrap();

// The whole packet decodes: one 20 ms Opus frame at 48 kHz, less the pre-skip
// trimmed off the first packet. Reading the fragment as legacy hands the codec
// a slice of the moof instead, which still decodes, just to a shorter buffer.
let frame = consumer.read().await.unwrap().expect("decoded frame");
// `as_micros`, not `==`: the CMAF path carries the fmp4 timescale and
// `Timestamp`'s equality is structural, so the scales would have to match too.
assert_eq!(frame.timestamp.as_micros(), 0);
let samples = Format::F32.as_interleaved_f32(&frame.data, 2).unwrap();
assert_eq!(samples.len(), (960 - 312) * 2);
}
}
5 changes: 4 additions & 1 deletion rs/moq-audio/src/playback.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
//! Play decoded PCM out a speaker, via [`cpal`] (CoreAudio / WASAPI / ALSA).
//!
//! The playback counterpart to [`capture`](crate::capture), and where a
//! The playback counterpart to `capture`, and where a
// `capture` is deliberately not a doc link: the module is behind the
// off-by-default `capture` feature, so a link to it fails the `-D warnings`
// rustdoc build of a playback-only build (what `moq-cli`'s `play` enables).
//! [`decode::Consumer`](crate::decode::Consumer) ends up:
//!
//! ```no_run
Expand Down
6 changes: 6 additions & 0 deletions rs/moq-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ capture = ["dep:moq-video", "dep:moq-audio", "moq-audio/capture"]
# in moq-video and its codec dependencies. Enable with
# `cargo build -p moq-cli --features transcode`.
transcode = ["dep:moq-transcode", "dep:moq-video"]
# Native playback (`moq ... play`): decode into a wgpu window and a cpal
# speaker. Off by default because it pulls both graphics and audio device stacks
# into a binary that may only be routing containers or serving gateways.
play = ["dep:moq-video", "moq-video/render", "dep:moq-audio", "moq-audio/playback", "dep:pollster", "dep:winit"]
Comment thread
kixelated marked this conversation as resolved.
Resolved
Comment thread
kixelated marked this conversation as resolved.
Resolved
# NVIDIA hardware codecs for `capture` (Linux), on by default. Each just turns on
# the matching moq-video feature, and only bites when `capture` pulls in moq-video.
# For a `capture` build with no CUDA dependencies, drop them, e.g.
Expand Down Expand Up @@ -73,11 +77,13 @@ moq-srt = { workspace = true }
moq-token-cli = { workspace = true }
moq-transcode = { workspace = true, optional = true }
moq-video = { workspace = true, optional = true }
pollster = { version = "1.0", optional = true }
rustls = { version = "0.23", features = ["aws-lc-rs"], default-features = false }
tokio = { workspace = true, features = ["full"] }
tower-http = { version = "0.7", features = ["cors"] }
tracing = "0.1"
url = "2"
winit = { version = "0.30.13", optional = true }

[target.'cfg(unix)'.dependencies]
sd-notify = "0.5"
Expand Down
8 changes: 7 additions & 1 deletion rs/moq-cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Multi-arch images (`linux/amd64` and `linux/arm64`) are published to [Docker Hub

## Usage

`moq-cli` routes one endpoint onto a shared MoQ Origin: `moq <MoQ side> <import|export> <endpoint>`. The MoQ side (before the verb) is either `--client-connect <url>` (dial a relay) or `--server-bind <addr>` (self-host). `import` moves media into MoQ, `export` moves it out. The endpoint is a container format (`fmp4`, `ts`, `flv`, ... read from stdin / written to stdout), or a gateway (`hls`, `rtmp`, `srt`, `rtc`).
`moq-cli` routes one endpoint onto a shared MoQ Origin: `moq <MoQ side> <import|export> <endpoint>`. The MoQ side (before the verb) is either `--client-connect <url>` (dial a relay) or `--server-bind <addr>` (self-host). `import` moves media into MoQ, `export` moves it out. The endpoint is a container format (`fmp4`, `ts`, `flv`, ... read from stdin / written to stdout), or a gateway (`hls`, `rtmp`, `srt`, `rtc`). A build with the `play` feature can also render a broadcast locally with `moq <MoQ side> play`.

### Publish to a remote relay

Expand All @@ -35,6 +35,12 @@ moq --client-connect https://relay.example.com --broadcast my-stream.hang export
ffplay -
```

Play the broadcast in a native window and speaker (requires `--features play` when building):

```bash
moq --client-connect https://relay.example.com --broadcast my-stream.hang play
```

### Self-host: publish into a local relay

Hosts a MoQ server and publishes a single broadcast read from stdin into it. Useful for local testing without a separate relay process.
Expand Down
Loading
Loading