From e9a209ef61d88379aba103cd9e6fbb3cb4f714bb Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Tue, 4 Aug 2026 09:42:06 +0200 Subject: [PATCH] docs(troubleshooting): why streamed audio can sound worse than the host, and the knobs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit WP0.4. The 2026-08-03 reporter had no way to know their desktop mix was being routed through Steam's voice-carrier endpoint, and no documented way to change it — `PUNKTFUNK_HOST_AUDIO` existed only in a module doc comment. Two new sections: what the host actually captures (a render endpoint, not "the sound card"), what the new `engine_hz/engine_ch/engine_bits` log line tells you, and the `PUNKTFUNK_AUDIO_OUTPUT_MODE` / `_QUALITY` / `_REDUNDANCY` knobs — with host_and_client called out as the quickest A/B for the endpoint question; and why audio that lags the picture should now correct itself, plus what to check when it does not. Co-Authored-By: Claude Opus 5 (1M context) --- docs-site/content/docs/troubleshooting.md | 58 +++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs-site/content/docs/troubleshooting.md b/docs-site/content/docs/troubleshooting.md index 18d03cdc..9d925b6c 100644 --- a/docs-site/content/docs/troubleshooting.md +++ b/docs-site/content/docs/troubleshooting.md @@ -302,6 +302,64 @@ told your client so. [When the client and the host disagree](/docs/client-settings#when-the-client-and-the-host-disagree) lists what it does with each one. +## Streamed audio sounds worse than the host does + +The host does not capture "the sound card" — it captures a **render endpoint**, and by default it +picks one that is *silent on the host* so the audio plays on your client only. On a PC with Steam +installed that silent endpoint is Steam's **Streaming Microphone**, which exists to carry remote +*voice*. If Windows has it configured as a narrow device — mono, or below 48 kHz — then the whole +desktop mix is squeezed through that before it is ever encoded, and no amount of bitrate will bring +it back. + +Since 0.25 the host checks for this: it reads each candidate endpoint's real format, prefers a real +output device over a narrow virtual one, and says so in the log — + +``` +WARN the desktop-audio loopback endpoint mixes at 24000 Hz, so the stream is band-limited … +INFO audio loopback capturing device="…" engine_hz=48000 engine_ch=2 engine_bits=32 +``` + +That `engine_*` line is the endpoint's **own** format, so it tells you directly whether the source +was ever full quality. To choose the routing yourself, set in `host.env`: + +```ini +# client_only — default; audio plays on the client only (a silent endpoint) +# host_and_client — capture a real output device; audio plays on BOTH ends +# follow_default — capture whatever YOUR default playback device is, and never change it +PUNKTFUNK_AUDIO_OUTPUT_MODE=host_and_client +``` + +`host_and_client` is also the quickest way to A/B the problem: if the stream sounds right that way +and wrong on the default, the endpoint was the cause. + +Two related knobs: + +```ini +PUNKTFUNK_AUDIO_QUALITY=high # low | standard | high (default high — stereo 256 kbps) +PUNKTFUNK_AUDIO_REDUNDANCY=1 # force the loss-resilient audio plane on (default: automatic) +``` + +Audio is a fraction of a percent of a stream's bandwidth, so `high` costs nothing worth counting. +`standard` reproduces the pre-0.25 encoder exactly if you want to compare. + +## Audio lags behind the picture + +The client buffers a little audio to absorb network jitter. Since 0.25 that buffer **corrects +itself**: if it drifts deeper — a Wi-Fi burst, a stall, or just the two devices' clocks running at +fractionally different speeds — it trims itself back a few milliseconds at a time, inaudibly. +Before, it could only grow, so a single hiccup left audio permanently behind the video and the only +cure was reconnecting. + +If audio is still noticeably late: + +- **Reconnect once.** It confirms whether the delay was accumulated (gone after a reconnect) or + constant (something else). +- **Check for underruns** rather than guessing. The client logs its buffer depth periodically; a + rising `underruns` count means the buffer is being starved, which is a network or CPU problem, not + a buffering one. +- **Wired or 5 GHz Wi-Fi.** Arrival jitter is what the buffer exists to absorb; less jitter lets it + run shallower. + ## Windows: the host or the web console won't start The **`PunktfunkHost` service** runs both halves of the Windows host: the streaming host itself and