unom/punktfunk
6
0
Fork 1
Code Issues 3 Pull Requests 2 Actions 1 Packages Projects Releases 45 Wiki Activity
Files
ac395bbfa946775c0fb1fe0b68f90efb2a2db0a6
punktfunk/docs-site/content/docs/steam-deck.md
T
enricobuehler ac395bbfa9
ci / rust-arm64 (pull_request) Failing after 48s
Details
apple / swift (pull_request) Successful in 1m18s
Details
apple / screenshots (pull_request) Skipped
Details
ci / docs-site (pull_request) Successful in 1m22s
Details
android / android (pull_request) Successful in 3m22s
Details
ci / web (pull_request) Successful in 1m39s
Details
windows / build (aarch64-pc-windows-msvc) (pull_request) Successful in 1m0s
Details
ci / rust (pull_request) Canceled after 10m44s
Details
windows / build (x86_64-pc-windows-msvc) (pull_request) Canceled after 1m43s
Details
feat(clients/input): system buttons route around local overlays 
Pressing guide/Steam/QAM collided with the client device's own shell: iOS 26
opens its Game Overlay for the Home press (no app opt-out until iOS 27 makes
it a user setting), and a Gaming-Mode client opened BOTH Steam overlays for
one press — the local one covering the stream.

Two cross-client tier-P settings, zero wire changes:

- system_buttons (auto|forward|local): raw guide+misc1 passthrough. Auto
  forwards everywhere EXCEPT under gamescope, where SteamOS reacts to the
  same physical press no matter what.
- guide_gesture (auto|on|off): hold Select ALONE ~350ms sends the HOST's
  guide, down until release — held on, that's the host's long-press, which
  opens a Gaming-Mode host's QAM for regular pads. A Select tap is delivered
  on release with its up TAP_PRESS (50ms) behind, because per-transition
  sends fold into seq'd GamepadState snapshots and a back-to-back pair can
  coalesce into no press at all. A Select inside a combo (the escape chord)
  passes through untouched. Auto arms it only where the raw press can't
  reach the host cleanly: gamescope, iOS/iPadOS, tvOS.

The same SelectGesture rules live in pf-client-core (pure state machine +
unit tests), the Apple client (mask-diff adaptation in GamepadCapture), and
Android's GamepadRouter. Settings rows on every surface (GTK, WinUI,
console UI, Decky, Apple x2, Android x2) with profile plumbing throughout.

punktfunk-session grows a control socket
($XDG_RUNTIME_DIR[/app/$FLATPAK_ID]/punktfunk-session-ctl.sock — the one
runtime path a flatpak and the host see identically): 'guide'/'qam' verbs
inject synthetic taps. The Decky panel gains a Host menus section (visible
while the client runs) whose buttons press the host's Steam/QAM and close
the local menu so the host's shows through.

iOS 27's GCControllerHomeButtonSettingsManager deep-link is a TODO (the
class needs the Xcode 27 SDK to compile). Docs: input, client-settings,
steam-deck. Design: punktfunk-planning design/system-buttons-routing.md.

Gates: docker clippy --all-targets --locked -D warnings + tests
(pf-client-core 88 incl. 6 new gesture tests, pf-console-ui 47),
cargo fmt --all --check, swift build (macOS), gradle kit+app compile,
decky tsc --noEmit + py_compile. clients/windows not compiled (no box).
2026-08-04 21:11:05 +02:00

12 KiB
Raw Blame History

title, description
title description
Steam Deck (Decky) Install the Punktfunk Decky plugin to discover, pair, and stream from the Steam Deck's Gaming Mode — no drop to Desktop.

The Decky plugin adds a Punktfunk panel to the Steam Deck's Quick Access Menu (the … button), so you can find a host, pair, and start streaming without leaving Gaming Mode. It's the couch-friendly front end for the Steam Deck — built from real Steam UI, gamepad-navigable end to end.

Under the hood the plugin doesn't decode video itself: it discovers hosts, runs the PIN pairing, and launches the regular Linux client (usually the io.unom.Punktfunk Flatpak) the way gamescope needs so it fullscreens correctly. So the Deck has two ways to stream, and they share one client + one paired identity:

  • Gaming Mode → the Decky plugin (this page).
  • Desktop Mode → run the Flatpak directly, like any Linux app.

Before you start

You need three things on the Deck:

  1. Decky Loader — the plugin loader. Install it from decky.xyz if you haven't already.

  2. A Punktfunk client on the Deck — the plugin doesn't decode video itself, it launches a client. On a normal Deck that's the Flatpak, installed once in Desktop Mode:

    flatpak install --user https://flatpak.unom.io/io.unom.Punktfunk.flatpakref

    (Full options: Install a Client → Steam Deck.) If you have no Flatpak but a native punktfunk-client — a sysext, a distro package, a nix profile, your own build — the plugin launches that instead; with both installed the Flatpak wins, unless PF_DECKY_CLIENT=native (or flatpak) is set in the plugin backend's environment. But pairing, Wake-on-LAN and the host game library still go through the Flatpak, so install it on the Deck even then. Both kinds share ~/.config/punktfunk, so your identity, known hosts and settings are the same either way.

  3. A Punktfunk host running on your LAN — see Install the Host. The Deck finds it automatically over mDNS, so nothing to configure here.

Install the plugin

The plugin is published as a ready-to-install zip on every build. You don't need the Decky CLI or a developer toolchain — just paste a URL into Decky:

  1. On the Deck, open the Quick Access Menu (…) → the plug icon (Decky) → the gear (Settings) → enable Developer Mode.

  2. Open the new Developer tab and choose Install Plugin from URL.

  3. Paste the stable link and confirm:

    https://unom.io/pf-decky

The Punktfunk panel appears in the Quick Access Menu right away — no Deck restart needed.

Channels. https://unom.io/pf-decky is a short link to the stable channel (moves on vX.Y.Z releases), currently https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip. For the latest main build use the canary zip — https://git.unom.io/api/packages/unom/generic/punktfunk-decky/canary/punktfunk.zip — or pin an exact version with https://git.unom.io/api/packages/unom/generic/punktfunk-decky/<version>/punktfunk.zip. See Release Channels.

Use it

Open the Punktfunk panel from the Quick Access Menu, or Open Punktfunk for the full-screen page (host list + stream settings).

  • Discover — hosts on your network appear automatically (mDNS). Tap Refresh to rescan. A lock icon means the host requires pairing.
  • Add a host by hand — if mDNS can't reach it (another subnet, a VPN), tap + on the Hosts tab and enter its address; the port defaults to 9777. Saved hosts can be renamed, re-pointed at a new address, or forgotten from the same row.
  • Sleeping host? Streaming sends a Wake-on-LAN packet first, and when one actually went out the Deck waits far longer than usual for the host to answer, so a stream survives a resume from sleep. Nothing to enable — it's a no-op until the plugin has learned that host's MAC address, and the packet only lands if the host machine is armed to wake in its BIOS and its network card.
  • Pair — for a locked host, arm pairing on the host (its console or web console shows a 4-digit PIN), then enter that PIN on the Deck's keypad. Pairing persists, so the next connection is silent.
  • Stream — pick a host and the stream launches fullscreen in Gaming Mode. The plugin drives a hidden Steam shortcut behind the scenes so gamescope focuses and fullscreens it.
  • Library entry — a visible, branded Punktfunk app also appears in your Steam library. Launching it opens the client's console home (host picker, pairing, settings), gamepad-navigable — it does not resume a stream. If it ever disappears, the Quick Access Menu panel has a button to put it back.
  • Games — tap Games on a host row to browse that host's library, and Pin the ones you play. Pinned games show up on the full page and in the Quick Access Menu as one-tap streams that launch straight into the game.
  • Settings — resolution, refresh rate, render scale, bitrate, video codec, gamepad type, host compositor, and mic, written to the client the plugin launches. Leave Resolution / Refresh on Native to get the Deck's own mode, Render scale at 1× unless you want to trade bandwidth for sharpness (>1×) or sharpness for bandwidth (<1×), and Video codec / Host compositor on Automatic — that suits almost every host, so change them only when you're troubleshooting. With Gamepad type on Automatic the Deck's built-in controller is forwarded as a Steam Deck pad (paddles, both trackpads, gyro) — that needs Steam Input set to Off for Punktfunk (game page → ⚙ → Controller Settings), else Steam keeps those controls and only sticks + buttons reach the host.

Steam Input off is a trade-off, not a free win. The plugin installs a Steam Input layout called Punktfunk and points its shortcuts at it, and that layout's whole job is making the Deck's touchscreen arrive at the stream as real touch. Leaving Steam Input On with that layout gives you native touch plus a standard gamepad; setting it Off gives you the full Steam Deck pad — paddles, both trackpads, gyro — but the touchscreen stops working as touch. Pick per game, on the game page → ⚙ → Controller Settings.

To leave a stream: hold L1 + R1 + Start + Select for about a second and a half, or close the "game" from the Steam overlay. Either ends the session and drops you straight back to Gaming Mode. A quick press of the same four only releases captured input, so it is safe to hit by accident.

The Steam and … buttons stay with the Deck while streaming. SteamOS opens its own menus for them no matter what, so forwarding the raw press as well opened both menus at once — the Deck's covering the stream. To reach the host's menus instead: hold Select for the host's Steam menu (how it works), or open the Punktfunk panel — while a stream runs it grows a Host menus section whose two buttons, Steam menu on host and Quick access on host, press the button on the host and close the Deck's own menu so the host's shows through. Want the raw forwarding back? Settings → Steam / guide button → Send to host.

Updating

The plugin checks for updates itself — no Decky store needed. It covers both the plugin and the streaming client (they version independently), so when either has a newer build the panel shows an Update button (in the Quick Access Menu and on the full page). Tap it: the client updates in place, and if the plugin itself changed it downloads, verifies, replaces itself, and reloads — all without leaving Gaming Mode.

One exception: if your client isn't one the plugin can install for you (a sysext, a nix profile, a source build), the panel shows you the update command instead of a button — tap-to-install would only fail. A pending plugin update still gets its button.

The plugin check follows the channel you installed from: a plugin installed from the stable link tracks stable releases; one installed from the canary link tracks main builds.

Updating the client from the terminal? The Flatpak client is installed per-user, so run flatpak update --user io.unom.Punktfunk — without sudo. sudo flatpak update only touches the system installation and silently skips the client. (Un-sudo'd flatpak update updates both scopes, so it's the safe default.)

If the plugin Update button never appears (an older Decky Loader, or no network), update the plugin manually: Decky → Developer → Install Plugin from URL, and paste the same channel link again. Decky replaces the installed copy in place.

Troubleshooting

Symptom Fix
The stream never starts, Pair reports flatpak-not-found, or Games says the client isn't installed Install the client Flatpak in Desktop Mode (see Before you start).
No hosts listed Make sure the host is running and on the same LAN; the Deck needs avahi (shipped on SteamOS). Tap Refresh.
Pairing fails / "not armed" The PIN is shown only after you arm pairing on the host. Arm it, then enter the PIN within the window.
Stream launches but doesn't focus Start it from the panel (not by launching the Flatpak by hand) so Steam/gamescope focuses it.
The stream wedges — black, or won't close Open the full page → About tab → Force-stop, then start it again.
The Punktfunk library entry disappeared Quick Access Menu → Recreate library shortcut; it puts the entry back in place.
You want a clean slate About tab → Reset Punktfunk — clears saved hosts, stream settings and pinned games on this Deck, and keeps your paired identity.

Nothing here matching? The problem is probably on the host side — start at Troubleshooting, which is organised by symptom (host not found, pairing rejected, black picture).

Uninstalling

Removing the plugin through Decky removes the plugin and nothing else, so do these in order:

  1. Remove the plugin. Quick Access Menu (…) → the plug icon (Decky) → the gear (Settings) → Plugins → Punktfunk → Uninstall.

  2. Remove the Steam shortcuts it created. The plugin adds two non-Steam entries, both named Punktfunk — the one you see in your library, and a second one it keeps hidden to carry the stream. Decky removes neither. In your library, right-click a Punktfunk entry → Manage → Remove non-Steam game from your library, and repeat for the hidden one once you've let the library show hidden games.

  3. Remove the client, if you're done streaming on this Deck. In Desktop Mode:

    flatpak uninstall --user --delete-data io.unom.Punktfunk

    Your identity and saved hosts live in ~/.config/punktfunk and survive that — delete the directory too for a clean slate. See Removing a client.

  4. Revoke the pairing on the host. The host still trusts this Deck until you remove it from its web console — see Managing paired devices.

The Steam Input layout the plugin installed also stays behind as a selectable template named Punktfunk (~/.local/share/Steam/controller_base/templates/punktfunk.vdf), along with the per-account configset entry pointing at it. Leave them — with the shortcuts gone they apply to nothing — or delete the file if you'd rather not see it offered as a template.

The plugin source lives in clients/decky.

Reference in New Issue View Git Blame Copy Permalink