Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
docs(research): narrow Host background diagnosis
AAA39465c52499d
diff --git a/docs/project-memory.md b/docs/project-memory.mdindex c19b4fd4..f937debf 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -39,7 +39,7 @@ Last updated: 2026-08-24## Current Priority-1. Diagnose desktop Host background/minimized behavior under controlled capture, codec, send, receive, decode, CPU, and GPU measurement, then diagnose the screen-audio `1 kbps` readout and physically validate live audio ceilings.+1. Finish the desktop Host background/minimized diagnosis on exact production with a real game/replay and separate direct Viewer, then diagnose the screen-audio `1 kbps` readout and physically validate live audio ceilings. A bounded current-Chrome Browser `getDisplayMedia()` WPF-window same-machine loopback did not observe an immediate Host-page lifecycle drop and therefore authorizes no keepalive or other Browser workaround.2. Then physically validate exact direct, browser-relay, and SFU codec behavior on deployed Browser v11, refine the invitation UI, and finish real-network route acceptance. Browser VP8 hardware acceleration and mobile Viewer lifecycle remain Accepted Later; Native/executable, distribution, and repository-wide simplification remain later phases.## Working Rulesdiff --git a/docs/research/browser-background-capture.md b/docs/research/browser-background-capture.mdindex 0e4925b6..f62a01ce 100644--- a/docs/research/browser-background-capture.md+++ b/docs/research/browser-background-capture.md@@ -3,21 +3,32 @@- Research date: 2026-08-24- Scope: desktop Chrome/Edge Web Host capture while the Host page isunfocused, occluded, backgrounded, or minimized-- Status: diagnostic plan; the reported degradation has not been reproduced or- attributed under controlled measurement, and no fix is accepted, implemented,- or deployed+- Status: one bounded current-browser screening did not observe an immediate+ Host-page background drop; the reported real-game case remains unreproduced+ and unattributed, and no new fix is accepted, implemented, or deployed## Current Conclusion-There is no evidence that Screener is missing a page-liveness signal. A live-display-capture track and a live WebRTC connection already put the page in the-media cases that current Chrome excludes from intensive timer throttling and-Energy Saver freezing. Those exclusions do not guarantee a requested capture-rate, encoder throughput, or remote rendering rate, and no Web API lets an-application assert foreground scheduling priority.--The current report therefore remains diagnostic-only. It must distinguish five-different effects before any product change is considered:+There is no evidence that Screener is missing a page-liveness signal. Chromium+already marks live `MediaStreamTrack` use as a scheduler opt-out from aggressive+throttling and wake-up alignment, feeds active capture into both renderer+priority policy paths, and holds an internal application-suspension wake lock+for active peer connections. Those mechanisms are intended to protect active+media from ordinary invisible-page background treatment; they do not guarantee+a requested capture rate, encoder throughput, or remote rendering rate, and no+Web API lets an application assert additional foreground scheduling priority.++A bounded Chrome 151 screening on the current Windows test machine also kept+real window capture, VP8 encoding, loopback receipt, and decode at about 29.4 to+29.6 fps while the Host document was focused, in a hidden tab, and in a+minimized browser window. No immediate Host-document background drop was+observed in those 15-second windows. The sample does not reproduce the reported+game workload, separate physical Viewer, production route, CPU/GPU contention,+or browser policies whose documented hidden-state threshold exceeds five+minutes.++The current report therefore remains open but diagnostic-only. It must+distinguish five different effects before any product change is considered:1. Host preview or stats presentation is throttled while transmitted media isunchanged.@@ -42,6 +53,15 @@ configuration. Encoder implementation is a diagnostic variable only after astable baseline exists; neither codec nor encoder choice is a page-keepalivemechanism.+The 2026-08-19 report came from exact release `769de201f7cc`, which still set+video `contentHint = "motion"`. Current source and production leave the video+hint unset; a separate controlled VP8 probe changed from 14.93 fps at 428x208+with `motion` to 29.73 fps at 1904x928 without it. That known old-source defect+is fixed in the current contract, but it does not prove that the state-dependent+background report had the same cause. The physical baseline must therefore+start from current production rather than carrying the old report forward as a+current regression.+## Current Source BoundaryThe no-video-hint review baseline is@@ -103,9 +123,23 @@ All sources were checked on 2026-08-24.stats timestamps are the comparison basis. Optional absent fields remainunknown. This is an Editor's Draft and does not require every browser to emitevery optional member.-- [W3C Page Visibility](https://www.w3.org/TR/page-visibility-2/) defines- observable document visibility; it does not define capture or encoder+- [WHATWG HTML Page Visibility](https://html.spec.whatwg.org/multipage/interaction.html#page-visibility)+ defines observable document visibility; it does not define capture or encoderpriority.+- [Chromium capture accounting](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/content/browser/renderer_host/render_frame_host_impl.cc)+ forwards the first `kCapturingMediaStream` to the renderer process, and the+ [process-priority calculation](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/content/browser/child_process_launcher.cc)+ treats a media stream as non-background when no priority override exists.+ Chromium's+ [Performance Manager voter registration](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/components/performance_manager/performance_manager_lifetime.cc)+ separately installs `FrameCapturingMediaStreamVoter` to cast a+ `USER_BLOCKING` vote for a capturing frame when that priority path is active.+ These are implementation policies, not a priority measurement from the local+ screening.+- [Chromium `MediaStreamTrack` scheduling](https://chromium.googlesource.com/chromium/src/+/0b9090f669ed390bbc61eadcd59a05ca98c6a0bc/third_party/blink/renderer/modules/mediastream/media_stream_track_impl.cc)+ disables aggressive throttling and wake-up alignment while a live or muted+ track exists. Ordinary hidden-page JavaScript timer batching remains+ independent.- [Chrome chained-timer throttling](https://developer.chrome.com/blog/timer-throttling-in-chrome-88)says hidden-page timers may be batched and `requestAnimationFrame()` is not abackground clock. A live WebRTC media track avoids the intensive once-per-@@ -118,9 +152,15 @@ All sources were checked on 2026-08-24.- [Chromium `DesktopCaptureDevice`](https://chromium.googlesource.com/chromium/src/+/master/content/browser/media/capture/desktop_capture_device.cc)schedules capture in the browser capture subsystem, requests an internaldisplay-sleep wake lock, and by default limits desktop capture to 50% of one- CPU core by lengthening the next capture period when capture work is slow.- This is direct evidence for measuring capture cost rather than manufacturing- renderer activity.+ CPU core by lengthening the next capture period when capture work is slow. On+ supported current Windows builds it also permits damage-driven WGC 0 Hz+ behavior for unchanged content. This is direct evidence for measuring capture+ work and actual content changes rather than manufacturing renderer activity+ or treating intentionally absent duplicate frames as degradation.+- [WebRTC Windows WGC minimized-window tests](https://webrtc.googlesource.com/src/+/master/modules/desktop_capture/win/wgc_capturer_win_unittest.cc)+ require temporary capture errors when the captured window itself is minimized+ and recovery after it is restored. This is distinct from minimizing the+ separate Host browser window and does not specify JavaScript event timing.- [Chromium WebRTC internals owner](https://chromium.googlesource.com/chromium/src/+/master/content/browser/webrtc/webrtc_internals.cc)requests an internal application-suspension wake lock for active peerconnections. This internal browser behavior is not equivalent to the Web@@ -132,6 +172,49 @@ All sources were checked on 2026-08-24.to prevent a visible document's screen from turning off; hidden documentslose the lock. It does not promise capture, encoder, timer, or rendererpriority.+- [Chrome performance settings](https://support.google.com/chrome/answer/12929150)+ and [Edge performance features](https://support.microsoft.com/en-us/edge/learn-about-performance-features-in-microsoft-edge)+ provide user-side energy and sleeping controls. Edge explicitly excludes+ active window/screen and user-media capture from Sleeping Tabs, while Energy+ Saver can still affect video or gaming smoothness. Browser exclusions are+ useful A/B controls, not Web application keepalive APIs.++## Bounded Current-Browser Screening++On 2026-08-24, Chrome `151.0.7922.174` on Windows 25H2 build `26200.9168`+captured a continuously changing native WPF window through real+`getDisplayMedia()`. The source remained visible and changing; capture returned+1186x712 at a 30 fps setting. One VP8/libvpx sender used no video hint, a 5 Mbps+ceiling, 30 fps ceiling, `scaleResolutionDownBy = 1`, and `balanced`, with one+same-machine loopback receiver. Each state had one 15-second RTCStats window.+The automation flag selected the named window in the picker only; no+background-timer, occlusion, renderer-priority, Energy Saver, or capture policy+was disabled.++| Host state | Capture fps | Encoded fps | Sent bitrate | Encode ms/frame | Decoded fps | Limitation |+| --- | ---: | ---: | ---: | ---: | ---: | --- |+| Focused | 29.58 | 29.58 | 1276 kbps | 1.50 | 29.51 | `none` |+| Hidden tab | 29.53 | 29.53 | 1206 kbps | 1.35 | 29.53 | `none` |+| Focused after hidden | 29.58 | 29.51 | 1231 kbps | 1.52 | 29.51 | `none` |+| Browser window minimized | 29.39 | 29.39 | 1316 kbps | 1.45 | 29.39 | `none` |+| Focused after minimize | 29.39 | 29.39 | 1341 kbps | 1.46 | 29.39 | `none` |++At every boundary sample, the capture track was enabled, unmuted, and live at+1186x712; the local preview played at focused boundaries and was paused at+hidden and minimized boundaries. Outbound and inbound boundary samples were+also 1186x712, and every end sample reported `qualityLimitationReason=none`.+The probe kept one unchanged PC, sender, and track. Capture, encoded, and decoded+rates divided their monotonic counter deltas by the same outbound-RTP RTCStats+timestamp interval; bitrates used the corresponding byte deltas. Source and+inbound timestamps and raw stats identity were not independently retained, so+this is not an A/B/C interval-identity proof.++This is a screening result, not the product acceptance run. It has one short+same-machine loopback, no production Screener route, no separate physical+Viewer, no real game/render load, no audio, no CPU/GPU counter correlation, and+no repetition, randomized order, or hidden/minimized hold beyond five minutes.+It narrows the next test to the reported workload and environment; it does not+close the TODO or justify a Browser workaround.## Minimal Reproduction@@ -162,7 +245,10 @@ Open `chrome://webrtc-internals` on Host and Viewer before sharing and keep itsoverhead constant across every run. Leave audio-debug recording, event-logrecording, packet capture, and media recording disabled. The current Screenerdiagnostic download may be taken at state boundaries as a latest-sample-cross-check; it is not used as a time series.+cross-check; it is not used as a time series. If a stable reproduction suggests+freezing or discard, inspect the Host tab from a pre-opened separate control+window in `chrome://discards` or `edge://discards` outside the timed measurement+window. That page may expose URLs and therefore remains local evidence.### Host-State Matrix@@ -209,6 +295,11 @@ Change one variable per fresh run:3. When investigating the 2026-08-19 production report, compare exact release`769de201f7cc` with the then-current exact `main` commit on the same machine,browser, driver, game scene, and direct wired Viewer.+4. If the short state matrix does not reproduce a report that concerns sustained+ background operation, run one fresh hold longer than Chrome's documented+ five-minute hidden-policy window in only the reported hidden or minimized+ state. Keep the source changing and compare the first and last minute with+ focused baselines; do not multiply that hold across every state.Do not run a full factorial matrix before the baseline reproduces. A follow-upmust have one stated hypothesis and one changed variable.diff --git a/docs/status.md b/docs/status.mdindex e808afa9..bb9eae31 100644--- a/docs/status.md+++ b/docs/status.md@@ -27,7 +27,7 @@ This is the current execution index. Git history owns completed timelines; [veri## Current Milestone-1. Reproduce the Host background/minimized report under controlled conditions while recording actual capture, codec, send, receive, decode, CPU, and GPU evidence.+1. Finish the Host background/minimized diagnosis on exact production with a real game/replay and separate direct Viewer. A bounded current-Chrome Browser `getDisplayMedia()` WPF-window same-machine loopback did not observe an immediate page-lifecycle drop, so no workaround is established; the reported workload still needs synchronized capture, send, receive, decode, CPU, and GPU evidence.2. Diagnose the reported screen-audio `1 kbps` readout and physically validate live audio ceilings.3. Physically verify the deployed `screener-v11` fixed-VP8/no-video-hint direct, browser-relay, and SFU paths from actual codec, capture, outbound, and decoded stats.4. Refine the Host invitation controls without changing grant semantics implicitly.diff --git a/docs/todo.md b/docs/todo.mdindex 6e52fab3..61aee1d1 100644--- a/docs/todo.md+++ b/docs/todo.md@@ -6,7 +6,7 @@ Only items in **Now** are executable after their stated decision gate. A branch## Now-1. **Diagnose desktop Host background/minimized performance.** On the same machine, dynamic scene, direct Viewer, browser, and fresh share, compare foreground, occluded, minimized, and hidden states while recording the actual negotiated codec. Correlate capture settings/FPS, frames captured/encoded/sent/decoded, bitrate, `qualityLimitationReason`, encode time, browser/game CPU and GPU, and the existing local-preview pause boundary. Treat browser scheduling/throttling and codec effects as hypotheses until measured. Do not spoof page activity, add keepalive timers, or misuse Wake Lock; if current Chrome/Edge cannot preserve the accepted Host behavior through standard Web APIs, record that capability boundary before considering the packaged/native Host.+1. **Finish the real-game Host background/minimized diagnosis.** A bounded Chrome Browser `getDisplayMedia()` capture of a changing WPF window with one same-machine loopback receiver did not observe an immediate Host-page lifecycle drop; this does not close the reported case. On exact production with a continuously changing real game or replay and a separate direct wired Viewer, compare foreground, occluded/unfocused, hidden-tab, and minimized Host states while the captured source stays visible. Correlate RTCStats-timestamped capture, encode, send, receive, decode, browser/game CPU and GPU, and the existing local-preview pause boundary; record energy settings and inspect discard state only outside timed windows. Do not spoof page activity, add keepalive timers, misuse Wake Lock, or carry the old `contentHint = "motion"` release forward as current evidence. If current Chrome/Edge cannot preserve the accepted Host behavior through standard Web APIs, record that capability boundary before considering the packaged/native Host.2. **Diagnose and physically validate live screen audio.** First reproduce the Host diagnostic remaining at `1 kbps` after switching the shared source, and distinguish stale/reset statistics from an actual RTP bitrate problem. The app already requests audio and supplies system/window audio hints; record the selected surface, returned audio track, sender/receiver counters, and audible result because the browser owns the picker and may still return video only. Then switch the 64/128/256 kbps ceilings across direct, browser-relay, and SFU paths, create a new edge, and switch source while checking route continuity and A/V synchronization. Do not infer fidelity or room-wide atomic convergence from configuration alone.3. **Physically validate fixed Browser VP8 with no video hint.** Production exact deployed application/runtime revision `679fe3e7af634309322bea83b316641f51ad3d09`, release `679fe3e`, already runs the strict v11 wire, VP8-only direct/browser-relay offers, VP8 SFU publication with no backup codec, unset video `contentHint`, and no codec UI/state/wire. Confirm actual codec, capture, outbound, and decoded stats on direct, browser-relay, and SFU paths; deployment postflight alone does not close this gate.4. **Redesign the Host invitation controls.** Replace the current raw-link-heavy block with a compact copy-first layout while preserving the accepted copy-link, copy-room-code, code-entry policy, rotate, and revoke actions. Keep the credential out of logs and request URLs; changing the copied credential length is blocked on the explicit product decision below.diff --git a/docs/verification-status.md b/docs/verification-status.mdindex 7bd5dfe7..0eb58cd4 100644--- a/docs/verification-status.md+++ b/docs/verification-status.md@@ -24,12 +24,14 @@ Capacity and routing entries below describe the exact tested source or release o- Chrome 151 with local LiveKit 1.13.5/client 2.22.0 proved one SFU/UDP root after `q,f` -> `q,h`: decoded frames advanced 3 -> 23, rendered frames reached 26, Host used one edge, and leaves were clean. This is functional evidence only. See [low-server media routes](./research/low-server-media-routes.md).- Host A+B and authenticated P2P Viewer C evidence is sanitized, generation-bound, diagnostic-only, and closed for stale or ambiguous reports. Production can expose a Host-local current SFU `h` snapshot and clears it on publisher identity changes; raw media metadata is not retained. See [realtime quality adaptation](./research/realtime-quality-adaptation.md).- Fresh Chrome 151 tab-capture probes identified two separate Browser boundaries. Removing video `contentHint = "motion"` changed VP8 from 14.93 fps at 428x208 to 29.73 fps at 1904x928 under the same 5 Mbps balanced setup. No-hint AMD H.264 remained about 14--16 fps with hundreds of outer rate-limiter drops, while the same MFT reached 29.93 fps under diagnostic Desktop SW BRC; OpenH264 was slower. The page cannot enable that Chromium field trial or select an adapter/MFT. No-hint VP8 used libvpx software and held about 30 fps in one- and two-sender loopback on the test machine, but the process CPU totals include capture and local decode and are not real-game or weaker-device evidence. This evidence selects fixed VP8 for the Browser contract; current source and production implement that decision, while physical production codec behavior remains unverified. See [realtime quality adaptation](./research/realtime-quality-adaptation.md), [Native H.264](./research/native-h264-hardware-decision.md), and [Native shared encode](./research/native-shared-encode-sender.md).+- One bounded Chrome 151/Windows 25H2 current-browser screening used real `getDisplayMedia()` window capture, VP8/libvpx with no video hint, a continuously changing WPF source, and one same-machine loopback receiver. Focused, hidden-tab, and minimized 15-second windows measured about 29.4--29.6 capture/encoded/decoded fps and 1.35--1.50 ms encode time per frame; each boundary sample read an enabled, unmuted, live 1186x712 track and each end sample reported `qualityLimitationReason=none`. All rates used monotonic counter deltas over the outbound-RTP RTCStats timestamp interval; source/inbound timestamps and raw stats identities were not retained independently. The sample did not observe an immediate Host-document background drop; it does not cover exact production code, a real game, physical Viewer, CPU/GPU contention, audio, repetition, a hold beyond five minutes, or public routing. See [Browser background capture](./research/browser-background-capture.md).- Native Windows 11 process audio is source-only and default-off. A retained run isolated the target by about 4018x and delivered 495 Opus packets to one Viewer; package download, game sync, Windows 10, and other routes remain open. See [ADR-0008](./adr/0008-window-scoped-audio-capture.md).## Open Proof Boundaries- Routing: exact v10 local direct loopback remains historical evidence for admission-20 initial ingress and exact-candidate first-frame commit timing on that source. Current v11 production still needs physical direct, browser-relay, and SFU codec verification, together with route rollback, direct-stage exhaustion and SFU admission, relay-ingress reparent with subtree retention, disconnect/effective-capacity drain, pause/resume, and bounded failure on real browser/media paths. Silent control partitions may wait 30 to 60 seconds for heartbeat detection before the default five-second grace; a non-paused decoded-frame stall may invalidate only that exact child edge.- Quality: production startup blur remains unclassified. One same-`balanced` local A/B retained route/PC/SSRC/track while 720p rose to 1080p, but natural ramp prevents causal, production, or SFU conclusions. Correlate Host capture/encode/send with Viewer receive/decode before changing policy.+- Host background: the current-Chrome Browser `getDisplayMedia()` WPF-window screening did not observe an immediate hidden/minimized Host-page media drop. The reported game case still requires exact production, a continuously changing real game or replay, a separate direct wired Viewer, synchronized capture/outbound/inbound plus CPU/GPU evidence, and repeated focused/unfocused/hidden/minimized windows. Current evidence authorizes no keepalive, Wake Lock, timer, codec switch, route change, or Native fallback.- Relay resources: current v11 source and production expose the authenticated `1/2/3` endpoint-cap boundary, and retained v10 local loopback evidence covers 20 Viewers at cap `2` only for that source. CPU/GPU/upload and heterogeneous-network measurements remain diagnostics, not authority to change the contract.- Room scale: current source and production admit 20 Viewers plus one Host, and the retained v10 local Browser convergence gate covers that bound on direct loopback. A real public-network 1:20 session, quality, and sustained resource matrix remain open.- SFU: production uses one Host publication with exact Viewer subscriptions and no fixed root-count or room-wide lease rule. Real LiveKit lifecycle/JWT replay, shaped packet-flow, BWE downshift/recovery, resource use, and SFU-fed first-child evidence remain open. Use Linux `tc` or an authorized public canary for per-leaf shaping, never CDP throttling.