kixelated · Oct 6, 2026 · Sep 24, 2026 · Sep 25, 2026 · Sep 25, 2026 · Sep 25, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -142,6 +142,7 @@ loom = { version = "0.7.2", features = ["futures"] }
 # DNS-SD advertisement and browsing for LAN peer discovery (moq-tokio's `mdns` feature).
 # `async` awaits the event channel instead of blocking a thread on it.
 mdns-sd = { version = "0.21", features = ["async"] }
+moq-archive = { version = "0.0.11", path = "rs/moq-archive" }
 moq-audio = { version = "0.1.10", path = "rs/moq-audio", default-features = false }
 moq-auth = { version = "0.2.1", path = "rs/moq-auth" }
 moq-flate = { version = "0.2.0", path = "rs/moq-flate" }

diff --git a/doc/bin/cli.md b/doc/bin/cli.md
@@ -19,9 +19,11 @@ Docker; see [Install](/setup/install).
 | `import` | `capture` | Capture a camera, display, window, or app plus a microphone, and encode natively. |
 | `import` | `hls <url>` | Pull a remote HLS playlist. |
 | `import` | `rtmp`, `srt`, `rtc` | Accept pushes (`--listen`) or pull from a remote (`--connect`). |
+| `import` | `archive <url>` | Replay a recording from an object store. |
 | `export` | `fmp4`, `mkv`, `ts`, `flv`, `h264`, `h265` | Write a container to stdout. |
 | `export` | `hls --listen` | Serve the broadcast as HLS over HTTP. |
 | `export` | `rtmp`, `srt`, `rtc` | Serve plays (`--listen`) or push to a remote (`--connect`). |
+| `export` | `archive <url>` | Record the broadcast into an object store. |
 | `play` | | Decode and play in a native window with sound. |
 | `transcode` | | Publish a just-in-time rendition ladder next to a broadcast. |
 | `announced` | `[prefix]` | Follow the broadcasts announced on a relay. |
@@ -148,7 +150,7 @@ The `fmp4`, `mkv`, `flv`, `h264`, and `h265` exports select renditions with
 flags before the sink: `--video-name` and `--audio-name` pick a rendition,
 `--video-codec` and `--audio-codec` keep a codec family, and `--no-video` or
 `--no-audio` leaves a role out. `h264` and `h265` refuse `--no-video` and the
-audio selection flags. `ts` and the gateways don't apply selection, so they
+audio selection flags. `ts`, `archive`, and the gateways don't apply selection, so they
 refuse these flags.
 
 ```bash
@@ -338,6 +340,41 @@ refuses any listener, cluster, auth, or `--hop` flag. It gives up after 30
 seconds, as `/fetch` does, and exits non-zero when the broadcast or group is not
 found (before writing anything), the relay refuses, or the deadline passes.
 
+## Archive
+
+```bash
+# Record a broadcast until it ends
+moq --connect https://relay.example.com/anon --broadcast event.hang export archive s3://recordings/event
+
+# Replay it under another name
+moq --connect https://relay.example.com/anon --broadcast event-replay.hang import archive s3://recordings/event
+```
+
+`export archive` records one broadcast with
+[moq-archive](https://docs.rs/moq-archive), reading its catalog as it changes.
+Every track gets its own timeline, stored in spans cut at group boundaries
+between 2s and 10s. The catalog and every text, JSON, and binary track are
+sparse data, so each of their groups is stored as soon as it finishes, and a
+group that never closes is stored in pieces as it grows. It refuses a rendition served
+from another broadcast, and one that returns after the catalog dropped it. The
+stage ends once the broadcast does. A store URL that already holds a
+recording is continued: each track resumes after its newest stored span. `--retention 1h` keeps only the last hour (a DVR),
-recording is continued: each track resumes after its newest stored span. `--retention 1h` keeps only the last hour (a DVR),
+recording is continued: each track resumes after its newest stored span. If a source restarts with group sequences below the recovered floor, `handle` skips those groups; use a new store prefix. `--retention 1h` keeps only the last hour (a DVR),
-recording is continued: each track resumes after its newest stored span. `--retention 1h` keeps only the last hour (a DVR),
+recording is continued: each track resumes after its newest stored span. If a source restarts with group sequences below the recovered floor, `handle` skips those groups; use a new store prefix. `--retention 1h` keeps only the last hour (a DVR),
+deleting expired objects, and timeline objects no longer needed to recover it,
+`--retention-grace` (default 30s) after the timeline stops needing them. Every
+track keeps at least its newest span, so a catalog that never changes outlives
+the video it was published with.
+
+`import archive` republishes a recording: each track's timeline replays as a
+live track and every track's groups are served on request, one object GET per
+stored span. By default it replays what is stored and ends the timelines there;
+`--follow 2s` keeps checking for new spans, and newly recorded tracks, of a
+recording still being made.
+
+Store URLs are `file:///absolute/path`, `s3://bucket/prefix`,
+`gs://bucket/prefix`, or `az://container/prefix`. Cloud credentials come from
+the usual `AWS_*`, `GOOGLE_*`, and `AZURE_*` environment variables. The `s3`,
+`gcs`, and `azure` cargo features are on by default.
+
 ## Multiple stages
 
 Separate stages with `--` to bridge several broadcasts, or both directions,
@@ -346,7 +383,8 @@ over one connection:
 ```bash
 moq --connect https://relay.example.com/anon \
     import --broadcast event.hang srt --listen 0.0.0.0:9000 \
-    -- export --broadcast event.hang hls --listen 0.0.0.0:8080
+    -- export --broadcast event.hang hls --listen 0.0.0.0:8080 \
+    -- export --broadcast event.hang archive file:///recordings/event
 ```
 
 ## Redundant publishers

diff --git a/doc/bin/hls.md b/doc/bin/hls.md
@@ -17,34 +17,63 @@ moq --connect https://relay.example.com/anon --broadcast my-stream.hang export h
 moq --connect https://relay.example.com/anon --broadcast my-stream.hang import hls https://example.com/live/master.m3u8
 ```
 
-Export never subscribes to media. It reads the broadcast's
-[timeline track](/concept/hang#catalog), a log of complete segments aligned
-across every rendition, to build playlists, then fetches exactly the groups a
-requested segment covers from the relay's cache and transmuxes them to CMAF on
-demand. So a segment is servable for as long as the relay's
+Export never subscribes to media. It reads each rendition's
+[timeline track](/concept/hang#catalog), a small index of that rendition's
+groups, to build playlists, then fetches exactly the frames a requested segment
+covers from the relay's cache and transmuxes them to CMAF on demand. So a
+segment is servable for as long as the relay's
 [cache](/bin/relay/config#cache) retains it, and idle renditions cost nothing.
-Because segments are aligned, the same number names the same span of content in
-every media playlist; a record with nothing for a rendition renders as
-`EXT-X-GAP` and a jump in content time as `EXT-X-DISCONTINUITY`. A broadcast
-whose catalog advertises no timeline is skipped. One server exposes every
+Segment boundaries come from one reference rendition (the first video
+rendition by name, or the first audio one without video) and are numbered by
+its records, so every edge and every reload agree. Every other video rendition
+snaps each boundary to its nearest keyframe within about a second, and a
+segment with none in range renders as `EXT-X-GAP`; audio takes every frame
+inside the segment's span. A jump in content time renders as
+`EXT-X-DISCONTINUITY`. Gaps are a fallback: a publisher wanting clean HLS
+export should align video GOPs across renditions. A timeline that fails
+(malformed, refused, or lost) is not retried, since the relay already rides out
+transient source failures. The reference timeline failing ends every playlist
+with `EXT-X-ENDLIST`, and any other rendition's timeline failing ends that
+rendition's playlist at the last segment it covers. A broadcast
+whose catalog advertises no timelines is skipped. One server exposes every
 broadcast by path:
 
 ```text
 /{broadcast}/master.m3u8
 /{broadcast}/manifest.mpd
 /{broadcast}/{video|audio}/{rendition}/media.m3u8
 /{broadcast}/{video|audio}/{rendition}/init.{hash}.mp4
-/{broadcast}/{video|audio}/{rendition}/seg/{segment}.m4s
-/{broadcast}/{video|audio}/{rendition}/seg/t{pts}.m4s
+/{broadcast}/{video|audio}/{rendition}/seg/{reference}.{segment}.m4s
+/{broadcast}/{video|audio}/{rendition}/seg/{reference}.t{pts}.m4s
 ```
 
+Segment boundaries come from one reference rendition's timeline, and its records
+number the segments. `{reference}` is a short hash of that rendition's kind and
+name, so every edge derives the same URL, and a reference that changes (a new
+first video rendition) starts a new numbering under new URLs rather than reusing
+the old ones for other content.
+
+A [`moq-archive`](https://docs.rs/moq-archive) recording replayed through its
+`Reader` is served the same way, with no second stored copy. Playlists come
+from the replayed timelines alone, and a segment GETs only its rendition's
+stored objects, so switching renditions never downloads both. An
+inline-parameter-set codec with no catalog `description` is the exception:
+the first playlist render GETs one keyframe group to build the init segment,
+then caches it. Out-of-band configs need no media GET. When the catalog's
+`archive` entry names a `store` and no `replay` path, its spans are durable on
+this broadcast, so the playlists list the whole retained timeline and only the
+recording's own retention trims them; DASH `timeShiftBufferDepth` is the listed
+span. The playlist ends with `EXT-X-ENDLIST` only once the reader's caller
+declares the recording finished; the store holds no completion marker.
+
 The init URL carries a hash of its bytes, so a reconfigured rendition gets a
 new one. An embedder of the library can also label the publisher's run with
 `Broadcaster::set_generation`. Every segment URL then carries it
-(`seg/{generation}.{segment}.m4s`), since a restarted publisher reuses segment
+(`seg/{generation}.{reference}.{segment}.m4s`), since a restarted publisher reuses segment
 numbers for different media.
 
-`--window` sets the playlist duration (default 16 s),
+`--window` sets the live playlist duration (default 16 s) and caps segment
+`Cache-Control: max-age` for every broadcast,
 `--listen-tls-cert`/`--listen-tls-key` or `--listen-tls-generate` serve HTTPS,
 and `--cors-origin` opens it to browsers.
 H.264/H.265 and AAC/Opus renditions are served. Import handles classic HLS;

diff --git a/doc/concept/hang.md b/doc/concept/hang.md
@@ -57,8 +57,8 @@ A few things the catalog can express beyond decoder config:
 - **Jitter.** A rendition can say how far its frames fell behind the media clock before the publisher flushed them, in whole milliseconds rounded up. Encoders report the spread of lateness above each rendition's own recent minimum, so a constant encoder delay is not jitter; container imports estimate batch spans without counting ingest delay. It describes the publisher, never the network, only grows over the life of a stream, and a player sizes its buffer to at least this much. A `0` is read as absent.
 - **Delay.** A rendition can also say how far its frames reach the transport behind the broadcast's earliest rendition, measured the same way from each rendition's minimum lateness, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's.
 - **Stalled renditions.** A publisher can flag a rendition as temporarily bad so players prefer another one without the track disappearing. First-party video publishers set this flag after more than three frame intervals of source silence or encoding lag while subscribed, and clear it after three on-time completed frames or when idle. Browser and native capture poll while waiting; FLV and MPEG-TS importers observe video silence as container data arrives. The shared detector is `hang::catalog::stalled::Detector` in Rust and `Catalog.Stalled.Detector` in JavaScript. It is a playback diagnostic, not an authorization or routing signal.
-- **Archive.** A broadcast may advertise an `archive` entry naming its timeline track (a small index of each complete aligned segment) and, if recorded, the replay MoQ path, object-store URL, and format version. The timeline is what lets the [HLS gateway](/bin/hls) build playlists without subscribing to media.
-- **Clock.** The optional root `clock` maps PTS zero to wall time so every media track and the archive index share one fixed epoch after timescale conversion. It is independent of `archive`, so a live-only publisher can expose wall-clock timing without creating a segment index.
+- **Archive.** A broadcast may advertise an `archive` entry mapping each track, the catalog included, to its own timeline track (a small index of the track's spans: timing plus group and frame positions) and, if recorded, the replay MoQ path, object-store URL, and format version. Every track is cut by one rule, at group boundaries between 2s and 10s (a zero minimum for sparse data such as the catalog), and tracks commit and expire independently. The timelines are what let the [HLS gateway](/bin/hls) build playlists without subscribing to media.
+- **Clock.** The optional root `clock` maps PTS zero to wall time so every media track and the archive index share one fixed epoch after timescale conversion. It is independent of `archive`, so a live-only publisher can expose wall-clock timing without creating a timeline.
 - **Extensions.** The root is a loose object. Applications add their own sections (`scte35`, for example) next to the ones hang defines, optionally naming a track that carries the data. Every library exposes a way to write your section without clobbering the built-in ones, and readers ignore what they don't know.
 
 ## Text

diff --git a/doc/lib/js/hang.md b/doc/lib/js/hang.md
@@ -24,8 +24,8 @@ import * as Container from "@moq/hang/container";
 `Catalog.EscapingBroadcast` for a `broadcast` reference that walks above the
 handle's `path`. Run the same checks on a catalog from another source with
 `Catalog.checkRenditions(root)` and `Catalog.checkResolvable(root, base)`.
-`Hang.Timeline.Consumer.subscribe(broadcast, root.archive)` reads segment
-`push`, `pop`, and `skip` events when a root advertises an archive.
+`Hang.Timeline.Consumer.subscribe(broadcast, root.archive, track)` reads one
+track's timeline as record `push`, `pop`, and `skip` events when a root advertises it.
 
 Most apps never import it directly; the elements and `Broadcast` classes in
 the watch and publish packages do. Reach for it when hand-rolling a catalog

diff --git a/doc/lib/rs/hang.md b/doc/lib/rs/hang.md
@@ -12,7 +12,7 @@ The [hang media format](/concept/hang) on top of `moq-net`: a live catalog
 describing renditions with WebCodecs-style decoder configs, and containers
 that carry a timestamp with every frame.
 
-- **Catalog producer and consumer.** Typed `VideoConfig`, `AudioConfig` and text renditions, the `json` and `binary` data track sections, shared video properties (display size, rotation, flip), stalled hints, cross-broadcast rendition references, and the `archive` entry (timeline track, optional replay path, store URL, and format version). Extend it with your own sections through a lock or `#[serde(flatten)]`, or read unknown sections as raw JSON.
+- **Catalog producer and consumer.** Typed `VideoConfig`, `AudioConfig` and text renditions, the `json` and `binary` data track sections, shared video properties (display size, rotation, flip), stalled hints, cross-broadcast rendition references, and the `archive` entry (each track's timeline track, optional replay path, store URL, and format version). Extend it with your own sections through a lock or `#[serde(flatten)]`, or read unknown sections as raw JSON.
 - **Containers.** `legacy`, `cmaf`, and `loc`, decoded for you; unknown kinds pass through untouched.
 - **`Ordered`** reads a media track as timestamped frames, reorders groups, and skips ones that fall past your max age.
 - **Codecs described**: H.264, H.265, VP8, VP9, AV1, AAC, Opus, PCM.

diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md
@@ -19,7 +19,7 @@ The reference implementation. Every crate is on
 | [moq-uring](https://docs.rs/moq-uring) | Experimental Linux io\_uring worker: one pinned thread per ring serving moq-lite over its own QUIC stack. |
 | [hang](/lib/rs/hang) | The media layer: catalog, containers, ordered frame delivery. |
 | [moq-mux](/lib/rs/moq-mux) | Import and export fMP4/CMAF, MPEG-TS, Matroska, FLV, and Annex-B. |
-| [moq-archive](https://docs.rs/moq-archive) | Versioned hang recordings on any `object_store` backend: track layout, `.info` JSON, and segment objects. |
+| [moq-archive](https://docs.rs/moq-archive) | Versioned hang recordings on any `object_store` backend: track layout, `.info` JSON, per-track timelines, and span objects. |
 | [moq-video](/lib/rs/moq-video) | Native capture, hardware encode/decode (Apple, Windows, NVIDIA, VAAPI, V4L2, Android), and GPU rendering. |
 | [moq-v4l](https://docs.rs/moq-v4l) | Safe Video4Linux 2 bindings with the kernel headers checked in, so a build needs no libclang. |
 | [moq-audio](/lib/rs/moq-audio) | Microphone and speaker, Opus/PCM/AAC codecs, echo cancellation. |