Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
34 changes: 33 additions & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

40 changes: 21 additions & 19 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Docker; see [Install](/setup/install).
| `export` | `rtmp`, `srt`, `rtc` | Serve plays (`--listen`) or push to a remote (`--connect`). |
| `play` | | Decode and play in a native window with sound. |
| `transcode` | | Publish a just-in-time rendition ladder next to a broadcast. |
| `ls` | `[prefix]` | List the broadcasts live on a relay. |
| `announced` | `[prefix]` | Follow the broadcasts announced on a relay. |
| `fetch` | `<track>` | Write one group of a track to stdout. |
| `auth` | | Generate, sign, and verify relay JWTs. |
| `devices` | | List capture sources and their ids. |
Expand All @@ -35,7 +35,7 @@ Docker; see [Install](/setup/install).
moq <MoQ side> import <source> [options]
moq <MoQ side> export <sink> [options]
moq <MoQ side> play [options]
moq <MoQ side> ls [prefix] [options]
moq <MoQ side> announced [prefix] [options]
moq <MoQ side> fetch <track> [options]
```

Expand Down Expand Up @@ -287,28 +287,30 @@ heights and bitrates must then increase strictly together. Duplicate heights or
bitrates, inverted rankings, and zero-sized or zero-bitrate rungs are rejected
before connecting.

## List
## Announced

```bash
moq --connect https://relay.example.com/anon ls
moq ... ls room --follow --json
moq --connect https://relay.example.com/anon announced
moq ... announced room --json
```

Lists the broadcasts live on a relay over MoQ, with the session's own auth: the
counterpart of the relay's HTTP `/announced/<prefix>`. It prints one path per
line, relative to the `--connect` path, and exits once the relay has sent
everything live under `prefix`. `--follow` keeps running: it prints `+ path`
for each live broadcast, then `+ path` and `- path` as broadcasts come and go,
and exits non-zero if the session ends. `--json` prints
`{"path": "room/alice", "active": true}` per line instead, in either mode.

Like `/announced`, it lists announced prefixes, which by convention are
broadcast paths. A new route to a path already live prints nothing. A name
starting with `.` stays hidden unless `prefix` names it. `ls` only dials
Follows the broadcasts announced on a relay over MoQ, with the session's own
auth: the live counterpart of the relay's HTTP `/announced/<prefix>`. Paths are
relative to the `--connect` path. On a terminal it shows what is announced
under `prefix` right now, redrawn as broadcasts start and end, and a list
taller than the terminal ends in a count of the rest. Piped, it prints
`+ path` for each broadcast already announced, then `+ path` and `- path` as
broadcasts come and go. `--json` prints `{"path": "room/alice", "active": true}`
per line instead, on a terminal or not. It runs until interrupted, and exits
non-zero if the session ends.

Like `/announced`, it follows announced prefixes, which by convention are
broadcast paths. A new route to a path already announced prints nothing. A name
starting with `.` stays hidden unless `prefix` names it. `announced` only dials
`--connect`, and refuses any other MoQ-side flag.

[Inspect a relay](/bin/inspect) walks through `ls` and `fetch` next to their
`curl` equivalents, including reading the relay's stats.
[Inspect a relay](/bin/inspect) walks through `announced` and `fetch` next to
their `curl` equivalents, including reading the relay's stats.

## Fetch

Expand Down Expand Up @@ -441,7 +443,7 @@ way. Only `ts` can mark the restart, so the other formats refuse `--linger`.
## Debugging

`RUST_LOG=debug` prints the negotiated version and every subscription.
`moq --connect <url> ls`, or `curl http://relay:4443/announced`, confirms the
`moq --connect <url> announced`, or `curl http://relay:4443/announced`, confirms the
relay is reachable and shows what it holds; see [Inspect a relay](/bin/inspect). Connection refused means UDP isn't getting through; certificate
errors on a dev relay want `--connect-tls-insecure` or the `http://`
fingerprint flow.
28 changes: 15 additions & 13 deletions doc/bin/inspect.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,22 @@ with the session's own auth, and a `curl` against the relay's

| Question | MoQ | HTTP |
| --- | --- | --- |
| What is live? | `moq --connect <url>/<path> ls [prefix]` | `GET /announced/<path>` |
| What changes? | `moq ... ls --follow` | (none) |
| What is live? | `moq --connect <url>/<path> announced [prefix]` | `GET /announced/<path>` |
| What changes? | `moq ... announced [prefix] \| cat` | (none) |
| What is in a group? | `moq ... --broadcast <name> fetch <track>` | `GET /fetch/<path>/<name>/<track>` |

## What is live

```bash
moq --connect http://localhost:4443/anon ls
moq --connect http://localhost:4443/anon announced
curl http://localhost:4443/announced/anon
```

Both print one broadcast path per line, relative to the path in the URL, and
both use that path for auth, so a token rooted at `rooms/123` lists only its
room. `moq ls room` narrows the listing to one prefix, and `--json` prints
`{"path": "room/alice", "active": true}` per line instead.
Both name broadcasts by path, relative to the path in the URL, and both use
that path for auth, so a token rooted at `rooms/123` lists only its room.
`curl` prints a snapshot, one path per line. `moq announced` keeps running and
redraws the list in place as broadcasts start and end, until you stop it.
`moq announced room` narrows either to one prefix.

Both list announced prefixes, which by convention are broadcast paths. A
segment starting with `.` stays hidden unless the URL path or `prefix` names
Expand All @@ -35,13 +36,14 @@ it, which keeps the relay's own `.stats` out of the listing.
## What changes

```bash
moq --connect http://localhost:4443/anon ls --follow
moq --connect http://localhost:4443/anon announced | cat
```

`--follow` prints `+ path` for each live broadcast, then `+ path` and `- path`
as broadcasts come and go, until you stop it. It exits non-zero if the session
ends, so a script can tell a lost relay from a quiet one. `curl` has no
equivalent: `/announced` is a snapshot.
Piped, `moq announced` prints `+ path` for each broadcast already announced,
then `+ path` and `- path` as broadcasts come and go, and `--json` prints
`{"path": "room/alice", "active": true}` per line instead. It exits non-zero if
the session ends, so a script can tell a lost relay from a quiet one. `curl`
has no equivalent: `/announced` is a snapshot.

## What is in a group

Expand All @@ -66,7 +68,7 @@ counters as ordinary broadcasts under `.stats`, so the same tools read them.
Dial the `.stats` path, which the token must cover:

```bash
moq --connect http://localhost:4443/.stats ls
moq --connect http://localhost:4443/.stats announced
moq --connect http://localhost:4443/.stats --broadcast node/local/host fetch publisher.json | jq
curl http://localhost:4443/fetch/.stats/node/local/host/publisher.json | jq
```
Expand Down
2 changes: 1 addition & 1 deletion doc/bin/relay/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The announcement listing names each announced route by the prefix it covers;
by convention a publisher announces each broadcast's exact path, so the list
reads as broadcast names.

`moq ls` and `moq fetch` answer the same questions over MoQ; see
`moq announced` and `moq fetch` answer the same questions over MoQ; see
[Inspect a relay](/bin/inspect).

A relay configured with more than one certificate has no single fingerprint to
Expand Down
2 changes: 1 addition & 1 deletion quest/m0/broadcast-epoch/hop-removal.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ publisher's hop chain.
and "the first entry identifies the endpoint that originated the route". In
`drafts/draft-lcurley-moq-cluster.md`: the unknown-publisher stamping text,
the relay behavior that stamps, and the changelog bullets.
- CLI: `rs/moq-cli/src/{args,complete,fetch,ls}.rs`. Relays keep `cluster.id`
- CLI: `rs/moq-cli/src/{args,complete,fetch,announced}.rs`. Relays keep `cluster.id`
as their node id.
- Docs: `doc/bin/cli.md` ("Redundant publishers" uses `--epoch`), the
migration row in `doc/setup/upgrade.md`, the stamping paragraph in
Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,6 @@ blocks. The quests that gated m0 lines moved under them.
- [moq-bot may push workflow changes](/quest/m1/bot-workflows-permission.md) - condition: the maintainer grants moq-bot's GitHub App the `workflows` permission, so back-merges carrying workflow changes go through
- [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay
- [moq-net owns its transport seam](/quest/m1/transport-seam.md) - moq-net names only its own transport traits, so a web-transport-trait or qmux major bump is a patch for it
- [moq announced](/quest/m1/cli-announced.md) - `moq ls` becomes a follow-only live view named `moq announced`, with local-only shell completion
- [fMP4 init from the catalog](/quest/m1/fmp4-catalog-init.md) - fMP4 export writes avc3/hev1 entries from the catalog, so an Annex-B H.264 or H.265 init no longer waits for the first keyframe
- [Delete the live marker](/quest/m1/announce-live-removal.md) - announce streams yield only route events; the `Live` marker and its hold machinery are gone
- [Browser close code](/quest/m1/browser-close-code.md) - a playwright case proves the page reads a relay's close code and reason, on every web-transport backend
Expand Down
6 changes: 1 addition & 5 deletions quest/m1/announce-live-removal.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Decided 2026-09-29 by the maintainer, after walking through a page-load fix,
a Live/Offline toggle, and a per-session `live()`:

- The marker answers "has the initial list arrived?" Only one-shot listing
(`moq ls`, shell completion) uses it, and no app does: room, watch, and the
(`moq ls`, shell completion, both since removed) used it, and no app does: room, watch, and the
demo skip it. An origin merges many sessions and local publishers, so
"caught up" there needs aggregation across connections that start, fail,
and reconnect independently. That produced the page-load race, the special
Expand Down Expand Up @@ -45,7 +45,3 @@ Guidance:

Public API: removes `AnnounceEvent::Live` / `{ kind: "live" }` /
`MoqAnnounceEvent::Live` and the binding aliases. Wire: none.

## Required

- [moq announced](/quest/m1/cli-announced.md) - the CLI stops reading the marker first
41 changes: 0 additions & 41 deletions quest/m1/cli-announced.md

This file was deleted.

9 changes: 4 additions & 5 deletions rs/moq-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ reqwest = { workspace = true, features = ["rustls", "json"] }
rustls = { version = "0.23", features = ["aws-lc-rs"], default-features = false }
serde = { workspace = true }
serde_json = { workspace = true }
terminal_size = "0.4.4"
tokio = { workspace = true, features = ["full"] }
tower-http = { workspace = true }
tracing = { workspace = true }
Expand All @@ -124,18 +125,16 @@ winit = { version = "0.30.13", optional = true }
sd-notify = { workspace = true }

[dev-dependencies]
# Authors an MSF-only catalog, which is the one shape that tells a completer reading
# the wrong catalog track apart from one reading the right one: `moq-mux`'s producer
# publishes hang and MSF from the same source, so both answer for an ordinary broadcast.
moq-msf = { path = "../moq-msf" }
# `test_relay` stands up a real relay for the `fetch` tests to read through.
# `test_relay` stands up a real relay for the `fetch` and `announced` tests to read through.
moq-relay = { path = "../moq-relay", default-features = false, features = ["test-support"] }
# Writes the PAT and PMTs, CRCs included, of the two-program input `import ts --program all` splits.
mpeg2ts = "0.6.0"
tempfile = { workspace = true }
# `test-util` enables `tokio::time::pause` so the TS round-trip test simulates the
# exporter drain timeouts instantly instead of waiting on the wall clock.
tokio = { workspace = true, features = ["test-util"] }
# Plays the `announced` view's frames on a virtual terminal, scrolling included.
vt100 = "0.16.2"

[[bench]]
name = "play_buffer"
Expand Down
Loading
Loading