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(media): correct content hint and codec truth (#228)

AAA4d1030da5191
diff --git a/docs/adr/0007-demand-driven-dual-representation-quality.md b/docs/adr/0007-demand-driven-dual-representation-quality.md
index 71e69203..bb2eac29 100644
--- a/docs/adr/0007-demand-driven-dual-representation-quality.md
+++ b/docs/adr/0007-demand-driven-dual-representation-quality.md
@@ -139,7 +139,7 @@ results do not create an application media-layer selector or route authority:
spatial-quality ceiling. Server 1.13.5 derives requested spatial/temporal
maxima from quality, dimensions and FPS, but actual selection is
codec-specific: VP8 has temporal selection, while H.264/H.265 simulcast is
- spatial-only. The fixed VP8 publication can adapt each SFU downtrack between
+ spatial-only. A VP8 publication can adapt each SFU downtrack between
`q,h` spatial representations and recover it independently. Server
Dynacast takes the maximum requested quality and enables every quality at or
below it, so any `HIGH` root keeps `LOW` active. That cumulative behavior
diff --git a/docs/adr/0008-window-scoped-audio-capture.md b/docs/adr/0008-window-scoped-audio-capture.md
index 4b57fd91..b1d3190a 100644
--- a/docs/adr/0008-window-scoped-audio-capture.md
+++ b/docs/adr/0008-window-scoped-audio-capture.md
@@ -130,9 +130,9 @@ The helper multiplexes process-tree PCM, H.264 access units, and bounded local
status. Go writes H.264 directly to the existing shared fanout; the browser UI
receives only a one-way local copy for `VideoDecoder` preview. PCM retains the
existing WebCodecs Opus bridge. PLI/FIR recovery is generation-bound and
-coalesced into a helper key-frame command. The normal browser source uses the
-fixed VP8 contract; the native H.264 source remains an explicit mode and is not
-an implicit runtime downgrade.
+coalesced into a helper key-frame command. The normal browser source uses its
+independent Browser codec path; the native H.264 source remains an explicit mode
+and is not an implicit runtime downgrade.
## Consequences
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 782f1a17..95421d43 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -18,7 +18,7 @@ Last updated: 2026-08-24
- Ordinary peer ICE is STUN-only, and current LiveKit media is UDP-only. Credentials, room secrets, candidate details, and diagnostic data remain private and narrowly scoped. A future strict-firewall transport requires separate evidence and must remain inside LiveKit rather than becoming another Screener route candidate.
- Browser peers use existing periodic WebRTC/LiveKit stats to maintain one exact-route decoded-progress timestamp. New frames or route/connection changes reset it; a non-paused deadline reports the edge once. Track availability, bitrate, FPS, resolution, freeze, RTT, jitter, loss, sender stats, and SFU layer describe only the current path: they remain framework or diagnostic inputs and cannot prove another parent would be better.
- Browser capture requests available share audio by default on initial capture and source switch, with an explicit video-only warning when no audio track is returned. Its screen-audio control offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The last-wins quality wire owns desired state; each endpoint serially applies and reads back current Host/relay/SFU audio senders, exposes local failures, and gives future senders the latest desired value. Opus remains fixed, and without an applied-ack wire the Host does not claim room-wide atomic convergence. These are configuration ceilings, not fidelity claims.
-- The accepted Browser codec is fixed VP8 with no codec/profile control or quality-state field. Current Windows evidence found Chrome's H.264 performance depended on an OS-selected AMD versus NVIDIA Media Foundation encoder that a website cannot choose; profile ordering did not repair it, and the dated production A/B recovered after forced H.264 was removed. Actual codec/profile/encoder stats remain diagnostic only. Current v10 source and production retain the temporary selector until the atomic v11 implementation and deployment replace it.
+- The accepted Browser display-video behavior leaves `contentHint` unset so Chromium retains its screen-capture classification; returned audio tracks keep `contentHint = "music"`. Current v10 source and production still set video `motion` until the source change is integrated and deployed. The final Browser video codec remains undecided; v10 defaults to VP8 and retains the pre-share diagnostic selector, fixed for each share, until controlled game-load evidence supports one codec and the selector/wire can then be removed atomically. Actual codec/profile/encoder stats remain diagnostic only.
- Recommended quality remains exactly `1080p60`, `1080p30`, and `720p30`, with the middle `1080p30` as the accepted default. `480p` means only an advanced `854x480` resolution choice whose FPS and bitrate remain independently selected; it is not a fourth recommended profile.
- Two distribution artifacts are accepted only after the current feature, NAT, and real-network ledger is complete. A public-server one-click deployment package installs the current application plus STUN/SFU and proxy components on a user-owned server. A Windows/macOS/Linux local package runs the Host, application server, and local state on the broadcaster's machine without source, Node, or any external Screener/network service; it keeps workable direct P2P but reports the reachability loss imposed by public ingress, TLS, gateway, NAT, or firewall limits rather than promising universal connectivity.
- Current UI, presence, route labels, and diagnostics describe observed state only; they do not create route authority.
@@ -33,14 +33,14 @@ Last updated: 2026-08-24
- Exact production artifacts, rollback boundary, services, and ports are owned by [deployment](./deployment.md) and indexed by [status](./status.md).
- Source and production default new shares to VP8, keep the diagnostic selector pre-share only and fixed for the share lifetime, use `shareGeneration`-fenced Pause/Resume, and require the v10 wire. They implement live 64/128/256 kbps audio-ceiling mutation, typed first-frame Viewer presentation, privacy-safe on-demand route diagnostics, neutral room-code denial, responsive entry controls, exactly three recommended profiles with `1080p30` as default and advanced-only `854x480`.
- Browser SFU subscribers reconcile eligible Host screen publications across connect/activate event ordering, participant/track arrival, and reconnect. Production LiveKit logs only warn/error, and the application service has a bounded same-host LiveKit readiness preflight.
-- Exact v10 runtime source `fdd5a4a529ff297f41c05ea3388bf484d76afe8f` passed 610 Web tests in 45 files, TypeScript typecheck, client/server production builds, access/privacy, the 257-test SFU admission gate, dependency audit, and repository hygiene. Its one-Host/20-Viewer Chrome 151 loopback decoded every Viewer, propagated fixed VP8 settings, bounded Host/relay fanout at `2`, captured all current-child timing distributions, and observed no SFU publication. It is not public-network, SFU, mobile, physical audio/codec, H.264 performance, or background-lifecycle evidence.
+- Exact v10 runtime source `fdd5a4a529ff297f41c05ea3388bf484d76afe8f` passed 610 Web tests in 45 files, TypeScript typecheck, client/server production builds, access/privacy, the 257-test SFU admission gate, dependency audit, and repository hygiene. Its one-Host/20-Viewer Chrome 151 loopback decoded every Viewer, propagated the selected VP8 settings, bounded Host/relay fanout at `2`, captured all current-child timing distributions, and observed no SFU publication. It is not public-network, SFU, mobile, physical audio/codec, H.264 performance, or background-lifecycle evidence.
- Postflight found `screener`, LiveKit, coturn, and nginx active with `NRestarts=0`; local and public `/` and `/healthz` return 200, every served client file matches the immutable release, the public Browser bundle contains `screener-v10` and no `screener-v9`, the release shares no regular-file inode with its predecessor, and the accepted socket/firewall boundary is intact. The LiveKit namespace remained empty, so deployment evidence is not route or physical-media acceptance. Detail is owned by [deployment](./deployment.md) and [verification status](./verification-status.md).
- Chrome loopback, cap2/cap3, short resource, recovery, MBB, and A/V fixtures are bounded evidence only. They do not establish quality, resource limits, or product policy.
## Current Priority
-1. Implement the accepted fixed-VP8 Browser v11 contract, delete the temporary codec selector and wire field, and deploy it atomically; no H.264 relay or SFU validation is required.
-2. Run the mobile lifecycle matrix and later mechanism-simplification audit only at their stated boundaries; Native/executable and distribution work remain later product phases.
+1. Remove the Browser video `contentHint`, run focused capture/encode verification, and keep the final codec decision open until controlled game-load evidence is sufficient.
+2. Diagnose screen audio and invitation UI, then finish background/mobile/network evidence at their stated boundaries; 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 aad67972..82f2576e 100644
--- a/docs/research/browser-background-capture.md
+++ b/docs/research/browser-background-capture.md
@@ -36,7 +36,7 @@ does not say that minimizing the separate capturing page must reduce capture.
Capture constraints are post-selection preferences and allow frame decimation,
so requested `maxFramerate` is not proof of actual source or encoded frame rate.
-The accepted and deployed default video preference is VP8. Every run records
+The current deployed default video preference is VP8. Every run records
the actual negotiated codec and encoder rather than inferring either from
the preference. H.264, VP8, and encoder implementation are diagnostic variables
only after a stable baseline exists; none is a page-keepalive mechanism.
@@ -50,10 +50,12 @@ implement a page-keepalive mechanism, and deployment health supplies no
physical background-capture evidence.
- `src/client/media/quality.ts` obtains one `getDisplayMedia()` stream, applies
- ideal/max capture constraints, marks video as `motion`, and applies sender
+ ideal/max capture constraints, currently marks video as `motion`, and applies sender
bitrate, frame-rate, and degradation ceilings. Explicit sharing pause and
authoritative reconnect re-pause change capture tracks' `enabled` state;
neither manufactures foreground activity.
+- The accepted source change removes that video hint; production retains it
+ until a later deployment. Audio `contentHint = "music"` remains unchanged.
- `src/client/pages/HostPage.tsx` pauses the existing local preview video when
the Host document is hidden or unfocused and resumes that preview when it is
visible and focused. This does not stop, mute, disable, or replace the capture
@@ -167,7 +169,7 @@ Use equal 60-second measurement windows, restore the focused baseline between
states, randomize state order, and repeat three fresh controlled runs. These
window and repeat counts define a small comparable sample; they are not product
timeouts, quality thresholds, or proof of statistical significance. Record the
-actual initial negotiated VP8 codec and encoder; do not switch codec inside a
+actual initial negotiated codec and encoder; do not switch codec inside a
run.
For each exact overlapping window, correlate:
diff --git a/docs/research/native-h264-opt-in-path.md b/docs/research/native-h264-opt-in-path.md
index 1d809adc..75ea7d81 100644
--- a/docs/research/native-h264-opt-in-path.md
+++ b/docs/research/native-h264-opt-in-path.md
@@ -3,7 +3,7 @@
## 2026-08-21 Native Window Source
The Native sender has two explicit local video sources. The Web source uses the
-fixed Browser VP8 contract; the separate `native-window-h264` source is Windows
+independent Browser codec path; the separate `native-window-h264` source is Windows
11-only and requires
the user to select one local opaque window target. It never silently replaces a
browser source or falls back to software encode, another codec, monitor capture,
@@ -34,7 +34,7 @@ local WebCodecs Opus bridge.
PLI/FIR and fanout recovery requests enter the generation-bound helper stdin as
one coalesced `K` command. The helper forces an in-band SPS/PPS/IDR recovery
unit, while the existing Pion `H264Payloader`, exact `42c01f` MediaEngine, one
-shared track, and two-edge cap remain unchanged. Browser VP8 uses the existing
+shared track, and two-edge cap remain unchanged. The Browser source uses the existing
`getDisplayMedia` and `VideoEncoder` path.
Both the product helper and offline fixture compile the same MF encoder source.
@@ -110,7 +110,7 @@ separate encoder-contract measurement.
## Scope
-- The Web source uses fixed VP8; production rollout remains tracked separately
+- The Web source keeps the Browser codec decision independent; production rollout remains tracked separately
from this Native research path.
- No codec matrix, benchmark, second viewer, or endurance run is required for
this landing slice.
diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.md
index f925ec37..57a591e5 100644
--- a/docs/research/realtime-quality-adaptation.md
+++ b/docs/research/realtime-quality-adaptation.md
@@ -224,81 +224,86 @@ wire, server telemetry, global score, selector or new UI framework. Production
deploys this v10 publisher view; its target-browser fields and values still need
physical evidence.
-## Fixed Browser Codec Decision
-
-The Browser product uses one fixed VP8 path and exposes no codec or profile
-control. Direct and browser-relay offers put VP8 first while retaining its
-browser-advertised repair codecs; the SFU publication explicitly requests VP8
-with `backupCodec=false`. Actual codec/profile and encoder fields remain
-diagnostic results. They do not authorize codec switching, route changes, or a
-second encoder policy.
-
-The decision combines dated production behavior with an exact target-machine
-probe. Production first forced H.264 through standard codec ordering and a
-single LiveKit H.264 publication; removing that preference restored the reported
-frame rate. On 2026-08-24, fresh Chrome/Edge 151 sessions then used real
-`getDisplayMedia()` tab capture, `1920x1080@30`, a 5 Mbps ceiling, `balanced`,
-`motion`, ten seconds of warm-up, and a fifteen-second wall-clock sample:
-
-| Browser / requested format | Actual encoder | Encoded FPS | Encode time/frame | End resolution | Limitation |
-| --- | --- | ---: | ---: | --- | --- |
-| Chrome VP8 | libvpx, software | 15.00 | 2.69 ms | 402x214 | `bandwidth` |
-| Chrome H.264 Baseline `42001f` | AMD Media Foundation, hardware | 11.87 | 12.10 ms | 1920x1024 | `none` |
-| Chrome H.264 CBP `42e01f` | OpenH264, software | 15.00 | 1.33 ms | 402x214 | `bandwidth` |
-| Chrome H.264 Main `4d001f` | AMD Media Foundation, hardware | 11.86 | 12.61 ms | 1920x1024 | `none` |
-| Chrome H.264 High, negotiated `64001f` | AMD Media Foundation, hardware | 12.60 | 12.53 ms | 1920x1024 | `none` |
-| Edge H.264 Baseline `42001f` | NVIDIA Media Foundation, hardware | 28.98 | 5.67 ms | 1396x732 | `bandwidth` |
-
-The synthetic content, headless capture, loopback path, and BWE-driven resolution
-changes prevent a physical-game image-quality or intrinsic codec-efficiency
-ranking. They do establish the first bottleneck: Windows had an explicit
-minimum-power preference for Chrome (`GpuPreference=1`), Chrome selected the AMD
-H.264 MFT, and Baseline/Main/High all stayed near 12 fps. Edge had no explicit
-preference, selected the NVIDIA MFT, and approached 29 fps. Chrome's
-`--force-high-performance-gpu` flag still selected the AMD MFT and produced
-12.66 fps, so that ANGLE/EGL switch does not override Media Foundation selection.
-
-Chromium 151 enumerates Windows Media Foundation encoders in adapter/MFT order
-and activates the first compatible result. Its preferred adapter LUID is used to
-handle cross-GPU resources, not to let a website select a vendor. The WebRTC API
-can reorder codec/profile formats but has no API to select NVIDIA, AMD, or a GPU
-adapter. Windows Graphics preference, disabling an iGPU, or launching a whole
-browser differently are host diagnostics, not a Screener product mechanism.
-See Chromium's [MFT enumeration](https://chromium.googlesource.com/chromium/src/+/refs/tags/151.0.7922.174/media/gpu/windows/mf_video_encoder_util.cc#347),
-[encoder activation](https://chromium.googlesource.com/chromium/src/+/refs/tags/151.0.7922.174/media/gpu/windows/media_foundation_video_encode_accelerator_win.cc#1422),
-and [GPU switch scope](https://chromium.googlesource.com/chromium/src/+/refs/tags/151.0.7922.174/gpu/ipc/service/gpu_init.cc#291), plus the
-[WebRTC Stats](https://www.w3.org/TR/webrtc-stats/) and
-[Media Capabilities](https://www.w3.org/TR/media-capabilities/) specifications.
-
-SDP level rewriting is not a repair: Chromium matches H.264 hardware formats by
-profile and packetization mode and lets the encoder choose the output level from
-the real dimensions and rate. Reordering High only changes the requested profile
-and still selected the same AMD MFT. CBP deliberately fell back to OpenH264 and
-lost resolution under the same budget. Pinned LiveKit 1.13.5/Pion 4.2.17 also
-preserves Chrome's H.264 offer order, whose first compatible entry is Baseline
-`42001f/mode1`, not CBP. No profile special case, SDP munging, GPU selector,
-codec controller, or H.264 relay/SFU follow-up enters the Browser product.
-
-Discord's published Go Live material is a useful architecture comparison, not
-a preset to copy. It describes native OS/driver-integrated capture and encoding,
-GPU hardware encoding, WebRTC transport, and one codec that the sender and all
-current viewers can decode. Discord lists VP8 and H.264 as its broad baseline,
-with HEVC and AV1 on selected platforms; its RTC worker routes the sender's
-stream rather than requiring one browser PeerConnection per viewer. This is
-evidence for a common publication, not proof of one physical encoder object.
-Discord also documents a feedback loop that could lock 60 fps output down to
-30 fps, accidental keyframes as often as once per second, and the resulting
-quality gains from a stable encoder lifetime, explicit keyframe cadence, and
-rate-control headroom. These findings support measuring the complete
-capture/encoder/congestion loop; they do not make AV1 universally cheaper.
-
-A read-only inspection of the locally installed Oopz 0.87.425 package is
-consistent with a native, hardware-first common publication: its Viewer bundle
-selects H.264, the package exposes a hardware-acceleration status, and the
-inspection found one screen-track publication. It does not prove the runtime
-codec/GPU choice or one physical encoder. Components, retained hashes, and the
-privacy boundary are owned by
-[Native shared-encode sender](./native-shared-encode-sender.md).
+## Browser Codec And Content-Hint Evidence
+
+The accepted change is narrow: Browser display video does not set
+`contentHint`; returned audio keeps `contentHint = "music"`. The final Browser
+video codec is not decided. V10 continues to default to VP8 and retains the
+pre-share diagnostic selector, fixed for one share, until a controlled real-game
+comparison supports one codec. Codec/profile/encoder stats remain diagnostic
+and do not authorize automatic switching, route changes, or another controller.
+
+Chromium maps video `contentHint = "motion"` to libwebrtc `kFluid`, and
+libwebrtc clears `is_screencast` for that mode. Screener was therefore replacing
+the display-capture screen classification with realtime-camera semantics. Fresh
+Chrome 151 loopback probes on 2026-08-24 used real dynamic tab
+`getDisplayMedia()`, `balanced`, ten seconds of warm-up, and a fifteen-second
+sample:
+
+| Requested path | Ceiling | Actual encoder | Encoded FPS | Encode time/frame | Bitrate | End resolution | Limitation |
+| --- | ---: | --- | ---: | ---: | ---: | --- | --- |
+| VP8 + `motion` | 5 Mbps | libvpx software | 14.93 | 2.85 ms | 3.663 Mbps | 428x208 | `bandwidth` |
+| VP8 + no hint | 5 Mbps | libvpx software | 29.73 | 6.62 ms | 4.944 Mbps | 1904x928 | `none` |
+| H.264 + no hint | 8 Mbps | AMD Media Foundation | 14.18 | 14.24 ms | 8.214 Mbps | 1904x928 | `none` |
+| H.264 + no hint + diagnostic Desktop SW BRC | 5 Mbps | AMD Media Foundation | 29.93 | 8.17 ms | 3.650 Mbps | 1904x928 | `none` |
+| H.264 + no hint + hardware encode disabled | 5 Mbps | OpenH264 software | 10.47 | 13.08 ms | 4.832 Mbps | 1904x928 | `none` |
+
+The VP8 result establishes that `motion` was harmful independently of the H.264
+issue. VP8 reported trusted rate control, so libwebrtc's outer frame dropper was
+off and libvpx owned its CBR behavior. In the ordinary AMD H.264 path,
+libwebrtc's outer rate limiter dropped hundreds of frames; raising the ceiling
+through 8/10/12 Mbps or selecting `maintain-framerate` did not restore 30 fps.
+The diagnostic SW-BRC run made the same AMD MFT report trusted rate control and
+reach 29.93 fps, so the MFT itself is not a fixed 12--15 fps throughput limit.
+That browser-process experiment bypasses a Chromium AMD workaround and is not a
+Web product API; a page cannot enable the field trial or select a GPU/MFT.
+
+A separate no-hint VP8 CPU sample used a Ryzen 7 9700X, Chrome 151, one dynamic
+1904x928@30 capture, 5 Mbps per sender, and loopback receivers. One sender held
+29.86 fps and the isolated Chrome process tree consumed 21.14 CPU-seconds over
+26.65 seconds, or 0.793 logical core / 4.96% of the 16-thread machine. Two
+independent senders both held 29.93 fps and used 35.88 CPU-seconds over 26.70
+seconds, or 1.344 logical cores / 8.40%. These totals include source rendering,
+capture, WebRTC, and local decode, so they are not pure encoder cost. They show
+that software VP8 is workable on this machine, not that it is cheap on a weaker
+CPU, mobile device, or beside a real game.
+
+Chromium's generic WebRTC factory can wrap hardware VP8 when a platform backend
+advertises it, but this Windows Chrome run selected libvpx and Chromium 151's
+Windows Media Foundation backend advertises VP9, H.264, AV1, and conditional
+HEVC rather than VP8. A website can prefer a codec/profile but cannot require a
+particular hardware implementation. Hardware VP9 or AV1 may provide usable rate
+control on supported machines, while H.264/HEVC remain important hardware paths,
+but none currently combines VP8's WebRTC baseline coverage with deterministic
+hardware selection across Screener's browser targets. Capability advertisement
+alone is not acceptance; an actual sender must prove codec, implementation,
+power efficiency, rate control, and game-load behavior.
+
+Comparable native products do not resolve this browser boundary. Discord
+negotiates VP8/H.264 and selected-platform HEVC/AV1 through its own capture and
+hardware pipeline, and documents an AMD rate-control/frame-dropper repair.
+Parsec, Steam Remote Play, and Moonlight/Sunshine primarily use controlled
+hardware H.264/HEVC/AV1 paths. Oopz only publicly identifies Agora as its screen
+sharing SDK; Agora may use VP8/H.264/H.265 or automatic selection, so Oopz's
+actual session codec is unknown without runtime stats. These native designs do
+not prove that an ordinary web page can force the same encoder path.
+
+Primary implementation evidence: Chromium's
+[content-hint bridge](https://chromium.googlesource.com/chromium/src/+/refs/tags/151.0.7922.174/third_party/blink/renderer/modules/peerconnection/media_stream_video_webrtc_sink.cc#36),
+libwebrtc's [sender classification](https://webrtc.googlesource.com/src/+/f20ebb8adbf4fa781830e4384c61f732bd28a217/pc/rtp_sender.cc#1419),
+[VP8 rate control](https://webrtc.googlesource.com/src/+/f20ebb8adbf4fa781830e4384c61f732bd28a217/modules/video_coding/codecs/vp8/libvpx_vp8_encoder.cc#1360),
+Chromium's [hardware codec mapping](https://chromium.googlesource.com/chromium/src/+/refs/tags/151.0.7922.174/third_party/blink/renderer/platform/peerconnection/rtc_video_encoder_factory.cc#75),
+its [Windows encoder backend](https://chromium.googlesource.com/chromium/src/+/refs/tags/151.0.7922.174/media/gpu/windows/media_foundation_video_encode_accelerator_win.cc#606),
+the [Desktop SW BRC switches](https://chromium.googlesource.com/chromium/src/+/refs/tags/151.0.7922.174/media/gpu/windows/mf_video_encoder_switches.cc#26),
+and Chromium's [AMD workaround](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/gpu/config/gpu_driver_bug_list.json#3303).
+Product comparisons: [Discord Go Live](https://discord.com/blog/how-it-all-goes-live-an-overview-of-discords-streaming-technology),
+[Discord AMD rate control](https://discord.com/blog/from-blocky-to-brilliant-improving-video-quality-on-discord-go-live-on-amd-gpus),
+[Oopz privacy policy](https://help.oopz.cn/agreement/privacy), and
+[Agora codec selection](https://doc.shengwang.cn/api-ref/rtc/windows/API/enum_videocodectype),
+[Parsec compatibility](https://support.parsec.app/hc/en-us/articles/32381568346644-Hardware-and-Software-Compatibility),
+[Steam Remote Play update](https://store.steampowered.com/news/posts/?enddate=1734653759&feed=steam_clientAny),
+[Moonlight](https://github.com/moonlight-stream/moonlight-qt), and
+[Sunshine](https://github.com/LizardByte/Sunshine/blob/master/docs/configuration.md).
## Evidence Before Adaptation
@@ -701,9 +706,11 @@ guarantees the emitted resolution, frame rate, or bitrate.
- A live profile change uses `track.applyConstraints()` and updates every
current sender with `RTCRtpSender.setParameters()`. It does not reopen the
source picker or renegotiate healthy peer connections.
-- The video track keeps `contentHint = "motion"`; recommended profiles and the
- advanced initial value use `balanced`, with explicit `maintain-resolution`
- and `maintain-framerate` choices. None promises an emitted resolution or rate.
+- Current v10 source and production set video `contentHint = "motion"`; the
+ accepted source change removes that assignment so display capture retains
+ browser screen semantics. Recommended profiles and the advanced initial value
+ use `balanced`, with explicit `maintain-resolution` and
+ `maintain-framerate` choices. None promises an emitted resolution or rate.
- `maxBitrate` and `maxFramerate` are ceilings. They are neither minimums nor
target guarantees, and the project does not use SDP bitrate hacks.
- The current deployed `screener-v10` Share advanced settings panel accepts
@@ -754,8 +761,8 @@ CPU/GPU cost, public networks, or sustained behavior.
- No canvas pixel-difference detector, machine-learned rate controller, or
periodic profile switching.
- No copied x264 CRF/preset recipe in the browser path.
-- No runtime or automatic codec switching. VP8 is the one Browser product codec;
- there is no codec selector or H.264 product fallback.
+- No runtime or automatic codec switching. The current v10 pre-share selector
+ remains diagnostic and fixed for one share until the final codec decision.
- No channel-count, sample-rate, codec, arbitrary bitrate, stereo, DTX, RED or
FEC control, and no inference of actual stereo or sample rate from
`opus/48000/2`. Screen media uses one route-consistent stereo contract;
diff --git a/docs/research/webrtc-p2p-screen-sharing.md b/docs/research/webrtc-p2p-screen-sharing.md
index d40bf291..11f28bc9 100644
--- a/docs/research/webrtc-p2p-screen-sharing.md
+++ b/docs/research/webrtc-p2p-screen-sharing.md
@@ -149,11 +149,9 @@ Web 版本能直接使用 `getDisplayMedia()` + WebRTC,最适合验证产品
直播中换源不需要先关房间。`RTCRtpSender.replaceTrack()` 可在同类媒体且协商 envelope 允许时替换 sender 的来源而不重新协商;分辨率、帧率块率、音频声道或编码约束不兼容时会拒绝,因此应用必须把失败限制在该 viewer 并重建其连接。为支持浏览器有时返回音频、有时不返回,初始 offer 可以预留 send-only audio transceiver,再将 audio sender 在 `null` 与真实 track 间替换。新的 `getDisplayMedia()` 仍必须由用户手势触发并重新选源,取消选择时旧流应继续工作。
-游戏轨建议设置:
+游戏轨不覆盖 display-capture 的内容分类:
```js
-track.contentHint = "motion";
-
const parameters = sender.getParameters();
parameters.encodings ??= [{}];
parameters.encodings[0].maxFramerate = 60;
@@ -162,7 +160,7 @@ parameters.degradationPreference = "balanced";
await sender.setParameters(parameters);
```
-这些参数是偏好或上限,不能绕过浏览器拥塞控制,也不能保证目标码率。`balanced` 允许浏览器在分辨率和帧率之间权衡,但不规定具体算法;本项目的 `contentHint = "motion"` 还会影响 Chromium/libwebrtc 对来源的内部分类,因此不能套用其仅限 screen encoder 的 `maintain-resolution` 重解释。当前源码链与测量要求见 [Realtime quality adaptation](./realtime-quality-adaptation.md)。静态画面通常能降低编码数据量,但规范不保证所有浏览器主动降低捕获频率或 GPU 开销。
+这些参数是偏好或上限,不能绕过浏览器拥塞控制,也不能保证目标码率。`balanced` 允许浏览器在分辨率和帧率之间权衡,但不规定具体算法;视频 track 不设置 `contentHint`,让 Chromium/libwebrtc 保留 display capture 的 screen 分类。当前源码链与测量要求见 [Realtime quality adaptation](./realtime-quality-adaptation.md)。静态画面通常能降低编码数据量,但规范不保证所有浏览器主动降低捕获频率或 GPU 开销。
因此首版不实现画面差分检测、周期性 `applyConstraints()` 或自定义动态 FPS 状态机。先对静态桌面和高动态游戏分别记录 `framesEncoded`、发送码率、`totalEncodeTime / framesEncoded`、`qualityLimitationReason` 及主机 CPU/GPU 占用;只有测量显示浏览器行为留下显著问题时,再设计最小的控制策略。这避免用额外竞态、计时器和画质跳变解决一个可能已由捕获器、编码器和 WebRTC 拥塞控制处理的问题。
diff --git a/docs/session-handoff.md b/docs/session-handoff.md
index 0d0e3978..84c9183f 100644
--- a/docs/session-handoff.md
+++ b/docs/session-handoff.md
@@ -44,9 +44,9 @@ Current high-signal boundary:
loss, local Host preference replay, an independent expiring Viewer grant, and
open/password/disabled code entry. Neither source nor production uses SQLite;
exact rollback artifacts are owned by deployment.
-- The accepted Browser v11 contract fixes VP8 and removes the diagnostic codec
- selector and quality-wire field. Current source and production remain v10
- until that client/server change is integrated and deployed atomically;
+- Browser display video must leave `contentHint` unset; audio keeps `music`.
+ The final Browser video codec is not decided. Current source and production
+ remain v10, default VP8, with the diagnostic selector fixed for each share;
heterogeneous-network and SFU media evidence remains open.
- Ordinary browser ICE owns direct reachability. Do not build port prediction,
guessed candidates, NAT classification, TCP probes, quality scores, or
diff --git a/docs/status.md b/docs/status.md
index 90012986..d2233fa8 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -22,11 +22,11 @@ This is the current execution index. Git history owns completed timelines; [veri
- Current source implements live 64/128/256 kbps audio-ceiling mutation for current and future Host/relay/SFU senders. Browser sharing defaults to VP8; `automatic | H.264 | VP8` is a temporary pre-share-only diagnostic input and remains fixed for the share lifetime. Ordinary Pause/Resume changes the existing tracks and Host SFU publication under the exact current Host session and `shareGeneration`.
- Current source implements typed first-frame Viewer presentation and recovery, Chinese user-facing route/access failures, privacy-safe failed-page export, authenticated Host-only on-demand route snapshots, neutral `ROOM_ACCESS_DENIED` room-code admission, and responsive entry controls.
- Recommended quality remains exactly `1080p60`, `1080p30`, and `720p30`; current source defaults to `1080p30`. Advanced resolution adds `480p` as `854x480` without adding a fourth preset, and advanced FPS and bitrate remain independent.
-- Exact v10 runtime source `fdd5a4a529ff297f41c05ea3388bf484d76afe8f` passed 610 Web tests in 45 files, TypeScript typecheck, client/server production builds, the access/privacy gate, the 257-test SFU admission gate, production-dependency audit, and repository hygiene. Its one-Host/20-Viewer Chrome 151 loopback decoded every Viewer, propagated the fixed VP8 settings, kept Host and relay fanout within cap `2`, captured all four current-child timing distributions, and observed no SFU publication. This is source, state-machine, build, privacy, and direct-loopback evidence, not public-network, SFU, mobile, physical audio/codec, H.264 performance, or Host-background evidence.
+- Exact v10 runtime source `fdd5a4a529ff297f41c05ea3388bf484d76afe8f` passed 610 Web tests in 45 files, TypeScript typecheck, client/server production builds, the access/privacy gate, the 257-test SFU admission gate, production-dependency audit, and repository hygiene. Its one-Host/20-Viewer Chrome 151 loopback decoded every Viewer, propagated the selected VP8 settings, kept Host and relay fanout within cap `2`, captured all four current-child timing distributions, and observed no SFU publication. This is source, state-machine, build, privacy, and direct-loopback evidence, not public-network, SFU, mobile, physical audio/codec, H.264 performance, or Host-background evidence.
## Current Milestone
-1. Implement and atomically deploy the accepted fixed-VP8 Browser v11 contract, removing the temporary codec selector and quality-wire field. Current source and production remain v10 until that cutover; no H.264 relay or SFU validation is scheduled.
+1. Remove the Browser video `contentHint` and verify the resulting capture/encode behavior. The final Browser codec remains undecided; current source and production remain v10, default VP8, with the pre-share diagnostic selector fixed for each share.
2. Diagnose the reported screen-audio `1 kbps` readout and validate live audio ceilings, then refine the Host invitation controls without changing grant semantics implicitly.
3. Reproduce the Host background/minimized report under controlled conditions while recording the actual negotiated codec.
4. Finish representative ICE/STUN/SFU acceptance including mobile networks. Browser port prediction, NAT classification, TCP probing, fake page keepalive, and quality-driven reparenting remain outside the accepted model.
@@ -42,6 +42,6 @@ This is the current execution index. Git history owns completed timelines; [veri
## Current Hold
There is no active P0/P1 source or deployment hold. Current source and production run the postflight-clean
-Browser v10 contract while the accepted fixed-VP8 v11 change is pending. Audio, heterogeneous-network, SFU,
+Browser v10 contract while the no-video-hint source change and final codec evidence remain pending. Audio, heterogeneous-network, SFU,
background, and mobile evidence remains open. Native/executable work and broad repository cleanup
remain outside the current evidence boundary.
diff --git a/docs/todo.md b/docs/todo.md
index 6eb75a4a..ce2c316c 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. **Ship the fixed-VP8 Browser contract.** Remove the temporary `automatic | H.264 | VP8` UI, quality-state/wire field, and share-lifetime codec branches; use VP8 for direct, browser-relay, and SFU senders, bump the private Browser wire once, and deploy client/server atomically. Keep actual codec/profile/encoder stats as diagnostics. Do not add GPU selection, SDP munging, profile fallback, or H.264 relay/SFU work.
+1. **Remove the Browser video content hint.** Stop assigning any video `contentHint` so display capture keeps the browser's screen semantics; retain audio `contentHint = "music"`. Verify the focused quality helper and a real `getDisplayMedia()` encode sample. This source-only change does not alter the v10 wire or decide the final codec.
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. **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.
4. **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.
@@ -33,6 +33,7 @@ These items are real product work, ordered after the current physical-media, rea
| #182 signaling watchdog | Confirm Host and mobile/background session semantics before calling it complete. |
| Viewer invitation credential length | The current grant is about 62 characters because its 43-character random suffix is the shortest base64url encoding of the accepted 256-bit secret. Decide whether a shorter copied URL justifies changing that security requirement or adding server-side indirection; do not truncate it ad hoc. |
| Viewer invitation lifetime | Align a grant with the exact in-memory room incarnation instead of an independent seven-day clock: it remains usable while that room exists and ends on rotate, revoke, process restart, or room reclamation. This deferred room change needs its own truth checkpoint before implementation. |
+| Final Browser video codec | Current v10 defaults to VP8 and retains the pre-share diagnostic selector. Compare no-hint VP8 and available hardware paths under real game load, then choose one codec and remove the selector, quality-state field, and share-lifetime codec branches atomically. Do not add application codec switching, GPU selection, SDP munging, or a codec ladder. |
| Project license and closed-commercial boundary | Decide the repository and distribution license before any public release or package distribution. GPL/AGPL implementations remain research-only until then. |
These decisions are not permission to continue old branches, and current deployment remains unchanged until a scoped decision is made.
diff --git a/docs/verification-status.md b/docs/verification-status.md
index 584656ca..ffec6e9b 100644
--- a/docs/verification-status.md
+++ b/docs/verification-status.md
@@ -19,11 +19,11 @@ Capacity and routing entries below describe the exact tested source or release o
## Retained Functional Evidence
-- Exact v10 runtime source `fdd5a4a529ff297f41c05ea3388bf484d76afe8f` passed repository hygiene, TypeScript typecheck, client and server production builds, all 610 Web tests in 45 files, the 257-test SFU admission gate, the access/privacy Browser gate, and the production-dependency audit with zero vulnerabilities. Its one-Host/20-Viewer Chrome 151 direct-loopback report passed all seven assertions: all Viewers decoded, fixed VP8 settings reached every participant, Host and relay media edges stayed within cap `2`, no orphan SFU publication appeared, and all four current-child timing distributions contained 20 values. The report SHA-256 is `802CBB7632E9AEA3C39FE831A7F7880D24140B2E83942CE0DFDA05DE4B408EED`. This validates the v10 source boundary, not H.264 quality, hardware attribution, physical capture, public-network behavior, or SFU packet flow.
+- Exact v10 runtime source `fdd5a4a529ff297f41c05ea3388bf484d76afe8f` passed repository hygiene, TypeScript typecheck, client and server production builds, all 610 Web tests in 45 files, the 257-test SFU admission gate, the access/privacy Browser gate, and the production-dependency audit with zero vulnerabilities. Its one-Host/20-Viewer Chrome 151 direct-loopback report passed all seven assertions: all Viewers decoded, the selected VP8 settings reached every participant, Host and relay media edges stayed within cap `2`, no orphan SFU publication appeared, and all four current-child timing distributions contained 20 values. The report SHA-256 is `802CBB7632E9AEA3C39FE831A7F7880D24140B2E83942CE0DFDA05DE4B408EED`. This validates the v10 source boundary, not H.264 quality, hardware attribution, physical capture, public-network behavior, or SFU packet flow.
- Chrome 151 synthetic `1/3/5/8` and 720p30 runs preserved bounded fanout and decoding. A `9461e20`-era three-Viewer rerun kept Host2/Browser Viewer1, decoded every Viewer, and recovered a hard first-level relay departure in 5,380 ms; it did not exercise quality-triggered MBB. Sixteen-Viewer cap2/cap3 loopbacks decoded all Viewers and a ten-second follow-up recorded guarded sender and aggregate Chromium CPU evidence, but resolution/FPS remained low and the ordinary-PC data cannot rank caps, select product policy, or prove sustainable heterogeneous-network quality. See [peer-assisted media](./research/peer-assisted-media.md).
- 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).
-- A fresh Chrome/Edge 151 tab-capture probe identified the current Browser H.264 boundary: Chrome, configured by Windows for minimum-power graphics, used `MediaFoundation AMDh264Encoder` for Baseline/Main/High and sustained about 12 fps; the same-machine Edge Baseline used the NVIDIA MFT and sustained about 29 fps. The Chromium high-performance GPU flag did not change Chrome's MF encoder. This is strong encoder-selection and wall-clock throughput evidence, not a physical-game image-quality ranking. The Web platform cannot select the adapter/MFT, so the accepted Browser product codec is fixed VP8 and H.264 relay/SFU validation is not scheduled. Native WGC/MF remains a separate later path with one-Viewer hardware evidence. 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).
+- 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. The accepted change is therefore only to leave video hint unset; the final Browser codec remains undecided. 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).
- 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
diff --git "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md" "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"
index bce52da6..1bb0c09f 100644
--- "a/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"
+++ "b/docs/\346\226\271\346\241\210\350\256\276\350\256\241.md"
@@ -2,7 +2,7 @@
## 2026-08-18 14:45
-状态:已接受的下一 Browser 合同固定 VP8 并移除 codec selector/wire 字段,以单一 `screener-v11` 原子替换 v10;Current source 与 production 在该实现合并和部署前仍是 `screener-v10`。Pause/Resume 继续由当前 Host session 和 `shareGeneration` 约束。精确 deployed behavior 只由 deployment 文档记录。
+状态:已接受 Browser display video 不设置 `contentHint`,audio 保留 `music`;最终 Browser codec 尚未决定。Current source 与 production 仍是 `screener-v10`、默认 VP8,并保留对每次分享固定的临时诊断 selector。Pause/Resume 继续由当前 Host session 和 `shareGeneration` 约束。精确 deployed behavior 只由 deployment 文档记录。
## 目标与边界
@@ -108,7 +108,7 @@ Web Host 在 `authenticate` 中显式发送 `viewerPresence: true` capability,
WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-access cookie 是否有效;连接后五秒内第一条消息必须是当前单一 wire 的房间级 `authenticate`。Host 消息携带 room、role、内部 Host token 与 clientId,并由 socket state 复核 site access。Viewer 消息携带 room、role、clientId,以及 exact-room Viewer grant 或当前 code-only password attempt。成功的 `authenticated` 快照始终携带部署最终值 `endpointMediaCopyCapacity: 1|2|3`;普通模式的服务端 admission 只向 Host 激活稳定加入顺序中的至多该数量 Viewer,并在离开后提升等待者,双方信令只允许 active child。Browser Host 与 Viewer 严格校验该值,房间 `maxViewers` 只约束观看者总 admission。Native/executable sender 停留在旧 wire 并在 authority 前拒绝。服务端设置 64 KiB `maxPayload`、关闭 `perMessageDeflate`,并以 ping/pong 清理失效连接。单进程固定限制 2048 条总连接和 256 条未鉴权连接,容量在 upgrade 前预留,超限直接返回 HTTP 503 并销毁 socket。
-下表描述 accepted Browser 的单一 `screener-v11` wire;server 与 Browser assets 必须作为一个完整合同原子发布,v10 和更早客户端在取得房间 authority 前拒绝,不存在旧 parser、writer、translator 或中间协议子集:
+下表描述 current Browser 的单一 `screener-v10` wire;server 与 Browser assets 必须作为一个完整合同原子发布,v9 和更早客户端在取得房间 authority 前拒绝,不存在旧 parser、writer、translator 或中间协议子集:
| 方向 | 消息 | 作用 |
| --- | --- | --- |
@@ -128,7 +128,7 @@ WebSocket 使用无 query/fragment 的同源 `/signal`。upgrade 只记录 site-
Zod 在服务边界拒绝未知类型、超长字符串、非法 SDP/candidate 结构和越权目标。服务端根据已认证会话决定路由:观看者不能给另一名观看者发信令,分享者也不能向本房间以外的 peerId 发送。
-accepted 的唯一 wire 是 `screener-v11`,不做版本协商、v10 parser、双写或 translator。任何 v10 或更早页面及 executable sender 的首条消息在角色进入 room lookup 前得到同一个 fatal refresh 终态并停止自动重连。Client 与 server 共用 `SIGNAL_CLOSE_CODES` 定义会话替换、鉴权失败和 Viewer access revoke 的终态语义,避免双方对重连边界产生分叉;非法协议消息使用 WebSocket policy-violation close code。缺失、过期、跨房、已 rotate 或 revoked 的当前 Viewer grant 使用同一个通用“邀请无效或已失效”结果,不区分房间不存在与凭据错误。已通过 site access 的 well-formed code-only 预期拒绝只发 `ROOM_ACCESS_DENIED`:unknown/expired room、disabled policy、absent/wrong password、room full 与其他已知有界 admission refusal 使用同一 code、公开文案和共享 authentication-failed close code。Grant 继续使用 `INVALID_TOKEN`,Host 鉴权保持独立,unexpected internal failure 使用不含 raw message 的 `SERVER_ERROR`。
+current 的唯一 wire 是 `screener-v10`,不做版本协商、v9 parser、双写或 translator。任何 v9 或更早页面及 executable sender 的首条消息在角色进入 room lookup 前得到同一个 fatal refresh 终态并停止自动重连。Client 与 server 共用 `SIGNAL_CLOSE_CODES` 定义会话替换、鉴权失败和 Viewer access revoke 的终态语义,避免双方对重连边界产生分叉;非法协议消息使用 WebSocket policy-violation close code。缺失、过期、跨房、已 rotate 或 revoked 的当前 Viewer grant 使用同一个通用“邀请无效或已失效”结果,不区分房间不存在与凭据错误。已通过 site access 的 well-formed code-only 预期拒绝只发 `ROOM_ACCESS_DENIED`:unknown/expired room、disabled policy、absent/wrong password、room full 与其他已知有界 admission refusal 使用同一 code、公开文案和共享 authentication-failed close code。Grant 继续使用 `INVALID_TOKEN`,Host 鉴权保持独立,unexpected internal failure 使用不含 raw message 的 `SERVER_ERROR`。
## WebRTC 协商
@@ -156,17 +156,17 @@ accepted 的唯一 wire 是 `screener-v11`,不做版本协商、v10 parser、
| 1080p30 | 1920x1080、30 fps | 5 Mbps/peer |
| 720p30 | 1280x720、30 fps | 3 Mbps/peer |
-浏览器可返回更低设置,界面以 `track.getSettings()` 显示实际捕获结果。推荐区始终只有表中的三档并默认选择中档 `1080p30`;高级分辨率额外提供 `480p`(854x480)、720p、1080p 与 1440p,FPS 继续独立接受 15 至 60 整数,码率继续独立接受 2 至 12 Mbps,因此不建立第四个推荐档或 `480p` preset ID。视频 track 使用 `contentHint = "motion"`,返回的音频 track 使用 `contentHint = "music"`;二者都是内容提示而不是 codec 或质量档位。三档推荐质量与折叠高级区初始值统一采用 `degradationPreference = "balanced"`,并允许显式选择 clarity-first 或 fluid。“分享高级设置”不提供 codec 控件,只提供离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling。音频 ceiling 可在直播中串行更新。这些设置只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率或声道。
+浏览器可返回更低设置,界面以 `track.getSettings()` 显示实际捕获结果。推荐区始终只有表中的三档并默认选择中档 `1080p30`;高级分辨率额外提供 `480p`(854x480)、720p、1080p 与 1440p,FPS 继续独立接受 15 至 60 整数,码率继续独立接受 2 至 12 Mbps,因此不建立第四个推荐档或 `480p` preset ID。视频 track 不赋任何 `contentHint`,让 display capture 保留浏览器的 screen 分类;返回的音频 track 使用 `contentHint = "music"`。三档推荐质量与折叠高级区初始值统一采用 `degradationPreference = "balanced"`,并允许显式选择 clarity-first 或 fluid。当前 v10 的“分享高级设置”暂时保留仅分享前可用、对本次分享固定的诊断 codec selector,并提供离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling。音频 ceiling 可在直播中串行更新。这些设置只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率或声道。
每次 `setParameters()` 都必须从当次 `getParameters()` 派生更新,然后读回 requested/applied `maxBitrate`、`maxFramerate`、`scaleResolutionDownBy` 和 degradation preference。浏览器负责具体降级,实际结果由 stats 观测;拒绝或浏览器改写必须进入可见状态,不能只写 `console.warn`。
-Web 视频端固定使用 `VP8`。P2P 与 browser relay 在首个 offer 前只保留 VP8 及其浏览器公布的 repair codecs,SFU publication 显式使用 VP8 并保持 `backupCodec: false`;无法采用 VP8 时明确失败,不静默协商另一种产品 codec。质量设置、房间 state、Pause/Resume、换源和 sender mutation 都不保存或改变 codec。实际 outbound codec/profile、encoder implementation 与 stats 仍是只读结果真相。Viewer answer 的 Opus stereo receive preference 是当前唯一应用 SDP 变换边界。
+当前 v10 Web 视频端默认使用 `VP8`。P2P、browser relay 与 SFU publication 使用分享开始时由临时诊断 selector 选定的同一 codec,且本轮分享内固定;不做运行时或自动 codec 切换。最终 codec 等待无 hint 的真实游戏负载证据后决定,再原子删除 selector、quality-state/wire 字段和 share-lifetime 分支。实际 outbound codec/profile、encoder implementation 与 stats 是只读结果真相。Viewer answer 的 Opus stereo receive preference 是当前唯一应用 SDP 变换边界。
Web display-audio 请求显式关闭 `echoCancellation`、`noiseSuppression`、`autoGainControl` 和 `voiceIsolation`,并以 `channelCount: { ideal: 2 }` 偏好双声道;这是当前 Chrome/Edge Host 基线的实现契约,用于避开网页 `getDisplayMedia()` 默认的语音处理和单声道 APM 候选,不宣称跨浏览器保证,也不固定采样率。所有值都是非强制 post-selection preference;不使用 `exact`、`min` 或 `advanced`。若 `getAudioTracks()` 为空,分享者界面必须显示“当前来源没有可共享音频”。Web 端同时传入 `windowAudio: "window"` 与 `systemAudio: "include"`:窗口选项请求该窗口/应用音频,整个屏幕选项允许用户勾选系统音频;标签页使用浏览器自身的标签页音频选择。浏览器可以忽略这些约束或 picker hints,且没有对应的标准来源类型读回,因此 UI 不额外推断或标注来源。系统音频由用户显式选择,可能包含语音或通知;video-only 始终可用。
当前 Windows Native sender 用本地 opaque ID 保存所选窗口的 HWND、PID 与进程创建时间;helper 在使用前重新验证三者绑定,并以 WASAPI process loopback 的 include-target-process-tree 捕获游戏及其子进程。目标进程无渲染流、退出或捕获失败时显示无声/未知,不回退为整机音频,也不上传 PID、路径、窗口标题、设备标识或原始音频。该路径只支持 Windows 11;Windows 10 game-only 音频保持明确不支持。
-同一 helper 的显式 `native-window-h264` source 用 `CreateForWindow` 建立 WGC item,在所选 adapter 的 free-threaded D3D11 frame pool 接收 BGRA surface;D3D11 VideoProcessor 做固定 1280x720/30 aspect-fit NV12 转换,随后进入 adapter-LUID-bound、hardware-only asynchronous Media Foundation H.264 MFT。输出必须是 Annex-B `42c01f`,首次、周期和反馈恢复帧携带 SPS、PPS 与 IDR。PCM、H.264 access unit 和 local-only hardware status 通过一个有界 helper protocol 进入 generation-bound Go session;H.264 直接写现有 shared fanout,UI 只收一份单向预览副本,PCM 保持现有本地 WebCodecs Opus bridge。任一 Native capture/encode 失败都终止该 source,不静默改用软件 MFT、其他 codec、browser capture、monitor capture 或 system mix;普通 Web Host 独立使用固定 VP8。一名普通 Chrome Viewer 已 decoded/rendered 203 帧并收到 500 Opus packets;同一 helper PID/adapter 的 `VideoEncode` 与 LUID 匹配。
+同一 helper 的显式 `native-window-h264` source 用 `CreateForWindow` 建立 WGC item,在所选 adapter 的 free-threaded D3D11 frame pool 接收 BGRA surface;D3D11 VideoProcessor 做固定 1280x720/30 aspect-fit NV12 转换,随后进入 adapter-LUID-bound、hardware-only asynchronous Media Foundation H.264 MFT。输出必须是 Annex-B `42c01f`,首次、周期和反馈恢复帧携带 SPS、PPS 与 IDR。PCM、H.264 access unit 和 local-only hardware status 通过一个有界 helper protocol 进入 generation-bound Go session;H.264 直接写现有 shared fanout,UI 只收一份单向预览副本,PCM 保持现有本地 WebCodecs Opus bridge。任一 Native capture/encode 失败都终止该 source,不静默改用软件 MFT、其他 codec、browser capture、monitor capture 或 system mix;普通 Web Host 使用独立的 Browser codec 路径。一名普通 Chrome Viewer 已 decoded/rendered 203 帧并收到 500 Opus packets;同一 helper PID/adapter 的 `VideoEncode` 与 LUID 匹配。
直播中切换来源仍由明确的按钮手势重新调用 `getDisplayMedia()`,不改变房间、host generation 或媒体拓扑。选源取消或失败时继续发送旧流;成功后为每个现有 sender 调用 `replaceTrack()`,健康连接不重新协商。初始 offer 预留 send-only audio transceiver,使音频可以在 `null -> track -> null` 间切换。若某个 peer 的替换或回滚失败,只重建该 peer;新流提交后才停止旧流,并以当前 stream 身份保护旧 track 的迟到 `ended` 事件。统计码率累加器在换源后重置,避免把不同 track 的计数器混算。
@@ -174,7 +174,7 @@ Web display-audio 请求显式关闭 `echoCancellation`、`noiseSuppression`、`
Host 本地预览直接绑定现有 capture stream,不创建 viewer、`RTCPeerConnection` 或额外媒体边,也不产生 SFU/应用服务器出口。预览仍可能有本地合成、缩放和 GPU 显示成本;在同一动态场景对预览开/关采集 Host CPU、GPU、encode time 和实际 FPS。后台性能诊断必须把 Host 页面前台/遮挡/最小化、被捕获 source 前台/遮挡/最小化以及 preview 播放/暂停分成独立变量,并关联 document visibility/focus、track mute/readyState 与 capture/outbound/inbound stats。页面 timer、伪活跃和 Screen Wake Lock 都不构成屏幕捕获保活方案;若标准浏览器无法维持目标行为,应记录平台能力边界而不是制造第二套 lifecycle。只有稳定收益且捕获、编码和远端画面不变时,才把直播后的默认动态预览改为静止缩略图或隐藏并允许按需展开;隐藏预览绝不停止 capture track 或 sender encode。
-固定 VP8 的依据由研究文档持有:同机 Chrome 的 Windows minimum-power GPU preference 选择 AMD H.264 MFT并稳定低帧,Edge 选择 NVIDIA MFT 后恢复,而网页没有选择 GPU adapter/MFT 的标准 API;H.264 profile 重排和 Chromium high-performance GPU flag 都不能修复 Chrome 的 MF encoder 选择。该结论不把合成 loopback 当作游戏画质排名,而是拒绝一个依赖宿主系统配置、应用无法约束的固定 Browser codec。实际 codec 与 encoder 字段继续用于诊断,不触发 codec 切换。
+codec 与 content-hint 依据由研究文档持有。`motion` 会把 Chromium/libwebrtc 的 display capture 从 screen 改成 realtime,并在同一 VP8 条件下造成明显降帧和降分辨率,因此产品不设置视频 hint。无 hint 时,普通 AMD H.264 MFT 的浏览器码控仍丢帧,而诊断性 Desktop SW BRC 可恢复约 30 fps,说明问题不等于硬件编码器本身的吞吐上限;网页没有启用该浏览器进程开关或选择具体 GPU/MFT 的 API。最终 codec 仍需真实游戏画面、整机负载和接收质量证据,实际 codec 与 encoder 字段只用于诊断,不触发 codec 切换。
`track.getSettings()` 中存在的 EC/NS/AGC/voice-isolation、`channelCount` 和 `sampleRate` 只能作为当前捕获观测;缺失字段保持未知,Opus 协商仍是独立事实。每个 Web Host 或浏览器 relay 的实际音频 sender 在首次绑定和换源后通过标准 `RTCRtpSender.setParameters()` 请求并读回当前 64/128/256 kbps ceiling;这只是上限,浏览器 WebRTC 拥塞控制仍可降低实际流量,不新增应用层音频降级器。128 kbps 保持默认,因为 RFC 7587 将 20 ms full-band stereo music 的建议区间列为 64--128 kbps,pinned LiveKit 2.22.0 也把 128 kbps 命名为 `musicHighQualityStereo`;256 kbps 是用户显式选择的较高上限,不是质量保证。Peer answer 声明 `stereo=1;maxaveragebitrate=256000`,让同一接收协商覆盖所有三档,实际 sender ceiling 仍由所选档位约束;普通 PC synthetic 不用于标定参数、听感或性能。
@@ -270,7 +270,7 @@ media-proof 和 bounded-recovery 不变量的 scoped code 与 tests。
每两秒在本地采集一次 `getStats()`。首版不上传原始统计。折叠详情可在产生该连接的本机显示 selected local/remote candidate 的 `address`/`port`,但浏览器未暴露时保持未知;地址不得进入信令、Viewer C、日志、诊断导出、持久化或路由/质量决策。在 peer 边中它只是当前连接端点,在 SFU 边中通常是 SFU 端点,不能标成参与者的权威公网 IP。
-accepted `screener-v11` 在 authenticated Host 点击下载诊断时发送一次 `request-route-diagnostic`;服务端当场返回严格 Host-only 的 `route-diagnostic-snapshot`,不连续推送。每个 current child 只保留 latest demand timestamp、operation/candidate start、first-frame/final outcome;新的 route demand 覆盖该 child 的旧 record,confirmed departure 与 room delete 立即删除,且不增加 timer、事件环或第二张 graph。`queueWaitMs` 只从同一个 current demand 到其 room-serial operation start计算;没有权威 demand timestamp 就是 `null`。Serializer 为本次导出分配 snapshot-local opaque ordinal,用它表达 current parent/SFU 关系、effective capacity、child count、current operation reason/stage/cursor/candidate count与相对 timing;`finalRoute` 只允许 `direct | sfu | waiting | failed`,`rejectionBucket` 只允许 `none | stale | endpoint-capacity | sfu-admission | candidate-failed | first-frame-timeout | operation-deadline | aborted`。Ordinal 不是身份或稳定 ID。Snapshot 不包含 room code、display name、真实 peer/session/connection/generation、地址、URL、SDP、token、raw error或 planner 曾过滤的 parent,不形成路由输入或前台第二套状态。Viewer 的 schema v2 只携带自身 stage、粗粒度 revision、typed failure、signal/Host state、route kind 与 current-frame proof,即使 connection list为空也可下载;未鉴权 `ROOM_ACCESS_DENIED` 分支只含 stage/code,不含 Host、route、revision或timing。
+current `screener-v10` 在 authenticated Host 点击下载诊断时发送一次 `request-route-diagnostic`;服务端当场返回严格 Host-only 的 `route-diagnostic-snapshot`,不连续推送。每个 current child 只保留 latest demand timestamp、operation/candidate start、first-frame/final outcome;新的 route demand 覆盖该 child 的旧 record,confirmed departure 与 room delete 立即删除,且不增加 timer、事件环或第二张 graph。`queueWaitMs` 只从同一个 current demand 到其 room-serial operation start计算;没有权威 demand timestamp 就是 `null`。Serializer 为本次导出分配 snapshot-local opaque ordinal,用它表达 current parent/SFU 关系、effective capacity、child count、current operation reason/stage/cursor/candidate count与相对 timing;`finalRoute` 只允许 `direct | sfu | waiting | failed`,`rejectionBucket` 只允许 `none | stale | endpoint-capacity | sfu-admission | candidate-failed | first-frame-timeout | operation-deadline | aborted`。Ordinal 不是身份或稳定 ID。Snapshot 不包含 room code、display name、真实 peer/session/connection/generation、地址、URL、SDP、token、raw error或 planner 曾过滤的 parent,不形成路由输入或前台第二套状态。Viewer 的 schema v2 只携带自身 stage、粗粒度 revision、typed failure、signal/Host state、route kind 与 current-frame proof,即使 connection list为空也可下载;未鉴权 `ROOM_ACCESS_DENIED` 分支只含 stage/code,不含 Host、route、revision或timing。
Host 与 relay Viewer 复用同一个纯 presentation reducer 保存远端 `ViewerQualityEvidence`。代际 identity 是 exact route identity(room/share、viewer/parent、assignment/connection、route revision 和当前可用的 media-binding generation,及适用时 publication generation);只有同 identity 且 sequence 严格递增才可承接旧字段,其他输入从新 evidence 重建。每个非空 metric 保存自己的本地观测时间并在五秒边界清空,页面 timer 总是指向最早边界;整块详情不因某个采样缺字段而卸载。`new`/`connecting`/`disconnected` 保留同 identity shell 但立即标为非 fresh,`failed`/`closed` 或 route identity 变化清空。任何依赖当前状态的消费者只读取 fresh presentation;该层不新增 wire 字段或服务端 route authority。
@@ -360,7 +360,7 @@ Token-free SFU standby prewarm 保持可选且不创建 participant、publicatio
## 当前交付边界
- Current source 与 production 使用单一 `screener-v10` wire,默认 VP8,codec selector 只在分享前可用且对本次分享固定,Pause/Resume 由当前 Host session 和 `shareGeneration` 约束。
-- 已接受的 Browser v11 固定 VP8 并删除 codec selector/wire 字段;H.264 不进入 browser relay 或 SFU 验证。Host 后台性能按受控根因证据诊断;标准 ICE/SFU 按真实异构网络验收。
+- 已接受 Browser video 不设置 `contentHint`;最终 codec 未决,当前 v10 selector/wire 暂时保留。Host 后台性能按受控根因证据诊断;标准 ICE/SFU 按真实异构网络验收。
- 当前发布面只包含 Web Host、Viewer 和 browser relay。Native sender、capture helper、shared-encode executable 与两个分发包仍由各自后续决策和物理证据驱动,不属于当前 Browser release。
任何一步只实现当前消费者需要的接口。不得为未来账号、第三种媒体拓扑或原生 sender 预建抽象层。
@@ -379,7 +379,7 @@ Pending candidate 的 receive-transport owner 只在当前 exact generation 下
首次需要 SFU 但 Host 已满时不建立另一条 rescue 流程。若 affected child 已是 Host direct child,就用它;否则用稳定加入顺序中最新的 connected Host direct child。`reconcileRoom` 为该 child 建立普通 SFU candidate,创建唯一 publication,保持其 subtree,并在该 child 首帧后提交。Host publication 取代释放的 peer slot,随后同一 fixed-point scan 再处理原 waiting/failed child。若旧 Host peer sender 在首帧前仍保留,candidate 必须持有同一 `TransitionOverlapSlot`。没有 overlap 时先 preflight server resource,再退休 exact producer;operation 保持原总 deadline、按新 graph 重算未尝试 suffix,并为被切断的 healthy direct edge追加一个最后 restore tuple。Forward candidate 与 restore 都失败才进入 waiting,不得产生第四份 endpoint copy或另一套恢复状态。
-所有非服务器端点共享一个 server-authoritative steady outbound media-copy cap `C`:唯一配置 `ENDPOINT_MEDIA_COPY_CAPACITY` 默认 `2`,只接受 `1`、`2` 或 `3`,不兼容旧键。服务端将 endpoint 当前广告的 `0..C` 可用值 clamp 为唯一 `effectiveDownstreamCapacity`;该值只表示当前可用 sender slots,不建立角色、浏览器、UA、设备或页面可见性 tier。peer child 或 Host publication 各占一份,upstream receive 免费;SFU subscriber egress 使用独立 server admission。Browser `screener-v11` 的 `authenticated.endpointMediaCopyCapacity` 把部署 `C` 交给 Host 与 Viewer;两端用该值校验稳态 assignment,并让 active+pending 的物理 copy 只在 controller 已授权 overlap 时达到 `min(C + 1, 3)`。代码通过一个 shared accounting guard 执行,不重复 magic number;v10 及更早 wire 与 Native executable 在 authority 前拒绝,不保留兼容路径。`C=3` 满载时先收到 active bounded-gap retirement再收到 prepare;任何会产生第四份 endpoint media copy 的 token都不得签发。
+所有非服务器端点共享一个 server-authoritative steady outbound media-copy cap `C`:唯一配置 `ENDPOINT_MEDIA_COPY_CAPACITY` 默认 `2`,只接受 `1`、`2` 或 `3`,不兼容旧键。服务端将 endpoint 当前广告的 `0..C` 可用值 clamp 为唯一 `effectiveDownstreamCapacity`;该值只表示当前可用 sender slots,不建立角色、浏览器、UA、设备或页面可见性 tier。peer child 或 Host publication 各占一份,upstream receive 免费;SFU subscriber egress 使用独立 server admission。Browser `screener-v10` 的 `authenticated.endpointMediaCopyCapacity` 把部署 `C` 交给 Host 与 Viewer;两端用该值校验稳态 assignment,并让 active+pending 的物理 copy 只在 controller 已授权 overlap 时达到 `min(C + 1, 3)`。代码通过一个 shared accounting guard 执行,不重复 magic number;v9 及更早 wire 与 Native executable 在 authority 前拒绝,不保留兼容路径。`C=3` 满载时先收到 active bounded-gap retirement再收到 prepare;任何会产生第四份 endpoint media copy 的 token都不得签发。
SFU admission 在应用单进程中只有一个注入实例。LiveKit credential tuple 完整时,必须同时显式配置私有 `LIVEKIT_API_URL`、正 safe integer `SFU_INGRESS_CAPACITY` 与 `SFU_EGRESS_CAPACITY`;容量没有产品默认值,也不从 Viewer 数、endpoint cap 或历史 root 数推导。专用 LiveKit 实例设置 `room.auto_create: false`。账本只保存全局已用计数,以及 exact room/share/publication generation 下的一份 publication handle 和按 Viewer identity 索引的 subscription handle。Publication 的 `reserved | committed | draining` 占 ingress `1`,每份 subscription 的同类状态占 egress `1`;离开 route 的 subscription 在该 generation 删除并确认 absent 前保持 draining,同一 Viewer handle 再次启用不重复计数。首个 SFU child 先 reserve publication 与自己的 subscription,再通过 `RoomService.CreateRoom` 创建 exact-generation room,成功后才 prepare 和签发 token;后续 child 只在同 generation reserve subscription 并复用 Host publication。exact candidate child 的 first decoded frame 后 commit 自己的资源;publication replacement 将旧 generation 及其全部 subscription 一起转入 draining,失败、超时、失联、分享换代、停止或删房按资源所有权进入同一生命周期。只有 `RoomService.DeleteRoom` 成功且 follow-up lookup 证明 room 不存在,账本才扣除该 generation 的 ingress/egress;auto-create 关闭后,旧 token 不能重建已删除 room。进程启动在接受流量前拒绝任何非 Screener room,删除全部遗留 Screener room并确认 namespace 为空;关闭时先 drain 再遗忘计数。Host 信令离线期间若 exact room 中的 Host participant 仍存在就继续计费并保留健康媒体,participant 消失后在一个有界轮询周期内回收。稳态 reserve/commit/drain bookkeeping 仍是 Map lookup 与整数加减;只有 generation 创建、删除、启动清场和 Host 离线检查访问 LiveKit control plane。多应用进程部署必须先增加共享原子 admission/lifecycle owner。
diff --git "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md" "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"
index bcd3d907..1cb8617c 100644
--- "a/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"
+++ "b/docs/\351\234\200\346\261\202\347\220\206\350\247\243.md"
@@ -27,7 +27,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;不读取旧键或保留第二套 tier。peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。服务端在每次 `authenticated` 权威快照中返回最终 `endpointMediaCopyCapacity`;普通非 peer-assisted 模式也只授权稳定加入顺序中的至多 `C` 个 Host child,超额 Viewer 保持入房等待并在槽位释放后提升,信令不能绕过该集合。Browser Host 与 Viewer 严格校验该值并用它约束稳态 assignment;并行产生媒体的 candidate 必须持有唯一 `TransitionOverlapSlot`,active+pending 物理 copy 只可达到 `min(C + 1, 3)` 并在 commit/abort 后释放。`C=3` 满载时必须先收到 active bounded-gap retirement 再 prepare,绝不产生第四份 copy。SFU subscriber egress 由独立 server admission 记账。当前不兼容房间合同以单一 release 原子升级;缺失/非法 cap、旧 wire 与 executable sender都在取得room/route authority前fail closed。
- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的 child。任何 source-reachable endpoint 在 effective capacity 有空位时都可作为 parent candidate;Peer-fed 与 SFU-fed endpoint 使用同一个 provisional-child transaction,并在 candidate child 解码出第一帧新画面后独立提交该 edge。Host 已满且首次需要 SFU 时,同一 reconcile 将 affected Host direct child(若无则稳定顺序中最新的 connected Host direct child)作为本次 child operation,创建唯一 Host publication 并把该 child 变为首个 SFU subscriber,subtree 不动;publication 取代释放的 Host peer slot,下一次扫描再处理原受限 Viewer,不建立 bootstrap 状态机。
- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers。浏览器 ICE connectivity checks 是 direct UDP 可达性的权威;Screener 不合成 remote candidate、不预测端口、不分类 NAT,也不使用 TCP 探测推断 UDP 媒体可达性。所有恢复和候选授权必须绑定 authenticated room/endpoint session、share generation、base/pending route revision 与 candidate connection identity;成功即停止,失败、超时或绑定失效即撤销,direct 阶段耗尽后在同一 operation deadline 内进入 SFU/UDP,全部可用路径耗尽后明确等待或失败。已接受的完整顺序只有保持或尝试 direct/STUN peers,再复用或建立 direct-ingress Host publication/SFU subscription。Screener 不配置 TURN、ICE/TCP、media TCP 或 TLS-relayed media;当前 LiveKit 也保持 UDP-only。未来若真实严格防火墙矩阵证明需要另一种传输,必须把它作为 LiveKit 内部能力重新决策,不能增加第三种应用 route candidate。LiveKit join JWT 仅按协议进入不得记录的 WebSocket request target;HTTPS/WSS 继续独立使用 TLS/TCP。
-- 质量控制:推荐档位始终只有 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档,默认选择中档 `1080p30`。高级设置的分辨率选项增加 `480p`(854x480),其 FPS 与码率仍由高级控件独立选择;不增加 `480p` 推荐档、preset ID 或固定的 480p FPS/码率组合。三档与高级设置初始值统一采用 `balanced`(平衡),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)保留为显式选择。Browser 视频固定使用 VP8,不提供 codec 选择、切换或 profile 控件。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。
+- 质量控制:推荐档位始终只有 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档,默认选择中档 `1080p30`。高级设置的分辨率选项增加 `480p`(854x480),其 FPS 与码率仍由高级控件独立选择;不增加 `480p` 推荐档、preset ID 或固定的 480p FPS/码率组合。三档与高级设置初始值统一采用 `balanced`(平衡),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)保留为显式选择。当前 v10 默认 VP8,并暂时保留仅分享前可选、对本次分享固定的诊断 codec selector;不做运行时或自动 codec 切换。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。
- 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先使用 pinned LiveKit 的标准两层 screen-share simulcast,让内建 per-subscriber BWE 独立降层和恢复,Screener 不实现媒体层 selector。应用只诊断实际接收层、硬件编码、游戏性能、资源和上传;SFU 自动降层不改变拓扑。`LOW` 停编只是资源优化,active representation/layer 硬上限为二且不随 viewer 增长。当前 Web P2P simulcast 与 Web/LiveKit SVC 不能证明跨 direct/peer 共享编码或可移植硬件路径;全部标准路径失败后才考虑 custom/native dual encode。
- 路由失效输入:应用不推断 parent-wide 质量,也不计算综合分数。当前 authenticated child 只在 PeerConnection `failed/closed`,或非权威暂停时现有 periodic stats 在统一 deadline 内没有新 decoded frame 时,使自己的 exact edge 失效并唤醒同一个 reconcile。decoded progress 只保存 route-keyed `lastDecodedAt`,route/connection变化或新帧重置、暂停抑制,同一 edge只报告一次,不增加轮询器。该 operation 把失败的 exact direct parent 在当前 fact version 直接视为已尝试,先选择其他 direct parent,再进入有界 SFU suffix;新的外部事实才允许原 direct tuple 重新进入。Track availability、低码率、低 FPS、模糊、sender/viewer stats 与 SFU layer只用于stock WebRTC/LiveKit恢复和诊断。relay自身ingress失效时,它作为child换父并保留subtree;disconnect或effective downstream capacity降低只让direct/overflow children逐个走同一事务。
- 断线恢复:临时网络变化先交给 WebRTC/LiveKit 的 ICE、consent、重连和流状态。Direct edge 可在 exact current parent/child sessions 内采用 framework rebuild 的新 connection ID而不改变topology。应用只在上述exact edge失效后运行一次有界reconcile;任一步成功即停止。候选耗尽时hard-invalid、confirmed-departed或overflow edge被退休并进入明确waiting,healthy bootstrap edge保留。所有异步结果受authenticated session、share generation、base/pending route revision与candidate connection identity约束,未受影响分支保持sticky。权威暂停abort未提交candidate、保留active graph、抑制stall,并在resume后重新reconcile。
@@ -45,7 +45,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
- 独立房间入口:合法 `/r/{code}#v={grant}` 邀请直接进入对应房间;没有 grant 的 `/join` 或 `/r/{code}` 先显示明确标为“站点访问”的整站验证,再提交 code-only 尝试。`open` 且可准入时直接进入;其余预期拒绝统一为 `ROOM_ACCESS_DENIED`,不得先披露 `password | disabled` policy。有效 site-access cookie 只跳过第一步,两类密码不得复用或互相替代。Host 可设置、轮换或移除房间观看密码;密码接受 1 至 64 个可见 ASCII 字符,异步 scrypt 全局最多执行 2 个、等待 16 个派生。Host 可把房间密码保存在同源本地创建偏好中;它不得进入 URL、cookie、日志或服务端持久存储。未知或过期房间、disabled policy、缺失/错误密码、队满和其他已知有界 admission refusal 都返回相同 code、公开文案和 close 行为。
- 统一自动路由:旗舰部署开启 `PEER_ASSISTED_MEDIA` 后,每个房间使用一个服务端 route controller,独占 committed graph、一个 pending child operation 和 event-driven reconcile。运行时只增加一个串行pump、一个operation deadline timer与typed resource lifecycle task,不维护另一份graph。operation持有candidate list/cursor、一个current candidate/资源预留、fact version和一个总deadline。committed graph必须无环、source-reachable,且每名Viewer同时至多一个active upstream。加入、容量变化、节点离开、exact edge `failed/closed`,以及非暂停decoded-frame stall都只唤醒同一个reconcile;其余健康分支保持sticky。候选按当前身份、source reachability、无环、effective capacity与sender transition硬过滤,再按结果深度、剩余sender slots、稳定加入顺序和peer identity排序;因此 Host root退出后新释放的Host槽位比已有root的更深槽位优先,但健康旧边不因周期性平衡而迁移。server admission在执行当前cursor时独立reserve。candidate child首帧ready触发`settleReady(commitAdmissionSync)`,成功prepare `P`提交active `P`;失败释放资源并用同一monotonic allocator广播`R>P` rollback,cursor推进但总deadline不重置。bounded-gap先preflight server resource,再retire producer、按新graph重算未尝试suffix,并在切断healthy edge时追加一个普通restore candidate。relay自身ingress失效时作为child换父并保留subtree;relay disconnect/cap降低让overflow children逐个走同一事务,childless后删除。房间admission和无环约束最大深度,不设独立hard cap。普通peer始终STUN-only,SFU使用独立admission。
-- 观看端连接反馈:Viewer 舞台从鉴权到首帧使用一个由现有权威状态推导的稳定阶段反馈,至少区分等待分享、分配线路、建立 P2P、连接备用线路、等待首帧、浏览器阻止自动播放、恢复连接和有界失败。阶段不是进度百分比,也不产生 route authority;只有当前 video element 实际提交首帧后才显示正在播放。播放按钮只在 `play()` 因自动播放策略被拒绝时稳定出现,连接中不得忽隐忽现;明确失败后才提供一次受现有 controller 约束的重试入口。make-before-break 或仍有可见旧帧时保留画面并叠加恢复状态,不为显示反馈主动清空健康 media element。Host 离线本身不使仍健康的媒体失效;exact upstream 硬失败或 route terminal failure 必须使 current frame proof 失效,已证明画面至多降为 retained background,不能遮蔽离线或有界失败。accepted `screener-v11` 服务端补充消息是 strict、current-revision-fenced `route-status` union,且只允许 `waiting/sfu-admission` 与 `failed/route-exhausted` 两种配对;它不携带 raw text、身份、candidate 或 retry hint,prepare/active、access、Host、signal、media 与 autoplay 继续由各自权威输入派生。
+- 观看端连接反馈:Viewer 舞台从鉴权到首帧使用一个由现有权威状态推导的稳定阶段反馈,至少区分等待分享、分配线路、建立 P2P、连接备用线路、等待首帧、浏览器阻止自动播放、恢复连接和有界失败。阶段不是进度百分比,也不产生 route authority;只有当前 video element 实际提交首帧后才显示正在播放。播放按钮只在 `play()` 因自动播放策略被拒绝时稳定出现,连接中不得忽隐忽现;明确失败后才提供一次受现有 controller 约束的重试入口。make-before-break 或仍有可见旧帧时保留画面并叠加恢复状态,不为显示反馈主动清空健康 media element。Host 离线本身不使仍健康的媒体失效;exact upstream 硬失败或 route terminal failure 必须使 current frame proof 失效,已证明画面至多降为 retained background,不能遮蔽离线或有界失败。当前 `screener-v10` 服务端补充消息是 strict、current-revision-fenced `route-status` union,且只允许 `waiting/sfu-admission` 与 `failed/route-exhausted` 两种配对;它不携带 raw text、身份、candidate 或 retry hint,prepare/active、access、Host、signal、media 与 autoplay 继续由各自权威输入派生。
- 质量控制扩展:推荐档位仍是默认入口且只保留 1080p60/1080p30/720p30 三档,当前页面初始 desired state 选择 1080p30 且不写 `localStorage`;“分享高级设置”允许 480p(854x480)/720p/1080p/1440p 分辨率 ceiling、15 至 60 的整数 FPS ceiling、2 至 12 Mbps 视频码率 ceiling、清晰/平衡/流畅三种偏好,以及离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling;480p 不形成推荐档或固定 FPS/码率组合,初始值采用 `balanced` 与 128 kbps。视频档位和音频档位可在直播中显式应用。所有当前及以后建立的 Web Host、Browser relay 与 SFU sender 都读取最新 desired 档位,并各自在 fresh sender parameters 上应用和读回 endpoint-local applied 值;实际码率仍由浏览器拥塞控制和 stats 决定。Peer 只在唯一明确的 active Opus audio 上做结构化、幂等的 Viewer answer `stereo=1;maxaveragebitrate=256000` 变换,使同一接收上限覆盖三档;非目标形态或 parser/writer 异常必须原样保留浏览器 answer,不得阻断可继续的 mono/video edge。不得用宽泛字符串/正则改 SDP,也不得改写浏览器协商的 FEC。SFU 将三档映射到 pinned SDK 的 music stereo preset 或显式 256 kbps ceiling,统一保留 `forceStereo = true`、`dtx = false` 与 pinned room default `red = true`。不得暴露任意码率、声道、采样率、audio codec、stereo、DTX、RED 或 FEC 控件;256 kbps 只是显式较高上限,不是无损、高保真或最低码率保证。实际质量持续低于所选上限时必须显示可解释的限制原因;在真实拥塞、编码器和接收端证据完成前,不把任一组合称为“完美平衡”。未来 microphone voice 若进入范围,必须是独立 track/处理链,不能把 AEC/降噪/DTX 套到电影或游戏音频。
- SFU 质量设置生命周期:直播中修改档位时,浏览器 sender 的 applied readback、LiveKit `LocalVideoTrack` 保存的 degradation preference、track restart options 与 `LocalTrackPublication` 的 republish options 必须作为同一次串行操作更新;任一步失败恢复旧 sender 与旧 SDK 保存态,旧 publication generation 不得回写当前状态。LiveKit full reconnect/republish 不得恢复初次发布的旧偏好。该修复不改变 codec、码率上限、层数或路由,也不能单独解释即时低帧。
- 本地预览性能候选:在相同动态场景中 A/B 测量 Host 动态预览开/关的 CPU、GPU、encode time 和实际 FPS。只有稳定收益且捕获、编码和远端画面不受影响时,才允许直播开始后默认显示静止缩略图或隐藏动态预览并提供按需展开;未测前不宣称收益。
@@ -58,12 +58,12 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
- 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。
- Windows 应用音频:Windows 11 Native sender 使用本地 opaque window target 绑定 HWND、PID 与进程创建时间,只捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享;“全部系统声音”只能由分享者显式选择。普通 Windows 10 不具备当前 process-loopback API 门槛,必须明确标为未解决/不支持而不是伪兼容。浏览器无法证明或隔离任意进程音频时必须如实提示,原生捕获失败、无声或进程退出不得静默扩大为整机捕获。
- 受限网络边界:当前媒体只使用 ordinary direct/STUN UDP 与 LiveKit SFU/UDP;全 UDP 封锁、只允许标准 HTTPS 出站等网络在有界窗口后明确失败。不得用 TCP 探测、客户端声称的 NAT 类型或另一套应用 route candidate 猜测可达性。若真实矩阵证明该失败边界需要扩展,先比较 LiveKit 内建 ICE/TCP 或其内部安全 relay transport,并另行接受安全、端口、延迟和部署合同。
-- Web 编码:Browser Host、browser relay 与 SFU publication 固定使用 VP8,产品不提供 codec 或 profile 控件;无法采用 VP8 时明确失败,不保留另一种产品 codec。实际 codec/profile、encoder implementation 与 stats 继续作为只读诊断事实,不产生自动切换或路由 authority;选择依据由 [realtime quality research](./research/realtime-quality-adaptation.md#fixed-browser-codec-decision) 持有。
+- Web 编码:视频 track 不设置任何 `contentHint`,让 display capture 保留浏览器的 screen 分类;音频 track 继续使用 `contentHint = "music"`。当前 v10 默认 VP8,并暂时保留仅分享前使用、对本次分享固定的诊断 selector;最终 codec 等待无 hint 的真实游戏负载证据后决定。实际 codec/profile、encoder implementation 与 stats 继续作为只读诊断事实,不产生自动切换或路由 authority;依据由 [realtime quality research](./research/realtime-quality-adaptation.md#browser-codec-and-content-hint-evidence) 持有。
### P2 - 可选功能
- 运行时有效容量:部署的 steady cap `C` 仍只接受 `1`、`2` 或 `3` 且默认 `2`,不按角色、设备或 UA 分类。服务端把 authenticated endpoint 当前广告的 `0..C` 可用值 clamp 成唯一 `effectiveDownstreamCapacity`;`0` 表示当前不承担下游,不是另一套 release tier。controller 通过同一个 reconcile 迁移 deterministic overflow children。H.264、hardware encode 或 shared encode 可以降低编码成本或同观感码率,但每个 ordinary child 仍消耗一份网络副本。
-- 原生 Windows 捕获辅助程序:显式 `native-window-h264` 模式使用同一 bound window target 的 WGC/D3D11 画面与 WASAPI process-tree PCM,并用 adapter-bound、hardware-only Media Foundation H.264 `42c01f` 直接进入现有 Go fanout;普通 Web Host 独立使用固定 VP8,不允许运行时静默改用软件编码、显示器画面或系统混音。一名普通 Chrome Viewer 已 decoded/rendered 203 帧并收到 500 Opus packets,同一 helper PID/adapter 的 `VideoEncode` 与 LUID 匹配。
+- 原生 Windows 捕获辅助程序:显式 `native-window-h264` 模式使用同一 bound window target 的 WGC/D3D11 画面与 WASAPI process-tree PCM,并用 adapter-bound、hardware-only Media Foundation H.264 `42c01f` 直接进入现有 Go fanout;普通 Web Host 保持独立的 Browser codec 路径,不允许运行时静默改用软件编码、显示器画面或系统混音。一名普通 Chrome Viewer 已 decoded/rendered 203 帧并收到 500 Opus packets,同一 helper PID/adapter 的 `VideoEncode` 与 LUID 匹配。
- Viewer 向电视输出:系统级屏幕镜像现在可直接使用;产品只复用平台 AirPlay/Cast,不自造投屏协议。截至 2026-08-21,Chromium 的 Remote Playback URL 路径和 WebKit 明确拒绝 wireless target 的 live `MediaStream` player 均未给当前 WebRTC `srcObject` 提供可用契约,因此不显示伪可用入口。只在浏览器实现明确支持并由实体 Apple TV 或 Chromecast/Google TV 证明当前 live 画面与音频后,才按通过的平台加入 Viewer 本地图标按钮。投屏不能改变 room、SFU/peer route、Host fanout 或服务端媒体分发;Google Cast receiver 需要可获取的媒体 URL,当前 P2P `MediaStream` 不满足该输入,因此不加入 Cast SDK/receiver。
- 多地区 server-assisted ingress/egress 调度及 SFU 的按地区、运营商可达率。
@@ -76,7 +76,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
- 安全:应用控制面全程 HTTPS/WSS;site access、Host token 与 room-scoped Viewer grant 权限正交,任何一个 Viewer grant 只授予一个房间的观看角色。P2P 边在 WebRTC 端点间使用 DTLS-SRTP,普通 SFU 是逐跳 DTLS-SRTP;只有另行实现并验收应用层 E2EE 才能对 SFU operator 保持媒体端到端机密。仓库、服务端持久存储、日志和错误不得包含明文密码或 grant。已鉴权 Host 与 shipped clients 是当前私密房间中的可信媒体参与者;越权房间、角色和未授权 subscription 必须拒绝。旧 generation 不得重新取得 route authority,并在有界 drain 后由 exact-room 删除阻止再次加入。
- 隐私:P2P 会向房间内好友暴露网络地址,首版威胁模型仅覆盖可信熟人;若要求隐藏 IP,必须切换为服务器转发。
- 可维护性:代码、需求、调研、项目记忆、`AGENTS.md` 和 `.codex/` 均在 Git 中跟踪;开发配置不得依赖单一操作系统的绝对路径。
-- 迁移完整性:项目拥有者明确宣布公开发布前,只维护当前内部产品合同,不承担 backward/forward compatibility。客户端、服务端和部署配置按同一 release 原子迁移;移除 Browser codec 选择的合同使用单一 `screener-v11`,v10 及更早客户端在 authority 前拒绝。替代后立即删除旧配置、wire、parser、双写、translator、deprecated alias、migration shim 与仅服务旧版本的测试,不保留第二套架构。Git 历史承担旧实现追溯;公开发布后才按明确的新要求重新评估兼容策略。
+- 迁移完整性:项目拥有者明确宣布公开发布前,只维护当前内部产品合同,不承担 backward/forward compatibility。客户端、服务端和部署配置按同一 release 原子迁移;若最终 codec 决策删除当前 selector/quality wire 字段,则使用一个新的单一 wire 原子替换 v10,旧客户端在 authority 前拒绝。替代后立即删除旧配置、wire、parser、双写、translator、deprecated alias、migration shim 与仅服务旧版本的测试,不保留第二套架构。Git 历史承担旧实现追溯;公开发布后才按明确的新要求重新评估兼容策略。
- Web 优先:每项用户能力先使用普通浏览器的标准 API 和正常权限流程;只有当前目标浏览器存在已证实的能力缺口且该功能仍属当前范围时,才允许独立、可选的 Sender。不得为假设中的未来能力预建客户端、兼容层或第二套会话架构。
- 兼容性:分享端首个目标矩阵为 Windows 10/11 的当前 Chrome/Edge;普通移动浏览器当前只属于 Viewer 矩阵。截止 2026-08-21,MDN Browser Compatibility Data 仍将 Chrome Android、Firefox Android 和 Safari iOS 的 `getDisplayMedia()` 标为不支持;Web Host 必须用运行时能力检测,API 缺失时明确显示不支持,API 存在但调用拒绝时区分用户拒绝/取消与 capture failure,不能用 UA/设备型号伪造兼容。观看端仍必须覆盖当前 Android Chrome 和 iOS Safari,并实测自动播放限制、横竖屏、锁屏恢复与移动网络切换。所有 Web Viewer 使用统一的 server-authoritative endpoint capacity;移动真机表现是兼容观察,不建立单独 route class。
@@ -102,7 +102,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
- Given production site access secret 短于 8 bytes、长于 128 bytes 或含非可见 ASCII,When 新 release 启动,Then 必须 fail-fast。Given 同一来源连续提交错误 secret,When 超过 deployment `limit_req` 的 `5r/m`、`burst=5 nodelay` 边界,Then nginx 返回不含凭据的通用限频结果;允许请求的错误值仍使用常量时间比较和统一鉴权失败,limiter 只使用 nginx 内存且不新增 IP 持久化/日志字段。
- Given 新建房间,When 服务端返回邀请并由 Host/Viewer 客户端读取,Then grant 含 256-bit 随机量、只授权该房间 Viewer、只在该页面会话的 room-scoped `sessionStorage` 留存,并在首次读取后从地址栏移除;HTTP request-target、WebSocket URL、Referrer、cookie、`localStorage`、服务端持久存储、日志和错误均不包含 grant。
- Given 本地输入不是 `1000..9999` 的四位房间码,When 用户提交或直接访问 malformed `/r/...`,Then 客户端保留原输入并直接提示“四位数字”,不发起房间鉴权、不静默删除字符。Given 默认新房,When 已通过站点访问的 Viewer 只输入合法房间码,Then 无房间密码即可在现有 Viewer/连接/egress 上限内加入,同时 Host 的主分享动作仍复制独立的 token-bearing link。
-- Given 已通过 site access 的 well-formed code-only 尝试对应未知/过期房间、disabled policy、缺失/错误密码、满房或其他已知有界 admission refusal,When `screener-v11` 首条信令鉴权到达,Then 服务端返回唯一 `ROOM_ACCESS_DENIED`,并使用共享的 authentication-failed close code;同一公开文案和 close 行为不得泄露房间存在性或 policy。UI 不自动断言“需要密码”,只允许可选密码重试并提示使用 Host 提供的邀请链接,不向服务器索取链接。Given grant 无效,Then 继续使用通用 `INVALID_TOKEN`;Host 鉴权保持独立错误,unexpected internal failure 使用不含 raw message 的 `SERVER_ERROR`。Given Viewer 持另一个房间的 grant、缺失/过期 grant 或自行把 role 改为 Host,Then 不能建房、发布、跨房或绕过 Host token。
+- Given 已通过 site access 的 well-formed code-only 尝试对应未知/过期房间、disabled policy、缺失/错误密码、满房或其他已知有界 admission refusal,When `screener-v10` 首条信令鉴权到达,Then 服务端返回唯一 `ROOM_ACCESS_DENIED`,并使用共享的 authentication-failed close code;同一公开文案和 close 行为不得泄露房间存在性或 policy。UI 不自动断言“需要密码”,只允许可选密码重试并提示使用 Host 提供的邀请链接,不向服务器索取链接。Given grant 无效,Then 继续使用通用 `INVALID_TOKEN`;Host 鉴权保持独立错误,unexpected internal failure 使用不含 raw message 的 `SERVER_ERROR`。Given Viewer 持另一个房间的 grant、缺失/过期 grant 或自行把 role 改为 Host,Then 不能建房、发布、跨房或绕过 Host token。
- Given Host rotate/revoke Viewer grant,When 新内存摘要和 authorization generation 提交,Then 服务端清除 Viewer grace/路由,命令 Viewer 关闭接收 PC/媒体并让每个 Host/relay/SFU upstream owner 关闭对应旧代次媒体边,最后关闭旧 Viewer socket;rotate 返回一次新 grant,revoke 锁定 grant 路径,code-only policy 保持独立。
- Given Host 同源本地偏好保存了 `open | password | disabled` 和可选房间密码,When 服务器重启后该 Host 下一次显式开始分享,Then 客户端清除失效 ownership、创建新四位房间并原子重放偏好;新的 Host token 和 grant 替换旧值。Given 换浏览器、换设备或清理站点数据,Then 不恢复这些偏好或所有权。
- Given 应用进程重启,When 旧 Host、Viewer 或 code-only 链接再次访问,Then 所有旧房间、租约、摘要、密码 verifier 和参与者均已丢弃并 fail closed;运行时不读取数据库、迁移旧 schema 或恢复旧号码。
@@ -133,7 +133,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
### 一对多与带宽保护
-- Given `ENDPOINT_MEDIA_COPY_CAPACITY=C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Browser Host 或任一 Browser Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,角色、浏览器和 UA 不改变 `C`;每个 `authenticated` 快照都携带同一个 `C`,并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。Given 当前 `screener-v11` 房间合同,When Host 或 Viewer 取得房间 authority,Then server 与 Browser assets 属于同一 release,缺失或越界的 `C`、其他 wire 与 executable sender 得到明确 mismatch,且 `C=3` 满载 Host 在取得会产生第四份 endpoint media copy 的 publication/token 前明确等待或失败。
+- Given `ENDPOINT_MEDIA_COPY_CAPACITY=C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Browser Host 或任一 Browser Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,角色、浏览器和 UA 不改变 `C`;每个 `authenticated` 快照都携带同一个 `C`,并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。Given 当前 `screener-v10` 房间合同,When Host 或 Viewer 取得房间 authority,Then server 与 Browser assets 属于同一 release,缺失或越界的 `C`、其他 wire 与 executable sender 得到明确 mismatch,且 `C=3` 满载 Host 在取得会产生第四份 endpoint media copy 的 publication/token 前明确等待或失败。
- Given peer-assisted 路径分别运行 1、5、10、20 名观看者,When 用户加入、容量释放、节点离开、重鉴权或当前 edge 失效,Then 服务端只为新 Viewer、等待 Viewer 或失去 parent 的 subtree root 选择一个 active parent;每名 Viewer 同时至多一个 active upstream,活动图无环,其余健康边保持 sticky。没有可用 parent 时明确等待或拒绝,不主动重平衡或引入常驻多源媒体。
- Given 一个 Host root 退出并释放 Host sender slot,When 新 Viewer 加入或一个失父 child 进入同一 reconcile,Then 候选按结果深度优先,选择 Host 而不是另一 root 的更深空槽;已健康挂在另一 root 下的旧 child 不被周期性搬动。Given authenticated Host 点击下载诊断,Then 服务端按需生成一份 current route snapshot,用 snapshot-local opaque ordinal 表达当前 parent 关系,并只包含 current operation reason/stage/cursor、每个 current child 的 latest demand/queue/candidate/first-frame timing 与封闭 outcome enum;该 ordinal 不是稳定身份,snapshot 不反推丢失事件、不记录 planner 过滤过的 parent、不包含 raw identity/address/error,也不参与 route。Given Viewer 请求房间级 snapshot,Then 服务端拒绝。
- Given 一名分享者和 20 名观看者,When 运行 bounded browser smoke,Then 全部 Viewer 取得明确媒体或 bounded wait/failure,非服务器端点不超过 `C`,并记录 route depth、首帧时间、实际 sender 数、应用服务器 CPU/内存以及 SFU 用量。诊断汇总报告 20 个 current-child 样本数、pending 数、每项原始排序时长和 nearest-rank p50/p95/max,不设通过阈值;confirmed departure 和 room delete 后对应 timing 必须消失。该 smoke 验证 admission、控制面效能和资源上界,不单独证明任意公网画质或 30 分钟 endurance。
@@ -158,7 +158,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
- Given 同一时刻采集、host outbound 与 viewer inbound 证据,When 进行根因分类,Then 关联派生后的实际协商视频 codec/profile/parameters、适用时的 `scalabilityMode` 与真实解码表现,依次区分 Capture 低、Capture 高但 outbound 因 CPU 低、Capture 高但 outbound 因 bandwidth 低、outbound 正常但 inbound 低、以及 inbound 正常但肉眼模糊五类;不用 UA 或设备型号代替运行时证据,也不上传 raw SDP。
- Given Viewer 发送低档请求,When 请求未鉴权、过频、重复、过期或没有匹配的 sender/viewer 统计,Then 请求不改变表示或路径状态;有效请求也只能作为交叉验证输入。
- Given 受控 RTT/丢包测试条件,When 连续分享高动态游戏画面 30 分钟,Then 延迟、帧率与丢帧达到上述目标,且没有不可恢复的冻结。
-- Given Windows Chrome/Edge Browser Host 开始或继续分享,When 建立 direct、browser-relay 或 SFU sender,Then 应用固定请求 VP8 且不暴露 codec/profile 选择;实际 RTP codec 与实现字段仍按浏览器 stats 如实显示。Given 浏览器未能采用 VP8,Then 该路径明确失败而不是静默切换为另一套产品 codec 或保留旧 selector/wire 字段。
+- Given Windows Chrome/Edge Browser Host 开始或继续分享,When 浏览器返回 display video track,Then 应用不赋任何视频 `contentHint`,并按浏览器 stats 如实显示实际 RTP codec 与实现字段。Given 当前 v10 建立 direct、browser-relay 或 SFU sender,Then 使用分享开始时选定的 codec;Pause/Resume、换源和直播中质量更新不改变它。
- Given 分享过程中切换 Wi-Fi/有线网络,When ICE 连接失败,Then 客户端触发 ICE restart,并在成功或超时后给出明确状态。
- Given 当前路径仍可播放且控制器准备迁移 logical parent 或替换 transport,When 候选路径拥有模型授权的 overlap 资源,Then 旧路径保持权威,直到 exact candidate child 解码出第一帧新画面后才原子提交;ICE `connected` 单独不能触发切换。
- Given 候选没有准入资源,或 provisional 路径失败、超时、代次过期、参与者变化、房间停止、权限撤销或 session 被替换,When 本次机会结束,Then 原路径和未受影响 branches 继续工作,临时资源被销毁,重试遵守模型定义的有界策略。
@@ -168,7 +168,7 @@ SFU 的 publication、subscription、server-resource accounting、临时 overlap
- Given Web Host 或浏览器 relay 建立或替换分享音轨,When 对实际音频 sender 应用发送参数,Then 从当次 `getParameters()` 派生所选 `encodings[0].maxBitrate = 64000 | 128000 | 256000`、调用 `setParameters()` 并立即读回,旧配置缺失时按 128000 处理;Given Web Viewer 为含唯一有效 audio/Opus payload 的 offer 生成 answer,Then 用结构化 SDP parser 只 upsert 该 payload 的 `stereo=1` 与 `maxaveragebitrate=256000`,并把同一个结果用于 `setLocalDescription()` 和 signaling。首次连接、ICE restart、同 parent rebuild 和 relay child 都适用;空 SDP、无/歧义 Opus、多个有效 audio、重复目标参数、畸形 fmtp 或 parse/write 异常必须按对象 identity 返回浏览器原 answer 并继续,不能发送部分修改或静默冒充 stereo/实际码率。只有实际 `setLocalDescription()` 失败才进入既有连接错误路径。`sprop-stereo` 与 `usedtx` 不新增,其他 fmtp/FEC/session/media 字段逐项保留。
- Given 通过 SFU 发布分享音轨,When 构建 LiveKit 2.22.0 publish options,Then 64 kbps 使用 `AudioPresets.musicStereo`、128 kbps 使用 `AudioPresets.musicHighQualityStereo`、256 kbps 使用同等结构的显式 sender ceiling,三档都设置 `forceStereo = true` 与 `dtx = false`,且不覆盖 pinned room default `red = true`;验收同时核对 SDK 选项、applied ceiling、当前 RTP codec/fmtp 与 stats 实际码率,不能从 preset 名称或 `opus/48000/2` 单独推断实际声道内容。
- Given 分享正在直播或暂停且 Host 选择新的 64/128/256 kbps 音频档位,When 当前 profile mutation 串行执行,Then 服务端以 last-wins 保存并广播最新 desired profile,每个当前 Host、relay 与 SFU audio sender 从 fresh `getParameters()` 派生 `setParameters()` 并立即 readback,过期 completion 不得覆盖新值;以后创建的 sender 使用最新 desired profile。单个端点应用失败时保留媒体与其旧 applied 值、显示可见告警并允许后续更新或重建重试,不得谎称全房已收敛。当前 applied readback 保持 endpoint-local;没有显式回执 wire 就不宣称跨端点原子提交。该操作不改变 Opus、route revision、media-binding generation 或 publication generation,也不创建第二个音频控制环。当前 screen-audio Host 基线是 Chrome/Edge;其他浏览器只有实际 sender readback 成功时才算支持。
-- Given Host 打开分享设置,When 查看推荐档或高级设置,Then 不显示 codec 控件,也不把 codec 写入房间 quality state。Given 新建当前或未来 sender,Then direct、browser relay 与 SFU publication 使用同一固定 VP8 合同;Pause/Resume、换源和直播中质量更新都不携带或改变 codec。
+- Given Host 打开当前 v10 分享设置,When 查看高级设置,Then codec selector 只作为临时诊断输入且默认 VP8。Given 分享已开始,Then selector 保持可见但禁用并说明本轮已锁定,direct、browser relay 与 SFU publication 使用分享开始时的同一 codec;Pause/Resume、换源和直播中质量更新都不改变 codec。最终 codec 决定后,该 selector 与对应 quality-state/wire 字段一起删除,不保留运行时切换。
- Given 浏览器返回屏幕音轨,When 产品展示音频状态或未来连接详情,Then 只能把存在性、浏览器实际返回的 track settings、实际协商 codec/fmtp 和实际流量分别标为捕获、协商或观测事实;字段缺失必须显示为未知,且不得从 Opus 的 `48000/2` RTP 声明推断源采样率或实际 stereo。
- Given Web 或后续 native sender 分享电影/视频音频,When 进行产品验收,Then 必须用独立 A/B/C 证据关联 capture audio track/settings、实际 negotiated codec/fmtp、outbound/inbound 实际码率、loss、jitter、concealment、jitter-buffer 与 A/V sync;P2P、浏览器 relay 与 SFU route switch 保持同一持久 Viewer `MediaStream`/媒体元素和 stereo 协商,不新增独立 audio element 或 Web Audio 时钟边界。native sender 必须通过该音质和同步矩阵,且不得把 audio `maxBitrate` ceiling 当作提质证明。
- Given 分享者同时运行语音软件,When 选择仅分享游戏声音,Then supported Windows 11 native sender 只保留目标游戏及其子进程的渲染音频,观众、通知和其他应用声音不得进入分享;浏览器 system audio 无法满足时必须允许 video-only 或明确告知其可能包含语音/通知,不能用 AEC、降噪或来源标签伪称已隔离。