Skip to content

fix(moq-hls): a segment URL names one byte sequence on every edge - #8778

Merged
kixelated merged 2 commits into
mainfrom
fix/hls-mux-estimates
Nov 15, 2026
Merged

kixelated merged 2 commits into
mainfrom
fix/hls-mux-estimates

Conversation

@kixelated

@kixelated kixelated commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

moq-hls names a segment seg/[{generation}.]{tag}.{n}.m4s, and the same URL on every edge must name the same bytes, since a CDN caches it and a player fails over between edges. Two cases broke that:

  • Live estimates reached the muxer. The tag hashes the normalized config (bitrate, framerate, and the other estimates cleared), but the muxer read the config as the edge first saw it plus the latest bitrate. A rendition built before the publisher's framerate estimate muxed at 90 kHz; one built after it, at framerate * 1000. Two edges then served differently timed segments under one URL (reproduced: video0: segment 0 names one byte sequence failed on main). The AAC descriptor also took the latest bitrate, so the init hash depended on when the edge built it.
  • A retired rendition's cut was edge-local. When the catalog drops or replaces a rendition, the old instance cuts its open segment at the last group it had read, under the uncut URL. Edges that see the catalog update at different media points cut at different groups (reproduced: 118 vs 148 bytes for one URL).

Approach

  • A rendition keeps its normalized config and muxes from it, so the tag hashes exactly what the muxer reads. Bandwidth and framerate for the master playlist and DASH manifest still follow the estimates. Video from a LOC or legacy container now always muxes at 90 kHz, and a synthesized AAC descriptor always carries the AAC-LC default bitrates.
  • A cut segment's tag is segments::cut(tag, groups_end, end), so each cut has its own URL. The uncut URL and another edge's cut URL return None. Rendition::segment finds a predecessor by the row it holds, so the cut stays reachable after a replacement.

New tests: edges_mux_alike_across_live_estimates and edges_name_a_retired_cut_apart. Both fail on main. estimate_before_first_init_reaches_aac_descriptor is removed because it asserted the old behavior.

Impact

  • No public API or wire change.
  • Output bytes change: HLS/DASH segments and inits for a LOC or legacy video rendition whose catalog carried a framerate now use a 90 kHz timescale. Synthesized AAC inits carry 256000/128000 in the descriptor instead of the catalog bitrate. A deployment that versions its packaged bytes in URLs should bump that version.
  • A retired rendition's last, cut segment lists under a new URL.

Alternatives

  • Hash the estimates into the tag. Rejected: each estimate would mint new URLs on every edge, and edges that read different estimates would never share a URL.
  • Drop the cut segment from a retired rendition. Rejected: a recorder would lose the last segment of every replaced rendition.

Follow-ups

None.

Caused by

  • moq-dev/moq#3406 - fed the latest catalog bitrate into the muxer, so the AAC descriptor changed with the estimate
  • moq-dev/moq#4641 - kept a rendition across framerate estimates but muxed at the timescale of whichever framerate the edge saw first
  • moq-dev/moq#7652 - cut a retired rendition's last segment at an edge-local boundary under the uncut segment's URL

Validation

  • cargo test -p moq-hls: 257 passed. The two new tests failed before the fix, at the segment-bytes and same-tag assertions.
  • just check origin/main and just ci origin/main passed.

Models

Size: S
Implementer: Claude Code, claude-opus-5-5, unknown effort

(Written by Opus 5.5)

🤖 Generated with Claude Code

Review

Rewritten by quest review after each round.

  • Head: abd9aa7

  • Base: origin/main at 6bc0984

  • Reviewer: Codex, gpt-6.1-sol, medium effort

  • Session: 01a1dcbd-c2c6-71d3-b98b-672c191426d1, round 1

  • Score: 9/10, The normalized muxing configuration and distinct cut-segment identities address cross-edge byte consistency with no actionable defects found; builds and tests were not run, as instructed.

  • Rounds: 1; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

kixelated and others added 2 commits November 14, 2026 16:38
An edge muxed with the catalog's live estimates: the framerate it saw when
building a rendition picked the timescale, and the latest bitrate the AAC
descriptor. Neither is in the tag, so two edges serving one segment URL could
serve differently timed bytes. The rendition now keeps and muxes its
normalized config, the one its tag hashes.

A retired rendition's cut segment ended where its own edge stopped reading,
under the uncut segment's URL. A cut is now named by where it ends.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 15, 2026 01:07
@coderabbitai

coderabbitai Bot commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 10 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 63f0c97e-30a5-4c8b-944d-b1561ce136af
Commits

Reviewing files that changed from the base of the PR and between 1ed1b35 and abd9aa7.

Files selected for processing: 3

  • rs/moq-hls/src/export/mod.rs
  • rs/moq-hls/src/export/rendition.rs
  • rs/moq-hls/src/export/segments.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

I reviewed both commits: moq-hls now muxes from the same normalized config the segment tag hashes, and a retired rendition's last cut segment gets its own URL.

  • Normalized config feeds the muxer — Rendition::video/audio store the normalize_* output, and muxer() builds from it directly. A LOC or legacy video now always muxes at 90 kHz with the 30 fps default_frame, and a synthesized AAC esds always carries the default bitrates. The master playlist and DASH still read the live estimates through refresh. matches_video, continues and handover read only decode and source fields, so normalizing the stored config does not change them.
  • Cut segments get distinct URLs — Follow::list retags the retired instance's final row with segments::cut(tag, groups.end, end). It hashes end as well as groups_end, so edges that cut at the same group but saw a different first "theirs" group still get different URLs.
  • Predecessor lookup by row — Rendition::segment drops the redundant rendition.tag == id.tag filter. live.holds already matches on the row's tag, so the cut URL resolves to its predecessor and the uncut URL for that number returns None. DASH lists only the current instance's own rows under rep.tag, so the cut never shows up in a manifest.
  • Tests — edges_mux_alike_across_live_estimates and edges_name_a_retired_cut_apart cover both cases. The hand-over tests now expect the cut tag.

A small doc follow-up: the segments::Row::tag doc and the module doc in rs/moq-hls/src/export/segments.rs still describe a row's tag as its track's tag. That is no longer true for a cut row. Both lines are outside the diff, so I couldn't comment on them inline.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 15, 2026
Merged via the queue into main with commit c386198 Nov 15, 2026
9 checks passed
@kixelated
kixelated deleted the fix/hls-mux-estimates branch November 15, 2026 05:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant