enricobuehler
12148243bd
ci / docs-site (push) Successful in 1m0s
ci / web (push) Successful in 2m13s
arch / build-publish (push) Failing after 6m17s
decky / build-publish (push) Successful in 18s
android / android (push) Failing after 6m43s
docker / build-push (--build-arg FEDORA_VERSION=44, ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm) (push) Successful in 9s
docker / build-push (., web/Dockerfile, punktfunk-web) (push) Successful in 10s
docker / build-push (ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 9s
docker / build-push (ci, ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 8s
docker / build-push (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Successful in 53s
ci / bench (push) Successful in 5m6s
ci / rust (push) Failing after 9m30s
docker / deploy-docs (push) Successful in 27s
flatpak / build-publish (push) Failing after 4m50s
deb / build-publish (push) Failing after 7m17s
rpm / build-publish (43, bazzite, punktfunk-fedora-rpm) (push) Failing after 6m10s
rpm / build-publish (44, fedora-44, punktfunk-fedora44-rpm) (push) Failing after 6m2s
windows-host / package (push) Failing after 3m4s
apple / swift (push) Failing after 1m25s
windows-msix / package (arm64, C:\Users\Public\ffmpeg-arm64, --no-default-features, aarch64-pc-windows-msvc, C:\t-a64) (push) Failing after 3m1s
release / apple (push) Failing after 1m28s
windows-msix / package (x64, C:\Users\Public\ffmpeg, , x86_64-pc-windows-msvc, C:\t) (push) Failing after 2m15s
windows / build (aarch64-pc-windows-msvc) (push) Failing after 4m36s
windows / build (x86_64-pc-windows-msvc) (push) Failing after 4m43s
apple / screenshots (push) Has been skipped
plan §4.6 + Phase 3 productization: - Pinned bitrate: an Automatic client (bitrate 0) on a PyroWave session resolves to the codec's ~1.6 bpp operating point for the mode (≈200 Mbps at 1080p60) instead of the 20 Mbps H.26x default; explicit rates are honored. Mid-stream SetBitrate retargets are refused with the pinned rate acked (guards old/foreign clients), and the client-side AIMD controller + startup capacity probe stay off for the codec — no rate descent into wavelet mush, no climb probe whose VBV reasoning doesn't apply to hard per-frame CBR. Unit-tested. - All-intra silencing: the data plane drops drained keyframe/RFI requests on PyroWave sessions (the next frame IS the recovery), so the forced-IDR cooldown, RFI attempt, and storm coalescing never run. - Opt-in UI: 'PyroWave (wired LAN)' joins the console's Video-codec cycler; trust::Settings maps it to CODEC_PYROWAVE. Safe everywhere by the negotiation contract — an un-advertised preference falls back through the ladder. - FEC: decision recorded — adaptive FEC (10% start, loss-report driven) stays as-is for the MVP opaque-AU mode; the FEC≈0 policy belongs to the Phase-4 datagram-aligned mode. - THIRD-PARTY-NOTICES: the generator now lists third-party trees vendored inside first-party crates (pyrowave, Granite subset, volk, Vulkan-Headers) with their full license texts; file regenerated. - docs-site: 'PyroWave (wired-LAN codec)' page — what it is, the bandwidth table, how to enable it, current limits. Validated on .21: 309 host + 148 core + 26 client tests green, console-ui clean, both feature configs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
---
|
||
title: PyroWave (wired-LAN codec)
|
||
description: The opt-in ultra-low-latency wavelet codec for wired links — what it is, the bandwidth it needs, and how to turn it on.
|
||
---
|
||
|
||
PyroWave is an **opt-in** video codec mode for links that can afford real bandwidth: wired
|
||
Ethernet, a docked Steam Deck, a 2.5GbE LAN. It trades bitrate for latency — instead of
|
||
H.264/HEVC/AV1 on the GPU's video engine, frames are compressed with
|
||
[PyroWave](https://github.com/Themaister/pyrowave), an intra-only wavelet codec running as plain
|
||
Vulkan compute. Punktfunk vendors a pinned copy and runs it on both ends.
|
||
|
||
**It is never selected automatically.** HEVC/AV1 remain the codecs for Wi-Fi and everything
|
||
else; PyroWave engages only when *you* pick it on the client **and** the host supports it. If
|
||
either side can't, the session silently falls back to the normal codec ladder.
|
||
|
||
## Why you'd want it
|
||
|
||
- **Codec latency drops by an order of magnitude.** Encode and decode each take a fraction of a
|
||
millisecond of GPU compute (measured ~0.15 ms encode / ~0.07 ms decode at 1080p on an
|
||
RTX 5070 Ti), versus one-to-several milliseconds per side for the hardware H.26x pipelines.
|
||
- **Every frame is a keyframe.** There is no GOP, no reference chain, no keyframe round-trip
|
||
after packet loss — a lost frame costs exactly that frame, and the next one is already a
|
||
complete picture. The whole IDR/recovery apparatus that produces loss-time stutter simply
|
||
doesn't exist in this mode.
|
||
- **Uniform frame sizes.** The rate control hits its per-frame byte budget exactly, so the
|
||
pacer sees a flat load instead of 20–40× keyframe spikes.
|
||
|
||
## What it costs
|
||
|
||
Bandwidth. At the codec's ~1.6 bits-per-pixel operating point (4:2:0, 60 fps):
|
||
|
||
| Mode | Bitrate |
|
||
|---|---|
|
||
| 1280×800 @ 60 (Deck) | ≈ 100 Mbps |
|
||
| 1920×1080 @ 60 | ≈ 200 Mbps |
|
||
| 2560×1440 @ 60 | ≈ 355 Mbps |
|
||
| 3840×2160 @ 60 | ≈ 800 Mbps |
|
||
|
||
120 Hz doubles these. Gigabit Ethernet tops out around 940 Mbps of payload, so 4K60 wants
|
||
2.5GbE (or a lower rate). **Do not run this over Wi-Fi** — that's what HEVC/AV1 are for.
|
||
|
||
Also: PyroWave is **8-bit SDR only**. An HDR session stays on HEVC/AV1 regardless of this
|
||
setting.
|
||
|
||
## Turning it on
|
||
|
||
1. **Host** (Linux): build/install a host with the `pyrowave` feature. On an NVIDIA host the
|
||
capture path additionally needs `PUNKTFUNK_ENCODER=pyrowave` in `host.env` for the codec to
|
||
be advertised; AMD/Intel hosts advertise it automatically when the feature is present.
|
||
2. **Client** (Linux session client with the `pyrowave` feature): set **Settings → Video
|
||
codec → PyroWave (wired LAN)** in the gamepad console, or launch with
|
||
`PUNKTFUNK_PREFER_PYROWAVE=1`.
|
||
3. Leave the bitrate on Automatic: a PyroWave session pins itself to the ~1.6 bpp rate for
|
||
your mode (≈200 Mbps at 1080p60). An explicit bitrate is honored if you set one, but the
|
||
adaptive-bitrate controller stays off either way — this codec has no useful low-rate
|
||
regime, so under sustained loss the right move is switching back to HEVC, not degrading.
|
||
|
||
The stats overlay shows `pyrowave` as the decode path when the mode is active.
|
||
|
||
## Current limits
|
||
|
||
- Linux host + Linux client (including docked Deck) today; the Windows host and the Apple
|
||
native port are tracked on the [roadmap](/docs/roadmap).
|
||
- 8-bit SDR, 4:2:0 only.
|
||
- Mid-stream resolution changes rebuild the stream rather than switching seamlessly.
|