enricobuehler
30bd10e301
Four changes to the client interface, kept together because two of them touch the same rows
and the last is a bug the first would have made far more visible.
A thirteenth `ui_palette` entry, `oled`. The palette table is hand-mirrored in three languages
(`pf-console-ui`'s `library.rs`, `GamepadPalette.swift`, `GamepadPalette.kt`), so it goes into
all three at index 1, directly after the brand default — which keeps `PALETTES[0]` the unknown-id
fallback and keeps the dark-to-pale cycling order intact. What earns the name is arithmetic, not
a darker shade of violet: the ramp's first two stops are literally (0,0,0) and the ground is pure
black, so the shaded half of the field is pixels switched off rather than "very dark grey", and
the calm mix the form screens sit under lifts toward nothing at all. Mean cell luminance is 0.019
against Violet's 0.254. The bright corner keeps a faint indigo-to-violet ember so the backdrop is
still a field with somewhere to go, and that ember carries enough chroma at that luminance
(60 degrees of hue travel across 13 of the 16 cells) to satisfy the existing multi-tone assertion
without adding `oled` to the near-neutral exemption Graphite and Opal take. Each port gains an
`oled_is_actually_black` test that measures the claim — pure-black corner cells, a mean under half
the darkest other field's — rather than restating the table.
A new device key, `gamepad_ui_mode`. The gamepad-UI switch had been deciding two things at once:
whether to offer the controller-optimized interface at all, and that it appears only while a pad
is attached. A user asked for the second half to stop applying. `"connected"` (the default, and
exactly what the lone Bool meant) and `"always"` separate them, surfaced as a "Show it" row
directly under the switch on all five settings surfaces and built only while that switch is on —
a picker whose every option decides nothing is worse than no picker. `GamepadUIEnvironment.isActive`
takes the mode with NO default argument on purpose: a call site that forgot it would silently
strand everyone who chose Always back on "only with a controller", which is the one bug this
parameter exists to make impossible. An unrecognized value waits for a controller, so a mode a
newer client wrote can never trap an older one in a layout it has no way back out of. It stays a
device preference on both platforms, never part of a profile: which interface this device wears
has nothing to do with how a host streams to it.
The smoothness buffer is hidden under Lowest latency, not dimmed. Everywhere else already hid it
— the GTK and WinUI shells, the Apple touch and tvOS screens, the Android touch screen — because
under that intent it names a quantity that does not exist. Two surfaces disagreed: Apple's gamepad
settings screen left the row live and steppable, and the desktop console dimmed it, having no way
to drop a row from a fixed list. That list is now rebuilt each frame through a `row_applies`
filter. The concern about a vanishing row moving everything under the cursor does not apply here
and the new test says why: the row it drops sits directly BELOW the row that drops it, so the only
cursor that can be present when the list shrinks is the one on the intent row, which does not
move. Two latent hazards went with it — `apply_row` had been indexing the row list on the
assumption the cursor is always in range, and nothing re-clamped that cursor when another writer
changed the intent behind the screen's back.
Pale palettes were unreadable on tvOS, reported from the field. `GamepadInk` was never the
problem: it flips correctly for a pale field, it is not platform-gated, and every tvOS gamepad
entry point already published it. The cause is that this app sets `preferredColorScheme` nowhere
and declares no `UIUserInterfaceStyle`, so every SYSTEM-derived colour landing on those screens —
a `.secondary` placeholder, a `.bordered` button's chrome, a NavigationStack title, a material's
frost — resolved against the DEVICE appearance, which the palette cannot reach. On iPhone, iPad
and Mac a great many users sit in Light mode, so under a pale palette those colours came out dark
and the theme looked correct by accident; an Apple TV is Dark essentially always, so every one of
them rendered white on a light field. The mirror image was broken too and had simply never been
reported: a dark palette on a Light-mode iPhone was already drawing dark on dark. The scheme is
now published beside the ink, once, in `GamepadInkModifier`, because the two are halves of one
decision and publishing only the ink silently loses every colour the frameworks draw on the app's
behalf. Two structural amplifiers went with it: `ConsoleGlass` had been scoping the scheme to the
fill inside its `.background {}` on the tvOS and pre-26 branches while the 26 branch put it on the
content, so no console row's own content ever saw it on tvOS; and `LibraryView`'s navigation
chrome and its loading, error and empty states sit above `LibraryCoverflowView` and so were never
inked at all on tvOS and macOS, where that view is presented directly rather than through the
iOS-only `GamepadLibraryScreen` wrapper.
That last one exposed a second tvOS gap worth closing in the same breath: `ui_palette` had no row
in tvOS's ordinary Settings, and the gamepad settings screen that owns it everywhere else needs an
extended-profile controller to open on tvOS. An Apple TV driven by the Siri Remote alone could not
reach the palettes at all, which would now include the OLED one. `SettingsView.tvBody` carries a
Background row.
Verified: pf-console-ui builds, passes `clippy --all-targets -D warnings` and runs 74 tests clean
under linux/amd64 (a Mac `cargo check` of that crate is vacuous — every module is cfg'd to
linux/windows); `cargo fmt --check` clean for it and pf-client-core. Android `:app` runs 80 tests
with 0 failures, including four new `gamepadUiActive` cases and the palette parity table. The
Apple package builds for macOS AND tvOS and its 9 palette/gamepad-UI tests pass — the tvOS
typecheck is possible because the checked-in xcframework already carries a `tvos-arm64` slice. The
tvOS RENDERING fix is compile-verified only; an on-glass Apple TV check under a pale palette is
still owed, and is the one thing here that a build cannot answer.
Low-latency desktop and game streaming with first-class Linux and Windows hosts.
Run the host on a Linux machine or a Windows PC, connect from a Mac, PC, phone, tablet, or TV, and stream your desktop or games — each device at its own native resolution and refresh rate, over your local network.
📖 Documentation: docs.punktfunk.unom.io — start with How It Works or the Quick Start.
💬 Community: Discord — chat, support, and Android beta access · r/Punktfunk.
🔒 Security: found a vulnerability? Report it privately to security@punktfunk.com — see SECURITY.md. Please don't open a public issue.
Punktfunk pairs a virtual-display streaming host with native clients on every platform. It speaks
the existing GameStream protocol, so any Moonlight client works
day one — and adds its own faster punktfunk/1 protocol that breaks the ~1 Gbps FEC wall with a
GF(2¹⁶) Leopard-RS transport. A single shared Rust core (punktfunk-core) holds the
protocol, FEC, and crypto, linked into the host and every native client — directly as a Rust crate
on Linux and Windows, and over a stable C ABI from the Apple and Android apps.
What makes it different
- Your device's exact mode. For each client that connects, the host spins up a virtual display sized to that device — 1080p60 to a laptop, 1440p120 to a desktop, 4K to a TV, all at once. No letterboxing, no scaling, no rearranging your real monitors.
- Displays you configure, not just create. Keep a game's display (and the game) alive across disconnects so a reconnect drops straight back in; make the stream your sole desktop or extend alongside your monitors; let several devices become monitors of one desktop; keep each client's scaling. One-click presets in the console — a dedicated couch box, a shared desktop, a multi-monitor workstation. See Virtual displays.
- A real virtual display on Windows, too. On Linux the host uses per-compositor virtual outputs; on Windows you get the same on-the-fly virtual display — at the client's exact mode, no physical monitor or dummy HDMI plug, even on the secure desktop (UAC / lock screen). It also has its own indirect display driver (IDD) the host pushes finished frames straight into, rather than scraping a screen — tight, push-based integration that's unusual for a Windows streaming host.
- Low latency, GPU end to end. Frames go straight from the compositor to the NVENC encoder with zero CPU copies (dmabuf → CUDA/Vulkan → NVENC), over a transport tuned for responsiveness rather than throughput. Stable 240 fps at 5120×1440; sub-millisecond capture-to-reassembly on-box, ~1.3 ms cross-machine on a LAN. (On Linux AMD/Intel, Vulkan Video for HEVC and AV1 with VAAPI for H.264 and as the fallback; a GPU-less software H.264 encoder exists as a last resort.)
- A library that fills itself. Steam and non-Steam titles show up as a grid on every client, and
plugins add their own sources — ROM Manager (your ROM collection, matched to installed emulators),
Playnite, VirtualHere. Install them from the console's Plugins page or with
punktfunk-host plugins add. See Plugins. - Works with what you already have. Any Moonlight/Artemis client connects over GameStream — and
native apps for macOS, Linux, Windows, and Android use the lower-latency
punktfunk/1protocol. - Secure by default. Hosts require a one-time SPAKE2 PIN pairing; after that, devices reconnect on a pinned identity. No accounts, no cloud. Hosts auto-advertise over mDNS, so clients find them on the network without typing an IP.
Status
| Component | State |
|---|---|
Core — punktfunk-core + C ABI (protocol · FEC · crypto · QUIC) |
✅ Complete & hardened |
| GameStream host → stock Moonlight | ✅ Live end-to-end: pairing, RTSP, audio, per-client virtual output at native resolution, GPU zero-copy NVENC, gamepads |
Native protocol — punktfunk/1 |
✅ Validated live: QUIC control + GF(2¹⁶) FEC/AES-GCM data plane, PIN pairing, mDNS discovery, mid-stream mode renegotiation |
| Windows host (Windows 11 22H2+, x64) | ✅ Beta — shipping as a signed installer: its own all-Rust IddCx virtual display (secure-desktop capable) with a sealed IDD-push capture path — finished frames pushed straight into its own driver, not screen-scraped (no DDA/WGC) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
macOS / iOS / tvOS client (clients/apple) |
✅ Streaming live: VideoToolbox decode (HEVC, and AV1 on hardware that decodes it), controllers incl. DualSense, discovery, pairing, speed test |
Linux client (clients/linux + clients/session) |
✅ Streaming live: relm4/GTK4 launcher shell that spawns a Vulkan session binary — Vulkan Video / VAAPI / software decode, PipeWire audio, SDL3 controllers, Skia console UI; ships as Flatpak/apt/rpm/Arch |
Android client (clients/android, phone + TV) |
✅ Streaming live: AMediaCodec decode + HDR10, AAudio audio, controllers, discovery, pairing |
Windows client (clients/windows, WinUI 3) |
✅ Streaming live: WinUI 3 shell + Vulkan session presenter, hardware decode on all GPU vendors via Vulkan Video → D3D11VA → software (NVIDIA + Intel validated on glass), WASAPI audio, SDL3 controllers, discovery, pairing; ships as signed MSIX (x64 + ARM64). Hardware decode and HDR10 present validated on glass on NVIDIA and Intel, including HDR pass-through on the Intel D3D11VA path |
Web console + management API (web/) |
✅ TanStack console over the OpenAPI mgmt API: host status, paired devices, on-demand PIN pairing, game library, virtual-display presets, plugin store, GPU selection, performance capture graphs, live host logs, host updates |
Every native client also ships a tiered stats overlay (Compact / Normal / Detailed) with a
shared vocabulary across platforms, and the session client carries a full gamepad-driven console
shell (pf-console-ui): host list, PIN pairing, settings, and an on-screen keyboard.
The GameStream host works with a stock Moonlight client — validated live on NVIDIA hardware
(RTX 5070 Ti, RTX 4090): PIN pairing that persists across restarts, an app catalog, RTSP/ENet/audio,
and video at the client's exact resolution and refresh via a per-session virtual output (KWin,
gamescope, Mutter, and Sway/wlroots backends), encoded with GPU zero-copy (dmabuf → CUDA/Vulkan →
NVENC) up to 5120×1440@240. The native punktfunk/1 protocol adds a QUIC control plane and a
GF(2¹⁶) Leopard-FEC + AES-GCM data plane (p50 ~0.8 ms capture→received at 720p120), with
mid-stream mode renegotiation and a wall-clock skew handshake so latency stays valid across machines.
Both run from one process: bare punktfunk-host serve is the secure native-only default
(punktfunk/1 + the management API/web console), and serve --gamestream additionally enables the
GameStream/Moonlight-compat planes (opt-in, trusted-LAN only — GameStream has inherent on-path
weaknesses). The host is managed through a REST API and web console. The host builds against
FFmpeg 7 or 8; the clients link no FFmpeg at all — they decode natively (Vulkan Video, DXVA,
VAAPI, VideoToolbox, MediaCodec, openh264 + rav1d).
What works where: the support matrix · where it's heading: the roadmap.
Install the host
Pick your platform and install from its package registry — the per-platform guide covers adding the repo, first run, and the web console. The Linux host is the primary, most battle-tested path; on SteamOS the host is built on-device by a script instead, and a Windows host ships as a signed installer (all-vendor: NVIDIA, AMD, Intel).
| Platform | Install | Guide |
|---|---|---|
| Ubuntu / Debian (apt) | sudo apt install punktfunk-host (after adding the repo) |
Ubuntu / Debian · packaging/debian |
| Bazzite / Fedora Atomic (systemd-sysext) | curl -fsSLO https://git.unom.io/unom/punktfunk/raw/branch/main/packaging/bazzite/punktfunk-sysext.sh && sudo bash punktfunk-sysext.sh install (no layering, no reboot; rpm-ostree + bootc also supported) |
Bazzite |
| Fedora (dnf) | sudo dnf install punktfunk (after adding the repo; the console comes with it) |
Fedora · packaging/rpm |
| Arch / CachyOS (pacman) | sudo pacman -Syu punktfunk-host (binary repo — always a full -Syu) |
Arch Linux · packaging/arch |
| SteamOS / Steam Deck (on-device build) | bash ~/punktfunk/scripts/steamdeck/install.sh (after cloning this repo to ~/punktfunk) |
SteamOS (Host) |
| Windows (11 22H2+, x64) | winget install unom.PunktfunkHost (after winget source add -n punktfunk https://winget.punktfunk.unom.io -t Microsoft.Rest) · or the signed setup.exe from the package registry |
Windows Host · packaging/winget |
punktfunk-host is the streaming host; punktfunk-web is the browser console (pairing + status).
Linux: every package ships systemd user units, so you don't launch the host by hand. The
host unit won't start until ~/.config/punktfunk/host.env exists, so copy the template your package
installed first:
mkdir -p ~/.config/punktfunk
# /usr/share/punktfunk/ on Fedora/Arch/Bazzite, /usr/share/punktfunk-host/ on Debian/Ubuntu
# (on Bazzite take host.env.bazzite instead)
cp /usr/share/punktfunk/host.env.example ~/.config/punktfunk/host.env
systemctl --user enable --now punktfunk-host # the streaming host
systemctl --user enable --now punktfunk-web # the web console (Arch: install punktfunk-web first)
The shipped host unit runs serve --gamestream — the native punktfunk/1 plane plus the
GameStream/Moonlight-compat planes, which belong on a trusted LAN only; for a native-only host drop
the flag with a systemctl --user edit punktfunk-host drop-in (which needs an empty ExecStart=
line before the replacement — the install guide has the snippet). Then open
https://<host-ip>:47992 and pair.
How the virtual display and input are wired up depends on your desktop — see KDE · GNOME · Steam / gamescope · Sway.
Windows: the installer registers and starts the host as a LocalSystem service, so there is
nothing to run by hand — open the web console and pair. Use
punktfunk-host service start|stop|restart|status if you need to control it. Upgrades happen in
place — the console's Updates card, winget upgrade unom.PunktfunkHost, or the newer
setup.exe over the old install; uninstall from Add/Remove Programs.
Full instructions: docs.punktfunk.unom.io/docs/install.
The console's Host page also shows when a newer host is out, along with the exact command for how this box was installed (or a one-click Update now on Windows) — see Updating the host. To remove it again, or to go back to an earlier version, see Uninstalling and Release Channels.
Connect a client
| Streaming to… | Use |
|---|---|
| Mac, iPhone, iPad, Apple TV | The Apple app (clients/apple) — also on TestFlight |
| Linux desktop / laptop | punktfunk-client (Flatpak / apt / rpm / Arch) |
| Steam Deck | The Decky plugin in Gaming Mode — it launches the client for you (Steam Deck); in Desktop Mode, the Flatpak directly |
| Android phone or TV | The Android app (clients/android) |
| Windows | Native punktfunk-client (signed MSIX) or Moonlight |
| Scripts, automation, another launcher | punktfunk — the headless CLI shipped in the Linux client packages (punktfunk pair, punktfunk hosts list --json, punktfunk launch <host>) |
| Anything else (browser, old phone, smart TV) | Moonlight over GameStream |
Each client discovers hosts on the network automatically and does a one-time PIN pairing. Per-device install steps: /docs/install-client.
Build & test (from source)
For development, or as an install fallback where no package is available:
cargo build --workspace # core, host, tray, shared client crates, Linux shell + session client, the `punktfunk` CLI, probe (Linux & macOS)
cargo test --workspace # unit + loopback + proptest + C ABI harness
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check
cargo run -p loss-harness # FEC loss-resilience sweep (no network needed)
bash crates/punktfunk-core/tests/c/run.sh # standalone C-ABI link + round-trip proof
The C header regenerates from crates/punktfunk-core/src/abi.rs on every build (cbindgen via
build.rs) into include/punktfunk_core.h. The Apple, Android, and Windows clients have their own
toolchains (Xcode/swift build, Gradle, and cargo on the MSVC target) — see each client's README
and the docs site.
Layout
crates/
punktfunk-core/ protocol · FEC · pacing · crypto · QUIC control plane — the C ABI (lib + cdylib + staticlib)
punktfunk-host/ the host (Linux + Windows): virtual displays · capture · encode · input · GameStream · punktfunk/1 · mgmt
pf-client-core/ shared client plumbing (Linux + Windows): session pump · native decode ladder · audio · SDL3 gamepads · trust · discovery
pf-presenter/ Vulkan session presenter: SDL3 window · ash swapchain · frame present · input capture
pf-console-ui/ Skia console UI for the session client: gamepad shell · stats OSD · pairing · on-screen keyboard
pf-bitstream/ H.264 / H.265 / AV1 bitstream parsing + per-AU decode plans — the one parser every native rung submits from
pf-vkdecode/ native Vulkan Video decode (H.264 / H.265 / AV1) on the presenter's own device
pf-dxvadec/ native DXVA buffer layouts + AuPlan → picparams conversion (the Windows D3D11VA rung)
pf-vaadec/ native libva buffer layouts + AuPlan → picparams conversion (the Linux VAAPI rung)
pf-driver-proto/ host ↔ pf-vdisplay driver contract: control IOCTLs + IDD-push frame transport (no_std)
punktfunk-tray/ host tray icon (Windows notification area / Linux StatusNotifierItem)
clients/
apple/ macOS / iOS / tvOS app (Swift · VideoToolbox · Metal · GameController)
linux/ Linux launcher shell (Rust · relm4 / GTK4 / libadwaita) — spawns the session client to stream
session/ punktfunk-session, the Vulkan streaming session (Rust · SDL3 · ash · Skia console UI) — also runs standalone (gamescope, Decky)
windows/ Windows desktop app (Rust · WinUI 3 · D3D11 · WASAPI · SDL3)
android/ Android phone + TV app (Kotlin · Rust JNI core · AMediaCodec · AAudio)
cli/ punktfunk, the headless client CLI — pair · hosts · wake · library · launch · punktfunk:// links
probe/ headless reference / measurement client for punktfunk/1
decky/ Steam Deck Decky plugin
web/ web console (TanStack) over the management API — status · devices · pairing · library · displays · plugins · GPUs · performance · logs · updates
api/openapi.json management-API OpenAPI spec (regenerated via `punktfunk-host openapi`, checked in)
sdk/ `@punktfunk/host` — TypeScript management-API client + event stream (Effect)
plugin-kit/ `@punktfunk/plugin-kit` — the plugin authoring kit (bun / TypeScript)
packaging/ apt · rpm / COPR · Arch · Flatpak · Bazzite sysext + bootc · Windows installer + drivers · winget · Nix · gamescope
docs-site/ public documentation site (Fumadocs) — https://docs.punktfunk.unom.io
include/punktfunk_core.h cbindgen-generated C header (checked in)
tools/ latency-probe · loss-harness (measurement)
ci/ CI container images (rust-ci · fedora-rpm)
Design invariants
- One core, linked everywhere. Protocol, FEC, and crypto live in
punktfunk-coreexactly once, exposed over a stable, versioned C ABI (punktfunk_abi_version(),PunktfunkConfigcarries its ownstruct_size). Every native client links the same core. - No async on the hot path. The per-frame pipeline uses native threads only;
tokio/quinnare gated behind the off-by-defaultquicfeature (control plane only). - Native client resolution, no scaling. Each session gets a virtual output at exactly the
client's WxH@Hz; each compositor keeps its own backend behind a shared
VirtualDisplaytrait. - FEC is the wall-breaker. GF(2⁸) (≤255 shards/block) for Moonlight compatibility; GF(2¹⁶)
(≤65535 shards/block, SIMD, O(n log n)) for
punktfunk/1to push past ~1 Gbps.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option — SPDX-License-Identifier: MIT OR Apache-2.0.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. See CONTRIBUTING.md.
Third-party components
Punktfunk's own source is MIT/Apache-2.0. Shipped binaries additionally link third-party components
under their own (permissive) licenses — see THIRD-PARTY-NOTICES.txt
(regenerate with scripts/gen-third-party-notices.sh). The Windows host build also
bundles FFmpeg under the LGPL v2.1+ (dynamically linked, replaceable DLLs; the license text and
notice ship in the installed licenses/ folder). The clients bundle no FFmpeg — they link
none.
Trademarks
Punktfunk is an independent project and is not affiliated with, endorsed by, or sponsored by NVIDIA, Microsoft, Sony, Valve, or the Moonlight project. "GameStream", "Moonlight", "Xbox", "DualSense", "DualShock", and "PlayStation" are trademarks of their respective owners and are used here only to describe interoperability.