Skip to content

CI only, do not merge: full CI for the #602/#604/#605 stack - #611

Closed
okdaichi wants to merge 27 commits into
mainfrom
ccr-2161bc2c-wkewvo-ingest-optin
Closed

okdaichi wants to merge 27 commits into
mainfrom
ccr-2161bc2c-wkewvo-ingest-optin

Conversation

@okdaichi

Copy link
Copy Markdown
Collaborator

A temporary draft to run the full CI suite on the top of the stack (#602 → #604 → #605). ci.yml only runs for PRs that target main or develop, so #604 and #605, which are stacked on other branches, get only check-changelog. This PR will be closed once CI finishes. Review and merge the real PRs instead.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY

claude and others added 27 commits November 15, 2026 12:07
Add `qumo abr`, a relay client that, for every broadcast announced
beneath ABR_PREFIX, publishes an ABR broadcast at the same path with
ABR_SUFFIX appended (/live/cam1 -> /live/cam1.abr). It carries the
source's tracks as they are plus one rendition per ladder rung shorter
than the source video, encoded by ffmpeg.

- Every video track is in one MSF alternate group (altGroup 1) with its
  width, height, bitrate, codec and initRef; the source's bitrate is
  measured from its first groups.
- Every rendition numbers its groups as the source does and opens each
  with a keyframe at the same frame (-force_key_frames source), so a
  player can switch tracks at any group boundary.
- Rendition frames keep the exact LOC timestamp of the source frame they
  were encoded from: outputs are matched back to source frames by order,
  confirmed by timestamp.
- One ffmpeg decodes the source once for all renditions. Frames go in as
  fragmented MP4 (one fragment per frame) and come out as FLV (one pipe
  per rendition): both are read and written frame by frame, so neither
  adds a frame of delay. Encoding uses a microsecond time base, as the
  default frame-rate time base snaps live timestamps to a grid.
- The source track is forwarded without re-encoding and never waits on
  the encoder; a lagging encoder drops frames up to the next group.

Tested by unit tests (ladder, FLV reader, matcher, track buffer, bitrate
meter), an encoder test against real ffmpeg with off-grid timestamps,
and an integration test: ffmpeg -> RTMP ingest -> relay -> abr -> relay
-> viewer, checking the catalog and group-by-group alignment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
The playground viewer plays an MSF broadcast whose video tracks share an
alternate group (as `qumo abr` publishes) adaptively, switching between
renditions at group boundaries, and lets the user pick one by hand.

- Renditions come from the catalog: the first video track and the video
  tracks in its altGroup, tallest first, each with its decoder config.
- A SwitchingTrack merges the renditions' subscriptions into the one
  track the frame reader consumes. Renditions number their groups alike,
  so the new rendition takes over at its first group past those handed
  out; when it joins at a group already played, the next group is
  reserved for it so the old rendition cannot race it. A step up keeps
  the old subscription until it has sent every group before the cutoff
  (make before break); a step down ends it at once to free the link.
- The decoder is configured for each group's rendition at its keyframe.
- An AbrController steps down when frames fall behind their media time
  (or a group is lost), to the best rendition the receive rate since
  they fell behind carries with headroom; it steps up one rendition
  after a calm stretch, doubling the wait whenever a step up does not
  hold, and not past what a subscription's opening burst measured.
- The subscribe board gains an Auto/rendition picker and ABR stats in
  the overlay.

fix(relay): a subscriber stopping one group keeps its subscription

deliverGroup treated any WriteFrame failure as the subscriber leaving
and ended its egress, so a subscriber that stopped one group's stream
(STOP_SENDING), as a player gives up a late group or one of a rendition
it is leaving, lost the whole subscription. A failure while the
subscription is still open now abandons only that group.

Verified in headless Chromium against playground + rtmp + abr: playback
climbs 360p -> 720p -> 1080p; a 3 Mbit/s limit on the relay-to-browser
link drops it to 360p within ~2.5 s, and it climbs back once lifted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
gosec G204: ffmpeg's path is the operator's ABR_FFMPEG and its arguments
are built from the ladder, so the launch is marked as intended.
staticcheck SA4023: encoder.read returns only once its stream ends, so
the nil check on its error was always true.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
…aliases

- Rebase source timestamps on the first frame before handing them to
  ffmpeg: its FLV output carries 32-bit milliseconds, which a source on a
  large clock (microseconds since 1970) overflowed, so no rendition frame
  matched its source frame. The encoder test now uses such timestamps.
- Close the encoders already started when a later one fails to start,
  so their ffmpeg is waited for rather than left a zombie (Windows starts
  one per rendition).
- Do not transcode HLS opt-in announcements (/.hls/...): they name a
  broadcast already transcoded at its own path.
- Treat group sequence 0 as a group: readTrack no longer drops it, and
  the track buffer tracks its position with flags, not a 0 sentinel.
- Integration test: no require from the reader goroutines.
- Playground SwitchingTrack: watch each stop signal once, not with a new
  handler on the long-lived signal per acceptGroup call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
…efix

A broadcast whose catalog subscription is redirected to another is an
alias of it, as an HLS opt-in is: qumo abr no longer transcodes it, and
transcodes the broadcast it names, announced at its own path. This
replaces the hard-coded token.HLSDirectory check with what makes those
announcements aliases, so any other alias is covered too.

The integration test announces an HLS opt-in beside the source and
checks it is not transcoded; with the redirect check disabled it fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
…ge cases

Go unit tests (internal/abr coverage 37% -> 52%):
- outputBroadcast: init data listed under the track's name and replaced,
  not duplicated; TRACK_INFO passes the source's properties on; bitrate.
- renditions: the catalog entry a configuration adds (altGroup, codec,
  size, bitrate, initRef); frames dropped before configuration and before
  a group opens; groups numbered as the source's, with its LOC and wire
  timestamps; a group opening on a non-keyframe continues the last one.
- initData, isAVC, outputTrack, AliasError.
- startEncoders stops the ffmpeg it started when a later one fails.

Integration (TestABR_RenditionsBesideSource): audio is forwarded, the
source's measured bitrate reaches the catalog, and the ABR broadcast is
withdrawn when its source stops.

Playground: the controller does not step below the lowest rendition,
forgets a burst measurement after 30 s, steps up to a rendition of
unknown bitrate, follows catalog updates, and falls to the lowest when
nothing fits; SwitchingTrack lets go of a quiet old rendition after 5 s
and closing ends every subscription and cancels queued groups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
Resolves the CHANGELOG [Unreleased] conflict with #603 by keeping both
sides' entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
… /.hls/

qumo abr no longer transcodes every broadcast beneath ABR_PREFIX. A
publisher opts a broadcast in by announcing it beneath /.abr/
(/.abr/live/cam1 for /live/cam1), an announcement carrying no media that
redirects every subscription to the broadcast, as the HLS opt-in does.

- token: ABRDirectory beside HLSDirectory, and a key confined to a prefix
  signs for its mirror beneath each opt-in directory (OptInDirectories),
  so the app that grants a broadcast grants its opt-ins with one key.
- internal/optin replaces internal/hlsoptin: the redirect Handler, Path,
  and Broadcast (moved from qumo hls), shared by both egresses.
- qumo abr accepts the opt-ins beneath /.abr/, reads the catalog through
  the opt-in and follows its redirect only to the broadcast it names: an
  opt-in leading elsewhere is refused (MisdirectedError), so no one has
  another's broadcast transcoded under their name. The ABR broadcast is
  announced once the source is reached, and withdrawn with the opt-in.
  ABR_PREFIX and the alias detection it needed are removed.

Tests: the token tests cover the /.abr/ mirror and its neighbours (they
fail without the change); the integration test opts in through
internal/optin, checks that a broadcast without an opt-in and an opt-in
leading elsewhere are not transcoded (watching announcements, so even a
brief one fails it; it does with the redirect check disabled), and that
withdrawing the opt-in withdraws the ABR broadcast and opting in again
brings it back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
… opts into ABR

MoQ-native publishers opt in beneath /.abr/, but a browser does not send
what qumo abr took: WebCodecs encodes H.264 in Annex B, its parameter
sets in the stream and none in the catalog, and with a hardware encoder
prefers VP9.

- internal/abr/source.go: a source adapts a video track to the encoder.
  AVCC H.264 goes as before; Annex B H.264 has its configuration read
  from the SPS and PPS of the first keyframe and its frames rewritten
  with 4-byte lengths (access unit delimiters dropped); VP9 with a full
  codec string and a picture size goes as is, fMP4 describing it from
  those. Renditions are H.264 whatever the source.
- transcode starts the encoders once the source's configuration is
  known: at once, or at an Annex B source's first keyframe.
- The playground publish board gains an ABR box, which announces the
  broadcast's opt-in beneath /.abr/ beside it; the publisher's HLS and
  ABR opt-ins share one helper.

Tests: Annex B splitting, AVCC rewriting and the configuration record
from parameter sets; the source formats taken; and real-ffmpeg encoder
runs from an Annex B and a VP9 source, every frame matched and every
group opening on a keyframe. Checked in headless Chromium: the
playground publishes its test pattern (software H.264, Annex B) opted
into ABR, qumo abr encodes a 360p rendition, and a viewer of
/live/pub.abr climbs from 360p to the 720p source.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
… abr

Transcoding costs the operator, so a tenant's key alone must not let its
publishers opt into ABR. The previous commit mirrored every key's prefix
beneath /.abr/ as beneath /.hls/, which let any tenant's app sign
opt-ins without paying. token.within mirrors /.hls/ alone again;
ABRDirectory stays, as the opt-in path. (How a paid tenant is granted
the opt-in is a decision still open on the PR.)

qumo abr can now sign its own relay credential: RELAY_SIGNING_KEY, a key
for the whole namespace, signs RelayGrant (subscribe anywhere, for the
opt-ins and their broadcasts, and publish the ABR broadcasts) on every
dial in place of ?jwt=, and relaycred.Keep renews it before it lapses,
as qumo hls does. A key confined to less is refused at startup.

Tests: the token tests now require a tenant key not to reach /.abr/
(they fail against the mirror); unit tests for RelayGrant, the key check
and the dial target (a fresh credential replaces ?jwt=, the rest of the
query is kept, an invalid URL does not echo its credential); and an
integration test against a relay that verifies tokens: the tenant's key
cannot sign for the opt-in, and the opt-in its publisher announces is
neither routed nor transcoded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
…BR can be sold

A key's prefix is mirrored beneath an opt-in directory only for the
opt-ins its key set entry lists: "optIns": ["hls", "abr"]. A control
plane that sells an egress sets the member as its tenant pays, and the
relay refuses a token for an opt-in the key does not hold, and revokes
one on air at the next 30 s check of live sessions once it is removed.
A key whose entry lists none holds hls alone, as every key did before;
an empty list holds none.

A relay session's credentials all come from one key (auth.Verifier.
Ticket), so the opt-in is granted on the tenant's own key rather than a
second one: the publisher presents its /.abr/ ticket on the session that
carries its broadcast.

- token: OptIn (hls, abr) with its directory; Key.OptIns, read from and
  written to the key set as "optIns" (absent and empty kept apart,
  unknown names refused, as "pause" is); Verify and Key.Holds mirror the
  prefix only for the opt-ins held. Sign signs for every opt-in of the
  key's own prefix and leaves the rest to the relay, so an app need not
  be reissued its key when its tenant pays.
- qumo auth keygen -opt-ins hls,abr writes the member for a key set kept
  by hand, and its summary says which mirrors the key holds.

Tests: Verify and Holds per optIns (absent, empty, abr, hls+abr), the key
set round trip, Sign never signing for another tenant's opt-in, keygen's
member and its refusal of an unknown opt-in, and TestABR_PaidOptIn
against a relay verifying tokens: unpaid (optIns absent or empty), the
publisher's ticket for the opt-in is refused, the opt-in is not routed
and nothing is transcoded; paid (optIns hls, abr), the same ticket is
granted, the opt-in is routed, and qumo abr, on its own credential,
publishes the ABR broadcast. The whole integration suite passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
… lists

A key whose key set entry listed no optIns held the HLS mirror by
default, kept so that relays with auth on would not lose the HLS opt-in
on upgrade. That made HLS the one egress a key held without its tenant
paying for it. Now every opt-in is held alike: a key signs for its
prefix's mirror beneath an opt-in directory only when its entry lists
the opt-in, and one that lists none holds none.

BREAKING CHANGE: on a relay with auth on, a key whose publishers opt
into qumo hls needs "optIns": ["hls"] in its key set entry (or a key set
re-issued with qumo auth keygen -opt-ins hls); until then the relay
refuses their opt-in tokens, saying the root lies outside "the opt-ins
it holds []". A relay with auth off is unaffected. CHANGELOG carries the
note.

The absent and empty optIns no longer differ, so the key set writes the
member only when it lists something. qumo auth keygen holds none unless
-opt-ins is given. Tests that meant a key holding HLS now say so, and
new cases check that a key listing none holds no HLS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
…lishers' behalf

A pushed or pulled stream can't announce an opt-in itself, so the ingest
announces it beside the broadcast (/.abr/live/cam for /live/cam) for each
egress INGEST_OPT_IN lists. With auth on, only when one of the tokens the
publisher presents may publish the opt-in, so the key set's optIns decide
as they do for an MoQ publisher. A push now carries several tokens, each as
a ?jwt= on the stream key or RTSP URL.

Through a relay with RELAY_SIGNING_KEY, the ingest presents a ticket for
each opt-in directory beside its credential (upstream.Config.OptIns),
retried while the relay refuses it (relaycred.Hold). A push to a path
beneath an opt-in directory is refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJL7PH3rPhK5UTGavaB
… relaycred.Target

The transcoder's session follows redirects and, on RELAY_SIGNING_KEY, may
read every broadcast. Only the catalog was checked against the broadcast
the opt-in names, so a source whose video track redirected elsewhere had
another broadcast's media published as its renditions. readTrack now
refuses a track answered from another broadcast (MisdirectedError).

Also:
- an Annex B source whose encoders fail to start no longer starts ffmpeg
  again for each remaining frame of the group;
- relaycred.Target replaces three copies of the signed-URL builder (abr,
  hls, upstream), and upstream's no longer quotes a credential-bearing URL
  in its parse error;
- checkSigningKey drops a Sign call that cannot fail for a "/" key;
- stale comments that said ABR takes a key of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
- newUpstream signed an opt-in grant per opt-in to check it, but Sign signs
  for every opt-in of a directory it already signed publishGrant for, so
  the check could never refuse anything.
- keygen re-parsed the key set it had just marshalled to show the opt-ins,
  which token.ParseOptIns already returns normalized.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
…alog can't

A catalog size counts only when both width and height are positive, as the
encoder side already required; otherwise the decoded size is stated, and
none at all when that is not known yet, never "0p (source)". An Annex B
source's entry gets its decoded size and label at its first keyframe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
The relay grants and routes exact paths, but the opt-in's broadcast was
derived with path.Clean: /.abr/acme/../victim/cam is announced under acme's
grant, yet named /victim/cam, which the transcoder (subscribing to '/') would
read and publish as /victim/cam.abr.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
… by a nil end

keep took a nil end to mean Hold: present at once, retry for good, warn once.
A caller passing nil for "no cleanup" would silently get retry-forever. The
policy is now an explicit renewal (renewGrant, renewTicket); end is only the
cleanup run when a grant lapses, and a nil end does nothing. Keep and Hold
behave as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
The merge of main filed them under the release heading it brought in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
…61bc2c-wkewvo-abr-optin

# Conflicts:
#	CHANGELOG.md
#	internal/hls/feed.go
#	internal/hls/mux.go
#	internal/hls/mux_test.go
…irst keyframe

Runs the whole pipeline over a loopback session: the opt-in, the catalog,
then one Annex B keyframe in LOC. The output catalog lists the source
rendition with no size until the keyframe, then 640x360 "360p (source)".
The ladder has no rung below the source, so no ffmpeg is needed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
optin.Broadcast now reports such a path as naming no broadcast. A push
beneath an opt-in directory is still refused either way, and publishAuthorizer
refuses one outright: cleaned, /.abr/other/../live/cam would pass
RELAY_PUBLISH=/live/ as /live/cam, while the relay grants and routes it
beneath /.abr/other/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KPWMJNAzsnsiqRPREa2JqY
@okdaichi

Copy link
Copy Markdown
Collaborator Author

Full CI passed on the top of the #602/#604/#605 stack (12/12, benchmark skipped). Closing: this PR was only for CI.

@okdaichi okdaichi closed this Nov 17, 2026
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.

2 participants