moq-hang: add optional Timeline track for seeking by time

[kixelated]

What

Adds an optional per-media timeline track to moq-hang that maps each moq-lite Group to the presentation timestamp of its first frame. It's the hang-flavored analog of MSF's media timeline track (draft-ietf-moq-msf-01), but binary and append-only instead of a JSON array.

Why

moq-lite's SUBSCRIBE/FETCH address content by absolute Group sequence, but users seek by time. Without an index, the only way to map a timestamp to a Group is to download and parse the start of every Group. The timeline track is a compact seek index: find the largest entry with PTS <= target, then subscribe/fetch that Group (which starts with a keyframe).

Design

• One frame per entry. The timeline is a single Group that grows over the broadcast, so a late subscriber reading from frame 0 receives the full index (moq-lite always retains the latest Group).
• Payload is a single varint — the Group delta from the previous entry (normally 1; larger values allow a sparse index).
• The PTS rides moq-lite's existing FRAME Timestamp Delta (zigzag signed, first-of-group = absolute), expressed in the track's Publisher Timescale. The timescale is application-defined and SHOULD match the media track being indexed.
• Referenced from VideoSchema/AudioSchema via a new optional timeline field naming the track.

Timeline Frame {
  Group Delta (i),
}

Reviewer notes

• No moq-lite changes — this is purely a hang-layer track definition plus one catalog field.
• A timeline describes one media track's structure; renditions of a media share it, while audio and video use separate timelines (described, not a normative MUST).
• Known sharp edge: because the Group delta is relative, a FETCH with Frame Start > 0 yields an absolute PTS (via the moq frame) but no Group anchor — consumers reconstruct Group numbers by reading from frame 0. Fine for the single-growing-group model.
• Wallclock is intentionally omitted; derivable from the broadcast Epoch + PTS later if needed.
• moq-hang has no changelog section (unreleased), so none was added (per CLAUDE.md).
• Validated with make draft-lcurley-moq-hang.txt (kramdown-rfc + xml2rfc-txt OK).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@kixelated, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 20 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c336c038-1d99-4514-a0d1-76fb2a7ea9a0

📥 Commits

Reviewing files that changed from the base of the PR and between 63bcb4f and 1514c7d.

📒 Files selected for processing (1)

• draft-lcurley-moq-hang.md

Walkthrough

The draft document is extended to introduce an optional Timeline track for seeking by media presentation timestamp. A "Timeline" term is added to the terminology section. Both the Video and Audio catalog schemas gain an optional timeline field (a track name reference), with accompanying descriptive text and updated schema examples. A new Timeline specification section is added, defining how subscribers resolve a target timestamp to a Group sequence, and specifying the encoding: timeline data is carried as moq-lite FRAME messages whose payloads contain Group delta values, with presentation timestamps derived from the frame's Timestamp Delta field, supporting sparse indexing and occasional backward steps.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding an optional Timeline track to moq-hang for time-based seeking.
Description check	✅ Passed	The description provides comprehensive context about the timeline track feature, explaining the problem it solves, the design approach, and implementation details relevant to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/hardcore-wiles-d159bd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

draft-lcurley-moq-hang.md (1)

53-53: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Tighten the Timeline definition.

The glossary says the index maps each Group to its presentation timestamp, but the later section defines that timestamp as the Group's first frame. Clarifying that here avoids ambiguity.

Suggested wording

- **Timeline**: An optional index mapping each media Group to its presentation timestamps, used for seeking.
+ **Timeline**: An optional index mapping each media Group to the presentation timestamp of its first frame, used for seeking.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@draft-lcurley-moq-hang.md` at line 53, Update the Timeline definition in the
glossary to clarify that the presentation timestamp refers to each Group's first
frame rather than leaving it as a vague reference to presentation timestamp.
Modify the existing definition to explicitly state that the index maps each
media Group to the presentation timestamp of its first frame, which will ensure
consistency with the detailed definition provided later in the document and
eliminate ambiguity for readers.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@draft-lcurley-moq-hang.md`:
- Around line 239-242: The section describing the timeline track uses "MAY start
a new Group" which makes re-anchoring optional, but this breaks the ability for
late subscribers to rebuild the full index unless earlier entries remain
discoverable. Either remove the optional permission to start a new Group (change
"MAY" to "SHOULD NOT" or remove the sentence), or if re-anchoring is allowed,
add explicit retention rules that guarantee earlier Group entries remain
discoverable to late subscribers even after a new Group is started, ensuring the
indexing contract remains intact.

---

Nitpick comments:
In `@draft-lcurley-moq-hang.md`:
- Line 53: Update the Timeline definition in the glossary to clarify that the
presentation timestamp refers to each Group's first frame rather than leaving it
as a vague reference to presentation timestamp. Modify the existing definition
to explicitly state that the index maps each media Group to the presentation
timestamp of its first frame, which will ensure consistency with the detailed
definition provided later in the document and eliminate ambiguity for readers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6c0d7b8c-9590-456e-ac5d-ef0a0e94bedb

📥 Commits

Reviewing files that changed from the base of the PR and between 0ef3524 and 63bcb4f.

📒 Files selected for processing (1)

• draft-lcurley-moq-hang.md