The lossless audio plane stops being an operator opt-in — PUNKTFUNK_AUDIO_HIRES defaults on #280

Merged

enricobuehler merged 1 commits from worktree-audio-hires-default-on into main 2026-08-17 11:18:59 +00:00

Conversation 0 Commits 1 Files Changed 10

+125 -68

enricobuehler commented 2026-08-17 11:14:53 +00:00

Owner

Copy Link

Copy Source

What happened

A user picked Lossless 96 kHz / 24-bit in the macOS client, connected to a bazzite host, and got Opus. Nothing in any UI said why. The reason existed only as one INFO line in the host's journal:

hi-res audio requested by the client but PUNKTFUNK_AUDIO_HIRES is not enabled on this host — the session uses Opus 48 kHz

Every other condition on that session was satisfiable — stereo, 96000/24 is a carried format, and the link had 300 Mbps of video against a 4.6 Mbps cost. The only thing that lost was an operator opt-in nobody knew to set.

What changes

The host's half of the gate goes default ON, with PUNKTFUNK_AUDIO_HIRES=0 as the opt-out. That makes it the same shape as PUNKTFUNK_444, PUNKTFUNK_CHACHA20 and PUNKTFUNK_10BIT, and pf-host-config's field stops being the one Option<bool> deliberately read as unwrap_or(false) — it is now a plain bool.

The old default rested on "this spends bandwidth the host's owner never agreed to." Every clause of that is still true, but the operator is not who spends it — the client's user is, and §8.4 condition 1 is already that user's explicit menu choice, which still ships OFF.

What was actually being protected turns out to be nothing. The conditions that keep a link safe are mechanical rather than consent-based:

• the capture path must honestly deliver the rate (asked of the device, not inferred from a successful open);
• the cost must fit 25 % of the session's video bitrate;
• a frame must fit a datagram at that channel count.

A 5 Mbps session still cannot buy 96/24. The operator gate was not keeping modest links safe — it was keeping the feature unreachable.

Not a wire or ABI change

HOST_CAP_AUDIO_HIRES is set only when a session actually resolved to PCM, so it remains a statement about that session's wire rather than a capability advert. An ordinary session — one whose client does not set CLIENT_CAP_AUDIO_HIRES — is byte-identical to before. No Hello/Welcome layout moves, no ABI bump.

Also in here

• The decline log now names the opt-out and the value it must have, and tells the operator to remove the line. The old wording sent people looking for something to enable, which is now exactly backwards.
• The capture-rate probe's short-circuit now rests on hires_asked alone. Its guarantee — an ordinary session must not pay COM work on Windows for a feature nobody asked for — used to be carried by two conditions and is now carried by one, so that condition has to stay first. Noted where it matters.
• Four Android comments got stronger, not weaker. They warn that sending 48000/16 as a stand-in for "default" silently opts users into PCM, and described the blast radius as "any host with PUNKTFUNK_AUDIO_HIRES=1". That is now every host that has not deliberately opted out, so the 0/0 sentinel is load-bearing in a way it was not before.
• The "must be asked for at BOTH ends" claim is corrected in the Apple, Android and pf-client-core settings docs, plus the two docs-site surfaces. Those rows also carried staleness that predates this PR — 48/96 kHz only, stereo only, 1.5–4.6 Mbps — from before the 44.1 kHz family and hi-res surround landed; the figures are now 44.1–176.4 kHz, stereo through 7.1, 1.4–8.5 Mbps.

Verification

Gated on linux/amd64 (punktfunk-rust-ci), since punktfunk-host does not build on macOS:

	result
clippy --all-targets -p punktfunk-host -p pf-host-config -- -D warnings	clean
punktfunk-host tests	597 passed, 0 failed, 3 ignored
pf-host-config tests	14 passed, 0 failed
cargo fmt --check	clean

Both crates verified non-vacuously compiled (Checking/Compiling present for each) against the warm shared target dir. the_operator_default_is_off became the_operator_default_is_on; the_operator_gate_alone_can_decline now covers the opt-out path and still passes.

Owed, not done here

• A release note. CHANGELOG.md has one section per stable release with no Unreleased section, and there is no docs/releases/v0.30.0.md yet, so I did not invent either. This is a default-behaviour change and wants naming when 0.30.0 is cut. The docs row says "since 0.30" — worth confirming if the version lands differently.
• design/hi-res-audio.md §8.4 condition 2 still describes the operator opt-in. That file is in punktfunk-planning, a different repo.
• pf-client-core/src/trust.rs still says the plane is stereo-only and that the host declines surround at the default MTU. That contradicts surround_is_decided_by_the_frame_ladder, but it may still correctly describe what the desktop settings UIs do (GTK greys the row under 5.1/7.1), so I left it alone rather than guess which half is stale.

## What happened A user picked **Lossless 96 kHz / 24-bit** in the macOS client, connected to a bazzite host, and got Opus. Nothing in any UI said why. The reason existed only as one `INFO` line in the host's journal: > `hi-res audio requested by the client but PUNKTFUNK_AUDIO_HIRES is not enabled on this host — the session uses Opus 48 kHz` Every other condition on that session was satisfiable — stereo, 96000/24 is a carried format, and the link had 300 Mbps of video against a 4.6 Mbps cost. The only thing that lost was an operator opt-in nobody knew to set. ## What changes The host's half of the gate goes **default ON**, with `PUNKTFUNK_AUDIO_HIRES=0` as the opt-out. That makes it the same shape as `PUNKTFUNK_444`, `PUNKTFUNK_CHACHA20` and `PUNKTFUNK_10BIT`, and `pf-host-config`'s field stops being the one `Option<bool>` deliberately read as `unwrap_or(false)` — it is now a plain `bool`. The old default rested on *"this spends bandwidth the host's owner never agreed to."* Every clause of that is still true, but **the operator is not who spends it** — the client's user is, and §8.4 condition 1 is already that user's explicit menu choice, which still ships OFF. What was actually being protected turns out to be nothing. The conditions that keep a link safe are mechanical rather than consent-based: - the capture path must **honestly** deliver the rate (asked of the device, not inferred from a successful open); - the cost must fit **25 % of the session's video bitrate**; - a frame must fit a datagram at that channel count. A 5 Mbps session still cannot buy 96/24. The operator gate was not keeping modest links safe — it was keeping the feature unreachable. ## Not a wire or ABI change `HOST_CAP_AUDIO_HIRES` is set only when a session *actually resolved to PCM*, so it remains a statement about that session's wire rather than a capability advert. An ordinary session — one whose client does not set `CLIENT_CAP_AUDIO_HIRES` — is byte-identical to before. No `Hello`/`Welcome` layout moves, no ABI bump. ## Also in here - **The decline log now names the opt-out and the value it must have**, and tells the operator to remove the line. The old wording sent people looking for something to *enable*, which is now exactly backwards. - **The capture-rate probe's short-circuit now rests on `hires_asked` alone.** Its guarantee — an ordinary session must not pay COM work on Windows for a feature nobody asked for — used to be carried by two conditions and is now carried by one, so that condition has to stay first. Noted where it matters. - **Four Android comments got stronger, not weaker.** They warn that sending `48000/16` as a stand-in for "default" silently opts users into PCM, and described the blast radius as "any host with `PUNKTFUNK_AUDIO_HIRES=1`". That is now every host that has not deliberately opted out, so the `0`/`0` sentinel is load-bearing in a way it was not before. - **The "must be asked for at BOTH ends" claim is corrected** in the Apple, Android and `pf-client-core` settings docs, plus the two docs-site surfaces. Those rows also carried staleness that predates this PR — 48/96 kHz only, stereo only, 1.5–4.6 Mbps — from before the 44.1 kHz family and hi-res surround landed; the figures are now 44.1–176.4 kHz, stereo through 7.1, 1.4–8.5 Mbps. ## Verification Gated on `linux/amd64` (`punktfunk-rust-ci`), since `punktfunk-host` does not build on macOS: | | result | |---|---| | `clippy --all-targets -p punktfunk-host -p pf-host-config -- -D warnings` | clean | | `punktfunk-host` tests | **597 passed**, 0 failed, 3 ignored | | `pf-host-config` tests | **14 passed**, 0 failed | | `cargo fmt --check` | clean | Both crates verified **non-vacuously** compiled (`Checking`/`Compiling` present for each) against the warm shared target dir. `the_operator_default_is_off` became `the_operator_default_is_on`; `the_operator_gate_alone_can_decline` now covers the opt-out path and still passes. ## Owed, not done here - **A release note.** `CHANGELOG.md` has one section per stable release with no Unreleased section, and there is no `docs/releases/v0.30.0.md` yet, so I did not invent either. This is a default-behaviour change and wants naming when 0.30.0 is cut. The docs row says "since 0.30" — worth confirming if the version lands differently. - **`design/hi-res-audio.md` §8.4 condition 2** still describes the operator opt-in. That file is in `punktfunk-planning`, a different repo. - **`pf-client-core/src/trust.rs` still says the plane is stereo-only** and that the host declines surround at the default MTU. That contradicts `surround_is_decided_by_the_frame_ladder`, but it may still correctly describe what the desktop settings UIs *do* (GTK greys the row under 5.1/7.1), so I left it alone rather than guess which half is stale.

enricobuehler added 1 commit 2026-08-17 11:14:57 +00:00

feat(host/audio)!: the lossless plane stops being an operator opt-in — PUNKTFUNK_AUDIO_HIRES defaults on ... 9a163d4ebf

A user picked "Lossless 96 kHz / 24-bit" in the macOS client, connected to a
bazzite host, and got Opus. Nothing in any UI said why; the reason was one INFO
line in the host's journal saying PUNKTFUNK_AUDIO_HIRES was not enabled.

So flip the host half: default ON, explicit-off grammar, `=0` to refuse. That
makes it the same shape as PUNKTFUNK_444, PUNKTFUNK_CHACHA20 and
PUNKTFUNK_10BIT, and the field stops being the one `Option<bool>` in
pf-host-config read as `unwrap_or(false)` — it is now a plain `bool`.

The old default rested on "this spends bandwidth the host's owner never agreed
to". Every clause of that is still true, but the operator is not who spends it —
the client's user is, and §8.4 condition 1 is already that user's explicit menu
choice, which still ships OFF. What was really being protected was nothing: the
conditions that keep a link safe are mechanical, not consent-based (the capture
path must honestly deliver the rate, the cost must fit a quarter of the
session's video bitrate, and a frame must fit a datagram). A 5 Mbps session
still cannot buy 96/24. The operator gate was not keeping modest links safe, it
was keeping the feature unreachable.

No wire or ABI movement: HOST_CAP_AUDIO_HIRES is set only when a session
actually resolved to PCM, so it stays a statement about that session's wire
rather than a capability advert, and an ordinary session (no
CLIENT_CAP_AUDIO_HIRES) is byte-identical to before.

Also:

- The decline log now names the opt-out and the value it must have, and tells
  the operator to remove the line. The old wording sent people looking for
  something to enable, which is now exactly backwards.
- The capture-rate probe's short-circuit guarantee ("an ordinary session must
  not pay COM work for a feature nobody asked for") now rests on `hires_asked`
  ALONE, so that condition has to stay first. Noted where it matters.
- The four Android comments warning that sending 48000/16 as a stand-in for
  "default" silently opts users into PCM described the blast radius as "any host
  with PUNKTFUNK_AUDIO_HIRES=1". That is now every host that has not
  deliberately opted out, so those warnings are strengthened, not softened — the
  0/0 sentinel is load-bearing in a way it was not before.
- The "must be asked for at BOTH ends" claim is corrected in the Apple, Android
  and pf-client-core settings docs, and in the two docs-site surfaces. Those
  rows also carried pre-flip staleness (48/96 kHz only, stereo only, 1.5-4.6
  Mbps) that predates the 44.1 family and hi-res surround landing; the figures
  are now 44.1-176.4 kHz, stereo through 7.1, 1.4-8.5 Mbps.

Gated on linux/amd64 (punktfunk-rust-ci): clippy --all-targets -D warnings
clean, punktfunk-host 597 passed / 0 failed, pf-host-config 14 passed / 0
failed, both crates verified non-vacuously compiled.

enricobuehler merged commit e68f411f34 into main 2026-08-17 11:18:59 +00:00

enricobuehler referenced this issue from a commit 2026-08-17 12:48:39 +00:00

release: 0.30.0 — version bump, notes, CHANGELOG, Play notes

enricobuehler referenced this pull request 2026-08-17 12:49:03 +00:00

0.30.0 #285

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

FernandoMX FlipperDan HitFrostbite enricobuehler (Enrico Bühler) kszlim luxus nannku neoney sassycrown

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unom/punktfunk#280