Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
aab6cf6
feat(abr): transcode broadcasts into an ABR ladder beside their source
claude Nov 15, 2026
df0545e
style(abr): gofmt the integration test
claude Nov 15, 2026
ae221e7
feat(playground): adaptive bitrate playback of ABR broadcasts
claude Nov 16, 2026
74eb3b8
fix(abr): satisfy golangci-lint, and note the changes in CHANGELOG
claude Nov 16, 2026
aecac95
fix(abr): review fixes — epoch-scale timestamps, ffmpeg cleanup, HLS …
claude Nov 16, 2026
976da68
refactor(abr): recognize aliases by their redirect, not the /.hls/ pr…
claude Nov 16, 2026
bb09ad7
test(abr): cover the output catalog, renditions, lifecycle and ABR ed…
claude Nov 16, 2026
3096de7
Merge origin/main into the ABR branch
claude Nov 16, 2026
11f24d5
feat(abr): opt broadcasts in beneath /.abr/, as into qumo hls beneath…
claude Nov 17, 2026
70a60bf
feat(abr): transcode browser sources (Annex B H.264, VP9); playground…
claude Nov 17, 2026
39936c9
fix(abr): no /.abr/ mirror of tenant keys; RELAY_SIGNING_KEY for qumo…
claude Nov 17, 2026
47e24e3
feat(token): opt-ins a key holds come from the key set (optIns), so A…
claude Nov 17, 2026
cb495ec
feat(token)!: HLS is an opt-in like ABR: a key holds only what optIns…
claude Nov 17, 2026
c2451d2
fix(abr): refuse source tracks redirected to another broadcast; share…
okdaichi Nov 17, 2026
c743900
fix(abr): size the source rendition by its decoded video when the cat…
okdaichi Nov 17, 2026
c23518b
fix(abr): refuse an opt-in not spelled exactly as its broadcast's
okdaichi Nov 17, 2026
5dd46f9
Merge remote-tracking branch 'origin/main' into ccr-2161bc2c-wkewvo
okdaichi Nov 17, 2026
d0009f0
docs(changelog): keep the ABR entries under Unreleased, not v0.21.261118
okdaichi Nov 17, 2026
fb4dd70
Merge remote-tracking branch 'origin/ccr-2161bc2c-wkewvo' into ccr-21…
okdaichi Nov 17, 2026
2216eb6
test(abr): an Annex B source without a catalog size is sized at its f…
okdaichi Nov 17, 2026
61dba27
refactor(abr): drop what nothing needs; a startEncoders test that can…
okdaichi Nov 17, 2026
f5729d5
refactor(playground): ABR tuning as constants; audio-only decoder config
okdaichi Nov 17, 2026
9ff8b35
docs: #describe keeps its comment; a compact ABR CHANGELOG entry
okdaichi Nov 17, 2026
9c75f9c
build(playground): rebuild dist for the ABR controller and catalog ch…
claude Nov 17, 2026
4150410
Merge remote-tracking branch 'origin/ccr-2161bc2c-wkewvo' into ccr-21…
okdaichi Nov 17, 2026
c7b72ed
Merge origin/main (#602 squashed, #606, #607) into ccr-2161bc2c-wkewv…
okdaichi Nov 17, 2026
ec73d73
docs(changelog): #606 and #607 are unreleased, not in v0.21.261118
okdaichi Nov 17, 2026
f2874a8
ci: run the full suite now that #604 targets main
okdaichi Nov 17, 2026
98e8b28
test(abr): dial the transcoder over native QUIC in TestABR_PaidOptIn
claude Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

> **Breaking for the HLS opt-in on a relay with auth on.** A key no longer signs for its prefix's mirror beneath `/.hls/` on its own: it signs for the mirror beneath an opt-in directory only when its entry in the key set lists the opt-in (`"optIns": ["hls"]`). Add the member to each key whose publishers opt into `qumo hls` (or re-issue the key set 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.

### Added

- **`qumo abr` transcodes broadcasts into an adaptive-bitrate ladder (`internal/abr`).** A relay client: for every broadcast announced beneath `ABR_PREFIX` it publishes an ABR broadcast beside it, at the same path with `ABR_SUFFIX` appended (`/live/cam1` → `/live/cam1.abr`), carrying the source's tracks as they are plus one rendition per rung of `ABR_LADDER` (default `720:2500,360:800`) shorter than the source video, encoded by ffmpeg (`ABR_FFMPEG`, `ABR_CODEC`, `ABR_PRESET`). Every video track is in one MSF alternate group (`altGroup`) with its size, bitrate and decoder configuration, and every rendition numbers its groups as the source does, each opening with a keyframe at the same frame, so a player can switch between them at any group boundary. Rendition frames keep the exact LOC timestamp of the source frame they were encoded from. One ffmpeg decodes the source once for every rendition, adding about 10 ms per frame; the source track is forwarded without re-encoding and never waits on it. Aliases, broadcasts that redirect subscribers to another (such as HLS opt-ins), are not transcoded: the broadcast they name is. The source must be H.264 without B-frames.
- **The playground plays ABR broadcasts adaptively (`playground`).** A broadcast whose video tracks share an alternate group is played adaptively: the viewer switches renditions at group boundaries, stepping down when frames fall behind their media time to what the rate measured since then carries, and up one rendition after a calm stretch. A step up keeps the old rendition until its last group before the switch has arrived; a step down drops it at once. The subscribe board picks a rendition by hand or automatically, and shows the rendition playing, the receive rate and the lag.
- **`qumo abr` transcodes broadcasts into an adaptive-bitrate ladder (`internal/abr`).** A publisher opts a broadcast in by announcing it beneath `/.abr/` (`/.abr/live/cam1` for `/live/cam1`), a redirect to it (`internal/optin`, shared with HLS); `qumo abr` then publishes `/live/cam1` + `ABR_SUFFIX` (`.abr`) with the source tracks as they are plus one H.264 rendition per `ABR_LADDER` rung shorter than the source (default `720:2500,360:800`; `ABR_FFMPEG`, `ABR_CODEC`, `ABR_PRESET`), all in one MSF `altGroup` with groups aligned to the source's, so a player can switch at any group boundary. Sources: H.264 (AVCC or Annex B) or VP9, without B-frames. A key holds an opt-in only when its key-set entry lists it (`"optIns": ["hls", "abr"]`, `qumo auth keygen -opt-ins`); the relay refuses other opt-in tokens and revokes a removed one within 30 s. `RELAY_SIGNING_KEY` lets `qumo abr` sign its own relay credential. See `docs/site/content/en/docs/cli/abr.md`.
- **The playground opts a broadcast into ABR, and plays ABR broadcasts adaptively (`playground`).** The publish board's ABR box announces the broadcast's opt-in beneath `/.abr/` beside it, as the HLS scenario does beneath `/.hls/`. A broadcast whose video tracks share an alternate group is played adaptively: the viewer switches renditions at group boundaries, stepping down when frames fall behind their media time to what the rate measured since then carries, and up one rendition after a calm stretch. A step up keeps the old rendition until its last group before the switch has arrived; a step down drops it at once. The subscribe board picks a rendition by hand or automatically, and shows the rendition playing, the receive rate and the lag.
- **`PEERS` names are resolved again while the relay runs, so peers behind a name join and leave without a restart; an entry without a port is an SRV name (`_moqt._udp.hubs.example.com`) (`internal/relay`).** A `PEERS` entry that is neither `host:port` nor a name without a port now stops the relay at startup, and a host that doesn't resolve is retried instead of being dialed by name.
- **The relay re-reads its certificates while it runs (`internal/relay`).** About once a minute it reads `CERT_FILE`/`KEY_FILE`, `PEER_CERT_FILE`/`PEER_KEY_FILE` and `CA_FILE` and compares them with what it holds; what changed is taken from the next TLS handshake on, so cert-manager, a Vault or step-ca agent, or any job that writes the files needs no restart. A public certificate is taken once it parses and matches its key; a peer certificate and the CA together, once they pass the startup checks (issued by the CA, the peering name, valid now). Anything else is logged, once per distinct error rather than at every read, and the certificates in use are kept; renewal tools should replace the files atomically (write, then rename). Sessions already established are untouched. The CA is now checked at each handshake on both sides: as the dialed relay (`GetConfigForClient`) and as the dialer (`VerifyConnection` against the current CA, with the same checks crypto/tls made). The relay's key-set and usage requests are signed with the renewed peer certificate (`reqsign.Signer.Rotate`), and `qumo dns` re-reads its `PEER_CERT_FILE`/`PEER_KEY_FILE` on the same one-minute cadence and signs its feed reads with a renewed pair (`internal/certreload`, shared by both). New metrics: `qumo_relay_cert_reloads_total{cert,result}` and `qumo_relay_cert_not_after_seconds{cert}`, and `qumo_dns_cert_reloads_total{cert,result}` and `qumo_dns_cert_not_after_seconds{cert}`; alert on the `not_after` gauges. A CA is rotated by putting the new one beside the old in `CA_FILE` first ([TLS & mTLS](docs/site/content/en/docs/deployment/tls.md#certificate-renewal)).

### Fixed

Expand All @@ -24,10 +28,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- **`PEERS` names are resolved again while the relay runs, so peers behind a name join and leave without a restart; an entry without a port is an SRV name (`_moqt._udp.hubs.example.com`) (`internal/relay`).** A `PEERS` entry that is neither `host:port` nor a name without a port now stops the relay at startup, and a host that doesn't resolve is retried instead of being dialed by name.

- **The relay re-reads its certificates while it runs (`internal/relay`).** About once a minute it reads `CERT_FILE`/`KEY_FILE`, `PEER_CERT_FILE`/`PEER_KEY_FILE` and `CA_FILE` and compares them with what it holds; what changed is taken from the next TLS handshake on, so cert-manager, a Vault or step-ca agent, or any job that writes the files needs no restart. A public certificate is taken once it parses and matches its key; a peer certificate and the CA together, once they pass the startup checks (issued by the CA, the peering name, valid now). Anything else is logged, once per distinct error rather than at every read, and the certificates in use are kept; renewal tools should replace the files atomically (write, then rename). Sessions already established are untouched. The CA is now checked at each handshake on both sides: as the dialed relay (`GetConfigForClient`) and as the dialer (`VerifyConnection` against the current CA, with the same checks crypto/tls made). The relay's key-set and usage requests are signed with the renewed peer certificate (`reqsign.Signer.Rotate`), and `qumo dns` re-reads its `PEER_CERT_FILE`/`PEER_KEY_FILE` on the same one-minute cadence and signs its feed reads with a renewed pair (`internal/certreload`, shared by both). New metrics: `qumo_relay_cert_reloads_total{cert,result}` and `qumo_relay_cert_not_after_seconds{cert}`, and `qumo_dns_cert_reloads_total{cert,result}` and `qumo_dns_cert_not_after_seconds{cert}`; alert on the `not_after` gauges. A CA is rotated by putting the new one beside the old in `CA_FILE` first ([TLS & mTLS](docs/site/content/en/docs/deployment/tls.md#certificate-renewal)).

- **A relay signs its key-set and usage requests, and `qumo dns` its feed reads, with its peer identity (`internal/reqsign`, #601).** With `PEER_CERT_FILE` and `PEER_KEY_FILE` (an ECDSA key; `qumo dns` takes the same two settings), each request carries `X-Relay-Certificate`, `X-Relay-Timestamp` and `X-Relay-Signature`: the key's ECDSA signature (ASN.1, base64) over SHA-256 of `qumo-relay-request`, the method, the request URI (path and query), the timestamp and the hex SHA-256 of the body, one per line, signed again on every retry. The receiver then knows which relay is calling from a key only that relay holds, and a captured request can't be changed or used for long, where a bearer token copied from a node could be reused until it is replaced. The bearer token (`QUMO_RELAY_TOKEN`, `QUMO_DNS_FEED_TOKEN`) is still sent beside it. A 401 is logged with the server's `Date` beside the local time. Funnel, HLS and ingest, which have no peer identity, are unchanged.

## [v0.20.261114] - 2026-11-14
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ qumo rtmp # Start an RTMP ingest server (bridges RTMP → MoQT over TCP
qumo rtsp # Pull from an RTSP source (e.g. an IP camera) and republish as MoQT
qumo rtsp-push # Start the RTSP push ingest server (TCP :8554; bridges RTSP → MoQT)
qumo hls # Start the HLS/DASH egress server (subscribes to a relay, serves HLS/DASH)
qumo abr # Transcode broadcasts into an ABR ladder with ffmpeg and republish them (renditions in one MSF altGroup)
qumo abr # Transcode broadcasts opted in beneath /.abr/ into an ABR ladder with ffmpeg (renditions in one MSF altGroup)
qumo funnel # Funnel many HTTP senders into one MoQT track (announce + POST records)
qumo playground # One-command local demo: in-process relay + embedded web UI on http://127.0.0.1:8080
qumo loadgen # Out-of-process capacity load generator (publish|subscribe) — see [docs/perf](docs/perf/README.md#benchmarking--capacity)
Expand Down
4 changes: 2 additions & 2 deletions cmd/seed-moq/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ import (

"github.com/qumo-dev/qumo/internal/cmaf"
"github.com/qumo-dev/qumo/internal/envconfig"
"github.com/qumo-dev/qumo/internal/hlsoptin"
"github.com/qumo-dev/qumo/internal/optin"
"github.com/qumo-dev/qumo/internal/quicconfig"
)

Expand Down Expand Up @@ -102,7 +102,7 @@ func main() {
// Opt the broadcast into the HLS egress, which serves what is announced
// beneath /.hls/. The opt-in has no tracks of its own: it redirects every
// subscription to the broadcast, keeping the track name.
mux.Publish(ctx, moqt.BroadcastPath("/.hls"+path), hlsoptin.Handler(moqt.BroadcastPath(path)))
mux.Publish(ctx, moqt.BroadcastPath("/.hls"+path), optin.Handler(moqt.BroadcastPath(path)))

httpMux := http.NewServeMux()
httpMux.Handle("/", &moqt.WebTransportHandler{
Expand Down
92 changes: 71 additions & 21 deletions docs/site/content/en/docs/cli/abr.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,50 @@ weight: 5
---

Transcodes the broadcasts on a relay into an adaptive-bitrate (ABR) ladder.
For every broadcast announced beneath `ABR_PREFIX`, it publishes an ABR
broadcast beside it, at the same path with `ABR_SUFFIX` appended
(`/live/cam1` → `/live/cam1.abr`). The ABR broadcast carries the source's
tracks as they are, plus one rendition per rung of the ladder that is shorter
than the source video, encoded by [ffmpeg](https://ffmpeg.org/).
A publisher opts a broadcast in as it opts one into [`qumo hls`]({{< relref "hls" >}}):
by announcing it again beneath `/.abr/` (`/.abr/live/cam1` for `/live/cam1`).
For every opt-in, `qumo abr` publishes an ABR broadcast beside the broadcast,
at the same path with `ABR_SUFFIX` appended (`/live/cam1.abr`). It carries the
source's tracks as they are, plus one rendition per rung of the ladder that is
shorter than the source video, encoded by [ffmpeg](https://ffmpeg.org/).

## Opting in

The opt-in carries no media. It answers every subscription with a redirect to
the broadcast, keeping the track name (`internal/optin`, the same handler as
the HLS opt-in). `qumo abr` reads the catalog through it and follows the
redirect only to the broadcast the opt-in names: an opt-in that redirects
elsewhere, or answers itself, is refused, so no one can have another
publisher's broadcast transcoded under their own name. Paths are compared
exactly, as the relay grants and routes them: an opt-in spelled with a
trailing or doubled slash, or a `.` or `..` segment, is refused rather than
read as the cleaned path it might name. Withdrawing the opt-in
withdraws the ABR broadcast; the broadcast itself plays on.

### Paying for the opt-in

Transcoding costs the operator, so the opt-in is an option a tenant holds,
not one every key has. A signing key confined to a prefix
(`qumo auth keygen -prefix acme/`) signs for the prefix's mirror beneath an
opt-in directory only when its entry in the relay's key set (`QUMO_AUTH_KEYS`)
lists that opt-in:

```json
{ "kid": "…", "prefix": "/acme/", "optIns": ["hls", "abr"] }
```

A control plane that sells ABR sets `optIns` when the tenant pays and removes
`abr` when it stops. The relay re-reads the key set every 30 s, so a new opt-in
is refused within half a minute, and one on air ends at the next 30 s check of
live sessions. HLS is held the same way (`"hls"`), and a key whose entry lists
no `optIns` holds none.

An alias is not transcoded: a broadcast that answers subscriptions with a
redirect to another, such as the HLS opt-in a publisher announces beneath
`/.hls/`, is another name for the broadcast it points to, which is announced
and transcoded at its own path.
The tenant's app signs the opt-in's token with the same key as the
broadcast's: `/.abr/acme/live/cam1` beside `/acme/live/cam1`, presented on the
publisher's session as a ticket, since a session's credentials all come from
one key. The app needs no new key when its tenant pays; the relay refuses the
token until the key set lists `abr`. `qumo auth keygen -opt-ins hls,abr` writes
the member for a key set kept by hand.

It dials the relay as an ordinary client: it subscribes to the source like any
viewer and publishes the ABR broadcast like any publisher. The relay itself
Expand All @@ -32,13 +66,14 @@ variables. Needs `ffmpeg` (or `ABR_FFMPEG`) on the host.
## Example

```console
$ RELAY_URL=https://relay:4433 ABR_PREFIX=/live/ ABR_LADDER=720:2500,360:800 qumo abr
INFO abr: starting relay=https://relay:4433 prefix=/live/ suffix=.abr ladder=720:2500,360:800 codec=libx264
$ RELAY_URL=https://relay:4433 ABR_LADDER=720:2500,360:800 qumo abr
INFO abr: starting relay=https://relay:4433 opt_in=/.abr/ suffix=.abr ladder=720:2500,360:800 codec=libx264
INFO abr: connected to the relay
INFO abr: transcoding source=/live/cam1 abr=/live/cam1.abr
INFO abr: transcoding opt_in=/.abr/live/cam1 source=/live/cam1 abr=/live/cam1.abr
```

A 1080p source at `/live/cam1` then has `/live/cam1.abr` beside it, whose
A 1080p source at `/live/cam1`, opted in at `/.abr/live/cam1`, then has
`/live/cam1.abr` beside it, whose
catalog lists:

| Track | Picture | Bitrate | From |
Expand All @@ -53,7 +88,10 @@ catalog lists:
- **One alternate group.** Every video track has `altGroup: 1` in the MSF
catalog, with its `width`, `height`, `bitrate`, codec and decoder
configuration (`initRef`), so a player knows they are alternatives of one
picture and what each costs.
picture and what each costs. The source's size is the one its catalog
states, or, when that states none (or a zero), the size decoded from its
video. An Annex B source's size is decoded only at its first keyframe, so its
entry has no size until then.
- **Aligned groups.** Every rendition numbers its groups as the source does,
and group N of each track starts at the same frame, with a keyframe. A
player can leave one track after group N and join another at group N+1
Expand All @@ -80,22 +118,34 @@ held up by the encoder.

## Requirements

- The source video must be H.264 (`avc1`) **without B-frames**: LOC carries
presentation timestamps only, so frames must arrive in presentation order.
OBS and ffmpeg in their low-latency settings (`-bf 0`, `-tune zerolatency`)
qualify.
- The source video must be one of:
- H.264 (`avc1`) with its decoder configuration in the catalog and
length-prefixed frames, as RTMP and RTSP ingest publish it;
- H.264 (`avc1`) in Annex B, its parameter sets in the stream before each
keyframe, as a browser's WebCodecs encoder in `annexb` format sends it:
the configuration is read from the first keyframe, and the frames are
rewritten with lengths for ffmpeg;
- VP9 with a full codec string (`vp09.PP.LL.DD`) and its picture size in
the catalog, as a browser's hardware encoder often sends it.

Renditions are H.264 whatever the source. Another codec is forwarded
without renditions.
- The source must have **no B-frames**: LOC carries presentation timestamps
only, so frames must arrive in presentation order. OBS and ffmpeg in their
low-latency settings (`-bf 0`, `-tune zerolatency`) and browser encoders in
`realtime` mode qualify.
- `ABR_CODEC` must be an H.264 encoder, so browsers decode every rendition
with the same decoder.

## Configuration

| Variable | Default | Description |
|---|---|---|
| `RELAY_URL` | `https://localhost:4433` | The relay to transcode broadcasts of, dialed as a client. It may carry a credential as `?jwt=` that grants subscribing to the sources and publishing the ABR broadcasts. |
| `RELAY_URL` | `https://localhost:4433` | The relay to transcode broadcasts of, dialed as a client. It may carry a credential as `?jwt=` that grants listing and subscribing to the opt-ins beneath `/.abr/` and the broadcasts they name, and publishing the ABR broadcasts. |
| `RELAY_SIGNING_KEY` | (unset) | A signing key (`qumo auth keygen`) the relay's key set trusts, for the whole namespace (prefix `/`). The transcoder signs a fresh credential with it on every dial, in place of any `?jwt=`, granting what it needs (subscribing anywhere, to read opt-ins and their broadcasts, and publishing the ABR broadcasts), and renews it on the session before it lapses. A credential fixed in `RELAY_URL` lapses with its token. |
| `RELAY_CA_FILE` | (unset) | PEM certificate to trust as the relay's root, instead of the system roots. |
| `RELAY_TLS_INSECURE` | `false` | Skip relay TLS verification, for a self-signed dev relay. |
| `ABR_PREFIX` | `/` | The directory whose broadcasts are transcoded. |
| `ABR_SUFFIX` | `.abr` | Appended to a source's path to name its ABR broadcast. Broadcasts already ending in it are not transcoded again, nor are aliases (broadcasts that redirect subscribers to another). |
| `ABR_SUFFIX` | `.abr` | Appended to a source's path to name its ABR broadcast. An opt-in for a broadcast already ending in it is ignored. |
| `ABR_LADDER` | `720:2500,360:800` | The renditions: comma-separated `height:kbps`. Rungs as tall as the source or taller are skipped. |
| `ABR_FFMPEG` | `ffmpeg` | The ffmpeg executable. |
| `ABR_CODEC` | `libx264` | The ffmpeg H.264 encoder, e.g. `h264_nvenc` or `h264_vaapi` for hardware encoding. |
Expand Down
Loading
Loading