Skip to content

armgit / Piik

Public Imported from GitHub
0

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.md
index 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 Rules
diff --git a/docs/research/browser-background-capture.md b/docs/research/browser-background-capture.md
index 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 is
unfocused, 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 is
unchanged.
@@ -42,6 +53,15 @@ configuration. Encoder implementation is a diagnostic variable only after a
stable baseline exists; neither codec nor encoder choice is a page-keepalive
mechanism.
+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 Boundary
The 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 remain
unknown. This is an Editor's Draft and does not require every browser to emit
every 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 encoder
priority.
+- [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 a
background 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 internal
display-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 peer
connections. 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 documents
lose the lock. It does not promise capture, encoder, timer, or renderer
priority.
+- [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 its
overhead constant across every run. Leave audio-debug recording, event-log
recording, packet capture, and media recording disabled. The current Screener
diagnostic 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-up
must have one stated hypothesis and one changed variable.
diff --git a/docs/status.md b/docs/status.md
index 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.md
index 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.md
index 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.