Development

The repository uses Just as its command runner. Run commands inside the Nix dev shell (nix develop) so your tools match CI. just check and just fix refuse to run outside it; set MOQ_ALLOW_HOST=1 to use the host toolchain anyway.

Command	Purpose
just	Start the local relay, test publisher, and web demo.
just --list	List every recipe.
just fix	Format and lint the packages this branch changed.
just check	Compile, lint, and test the same scope. This is what CI runs.
just fix --all, just check --all	The same, over every package.
just pub bbb <url>	Publish Big Buck Bunny (also tos, clock, gst, hls).
just sub gst bbb <url>	Play a broadcast through GStreamer.
just relay	Run a local relay on its own.
just boy	Run the MoQ Boy demo.

Recipes default to the local relay at http://localhost:4443. Pass https://cdn.moq.dev/anon to use the public relay instead. The default BBB/TOS publishers and just pub serve use MPEG-TS, with one audio frame per PES to avoid batching latency. Use just pub cmaf only when testing fMP4/CMAF.

BBB publishes the original 720p video and a pre-encoded 360p rendition at about 600 kbps. The player can switch between them as bandwidth or viewport size changes, without encoding while publishing. Consumers that only support one rendition get the 720p track.

To reproduce the hosted SD asset, run just pub encode-bbb-sd, then just pub upload bbb-sd.mp4 with access to the video bucket. The encode keeps the source frame timestamps and keyframes, and holds the final SD frame long enough to match the source audio's loop period. just pub check-bbb verifies both assets across three loops. Remove the local SD file before re-encoding.

Debugging

RUST_LOG=debug just            # structured logs
RUST_LOG=moq_net=trace just    # one crate
RUST_BACKTRACE=1 just          # panic backtraces

The relay's HTTP endpoints list announced broadcasts and fetch groups with curl, which is the quickest way to see what a relay holds.

Windows

Nix isn't available on Windows, so setup.bat installs the toolchain with winget: Git, Rust, Bun, Node, just, CMake, and the Visual Studio Build Tools. Run it from an Administrator terminal on a fresh machine, and re-run it after reopening the terminal if it reports tools missing from PATH.

Run just recipes from Git Bash, not PowerShell or cmd: they need bash and cygpath. Only one just dev can run at a time on Windows, because the free-port probe needs lsof. If a rebuild fails with "Access is denied", a previous relay is still running:

taskkill /IM moq-relay.exe /F
taskkill /IM moq.exe /F

Before opening a pull request

just fix
just check

These diff the branch against its upstream (or origin/main) and run only the modules the diff reaches. The map from paths to modules lives in sh/dispatch.sh. Recipes stay thin: any logic (conditionals, loops, traps) lives in a script under sh/.

See CONTRIBUTING.md for branch targeting, commit messages, and reviews, and Agent setup if an AI coding agent is doing the work.