Skip to content
Merged
2 changes: 1 addition & 1 deletion doc/bin/hls.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ What that means for you:
- **Publish timelines.** A broadcast whose catalog advertises no timelines is skipped, and a rendition is listed only once its own timeline is advertised. Without a duration hint, a publisher declares that timeline after the rendition's first segment.
- **Align GOPs across video renditions.** Segment boundaries come from one reference rendition. Other video renditions snap to their nearest keyframe, and a segment with none nearby becomes an `EXT-X-GAP`.
- **Disabled renditions are hidden.** A rendition the catalog marks `enabled: false` leaves the multivariant playlist and DASH manifest until it re-enables. Its media playlist keeps serving, so a player already on it is not ended with `EXT-X-ENDLIST`. If it supplied segment boundaries, an enabled sibling takes over at its first record numbered past the last advertised one, and DASH starts a new period. The media sequence is the record number, so every edge agrees: a sibling numbered ahead restarts the playlist with a discontinuity, and one numbered behind (such as a re-enabled rung) holds every playlist until its numbering catches up. `EXT-X-DISCONTINUITY-SEQUENCE` and DASH periods are counted per edge, so edges agree on them only when no discontinuity or handoff happened while each was running.
- **Segment URLs are stable.** Every edge and every reload derive the same URLs, so a CDN in front of export caches them.
- **URLs name the publisher instance.** Every URL the multivariant playlist and DASH manifest list sits under `@<instance>`, the publisher's epoch, so every edge and every reload derive the same URLs and a CDN in front of export caches them. A restarted publisher gets URLs of its own, whose numbering starts over. The multivariant playlist and manifest switch to it at once, while a player already on the old instance keeps playing until that publisher leaves; the player then has to reload the multivariant playlist. An instance without an epoch (one that reached export over moq-lite-06 or older) gets an id each export mints, so only that export serves its URLs.
- **Only a clean finish ends a playlist.** `EXT-X-ENDLIST` and a `static` DASH manifest mean the timeline finished. If the segment-boundary rendition's timeline fails instead, such as a publisher dropping its session, every media playlist and the DASH manifest answer HTTP 500 with `Cache-Control: no-store`, so a truncated recording never looks complete. A rendition whose own timeline fails answers the error alone and leaves the multivariant playlist and DASH manifest, so players switch to a sibling.

A [`moq-archive`](https://docs.rs/moq-archive) recording replayed through its
Expand Down
6 changes: 6 additions & 0 deletions doc/bin/rtc.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,5 +37,11 @@ resource URL tears a session down per the RFC. Each WHIP session publishes
under a fresh [epoch](/concept/moq-lite#publisher-epochs), so a publisher that
reconnects while its stale session lingers replaces it at once.

An export stays on the publisher it started with. A replacement publisher never
reaches its session, so timestamps and codec state never reset mid-session.
Once the original publisher leaves, the session ends with an error, and the
player or `export rtc --connect` must reconnect to reach the replacement.
`--connect` runs until its session ends.

Built on [str0m](https://crates.io/crates/str0m); the library is
[`moq-rtc`](https://docs.rs/moq-rtc).
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,6 @@ Binding durations wait on Duration support in the generated C.
- [SUBSCRIBE setup sees a cancel](/quest/m1/ietf-setup-cancel.md) - a subscriber that cancels mid-setup releases upstream demand and its slot at once
- [Every close records its cause](/quest/m1/close-cause.md) - protocol-violation closes and abandoned SETUP replies record why
- [Empty segments refused](/quest/m1/empty-segments.md) - `room//cam` fails loud instead of naming `room/cam`
- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - every moq-cli and moq-gst reader, moqsrc and `moq play` included, follows instances through `announced_broadcast` and an epochless `Restart` where its output can mark it; otherwise it stays on the old instance and fails once that route dies
- [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish
- [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters
- [Stats groups as tracks](/quest/m1/stats-group-tracks.md) - one stable node broadcast per stats producer, with each group a produced track listed by TRACKS
Expand Down
1 change: 0 additions & 1 deletion quest/m1/api-audit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,5 @@ Rejected in planning:
## Related

- [Claim request type](/quest/m1/api-audit/claim-request-type.md) - removes `accept` from application requests; [the origin announces](/quest/m1/api-audit/announce-owner.md) narrows `Prepared` beside it
- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - moves readers onto the follow operation that [two broadcast resolutions](/quest/m1/api-audit/resolve.md) names
- [API-diff check on release PRs](/quest/m1/api-diff.md) - the backstop that catches breaks this epic misses
- [Main is no slower than release](/quest/m1/release-perf/README.md) - the other release-readiness check
1 change: 0 additions & 1 deletion quest/m1/api-audit/resolve.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,5 +72,4 @@ Wire: none.

## Related

- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - moves readers to `follow`; whichever lands second adopts the other's names
- [Origin fronts park](/quest/m2/origin-front-parks.md) - touches the same retry
5 changes: 2 additions & 3 deletions quest/m1/broadcast-lifecycle/ts-follow.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,10 @@ Decided with the maintainer on 2026-10-23:
(`rs/moq-cli/src/args.rs`) keeps refusing; point its message at `--follow`
only where following applies.
- Move the follower onto `moq_mux::follow::Instances` here (decided
2026-10-24), as [readers follow restarts](/quest/m1/sink-restart-follow.md)
did for `moq play`, `moqsrc`, and `transcode`. `with_linger` waits from the
2026-10-24), as `moq play`, `moqsrc`, and `transcode` already do. `with_linger` waits from the
announcement through resolution and the first catalog, but `Instances`
yields `Start` only after resolution, so settle what `--follow` bounds
before moving the timer onto it. Coordinate the name with that quest.
before moving the timer onto it.
- Docs: `doc/bin/cli.md`, plus a migration note for moq-cli, moq-mux, and
moq-srt in the Impact bullet.

Expand Down
64 changes: 0 additions & 64 deletions quest/m1/sink-restart-follow.md

This file was deleted.

11 changes: 11 additions & 0 deletions rs/moq-hls/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,17 @@ How to update your code for each breaking change, newest first.

## Unreleased

### Rendition URLs name the publisher instance

`Server` follows each instance that takes over a broadcast, and every URL the
master playlist and DASH manifest list now sits under that instance:
`/{broadcast}/@{instance}/{kind}/{rendition}/...` instead of
`/{broadcast}/{kind}/{rendition}/...`. `Route::parse` refuses the old layout,
and `Resource::{Media, Init, Segment, SegmentAt}` carry the `instance` they
name. `Broadcaster::master_playlist` and `Broadcaster::manifest` render the new
layout. An embedder that answers through `Server::respond` needs no change; one
that routes rendition URLs itself must pass the `@{instance}` segment through.

### Denied broadcast references report authorization failure

A rendition whose referenced broadcast is outside the source origin's scope now
Expand Down
31 changes: 16 additions & 15 deletions rs/moq-hls/src/export/master.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
//! Each variant carries its own URI, so a caller with a different layout (a VOD
//! recorder writing `<name>/media.m3u8`, say) reuses the grouping and attribute
//! rules. [`Broadcaster::master_playlist`](super::Broadcaster::master_playlist)
//! renders the live layout, relative to `/<broadcast>/master.m3u8`.
//! renders the live layout, relative to `/<broadcast>/master.m3u8`: each rendition under the
//! publisher instance it lists (`@<instance>/<kind>/<rendition>/media.m3u8`).

use std::collections::BTreeMap;
use std::fmt::Write;
Expand All @@ -21,11 +22,11 @@ const AUDIO_GROUP: &str = "aud";
/// in both layouts.
pub(crate) const PATH_SEGMENT: &AsciiSet = &NON_ALPHANUMERIC.remove(b'-').remove(b'.').remove(b'_').remove(b'~');

/// The live layout's media-playlist URI for a rendition, relative to the master, with an
/// optional query (without the leading `?`) appended.
pub(crate) fn rendition_uri(kind: Kind, name: &str, query: Option<&str>) -> String {
/// The live layout's media-playlist URI for a rendition of the publisher `instance`, relative to
/// the master, with an optional query (without the leading `?`) appended.
pub(crate) fn rendition_uri(instance: &str, kind: Kind, name: &str, query: Option<&str>) -> String {
let mut uri = format!(
"{}/{}/media.m3u8",
"@{instance}/{}/{}/media.m3u8",
kind.as_str(),
utf8_percent_encode(name, PATH_SEGMENT)
);
Expand Down Expand Up @@ -197,7 +198,7 @@ mod tests {

fn video(name: &str, width: Option<u32>, height: Option<u32>) -> VideoVariant {
VideoVariant {
uri: rendition_uri(Kind::Video, name, None),
uri: rendition_uri("run", Kind::Video, name, None),
bandwidth: 2_500_000,
width,
height,
Expand All @@ -208,7 +209,7 @@ mod tests {
fn audio(name: &str, bandwidth: u64, codec: &str) -> AudioVariant {
AudioVariant {
name: name.into(),
uri: rendition_uri(Kind::Audio, name, None),
uri: rendition_uri("run", Kind::Audio, name, None),
bandwidth,
codec: codec.into(),
}
Expand All @@ -222,12 +223,12 @@ mod tests {
);
assert!(out.starts_with("#EXTM3U\n#EXT-X-VERSION:9\n"));
assert!(out.contains(
"#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aud\",NAME=\"audio\",DEFAULT=YES,AUTOSELECT=YES,URI=\"audio/audio/media.m3u8\"\n"
"#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"aud\",NAME=\"audio\",DEFAULT=YES,AUTOSELECT=YES,URI=\"@run/audio/audio/media.m3u8\"\n"
));
assert!(out.contains(
"#EXT-X-STREAM-INF:BANDWIDTH=2628000,RESOLUTION=1280x720,CODECS=\"avc1.42c01f,mp4a.40.2\",AUDIO=\"aud\"\n"
));
assert!(out.contains("\nvideo/video/media.m3u8\n"));
assert!(out.contains("\n@run/video/video/media.m3u8\n"));
}

#[test]
Expand Down Expand Up @@ -257,25 +258,25 @@ mod tests {
assert!(out.contains("GROUP-ID=\"aud-1\",NAME=\"opus\",DEFAULT=YES"));
assert!(out.contains("BANDWIDTH=2628000,RESOLUTION=1280x720,CODECS=\"avc1.42c01f,mp4a.40.2\",AUDIO=\"aud-0\""));
assert!(out.contains("BANDWIDTH=2660000,RESOLUTION=1280x720,CODECS=\"avc1.42c01f,opus\",AUDIO=\"aud-1\""));
assert_eq!(out.matches("\nvideo/video/media.m3u8\n").count(), 2);
assert_eq!(out.matches("\n@run/video/video/media.m3u8\n").count(), 2);
}

#[test]
fn audio_only_is_playable() {
let out = render(&[], &[audio("audio", 128_000, "opus")]);
assert!(out.contains("#EXT-X-STREAM-INF:BANDWIDTH=128000,CODECS=\"opus\"\n"));
assert!(out.contains("\naudio/audio/media.m3u8\n"));
assert!(out.contains("\n@run/audio/audio/media.m3u8\n"));
}

#[test]
fn rendition_names_are_percent_encoded_in_uris() {
assert_eq!(
rendition_uri(Kind::Video, "cam#1/main?alt", Some("jwt=abc.def")),
"video/cam%231%2Fmain%3Falt/media.m3u8?jwt=abc.def"
rendition_uri("run", Kind::Video, "cam#1/main?alt", Some("jwt=abc.def")),
"@run/video/cam%231%2Fmain%3Falt/media.m3u8?jwt=abc.def"
);
assert_eq!(
rendition_uri(Kind::Audio, "audio #1", None),
"audio/audio%20%231/media.m3u8"
rendition_uri("run", Kind::Audio, "audio #1", None),
"@run/audio/audio%20%231/media.m3u8"
);
}

Expand Down
36 changes: 30 additions & 6 deletions rs/moq-hls/src/export/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,9 @@ pub struct Broadcaster {
)
)]
broadcast: moq_net::broadcast::Consumer,
/// The publisher instance served, which every URL the master playlist and manifest list
/// starts with: its epoch, or an id minted for an epochless instance.
instance: Arc<str>,
/// The current rendition set, reconciled from the catalog by the watcher task.
renditions: renditions::Producer,
/// Aborts the catalog watcher when the broadcaster is dropped; `Drop` then retires the
Expand All @@ -152,10 +155,13 @@ impl Broadcaster {
/// Start tracking the renditions of `source`'s catalog broadcast.
pub fn new(source: moq_mux::Source, config: Config) -> Arc<Self> {
let broadcast = source.broadcast();
// An epoch names the instance on every edge, so each serves it under the same URLs.
let instance = broadcast.info().epoch.clone().unwrap_or_else(moq_net::Epoch::mint);
let renditions = renditions::Producer::new(config.window);
let timeline_watchers = Arc::new(Mutex::new(std::collections::BTreeMap::new()));
let broadcaster = Arc::new(Self {
broadcast,
instance: Arc::from(instance.as_str()),
renditions: renditions.clone(),
watcher: Mutex::new(None),
timeline_watchers: timeline_watchers.clone(),
Expand All @@ -167,6 +173,15 @@ impl Broadcaster {
broadcaster
}

/// The publisher instance every listed URL is under (`@{instance}/{kind}/{rendition}/...`).
#[cfg_attr(
not(feature = "server"),
allow(dead_code, reason = "only the `server` feature routes by instance")
)]
pub(crate) fn instance(&self) -> &Arc<str> {
&self.instance
}

/// Whether the source broadcast has closed (ended or dropped).
pub fn is_closed(&self) -> bool {
self.broadcast.is_closed()
Expand Down Expand Up @@ -263,15 +278,15 @@ impl Broadcaster {
}
match rendition.kind {
Kind::Video => video.push(master::VideoVariant {
uri: master::rendition_uri(Kind::Video, &rendition.name, query),
uri: master::rendition_uri(&self.instance, Kind::Video, &rendition.name, query),
bandwidth: rendition.bandwidth(),
width: rendition.width,
height: rendition.height,
codec: rendition.codec.clone(),
}),
Kind::Audio => audio.push(master::AudioVariant {
name: rendition.name.clone(),
uri: master::rendition_uri(Kind::Audio, &rendition.name, query),
uri: master::rendition_uri(&self.instance, Kind::Audio, &rendition.name, query),
bandwidth: rendition.bandwidth(),
codec: rendition.codec.clone(),
}),
Expand Down Expand Up @@ -343,6 +358,7 @@ impl Broadcaster {

Ok(Some(mpd::render_manifest(
&mpd::Manifest {
instance: self.instance.clone(),
availability_start,
publish: moq_clock::wall(),
window: self.renditions.window(),
Expand Down Expand Up @@ -2161,7 +2177,8 @@ mod tests {
"the init needs no generation"
);
let manifest = broadcaster.manifest(None).unwrap().expect("manifest");
assert!(manifest.contains("media=\"video/video0/seg/run-1.656e3d1b.t$Time$.m4s\""));
let run = broadcaster.instance();
assert!(manifest.contains(&format!("media=\"@{run}/video/video0/seg/run-1.656e3d1b.t$Time$.m4s\"")));

broadcaster.set_generation(Some("run-2")).unwrap();
assert!(
Expand Down Expand Up @@ -2430,7 +2447,8 @@ mod tests {
);
assert!(manifest.contains("id=\"video/video0\""));
assert!(manifest.contains("id=\"audio/audio0\""));
assert!(manifest.contains("media=\"video/video0/seg/656e3d1b.t$Time$.m4s\""));
let run = broadcaster.instance();
assert!(manifest.contains(&format!("media=\"@{run}/video/video0/seg/656e3d1b.t$Time$.m4s\"")));
// Both renditions list the same aligned segment spans (the live edge is not listed).
assert_eq!(manifest.matches("<S t=\"0\" d=\"2000\"/>").count(), 2);
assert_eq!(manifest.matches("<S t=\"2000\" d=\"2000\"/>").count(), 2);
Expand All @@ -2441,10 +2459,16 @@ mod tests {
.manifest(Some("jwt=abc.def"))
.unwrap()
.expect("manifest renders");
let hash = between(&signed, "initialization=\"video/video0/init.", ".mp4?jwt=abc.def\"");
let hash = between(
&signed,
&format!("initialization=\"@{run}/video/video0/init."),
".mp4?jwt=abc.def\"",
);
let init = video_rendition.init().await.unwrap().expect("init segment");
assert_eq!(video_rendition.init_versioned(hash).await.unwrap(), Some(init));
assert!(signed.contains("media=\"video/video0/seg/656e3d1b.t$Time$.m4s?jwt=abc.def\""));
assert!(signed.contains(&format!(
"media=\"@{run}/video/video0/seg/656e3d1b.t$Time$.m4s?jwt=abc.def\""
)));

// $Time$ resolves to the same bytes the aligned number does; unknown times miss.
let by_time = video_rendition
Expand Down
Loading
Loading