Picture & session

Fixes for a stream that connects but shows the wrong picture.

LinuxCopy Anchor Link

Black screen / no picture, but the client connectsCopy Anchor Link

The host can't capture this session. Check:

• You're logged into a Wayland session, not X11. Pick it on the login screen.
• The compositor meets its floor: Requirements → Desktop.
• host.env has no PUNKTFUNK_COMPOSITOR line. The host finds the live compositor itself; a pin aims it at one backend even when another session runs.
• Hyprland with ecosystem.enforce_permissions on: grant the host (Hyprland → Permission system).

Capture fails: "Session creation inhibited" (GNOME)Copy Anchor Link

A locked GNOME session blocks capture. Turn the lock off: GNOME → Do not lock the session.

Games from my library open on a physical monitor, not on the stream (Hyprland / sway / niri)Copy Anchor Link

A new window opens on the focused monitor, and something took focus from the stream: a click on a physical monitor, or a launcher (Steam Big Picture, Heroic) that opens the game window later.

• Leave the host's keyboard and mouse alone until the game is up.
• Set Displays → Customise → Your monitors while streaming → Turn off. Every window then lands on the stream.
• Or give each launch its own session: Displays → Dedicated game sessions → Dedicated (needs gamescope; see Dedicated game sessions).

Game Mode: black screen on connect, or the stream is stuck at the box's resolutionCopy Anchor Link

A screen is pinned under Displays → Stream this monitor, or host.env sets PUNKTFUNK_GAMESCOPE_ATTACH, so the host mirrors the box's own screen instead of taking the session over. The checks and the fix: gamescope → Troubleshooting.

WindowsCopy Anchor Link

Black screen with sound (Windows)Copy Anchor Link

The virtual display driver isn't answering, isn't installed, or doesn't match the host. The console's Troubleshooting page says which under Virtual display driver.

• Not answering: run punktfunk-host service restart from an elevated PowerShell. RivaTuner Statistics Server (MSI Afterburner) is a known cause; close it before you connect again.
• Missing or out of date: reinstall the host. Setup brings the matching driver.

Stutter while NVIDIA Instant Replay is on (Windows)Copy Anchor Link

Instant Replay is a second encoder on the same NVENC engine, and NVENC has no priority: the stream's frames wait behind its frames. The console's Troubleshooting page shows it under Video encoder sharing.

• By default the host pauses Instant Replay once a stream falls behind while another app encodes, and turns it back on when the last stream ends. Host → Pause Instant Replay: On pauses it for every stream, Off leaves it alone.
• Or press Alt+Shift+F10 before you connect, or turn it off in the NVIDIA App overlay.

The picture freezes for a moment, over and over (Windows)Copy Anchor Link

A freeze on a steady rhythm is a display or driver disturbance, not bandwidth. While it happens, the session's row on Home → Details → Capture health reads stalled.

Search the log on the console's Troubleshooting page for METRONOMIC. The line names the cause and its cures:

• …coincide with Windows monitor hot-plug/re-enumeration events: a display, cable, switch or AVR re-probes its link. Turn off the display's auto input scan (on a TV also instant-on and CEC), unplug it at the GPU, or fit a dummy plug. Disable monitor devices (PnP) stops Windows reacting.
• …with NO coinciding OS display event: the cause is below Windows, such as a sleeping screen the GPU driver services, display-poller software (SteelSeries GG, SignalRGB) or the refresh rate. Try another refresh rate. A laptop panel settles with Displays → Customise → Your monitors while streaming → Stay on, stream is main.

A freeze with no steady rhythm logs REPEATING without a stable period with the same fields.

Any hostCopy Anchor Link

Stutter, drops, or high latencyCopy Anchor Link

The link can't carry the stream's bitrate.

• Set Bitrate to Automatic so it adapts, or pick a lower fixed rate. The host menu's speed test suggests one. In Moonlight, lower it in Moonlight's settings.
• Use a wired connection or 5 GHz Wi-Fi.
• Several devices streaming at once share one encoder.

The stats overlay shows which stage is late.

The stream doesn't use the codec or HDR I pickedCopy Anchor Link

The host declined part of the request and told your client. When the client and the host disagree lists what it does with each setting.