Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
feat(media): add screen audio quality presets (#165)
AAAb95aaa5834dc
diff --git a/docs/project-memory.md b/docs/project-memory.mdindex f47e8ea5..d6e702a0 100644--- a/docs/project-memory.md+++ b/docs/project-memory.md@@ -31,7 +31,7 @@ Last updated: 2026-08-22- C+B stays edge-local: severe keeps its fallback ladder; relative relay FPS uses fresh parent evidence and peers only. Two confirmed children under one Viewer relay/session/share within 5s pause its eligibility for 30s and peer-only evacuate its children; no score.- Flagship media is UDP; HTTPS/WSS stays TLS/TCP; the old release remains rollback-only.- Treat settings as ceilings and degradation as unclassified. Use correlated Host A+B/Viewer C and one-variable evidence; never force AV1, infer by UA, or create a composite score.-- Screen audio: Web capture requests speech processing off and ideal stereo; peer answers use `stereo=1;maxaveragebitrate=128000`; SFU uses 128 kbps stereo/`forceStereo`, DTX off, RED retained. Proof open; no audio UI; voice and Native stay separate.+- Screen audio: Web capture requests speech processing off and ideal stereo. Share advanced settings offer 64/128/256 kbps sender ceilings, default 128, and lock the choice for the active share across P2P, browser relay, and SFU. Peer answers permit stereo up to 256 kbps; SFU keeps `forceStereo`, DTX off, and RED retained. Proof remains open; voice and Native stay separate.- Presence reports active upstream for topology; assignment alone never proves media. A Web SFU Viewer becomes connected only after session-bound first media; track/route/session loss clears it. Status/details stay neutral until current P2P/SFU/TURN evidence. Names stay socket/localStorage-only; Native remains outside.- Do not add scene detection, dynamic-FPS control, or forced AV1 without negotiation, encode, game, CPU/GPU, and sender evidence.- ADR-0002 grant/public access, the v3 room-password migration, and Web Host display names are deployed. Names/presence remain session-only without account or roster tables.@@ -43,16 +43,16 @@ Last updated: 2026-08-22## Current Implementation- The repository is one npm package using Node.js 24, React, TypeScript, Vite, native WebRTC, `ws`, Zod, Vitest, and separate coturn.-- Production: exact `27ad90ddf9f85d0a88a7d06fd366461622653649`, release `27ad90ddf9f8`, Web wire `screener-v4`.+- Production: exact `083c111437485064a766368944a7938b79e07365`, release `083c11143748`, Web wire `screener-v5`; `27ad90ddf9f8` remains the rollback release.- Web keeps one SFU stream, clears unavailable video, exposes evidence-backed routes/transports and paused preview, and drops signals to a grace-retained offline current-edge target. Routing is automatic; entry/nickname UI is live; Native remains source-only.- Web relay is cap2 with one upstream; child3 rejects and no UA/visibility split exists.- Deployed relay evidence reaches opted-in Host rosters; direct proof stays local-edge-only.-- Four services are active/running at `NRestarts=0`; local/public health are 200. SQLite v3 has five rooms, SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600.+- `screener`, LiveKit, coturn, and nginx are active; `screener` has `NRestarts=0`, local/public health are 200, and the endpoint-cap environment is unset so the parameterized default is two. SQLite v3 has five rooms, SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600.- Production keeps ordinary ICE STUN-only, SFU roots <=2, selected-edge UDP TTL 120, and one pending/answered `peer-selected` attempt per room excluding Host ingress. This rollout ran no browser/media/SFU/TURN/performance canary; earlier exact-`16f6eab` evidence proves active Host ingress only.- Production requires independent `SITE_ACCESS_PASSWORD`: its stateless cookie authorizes creation/Host and code-only Viewer attempts; private grants stay direct, while public/private code entry needs site access alone/plus room password. Env/endpoint/cookie/nginx naming migrated atomically; failures remain neutral; there are no accounts/JWT/session rows. Local `gate:access-privacy` proves fragment isolation, site/grant transport-log absence, and raw room-password SQLite absence; room-password WebSocket/log ingress and live/headful evidence remain open.- Production uses nginx, Node.js 24.19.0, coturn 4.17.2, and LiveKit 1.13.5 on UDP 7882 (TCP fallback off). Ordinary peer ICE receives no TURN; the selected-edge tuple is configured only for the current controller edge, with no credential pre-advertised to ordinary peers. Coturn retains the old authenticated-relay ports. Services are healthy with zero restarts.-- ADR-0005 rejects `PEER_ASSISTED_ROOM_IDS`; `PEER_ASSISTED_MEDIA=true` enables every room and ordinary peers stay STUN-only. Initial or active Host ingress may consume one bound relay-only grant; ready/abort clears it and failure restores peer baseline. Stale room-ID config fails startup. Production uses `screener-v4`; current Web and source-only Native move atomically to `screener-v5` for the bounded cap3 wire. Native does not subscribe to Web presence.-- Defaults are balanced with automatic codec; clarity/fluid and H.264/VP8 remain explicit. Codec is locked during a share. Web SFU uses LiveKit 2.22.0 `q,h`; SFU/UDP and selected-TURN work; BWE, Host A+B and production remain open.+- ADR-0005 rejects `PEER_ASSISTED_ROOM_IDS`; `PEER_ASSISTED_MEDIA=true` enables every room and ordinary peers stay STUN-only. Initial or active Host ingress may consume one bound relay-only grant; ready/abort clears it and failure restores peer baseline. Stale room-ID config fails startup. Production and source-only Native use `screener-v5`; Native does not subscribe to Web presence.+- Defaults are balanced with automatic codec and 128 kbps screen audio; clarity/fluid, H.264/VP8, and 64/128/256 kbps audio remain explicit. Codec and audio quality are locked during a share. Web SFU uses LiveKit 2.22.0 `q,h`; SFU/UDP and selected-TURN work; BWE and Host A+B remain open.- Chrome 151 five-Viewer 720p30 cap2 evidence: Host/relay fanout two; both relay children +80 decoded frames/~1.1 MB; every Viewer decoded; clean stop. Functional only; resource and heterogeneous-network behavior remain open.## Provisional Quality Targetsdiff --git a/docs/research/browser-screen-audio-quality.md b/docs/research/browser-screen-audio-quality.mdindex cb4b4b95..44b145f2 100644--- a/docs/research/browser-screen-audio-quality.md+++ b/docs/research/browser-screen-audio-quality.md@@ -2,11 +2,13 @@Accessed: 2026-08-21-Status: peer and SFU routes already use stereo and a 128 kbps target, but users+Status: peer and SFU routes already use stereo and a 128 kbps default, but usersstill report speech-gated movie/game audio, including on a phone connecteddirectly through the SFU. Current Chromium web `getDisplayMedia()` defaults to-local speech processing unless the request disables it. This slice makes that-source request explicit; target-device audible proof remains open.+local speech processing unless the request disables it. The source request is+explicit, and Share advanced settings now provide bounded 64/128/256 kbps+sender ceilings across P2P, browser relay, and SFU. Target-device audible proof+remains open.## Scope And Decision@@ -15,8 +17,8 @@ browser `RTCPeerConnection`. It does not decide whether the product ultimatelyneeds Windows per-application capture; that remains a separate native-senderrequirement.-The product keeps one screen-media audio mode rather than exposing codec-plumbing as quality controls:+The product keeps one screen-media audio mode and exposes only three bounded+sender ceilings rather than codec plumbing:- request audio with echo cancellation, noise suppression, automatic gain, andvoice isolation disabled, while preferring two capture channels;@@ -26,12 +28,12 @@ plumbing as quality controls:- treat an audio track as optional and warn before publishing when none exists;- preserve returned audio through source changes, picture pause, P2P, relay, andconfigured SFU routes;-- keep a `128000` bit/s sender ceiling, matching Opus stereo/maximum-average-- bitrate receive parameters, and DTX off across Web peer and SFU routes;+- offer 64/128/256 kbps sender ceilings, default 128 kbps, with one 256 kbps+ Opus receive maximum and DTX off across Web peer and SFU routes;- let the browser's existing WebRTC congestion control reduce actual audio andvideo traffic; do not add an application audio adaptation loop;-- expose no channel-count, sample-rate, codec, bitrate, stereo, DTX, RED, or FEC- user control; and+- expose no channel-count, sample-rate, codec, stereo, DTX, RED, FEC, arbitrary+ bitrate slider, or application-owned adaptation control; and- expose local, read-only audio RTP diagnostics without treating negotiatedcodec fields as source-quality facts.@@ -39,15 +41,17 @@ The music hint is metadata, not a codec or quality mode. Chromium accepts andreads it back, but the inspected libwebrtc audio-track interface has no matchingcontent-hint input to the Opus encoder. Screener therefore does not credit thehint with a quality change. RFC 7587 and the pinned LiveKit presets, rather than-an ordinary-PC benchmark, define the 128 kbps ceiling: the RFC places full-band+an ordinary-PC benchmark, define the 128 kbps default: the RFC places full-bandstereo music in a 64--128 kbps sweet spot, and LiveKit 2.22.0 names 128 kbps`musicHighQualityStereo`. Requested, applied, negotiated, and observed statesremain separate.-There is no audio setting or panel rename in this slice. Screen capture has one-reasonable media default, while a future microphone/voice feature would be a-separate track and processing path with its own AEC/noise-suppression/DTX-contract. It must not turn movie or game audio into a voice-processed source.+The advanced panel is named Share advanced settings. Its audio choice is locked+while sharing because peer SDP and SFU publication options are established for+that share; video-only ceiling changes remain live. A future microphone/voice+feature remains a separate track and processing path with its own+AEC/noise-suppression/DTX contract. It must not turn movie or game audio into a+voice-processed source.## Deployed Reports And Echo Boundary@@ -107,7 +111,7 @@ turn optional screen audio into a hard capture gate.| Source processing | Current Chromium accepts EC/NS/AGC/voice-isolation constraints on web display audio | Corresponding `track.getSettings()` fields can confirm values when exposed | Portable support, or that a missing field means false | Request all four off for movie/game audio and verify the target Host settings || Capture channels | Current Chromium accepts `channelCount: { ideal: 2 }`; the Screen Capture specification does not make it portable | `track.getSettings().channelCount` may describe the returned track when exposed | That every source/browser can supply stereo, or that RTP sends stereo | Prefer two without using `exact`; keep negotiated Opus truth separate || Capture sample rate | The Screen Capture specification does not list generic `sampleRate` as applicable to display audio | `track.getSettings().sampleRate` may be present in an implementation | The Opus mode, RTP clock semantics, receiver output rate, or end-to-end fidelity | Observe only in a future diagnostic; absent means unknown |-| RTP send bitrate | `RTCRtpSender.setParameters()` can set `encodings[].maxBitrate` for audio; Opus `maxaveragebitrate` advertises the receiver's maximum | A following `getParameters()` can show the applied sender ceiling; negotiated fmtp shows the receiver maximum; outbound byte deltas show actual traffic | A minimum, audible improvement, or moment-to-moment rate; congestion may keep traffic lower | Pair the 128 kbps sender ceiling with the same Opus receive maximum and retain actual bitrate as the acceptance fact |+| RTP send bitrate | `RTCRtpSender.setParameters()` can set `encodings[].maxBitrate` for audio; Opus `maxaveragebitrate` advertises the receiver's maximum | A following `getParameters()` can show the applied sender ceiling; negotiated fmtp shows the receiver maximum; outbound byte deltas show actual traffic | A minimum, audible improvement, or moment-to-moment rate; congestion may keep traffic lower | Apply the selected 64/128/256 kbps sender ceiling, advertise one 256 kbps receive maximum, and retain actual bitrate as the acceptance fact || Codec | The user agent chooses among negotiated send codecs unless a separately negotiated codec selection is available | `RTCCodecStats.mimeType` and `sdpFmtpLine` identify the codec and negotiated format parameters in use | That Opus was selected before stats exist, or that negotiated preferences describe actual content | Label only observed negotiated data; do not force a codec || Stereo | No stable sender parameter controls Opus stereo; RFC 7587 defines `stereo` as the receiver's one-way preference | Capture settings and negotiated codec/fmtp data can be inspected separately | Capture channel count and `opus/48000/2` do not prove encoded stereo | Use one bounded Opus answer transform on the declared Chrome/Edge baseline; no user control or inferred badge || DTX | The current WebRTC `RTCRtpEncodingParameters` dictionary has no `dtx` member; RFC 7587 defaults absent `usedtx` to `0` | No portable standard sender readback proves DTX operation | A deprecated browser field or SDK option is not a cross-browser contract | Keep peer default-off and set LiveKit `dtx: false`; no user control |@@ -286,14 +290,15 @@ browser congestion control:1. Request display audio with echo cancellation, noise suppression, automaticgain, and voice isolation disabled plus ideal two-channel capture. Keep- `contentHint = "music"` as metadata, one audio track and the existing 128 kbps- sender ceiling. Do not force a sample rate or add Web Audio mixing,+ `contentHint = "music"` as metadata and one audio track. Apply the selected+ 64/128/256 kbps sender ceiling, defaulting missing/legacy state to 128 kbps.+ Do not force a sample rate or add Web Audio mixing,resampling, a second representation or a new rate controller.2. On every Web Viewer answer, including ICE restart/rebuild answers, parse SDPwith direct dependencies on MIT-licensed `sdp-transform` 2.15.0 and itsTypeScript declarations. Select the single non-rejected audio media section,resolve its Opus payload from structured `rtp` entries, and idempotently- upsert `stereo=1` plus `maxaveragebitrate=128000` in that payload's fmtp before both+ upsert `stereo=1` plus `maxaveragebitrate=256000` in that payload's fmtp before both`setLocalDescription()` and signaling the same description. Preserve everyother media section, codec, fmtp key and session attribute. Empty SDP, nounambiguous active audio/Opus payload, multiple active audio sections,@@ -305,12 +310,13 @@ browser congestion control:3. Do not add `sprop-stereo`: RFC 7587 defines it as a sender-likelihood hint,not the receiver preference that permits the remote encoder to send stereo,and offer/answer parameters are orthogonal. Do not add `usedtx=0`; absent- `usedtx` already means off. `maxaveragebitrate=128000` is the receiver maximum- matching Screener's sender ceiling and pinned LiveKit preset, not a minimum;- stock congestion control can still lower actual traffic. Keep the browser's+ `usedtx` already means off. `maxaveragebitrate=256000` is the receiver maximum+ covering all three sender ceilings, not a minimum or current target; stock+ congestion control can still lower actual traffic. Keep the browser'sexisting `useinbandfec` negotiation untouched.-4. For SFU publication use LiveKit 2.22.0- `AudioPresets.musicHighQualityStereo`, `forceStereo: true` and `dtx: false`.+4. For SFU publication map 64 kbps to LiveKit 2.22.0+ `AudioPresets.musicStereo`, 128 kbps to `musicHighQualityStereo`, and 256 kbps+ to an explicit preset; retain `forceStereo: true` and `dtx: false`.Do not override the pinned room default `red: true`. RED and Opus in-band FECare distinct repair mechanisms; retaining one neither proves, replaces nordisables the other, and no FEC switch is exposed or reimplemented.@@ -323,8 +329,9 @@ otherwise change channel behavior. Native/Pion sender routes retain their ownexplicit encoded-track contract and need a focused compatibility check beforeclaiming the same result.-At the fixed ceiling, audio contributes at most 128 kbps RTP payload per active-outbound edge, or 256 kbps for the current two-child endpoint cap, excluding+At the default ceiling, audio contributes at most 128 kbps RTP payload per+active outbound edge, or 256 kbps for the current two-child endpoint cap. The+explicit highest preset doubles those bounds to 256/512 kbps, excludingRTP/SRTP/UDP/IP overhead. A Host SFU publication contributes one such ingress;each root/peer forward still sends its own copy. This is small beside thecurrent 3--8 Mbps video presets, but stereo can use more encoder work and@@ -428,14 +435,14 @@ only one post-SFU connectivity smoke. Correlate capture settings, negotiated codactual outbound/inbound bitrate, loss, jitter, concealment, jitter buffer, andA/V playout timing using a distinguishable stereo fixture plus game/film audio.-## UI And Voice Revisit Gate+## UI And Voice Boundary-Do not rename “高级视频设置” or add an audio control in this slice. One screen-media default is simpler and the browser already adapts actual traffic below-the ceiling. Revisit a single bounded “省流/高保真” choice only if sanitized-production stats establish that 128 kbps audio materially blocks a real target-network while video adaptation cannot preserve the core path. Do not expose-sample rate, channel count, codec, DTX, RED, FEC or an arbitrary bitrate slider.+Share advanced settings offers exactly 64/128/256 kbps and defaults to 128.+The choice is locked for the active share and follows the same room-memory+quality settings through P2P, browser relay, and SFU. It remains a sender+ceiling, not a guaranteed or constant bitrate. Do not expose sample rate,+channel count, codec, DTX, RED, FEC, an arbitrary slider, or a second audio+adaptation loop.If microphone voice enters scope, treat it as a separate source/track with anindependent privacy, AEC, noise-suppression, gain and DTX design. Oopz's publicdiff --git a/docs/status.md b/docs/status.mdindex eaab3b71..0f5f8ffb 100644--- a/docs/status.md+++ b/docs/status.md@@ -4,9 +4,9 @@ Last updated: 2026-08-22## Phase-Production is exact `27ad90ddf9f85d0a88a7d06fd366461622653649` at `https://share.bonfire.icu`, release `27ad90ddf9f8`, wire `screener-v4`. SQLite v3/five rooms keeps SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600. Four services and local/public health are green.+Production is exact `083c111437485064a766368944a7938b79e07365` at `https://share.bonfire.icu`, release `083c11143748`, wire `screener-v5`. SQLite v3/five rooms keeps SHA-256 `aef724ae52c4107be8ec8791e72f8dcaa11b0ec849fb432d022e2cfb9cfe0974`, owner/mode `screener:screener`/0600. `screener`, LiveKit, coturn, and nginx are active; local/public health are green and `screener` has `NRestarts=0`. The previous `27ad90ddf9f8` release remains the rollback target.Ordinary ICE is STUN-only; limits are SFU roots <=2, one `peer-selected` attempt excluding Host ingress, and selected UDP TTL 120. No browser/media/SFU/TURN/performance canary ran; exact-`16f6eab` Host-ingress proof is separate.-Stable SFU, route/transport truth, preview notice, entry/nickname UI and Web relay cap2 are live. Native is source-only. The controlled production A/B uses browser/LiveKit codec defaults; explicit codec controls are source-complete.+Stable SFU, route/transport truth, preview notice, entry/nickname UI, selected-edge lease authority, and corroborated bad-relay demotion are live. `MAX_PEER_RELAY_DOWNSTREAM_EDGES` is unset, so Web endpoints use the parameterized default of two. Native is source-only.## Execution Principle@@ -14,14 +14,14 @@ Parallel flagship work; use minimum relevant checks and rollback proof. Target-d## Current Snapshot-- Capture precedes rooms; source/quality changes and AV pause preserve peers. Defaults are balanced and automatic codec; clarity/fluid plus H.264/VP8 stay explicit, with codec locked during a share. Browser degradation and Host SFU A+B remain open.-- Deployed `screener-v4` admits private fragment grants directly; code-only Viewers need site access, and private rooms additionally need their password. Credentials remain unstored. Web presence fields remain opt-in and Native does not subscribe to them.+- Capture precedes rooms; source/quality changes and AV pause preserve peers. Defaults are balanced, automatic codec, and 128 kbps screen audio. Clarity/fluid plus H.264/VP8 stay explicit. Source adds 64/128/256 kbps audio presets under Share advanced settings; codec and audio quality are locked during a share. Browser degradation, audible route proof, and Host SFU A+B remain open.+- Deployed `screener-v5` admits private fragment grants directly; code-only Viewers need site access, and private rooms additionally need their password. Credentials remain unstored. Web presence fields remain opt-in and Native does not subscribe to them.- Deployed UI has nickname editing, room entry, Viewer roster, duplicate-only ID suffixes, pause notice, and session-bound SFU first-media truth that clears on track/route/session loss. P2P/SFU/TURN labels require evidence. Guarded relay evidence reaches opted-in Web Host rosters without Host-local transport claims or false parent-edge proof.-- Native v4 is source-only (memory rooms, 300s reclaim); it does not subscribe to Web presence, accepts the shared absolute three-child bound, and fails unsupported SFU/selected ingress boundedly. Production still clamps to two.+- Native v5 is source-only (memory rooms, 300s reclaim); it does not subscribe to Web presence, accepts the shared absolute three-child bound, and fails unsupported SFU/selected ingress boundedly. Production uses the default endpoint cap of two.- Production roots/Web relay <=2; Viewer upstream1. Source parameterizes endpoint cap at default2/range1-3 while SFU roots remain <=2; production stays2. One-root healthy-SFU MBB is deployed/media-unverified; source defers one cooldown ready for expiry reproof. Capacity `0 -> 1`, multi-root and browser gates remain open. Room `1` is historical; HTTPS/WSS is TLS/TCP.- After an answer, a generation-bound 15s initial-connect deadline enters ICE restart; success/replacement/disposal cancels it. It is deployed but not mobile-verified.-- C+B is uncalibrated. Production compares relay-child FPS with fresh parent input and tries peers only. Source lets two confirmed children pause one Viewer relay for 30s and peer-only reassign its children; no candidate keeps old edges. Not deployed; admission rescue remains deterministic.-- Source-only `screener-v5` selected-TURN work separates immutable grant revision from current route authority and parameterizes endpoint cap default2/range1-3: unrelated revisions may carry only the same in-budget edge, while topology/session/share/budget loss revokes it before active authority. Browser and production proof remain open.+- C+B is uncalibrated. Production compares relay-child FPS with fresh parent input; two corroborated children can pause one Viewer relay for 30s and trigger peer-only reassignment. No candidate keeps the old edge, and admission rescue remains deterministic.+- Deployed `screener-v5` selected-TURN authority separates immutable grant revision from current route authority. Unrelated revisions may carry only the same in-budget edge, while topology/session/share/advertised-budget loss revokes it before active authority. Browser/media proof remains open.## Verified Evidence@@ -35,6 +35,7 @@ Parallel flagship work; use minimum relevant checks and rollback proof. Target-d- Local gate proves pre-DOM fragment clearing, room-scoped session isolation, no site/grant transport-log hits, and no raw room-password SQLite sentinel; rotate/revoke tests pass. Headless loopback only.- Native wire/session tests enforce at most two authoritative children, no presence-created edge, stale-revision ignore, and one bounded unsupported-route failure per revision.- Production caps pending/answered `peer-selected` at one per room; Host ingress is independent. Focused admission/release/rollback/STUN-only tests pass; earlier Chrome proves active Host-ingress function only.+- Exact `083c111` deployed with the endpoint-cap environment unset, so the parameterized default remains two; local/public health are 200, all four services are active, and `screener` reports zero restarts.- Exact `6ccb516a` passed typecheck/build/hygiene and 32/489; deploy gates preserved artifacts, config/nft/DB, zero shared inodes and four zero-restart services. No browser/media/SFU/TURN/performance canary ran.## Unverified Boundaries@@ -56,7 +57,7 @@ Recovery: ICE restart -> same parent -> alternate peer -> SFU. Source-only manuaNative WGC/MF passed one-Viewer hardware; package download, Viewer2/FIFO and game A/V remain. Use representative target-device or production evidence for performance, not an ordinary-PC synthetic gate.Ordinary peers stay STUN-only; initial ingress, `peer-selected`, and healthy-reselection browser gates remain open.ADR-0004 still needs its resource/quality matrix; the 20-viewer gate precedes a default change. Mobile uses the same capacity and is a compatibility observation.-Screen-audio candidate disables Chromium speech APM and prefers stereo before 128 kbps peer/SFU; verify Host settings and direct routes.+Screen audio defaults to 128 kbps; the source-complete 64/128/256 kbps presets propagate through P2P, browser relay, and SFU and lock for the active share. Verify Host settings, negotiated/observed bitrate, audible quality, and route switches.## Blockers And Decisionsdiff --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 c99f3b7a..e357f051 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"@@ -152,7 +152,7 @@ Zod 在服务边界拒绝未知类型、超长字符串、非法 SDP/candidate| 1080p30 | 1920x1080、30 fps | 5 Mbps/peer || 720p30 | 1280x720、30 fps | 3 Mbps/peer |-浏览器可返回更低设置,界面以 `track.getSettings()` 显示实际捕获结果。Current source 保留有界手动质量控制:视频 track 使用 `contentHint = "motion"`,返回的音频 track 使用 `contentHint = "music"`;二者都是内容提示而不是 codec 或质量档位。三档推荐质量与折叠高级区初始值统一采用 `degradationPreference = "balanced"`,并允许显式选择 clarity-first 或 fluid。高级区将设置限制为 720p/1080p/1440p、15 至 60 整数 FPS、2 至 12 Mbps、三种 degradation preference,以及 `自动 | H.264 | VP8`;codec 直播中锁定并于下一次分享生效。它们只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率或硬编。本期屏幕音频只有一个固定媒体默认,不增加音频 UI。+浏览器可返回更低设置,界面以 `track.getSettings()` 显示实际捕获结果。Current source 保留有界手动质量控制:视频 track 使用 `contentHint = "motion"`,返回的音频 track 使用 `contentHint = "music"`;二者都是内容提示而不是 codec 或质量档位。三档推荐质量与折叠高级区初始值统一采用 `degradationPreference = "balanced"`,并允许显式选择 clarity-first 或 fluid。“分享高级设置”将视频设置限制为 720p/1080p/1440p、15 至 60 整数 FPS、2 至 12 Mbps、三种 degradation preference,以及 `自动 | H.264 | VP8`;同时提供离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling。codec 与音频质量在分享中锁定并于下一次分享生效。它们只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率、声道或硬编。每次 `setParameters()` 都必须从当次 `getParameters()` 派生更新,然后读回 requested/applied `maxBitrate`、`maxFramerate`、`scaleResolutionDownBy` 和 degradation preference。浏览器负责具体降级,实际结果由 stats 观测;拒绝或浏览器改写必须进入可见状态,不能只写 `console.warn`。@@ -172,11 +172,11 @@ Host 本地预览直接绑定现有 capture stream,不创建 viewer、`RTCPeer部署版 `769de201f7cc` 的模糊、游戏低帧、持续 `bandwidth` 提示和 Host 刷新恢复都只作为同一 release 的用户报告。首轮复现必须在相同机器、Chrome/Edge、驱动、游戏场景和单个有线 direct Viewer 上对照该 release 与最新 `main`,并分别执行只重建受影响 `HostPeer`、只替换 capture、完整 Host 重建和预览开/关;任何一次只改变一个变量。若实际 codec/encoder 不变而 BWE/发送恢复,则下调 codec 根因优先级;只有编码成本异常时才进入受控 codec spike。-当前 Web “高级视频设置”不暴露音频质量控件。`track.getSettings()` 中存在的 EC/NS/AGC/voice-isolation、`channelCount` 和 `sampleRate` 只能作为当前捕获观测;缺失字段保持未知,Opus 协商仍是独立事实。每个 Web Host、浏览器 relay 或 selected-edge 的实际音频 sender 在首次绑定和换源后通过标准 `RTCRtpSender.setParameters()` 请求并读回 128 kbps ceiling;这只是上限,浏览器 WebRTC 拥塞控制仍可降低实际流量,不新增应用层音频降级器。RFC 7587 将 20 ms full-band stereo music 的建议区间列为 64--128 kbps,pinned LiveKit 2.22.0 也把 128 kbps 命名为 `musicHighQualityStereo`。Peer answer 同时声明 `stereo=1;maxaveragebitrate=128000`,与 sender ceiling/SFU preset 对齐;普通 PC synthetic 不用于标定参数、听感或性能。+`track.getSettings()` 中存在的 EC/NS/AGC/voice-isolation、`channelCount` 和 `sampleRate` 只能作为当前捕获观测;缺失字段保持未知,Opus 协商仍是独立事实。每个 Web Host、浏览器 relay 或 selected-edge 的实际音频 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 不用于标定参数、听感或性能。-Web peer 的最小 stereo 契约只改 Viewer 生成的 answer。实现把 MIT `sdp-transform` 2.15.0 与 `@types/sdp-transform` 声明为 root direct dependencies,不依赖 LiveKit 的 transitive install,也不用字符串或正则拼接 SDP。Helper 仅在解析出唯一非 rejected audio media、通过结构化 `rtp` entry 找到唯一 Opus payload 时,才在该 payload 的 fmtp 幂等 upsert `stereo=1` 与 `maxaveragebitrate=128000`;随后 `ViewerPeer` 把同一个结果交给 `setLocalDescription()` 和 signaling。首次连接、ICE restart、同 parent rebuild、浏览器 relay child 与 selected-edge TURN 都走该边界;TURN 只改变 ICE transport。空 SDP、无或歧义 Opus、多个有效 audio、重复目标参数、畸形 fmtp、parse/write 异常都按对象 identity 返回浏览器原 answer,保住仍可继续的 mono/video edge,不发送半修改 SDP。RFC 7587 说明这两个值都是可选的单向 receiver parameters;`maxaveragebitrate` 是 maximum 而非最低保证,实际发送仍可随拥塞下降。当前 libwebrtc 把缺省 full-band stereo codec bitrate 配成 64 kbps,而 `RTCRtpSender.maxBitrate=128000` 只限制上界,不能单独把它提高;显式 128 kbps 参数让 peer 与 LiveKit preset 使用同一 codec 配置目标。`sprop-stereo` 只是 sender likelihood hint,`usedtx` 缺省已是 0,本 slice 不增加二者,也不改浏览器协商的 `useinbandfec`。+Web peer 的最小 stereo 契约只改 Viewer 生成的 answer。实现把 MIT `sdp-transform` 2.15.0 与 `@types/sdp-transform` 声明为 root direct dependencies,不依赖 LiveKit 的 transitive install,也不用字符串或正则拼接 SDP。Helper 仅在解析出唯一非 rejected audio media、通过结构化 `rtp` entry 找到唯一 Opus payload 时,才在该 payload 的 fmtp 幂等 upsert `stereo=1` 与 `maxaveragebitrate=256000`;随后 `ViewerPeer` 把同一个结果交给 `setLocalDescription()` 和 signaling。首次连接、ICE restart、同 parent rebuild、浏览器 relay child 与 selected-edge TURN 都走该边界;TURN 只改变 ICE transport。空 SDP、无或歧义 Opus、多个有效 audio、重复目标参数、畸形 fmtp、parse/write 异常都按对象 identity 返回浏览器原 answer,保住仍可继续的 mono/video edge,不发送半修改 SDP。RFC 7587 说明这两个值都是可选的单向 receiver parameters;`maxaveragebitrate` 是 maximum 而非最低保证,实际发送仍可随拥塞下降。当前 libwebrtc 把缺省 full-band stereo codec bitrate 配成 64 kbps,而 `RTCRtpSender.maxBitrate` 只限制上界;本接收上限允许三档,实际发送预算仍由 64/128/256 kbps sender ceiling 与拥塞共同决定。`sprop-stereo` 只是 sender likelihood hint,`usedtx` 缺省已是 0,本 slice 不增加二者,也不改浏览器协商的 `useinbandfec`。-SFU publisher 使用 pinned SDK 的 `AudioPresets.musicHighQualityStereo`、`forceStereo: true` 与 `dtx: false`。LiveKit 2.22.0 先合并 room publish defaults,其中 `red: true`;本实现不传 `red` 覆盖值,保留既有 RED request。RED 与 Opus in-band FEC 是不同修复机制,保留前者不声称实际启用、替代或等价于后者。只改 SFU 会导致 route switch 声道行为分叉,因此 P2P/browser relay 与 SFU 必须同一 slice 落地。Viewer 继续在同一个持久 `MediaStream`/媒体元素中增删 screen video/audio track;不新建 audio element、Web Audio mix/resample graph、第二 audio representation 或独立音频时钟。当前每条 outbound edge 的 audio RTP payload ceiling 为 128 kbps,cap2 节点最多 256 kbps(不含 RTP/SRTP/UDP/IP overhead),相对 3--8 Mbps 视频档位较小;stereo 仍可能增加编码与网络成本,且浏览器 relay 不保证跨 PeerConnection shared encode。未来 microphone voice 若进入范围,另建独立 source/track 与 AEC、降噪、gain、DTX 设计,不能作用于电影/游戏屏幕音频。详细证据与 Oopz 未知边界见 `docs/research/browser-screen-audio-quality.md`。+SFU publisher 将 64 kbps 映射到 `AudioPresets.musicStereo`、128 kbps 映射到 `musicHighQualityStereo`,256 kbps 使用显式 `maxBitrate`;三者都保留 `forceStereo: true` 与 `dtx: false`。LiveKit 2.22.0 先合并 room publish defaults,其中 `red: true`;本实现不传 `red` 覆盖值,保留既有 RED request。RED 与 Opus in-band FEC 是不同修复机制,保留前者不声称实际启用、替代或等价于后者。只改 SFU 会导致 route switch 行为分叉,因此 P2P/browser relay 与 SFU 必须同一 slice 落地。Viewer 继续在同一个持久 `MediaStream`/媒体元素中增删 screen video/audio track;不新建 audio element、Web Audio mix/resample graph、第二 audio representation 或独立音频时钟。默认每条 outbound edge 的 audio RTP payload ceiling 为 128 kbps,显式最高档为 256 kbps;cap2 节点对应最多 256/512 kbps(不含 RTP/SRTP/UDP/IP overhead)。stereo 仍可能增加编码与网络成本,且浏览器 relay 不保证跨 PeerConnection shared encode。未来 microphone voice 若进入范围,另建独立 source/track 与 AEC、降噪、gain、DTX 设计,不能作用于电影/游戏屏幕音频。详细证据与 Oopz 未知边界见 `docs/research/browser-screen-audio-quality.md`。`frameRate` 约束和 sender 的 `maxFramerate` 都是目标或上限;浏览器仍控制实际捕获、重复帧处理、编码和拥塞降级。静态画面可能由浏览器减少实际编码数据,但标准没有保证每个实现以同一种方式节省采集或 GPU 开销。本 PoC 不添加画面差分、定时改约束或自定义动态 FPS 状态机,先用 `framesEncoded`、实际发送码率、`totalEncodeTime`、质量受限原因和主机资源占用测量真实问题。@@ -372,7 +372,7 @@ hop 按[低服务器成本媒体路由](./research/low-server-media-routes.md)6. 可选 selected-edge TURN tuple、revision-bound one-use grant 与 parent/child rebuild 已在 source 和 production 配置闭环;下一功能验收只需一条 forced relay 媒体 smoke,完整网络/资源 benchmark 后置。ordinary STUN-only、SFU/UDP、coturn rollout 仍保持独立边界。7. 在媒体主线阶段验收后,用一个原子 PR 迁移 site access、`screener-v2`、room-scoped Viewer grant 和 SQLite v2;同一部署切换客户端/服务端/环境和数据库备份,随后删除 v1 配置、wire 与测试。用户名/roster 保持独立。8. Windows Native fixed-`HIGH` 保持可选且不改变 Web 默认;移动端保持 Viewer-only 且不单独分配 relay capacity。Viewer-to-TV 只采用已验证的平台本地输出,不改变媒体路由。-9. 屏幕音频在一个原子 Web slice 中声明 `sdp-transform`/types direct dependencies,加入 answer helper 与 `ViewerPeer` wiring,并同步设置 SFU stereo options、focused tests 和 owning docs;不增加音频 UI、Web Audio、第二表示或自定义降级算法。+9. 屏幕音频在一个原子 Web slice 中声明 `sdp-transform`/types direct dependencies,加入 answer helper 与 `ViewerPeer` wiring,并同步设置 SFU stereo options、focused tests 和 owning docs;高级设置只增加 64/128/256 kbps 离散 sender ceiling,不增加 Web Audio、第二表示或自定义降级算法。任何一步只实现当前消费者需要的接口。不得为未来账号、第三种媒体拓扑或原生 sender 预建抽象层。@@ -401,7 +401,7 @@ STUN-only;只有 controller-selected edge 可接收一次短期 grant。该边部署参数 `MAX_PEER_RELAY_DOWNSTREAM_EDGES` 默认 `2`、允许 `1/2/3`,统一约束 Host、Viewer、SFU publication 与 selected-edge overlay;客户端绝对能力为三,服务端按部署值钳制,SFU root 预算仍独立最多二。动态 evidence-driven capacity 仍须独立验收,不按 device/UA 分支,并由持续 sender bitrate、`availableOutgoingBitrate`、区间 encode time、`qualityLimitationReason`、loss/RTT 健康窗与 cooldown 共同限界。H.264、hardware encode 或 shared encode 可降低编码成本或同观感码率,但每个 child 的网络副本仍独立存在。-Peer-assisted 信令只接受一个严格对象:`resolution` 为 `720p | 1080p | 1440p`,`maxFramerate` 为 15 至 60 的整数,`maxBitrate` 为 2,000,000 至 12,000,000 的整数,`degradationPreference` 为 `maintain-resolution | balanced | maintain-framerate`,可选 `videoCodec` 为 `automatic | h264 | vp8`,其余字段和越界值拒绝。服务端用房间内存 Map 保存完整设置,默认 1080p60、8 Mbps、`balanced`、`automatic`,不写 SQLite;停止分享时保留,房间被放弃或过期时删除。只有 peer-assisted host 可更新,鉴权快照和在线广播携带同一设置;本 wire 由 `screener-v5` 隔离旧页面,普通 P2P 严格鉴权结构不变。SFU publisher 复用同一设置。+Peer-assisted 信令只接受一个严格对象:`resolution` 为 `720p | 1080p | 1440p`,`maxFramerate` 为 15 至 60 的整数,`maxBitrate` 为 2,000,000 至 12,000,000 的整数,`degradationPreference` 为 `maintain-resolution | balanced | maintain-framerate`,可选 `videoCodec` 为 `automatic | h264 | vp8`,可选 `screenAudioQuality` 为 `saver | music | very-high`,其余字段和越界值拒绝。服务端用房间内存 Map 保存完整设置,默认 1080p60、8 Mbps、`balanced`、`automatic`、`music`(128 kbps),旧的缺失音频字段也解析为该默认,不写 SQLite;停止分享时保留,房间被放弃或过期时删除。只有 peer-assisted host 可更新,鉴权快照和在线广播携带同一设置;本 wire 使用 `screener-v5`,普通 P2P 严格鉴权结构不变。SFU publisher 复用同一设置。Viewer 在处理 peer-assisted 鉴权快照时先更新 `ViewerRelay` 的 desired settings,再应用拓扑分配;同一个串行队列协调 remote stream、当前 child 更新和以后重建的 child,因此它们读取同一最新目标。每个 `HostPeer` 也把初始 sender 配置、`replaceStream()` 和 `updateProfile()` 放进同一 sender-mutation queue;desired settings 在入队前同步更新,已排队操作执行时读取最新值,使快速连续修改保持 last-wins,而不增加版本号或确认协议。这里同步的是浏览器 sender 的目标上限,不是实际分辨率、帧率、码率或 shared encoding 的性能保证。diff --git a/src/client/media/quality.ts b/src/client/media/quality.tsindex 5e62ff77..dd8b58b4 100644--- a/src/client/media/quality.ts+++ b/src/client/media/quality.ts@@ -4,6 +4,7 @@ import {type QualityProfileId,type QualityResolution,type QualitySettings,+ type ScreenAudioQuality,type VideoCodecPreference,} from "../../shared/protocol";import { displayMediaOptions } from "./audio-capture";@@ -13,6 +14,7 @@ export type {QualityProfileId,QualityResolution,QualitySettings,+ ScreenAudioQuality,VideoCodecPreference,} from "../../shared/protocol";@@ -26,6 +28,7 @@ export const QUALITY_PROFILES = {maxBitrate: 5_000_000,degradationPreference: "balanced",videoCodec: "automatic",+ screenAudioQuality: "music",},"720p30": {resolution: "720p",@@ -33,6 +36,7 @@ export const QUALITY_PROFILES = {maxBitrate: 3_000_000,degradationPreference: "balanced",videoCodec: "automatic",+ screenAudioQuality: "music",},} as const satisfies Record<QualityProfileId, QualitySettings>;@@ -63,6 +67,21 @@ export const VIDEO_CODEC_PREFERENCE_LABELS = {vp8: "VP8",} as const satisfies Record<VideoCodecPreference, string>;+export const SCREEN_AUDIO_QUALITY_LABELS = {+ saver: "64 kbps 省流",+ music: "128 kbps 音乐默认",+ "very-high": "256 kbps 极高音质",+} as const satisfies Record<ScreenAudioQuality, string>;++export const DEFAULT_SCREEN_AUDIO_QUALITY: ScreenAudioQuality = "music";+export const SCREEN_AUDIO_BITRATES = {+ saver: 64_000,+ music: 128_000,+ "very-high": 256_000,+} as const satisfies Record<ScreenAudioQuality, number>;+export const SCREEN_AUDIO_RECEIVE_MAX_BITRATE =+ SCREEN_AUDIO_BITRATES["very-high"];+export interface VideoSenderParameterValues {maxBitrate: number | null;maxFramerate: number | null;@@ -83,7 +102,18 @@ export interface TwoLayerVideoSenderParameterReadback {}export const SCREEN_SHARE_LOW_SCALE = 2;-export const SCREEN_AUDIO_MAX_BITRATE = 128_000;++export function resolveScreenAudioQuality(+ quality: ScreenAudioQuality | undefined,+): ScreenAudioQuality {+ return quality ?? DEFAULT_SCREEN_AUDIO_QUALITY;+}++export function screenAudioBitrate(+ quality: ScreenAudioQuality | undefined,+): number {+ return SCREEN_AUDIO_BITRATES[resolveScreenAudioQuality(quality)];+}export function screenShareLowBitrate(profile: QualityProfile): number {return Math.max(150_000, Math.floor(profile.maxBitrate / 4));@@ -98,7 +128,9 @@ export function qualitySettingsEqual(left.maxFramerate === right.maxFramerate &&left.maxBitrate === right.maxBitrate &&left.degradationPreference === right.degradationPreference &&- (left.videoCodec ?? "automatic") === (right.videoCodec ?? "automatic")+ (left.videoCodec ?? "automatic") === (right.videoCodec ?? "automatic") &&+ resolveScreenAudioQuality(left.screenAudioQuality) ===+ resolveScreenAudioQuality(right.screenAudioQuality));}@@ -292,12 +324,13 @@ export async function configureVideoSender(export async function configureScreenAudioSender(sender: RTCRtpSender,+ quality?: ScreenAudioQuality,): Promise<number | null> {const parameters = sender.getParameters();if (parameters.encodings.length === 0) {parameters.encodings = [{}];}- parameters.encodings[0]!.maxBitrate = SCREEN_AUDIO_MAX_BITRATE;+ parameters.encodings[0]!.maxBitrate = screenAudioBitrate(quality);await sender.setParameters(parameters);return sender.getParameters().encodings[0]?.maxBitrate ?? null;}diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsxindex 3a7bad47..692a9b9c 100644--- a/src/client/pages/HostPage.tsx+++ b/src/client/pages/HostPage.tsx@@ -76,10 +76,13 @@ import {QUALITY_PROFILE_LABELS,QUALITY_RESOLUTIONS,qualitySettingsLabel,+ resolveScreenAudioQuality,+ SCREEN_AUDIO_QUALITY_LABELS,setMediaPaused,type DegradationPreference,type QualityProfileId,type QualitySettings,+ type ScreenAudioQuality,type VideoCodecPreference,VIDEO_CODEC_PREFERENCE_LABELS,} from "../media/quality";@@ -102,6 +105,7 @@ import {reconcileBoundedMediaChildren,} from "../webrtc/media-assignment";import {+ screenAudioQualityLockNotice,shouldPauseLocalPreview,sourceSwitchNotice,videoCodecLockNotice,@@ -632,11 +636,27 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {setAdvancedQuality((current) => ({ ...current, videoCodec }));}+ function changeScreenAudioQuality(+ screenAudioQuality: ScreenAudioQuality,+ ): void {+ if (phase === "starting" || phase === "live") {+ return;+ }+ const next = { ...qualitySettingsRef.current, screenAudioQuality };+ qualitySettingsRef.current = next;+ setQualitySettings(next);+ setAdvancedQuality((current) => ({ ...current, screenAudioQuality }));+ }+async function changeQuality(nextProfile: QualitySettings): Promise<void> {if (phase === "live" &&- (nextProfile.videoCodec ?? "automatic") !==- (qualitySettingsRef.current.videoCodec ?? "automatic")+ ((nextProfile.videoCodec ?? "automatic") !==+ (qualitySettingsRef.current.videoCodec ?? "automatic") ||+ resolveScreenAudioQuality(nextProfile.screenAudioQuality) !==+ resolveScreenAudioQuality(+ qualitySettingsRef.current.screenAudioQuality,+ ))) {return;}@@ -1608,6 +1628,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {: "长期有效": null;const codecLockNotice = videoCodecLockNotice(phase);+ const audioQualityLockNotice = screenAudioQualityLockNotice(phase);return (<div className="app-shell">@@ -1914,6 +1935,9 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {...QUALITY_PROFILES[id],videoCodec:qualitySettingsRef.current.videoCodec ?? "automatic",+ screenAudioQuality: resolveScreenAudioQuality(+ qualitySettingsRef.current.screenAudioQuality,+ ),})}>@@ -1925,7 +1949,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {</fieldset><details className="advanced-quality">- <summary>高级视频设置</summary>+ <summary>分享高级设置</summary><div className="advanced-quality-grid"><label><span>分辨率上限</span>@@ -2066,6 +2090,58 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {</p>)}</fieldset>+ <fieldset+ className="control-group quality-priority"+ aria-describedby={+ audioQualityLockNotice+ ? "screen-audio-quality-lock-notice"+ : undefined+ }+ >+ <legend>音频质量</legend>+ <div className="segmented-control">+ {(+ Object.keys(+ SCREEN_AUDIO_QUALITY_LABELS,+ ) as ScreenAudioQuality[]+ ).map((audioQuality) => (+ <button+ key={audioQuality}+ type="button"+ className={+ resolveScreenAudioQuality(+ advancedQuality.screenAudioQuality,+ ) === audioQuality+ ? "is-selected"+ : undefined+ }+ aria-pressed={+ resolveScreenAudioQuality(+ advancedQuality.screenAudioQuality,+ ) === audioQuality+ }+ disabled={+ phase === "starting" ||+ phase === "live" ||+ changingQuality+ }+ onClick={() =>+ changeScreenAudioQuality(audioQuality)+ }+ >+ {SCREEN_AUDIO_QUALITY_LABELS[audioQuality]}+ </button>+ ))}+ </div>+ {audioQualityLockNotice && (+ <p+ id="screen-audio-quality-lock-notice"+ className="control-note"+ >+ {audioQualityLockNotice}+ </p>+ )}+ </fieldset><buttonclassName="button button-secondary"type="button"@@ -2076,7 +2152,7 @@ export function HostPage({ onAuthorizationRequired }: HostPageProps = {}) {}onClick={() => void changeQuality(advancedQuality)}>- {changingQuality ? "正在应用" : "应用视频设置"}+ {changingQuality ? "正在应用" : "应用分享设置"}</button></div></details>diff --git a/src/client/pages/host-page-notices.ts b/src/client/pages/host-page-notices.tsindex 463f60bb..295dda04 100644--- a/src/client/pages/host-page-notices.ts+++ b/src/client/pages/host-page-notices.ts@@ -39,3 +39,9 @@ export function videoCodecLockNotice(phase: string): string | null {? "本次分享的编码已锁定,停止分享后可修改": null;}++export function screenAudioQualityLockNotice(phase: string): string | null {+ return phase === "starting" || phase === "live"+ ? "本次分享的音频质量已锁定,停止分享后可修改"+ : null;+}diff --git a/src/client/sfu/publisher.ts b/src/client/sfu/publisher.tsindex 867ba67b..b267a75e 100644--- a/src/client/sfu/publisher.ts+++ b/src/client/sfu/publisher.ts@@ -8,10 +8,13 @@ import type {import {configureTwoLayerVideoSender,QUALITY_RESOLUTIONS,+ resolveScreenAudioQuality,SCREEN_SHARE_LOW_SCALE,+ screenAudioBitrate,screenShareLowBitrate,senderParameterWarning,type QualityProfile,+ type ScreenAudioQuality,type VideoSenderParameterReadback,} from "../media/quality";@@ -168,7 +171,7 @@ export class SfuPublisher {room,audioTrack,sdk.Track.Source.ScreenShareAudio,- audioPublishOptions(sdk),+ audioPublishOptions(sdk, profile.screenAudioQuality),);if (!this.owns(room, generation)) {return false;@@ -279,7 +282,7 @@ export class SfuPublisher {room,nextAudioTrack,sdk.Track.Source.ScreenShareAudio,- audioPublishOptions(sdk),+ audioPublishOptions(sdk, profile.screenAudioQuality),);if (!this.owns(room, generation)) {return false;@@ -372,6 +375,12 @@ export class SfuPublisher {if (!video || !previousProfile || !sdk) {throw new Error("SFU publisher has no active video publication");}+ if (+ resolveScreenAudioQuality(profile.screenAudioQuality) !==+ resolveScreenAudioQuality(previousProfile.screenAudioQuality)+ ) {+ return false;+ }try {const videoConfiguration = await configurePublishedVideo(@@ -630,9 +639,19 @@ function videoPublishOptions(};}-function audioPublishOptions(sdk: LiveKit): TrackPublishOptions {+function audioPublishOptions(+ sdk: LiveKit,+ quality: ScreenAudioQuality | undefined,+): TrackPublishOptions {+ const resolvedQuality = resolveScreenAudioQuality(quality);+ const audioPreset =+ resolvedQuality === "saver"+ ? sdk.AudioPresets.musicStereo+ : resolvedQuality === "music"+ ? sdk.AudioPresets.musicHighQualityStereo+ : { maxBitrate: screenAudioBitrate(resolvedQuality) };return {- audioPreset: sdk.AudioPresets.musicHighQualityStereo,+ audioPreset,forceStereo: true,dtx: false,};diff --git a/src/client/webrtc/host-peer.ts b/src/client/webrtc/host-peer.tsindex 132dee6e..94dd546d 100644--- a/src/client/webrtc/host-peer.ts+++ b/src/client/webrtc/host-peer.ts@@ -4,6 +4,7 @@ import type { QualityProfile } from "../media/quality";import {configureScreenAudioSender,configureVideoSender,+ resolveScreenAudioQuality,senderParameterWarning,} from "../media/quality";import {@@ -194,7 +195,11 @@ export class HostPeer {}updateProfile(profile: QualityProfile): Promise<boolean> {- if (this.disposed) {+ if (+ this.disposed ||+ resolveScreenAudioQuality(profile.screenAudioQuality) !==+ resolveScreenAudioQuality(this.desiredProfile.screenAudioQuality)+ ) {return Promise.resolve(false);}this.desiredProfile = profile;@@ -427,7 +432,10 @@ export class HostPeer {this.desiredProfile,);if (audioSender?.track) {- await configureScreenAudioSender(audioSender);+ await configureScreenAudioSender(+ audioSender,+ this.desiredProfile.screenAudioQuality,+ );}if (this.disposed) {return false;diff --git a/src/client/webrtc/screen-audio-sdp.ts b/src/client/webrtc/screen-audio-sdp.tsindex 852c9d61..e6d3a96f 100644--- a/src/client/webrtc/screen-audio-sdp.ts+++ b/src/client/webrtc/screen-audio-sdp.ts@@ -1,10 +1,10 @@import { parse, parsePayloads, write } from "sdp-transform";-import { SCREEN_AUDIO_MAX_BITRATE } from "../media/quality";+import { SCREEN_AUDIO_RECEIVE_MAX_BITRATE } from "../media/quality";const OPUS_RECEIVE_PREFERENCES = {stereo: "1",- maxaveragebitrate: String(SCREEN_AUDIO_MAX_BITRATE),+ maxaveragebitrate: String(SCREEN_AUDIO_RECEIVE_MAX_BITRATE),} as const;const OPUS_RECEIVE_FMTP = Object.entries(OPUS_RECEIVE_PREFERENCES).map(([name, value]) => `${name}=${value}`)diff --git a/src/client/webrtc/viewer-relay.ts b/src/client/webrtc/viewer-relay.tsindex 1cd65e42..6b0e557d 100644--- a/src/client/webrtc/viewer-relay.ts+++ b/src/client/webrtc/viewer-relay.ts@@ -3,7 +3,10 @@ import type {ServerMessage,SignalPayload,} from "../../shared/protocol";-import type { QualityProfile } from "../media/quality";+import {+ resolveScreenAudioQuality,+ type QualityProfile,+} from "../media/quality";import type { PeerSnapshot } from "../types";import { HostPeer } from "./host-peer";import { MAX_VIEWER_MEDIA_CHILDREN } from "./media-assignment";@@ -177,7 +180,12 @@ export class ViewerRelay {}updateProfile(profile: QualityProfile): Promise<boolean> {- if (this.disposed) {+ if (+ this.disposed ||+ (this.stream !== null &&+ resolveScreenAudioQuality(profile.screenAudioQuality) !==+ resolveScreenAudioQuality(this.desiredProfile.screenAudioQuality))+ ) {return Promise.resolve(false);}this.desiredProfile = profile;diff --git a/src/shared/protocol.ts b/src/shared/protocol.tsindex b58fbd97..5aa6a5f0 100644--- a/src/shared/protocol.ts+++ b/src/shared/protocol.ts@@ -177,6 +177,13 @@ export type VideoCodecPreference = z.infer<typeof videoCodecPreferenceSchema>;+export const screenAudioQualitySchema = z.enum([+ "saver",+ "music",+ "very-high",+]);+export type ScreenAudioQuality = z.infer<typeof screenAudioQualitySchema>;+export const qualitySettingsSchema = z.object({resolution: qualityResolutionSchema,@@ -184,6 +191,7 @@ export const qualitySettingsSchema = zmaxBitrate: z.number().int().min(2_000_000).max(12_000_000),degradationPreference: degradationPreferenceSchema,videoCodec: videoCodecPreferenceSchema.optional(),+ screenAudioQuality: screenAudioQualitySchema.optional(),}).strict();export type QualitySettings = z.infer<typeof qualitySettingsSchema>;@@ -193,6 +201,7 @@ export const DEFAULT_QUALITY_SETTINGS = {maxBitrate: 8_000_000,degradationPreference: "balanced",videoCodec: "automatic",+ screenAudioQuality: "music",} as const satisfies QualitySettings;export const DEFAULT_PEER_RELAY_DOWNSTREAM_EDGES = 2;diff --git a/tests/host-page-notice.test.ts b/tests/host-page-notice.test.tsindex fbaa9477..2fc2995a 100644--- a/tests/host-page-notice.test.ts+++ b/tests/host-page-notice.test.ts@@ -1,6 +1,7 @@import { describe, expect, it } from "vitest";import {+ screenAudioQualityLockNotice,shouldPauseLocalPreview,sourceSwitchNotice,videoCodecLockNotice,@@ -59,3 +60,17 @@ describe("videoCodecLockNotice", () => {}});});++describe("screenAudioQualityLockNotice", () => {+ it("explains why audio quality is locked during a share", () => {+ expect(screenAudioQualityLockNotice("starting")).toBe(+ "本次分享的音频质量已锁定,停止分享后可修改",+ );+ expect(screenAudioQualityLockNotice("live")).toBe(+ "本次分享的音频质量已锁定,停止分享后可修改",+ );+ for (const phase of ["idle", "ended", "error"]) {+ expect(screenAudioQualityLockNotice(phase)).toBeNull();+ }+ });+});diff --git a/tests/host-peer-tracks.test.ts b/tests/host-peer-tracks.test.tsindex e9884881..459c6711 100644--- a/tests/host-peer-tracks.test.ts+++ b/tests/host-peer-tracks.test.ts@@ -453,7 +453,15 @@ describe("HostPeer source replacement", () => {it("reserves send-only video and audio senders and replaces both tracks", async () => {const oldVideo = createTrack("video", "old-video");const oldAudio = createTrack("audio", "old-audio");- const peer = createPeer(createStream(oldVideo, oldAudio));+ const peer = createPeer(+ createStream(oldVideo, oldAudio),+ () => undefined,+ { iceServers: [] },+ {+ ...QUALITY_PROFILES["720p30"],+ screenAudioQuality: "very-high",+ },+ );await expect(peer.start()).resolves.toBe(true);const connection = FakePeerConnection.latest!;@@ -474,8 +482,8 @@ describe("HostPeer source replacement", () => {expect(connection.transceiverInputs).toHaveLength(2);expect(connection.senders[0]?.setParameters).toHaveBeenCalledTimes(2);expect(connection.senders[1]?.appliedMaxBitrates).toEqual([- 128_000,- 128_000,+ 256_000,+ 256_000,]);});@@ -540,6 +548,16 @@ describe("HostPeer source replacement", () => {degradationPreference: "balanced",encodings: [{ maxBitrate: 8_000_000, maxFramerate: 60 }],});+ expect(connection.senders[1]?.setParameters).toHaveBeenCalledOnce();++ await expect(+ peer.updateProfile({+ ...QUALITY_PROFILES["1080p60"],+ screenAudioQuality: "very-high",+ }),+ ).resolves.toBe(false);+ expect(connection.senders[0]?.setParameters).toHaveBeenCalledTimes(2);+ expect(connection.senders[1]?.setParameters).toHaveBeenCalledOnce();});it("accepts an answer without reapplying the selected profile", async () => {@@ -1547,4 +1565,47 @@ describe("ViewerRelay downstream ownership", () => {encodings: [{ maxBitrate: 10_500_000, maxFramerate: 45 }],});});++ it("retains the locked audio preset for current and future children", async () => {+ const lockedProfile = {+ ...QUALITY_PROFILES["1080p60"],+ screenAudioQuality: "saver",+ } as const;+ const relay = new ViewerRelay(+ { iceServers: [] },+ lockedProfile,+ { sendSignal: () => true },+ );+ relay.setChildren(["first-audio-child"]);+ relay.setStream(+ createStream(+ createTrack("video", "relay-video"),+ createTrack("audio", "relay-audio"),+ ),+ );+ await vi.waitFor(() =>+ expect(FakePeerConnection.latest?.senders[1]?.appliedMaxBitrates).toEqual([+ 64_000,+ ]),+ );+ const firstConnection = FakePeerConnection.latest!;++ await expect(+ relay.updateProfile({+ ...lockedProfile,+ screenAudioQuality: "very-high",+ }),+ ).resolves.toBe(false);+ expect(firstConnection.senders[1]?.appliedMaxBitrates).toEqual([64_000]);++ relay.setChildren(["second-audio-child"]);+ await vi.waitFor(() =>+ expect(FakePeerConnection.latest).not.toBe(firstConnection),+ );+ await vi.waitFor(() =>+ expect(FakePeerConnection.latest?.senders[1]?.appliedMaxBitrates).toEqual([+ 64_000,+ ]),+ );+ });});diff --git a/tests/protocol.test.ts b/tests/protocol.test.tsindex a5c981c1..24f6dbd7 100644--- a/tests/protocol.test.ts+++ b/tests/protocol.test.ts@@ -36,6 +36,7 @@ const qualitySettings = {const qualitySettingsWithCodec = {...qualitySettings,videoCodec: "h264",+ screenAudioQuality: "music",} as const;const qualityEvidence = {@@ -464,6 +465,18 @@ describe("client signaling protocol", () => {qualitySettings: qualitySettingsWithCodec,}).success,).toBe(true);+ for (const screenAudioQuality of [+ "saver",+ "music",+ "very-high",+ ] as const) {+ expect(+ clientMessageSchema.safeParse({+ type: "set-quality-settings",+ qualitySettings: { ...qualitySettings, screenAudioQuality },+ }).success,+ ).toBe(true);+ }for (const invalid of [{ ...qualitySettings, resolution: "2160p" },{ ...qualitySettings, maxFramerate: 14 },@@ -474,6 +487,8 @@ describe("client signaling protocol", () => {{ ...qualitySettings, maxBitrate: 5_000_000.5 },{ ...qualitySettings, degradationPreference: "automatic" },{ ...qualitySettings, videoCodec: "vp9" },+ { ...qualitySettings, screenAudioQuality: "lossless" },+ { ...qualitySettings, screenAudioQuality: 960_000 },{ ...qualitySettings, codec: "video/VP9" },]) {expect(diff --git a/tests/quality.test.ts b/tests/quality.test.tsindex 3bea0c35..199f04a0 100644--- a/tests/quality.test.ts+++ b/tests/quality.test.ts@@ -9,7 +9,7 @@ import {matchingQualityProfileId,QUALITY_PROFILES,qualitySettingsEqual,- SCREEN_AUDIO_MAX_BITRATE,+ SCREEN_AUDIO_BITRATES,screenShareLowBitrate,senderParameterWarning,setMediaPaused,@@ -100,6 +100,23 @@ describe("realtime quality controls", () => {expect(qualitySettingsEqual(h264, QUALITY_PROFILES["1080p60"])).toBe(false);});+ it("keeps audio selection orthogonal while defaulting old settings to music", () => {+ const saver = {+ ...QUALITY_PROFILES["1080p60"],+ screenAudioQuality: "saver",+ } as const;+ const {+ screenAudioQuality: _screenAudioQuality,+ ...legacySettings+ } = QUALITY_PROFILES["1080p60"];++ expect(matchingQualityProfileId(saver)).toBe("1080p60");+ expect(qualitySettingsEqual(saver, QUALITY_PROFILES["1080p60"])).toBe(false);+ expect(+ qualitySettingsEqual(legacySettings, QUALITY_PROFILES["1080p60"]),+ ).toBe(true);+ });+it("reads back every requested sender control after setParameters", async () => {let applied = { encodings: [] } as unknown as RTCRtpSendParameters;const setParameters = vi.fn(async (parameters: RTCRtpSendParameters) => {@@ -139,7 +156,11 @@ describe("realtime quality controls", () => {expect(setParameters).toHaveBeenCalledOnce();});- it("applies and reads back the screen audio send ceiling", async () => {+ it.each([+ ["saver", 64_000],+ ["music", 128_000],+ ["very-high", 256_000],+ ] as const)("applies and reads back the %s audio ceiling", async (quality, bitrate) => {let applied = { encodings: [] } as unknown as RTCRtpSendParameters;const sender = {getParameters: () => applied,@@ -148,12 +169,23 @@ describe("realtime quality controls", () => {}),} as unknown as RTCRtpSender;- await expect(configureScreenAudioSender(sender)).resolves.toBe(- SCREEN_AUDIO_MAX_BITRATE,+ await expect(configureScreenAudioSender(sender, quality)).resolves.toBe(+ bitrate,);- expect(applied.encodings).toEqual([- { maxBitrate: SCREEN_AUDIO_MAX_BITRATE },- ]);+ expect(applied.encodings).toEqual([{ maxBitrate: bitrate }]);+ expect(SCREEN_AUDIO_BITRATES[quality]).toBe(bitrate);+ });++ it("uses the music ceiling for a legacy setting without an audio preset", async () => {+ let applied = { encodings: [] } as unknown as RTCRtpSendParameters;+ const sender = {+ getParameters: () => applied,+ setParameters: vi.fn(async (parameters: RTCRtpSendParameters) => {+ applied = parameters;+ }),+ } as unknown as RTCRtpSender;++ await expect(configureScreenAudioSender(sender)).resolves.toBe(128_000);});it("reports fields the browser does not retain", async () => {diff --git a/tests/screen-audio-sdp.test.ts b/tests/screen-audio-sdp.test.tsindex 6c247676..116c10a8 100644--- a/tests/screen-audio-sdp.test.ts+++ b/tests/screen-audio-sdp.test.ts@@ -35,7 +35,7 @@ describe("preferScreenAudioStereo", () => {expect(session.media[0]?.fmtp).toContainEqual({payload: 111,config:- "minptime=10;useinbandfec=1;x-stereo=keep;stereo=1;maxaveragebitrate=128000",+ "minptime=10;useinbandfec=1;x-stereo=keep;stereo=1;maxaveragebitrate=256000",});expect(session.media[1]?.fmtp).toEqual([{ payload: 96, config: "packetization-mode=1;profile-level-id=42e01f" },@@ -52,7 +52,7 @@ describe("preferScreenAudioStereo", () => {});expect(parse(result.sdp!).media[0]?.fmtp[0]?.config).toBe(- "stereo=1;x-stereo=0;maxaveragebitrate=128000;x-maxaveragebitrate=keep",+ "stereo=1;x-stereo=0;maxaveragebitrate=256000;x-maxaveragebitrate=keep",);});@@ -64,7 +64,7 @@ describe("preferScreenAudioStereo", () => {expect(parse(result.sdp!).media[0]?.fmtp).toContainEqual({payload: 111,- config: "stereo=1;maxaveragebitrate=128000",+ config: "stereo=1;maxaveragebitrate=256000",});});@@ -82,7 +82,7 @@ describe("preferScreenAudioStereo", () => {expect(audio[0]?.fmtp[0]?.config).toBe("stereo=0");expect(audio[1]?.fmtp[0]?.config).toContain("stereo=1");- expect(audio[1]?.fmtp[0]?.config).toContain("maxaveragebitrate=128000");+ expect(audio[1]?.fmtp[0]?.config).toContain("maxaveragebitrate=256000");});it.each([diff --git a/tests/server-signal.test.ts b/tests/server-signal.test.tsindex 9babd99b..454acd22 100644--- a/tests/server-signal.test.ts+++ b/tests/server-signal.test.ts@@ -33,18 +33,21 @@ const defaultQualitySettings = {maxBitrate: 8_000_000,degradationPreference: "balanced",videoCodec: "automatic",+ screenAudioQuality: "music",} as const;const balancedQualitySettings = {resolution: "1080p",maxFramerate: 30,maxBitrate: 5_000_000,degradationPreference: "balanced",+ screenAudioQuality: "saver",} as const;const lowQualitySettings = {resolution: "720p",maxFramerate: 30,maxBitrate: 3_000_000,degradationPreference: "maintain-resolution",+ screenAudioQuality: "very-high",} as const;let runningServer: ScreenerServer | undefined;diff --git a/tests/sfu-client.test.ts b/tests/sfu-client.test.tsindex 90461270..d7c4092a 100644--- a/tests/sfu-client.test.ts+++ b/tests/sfu-client.test.ts@@ -218,6 +218,7 @@ const livekit = vi.hoisted(() => {};const AudioPresets = {+ musicStereo: { maxBitrate: 64_000 },musicHighQualityStereo: { maxBitrate: 128_000 },} as const;@@ -500,6 +501,33 @@ describe("SfuPublisher", () => {expect(room.disconnect).not.toHaveBeenCalled();});+ it.each([+ ["saver", 64_000],+ ["music", 128_000],+ ["very-high", 256_000],+ ] as const)("maps the %s audio preset to %i bps", async (screenAudioQuality, bitrate) => {+ const publisher = new SfuPublisher();+ const video = track("video", `video-${screenAudioQuality}`);+ const audio = track("audio", `audio-${screenAudioQuality}`);+ await publisher.connect(connection);++ await expect(+ publisher.activate(stream(video, audio), {+ ...qualityProfile,+ screenAudioQuality,+ }),+ ).resolves.toBe(true);++ expect(+ livekit.state.rooms[0]?.localParticipant.publishTrack,+ ).toHaveBeenNthCalledWith(2, audio, {+ source: Track.Source.ScreenShareAudio,+ audioPreset: { maxBitrate: bitrate },+ forceStereo: true,+ dtx: false,+ });+ });+it.each(["h264", "vp8"] as const)("passes an explicit %s preference to the SFU publisher",async (videoCodec) => {@@ -586,6 +614,27 @@ describe("SfuPublisher", () => {expect(publisher.getQualityWarning()).toBeNull();});+ it("rejects an audio preset change while the share is active", async () => {+ const publisher = new SfuPublisher();+ await publisher.connect(connection);+ await publisher.activate(+ stream(track("video", "video-1"), track("audio", "audio-1")),+ { ...qualityProfile, screenAudioQuality: "saver" },+ );+ const room = livekit.state.rooms[0];+ const videoPublication = room.localParticipant.publications[0];++ await expect(+ publisher.updateProfile({+ ...qualityProfile,+ screenAudioQuality: "very-high",+ }),+ ).resolves.toBe(false);++ expect(videoPublication.track.sender.setParameters).toHaveBeenCalledOnce();+ expect(room.localParticipant.publishTrack).toHaveBeenCalledTimes(2);+ });+it("retains the active profile for LiveKit track restart and republish", async () => {const publisher = new SfuPublisher();await publisher.connect(connection);@@ -905,7 +954,10 @@ describe("SfuPublisher", () => {const publisher = new SfuPublisher();const audio = track("audio", "audio-2");await publisher.connect(connection);- await publisher.activate(stream(track("video", "video-1")), qualityProfile);+ await publisher.activate(stream(track("video", "video-1")), {+ ...qualityProfile,+ screenAudioQuality: "very-high",+ });const room = livekit.state.rooms[0];await expect(@@ -914,7 +966,7 @@ describe("SfuPublisher", () => {expect(room.localParticipant.publishTrack).toHaveBeenNthCalledWith(2, audio, {source: Track.Source.ScreenShareAudio,- audioPreset: { maxBitrate: 128_000 },+ audioPreset: { maxBitrate: 256_000 },forceStereo: true,dtx: false,});diff --git a/tests/viewer-peer-generation.test.ts b/tests/viewer-peer-generation.test.tsindex 4b0c21ad..e3d4001b 100644--- a/tests/viewer-peer-generation.test.ts+++ b/tests/viewer-peer-generation.test.ts@@ -224,7 +224,7 @@ describe("ViewerPeer connection generations", () => {expect(description).toEqual(expect.objectContaining({type: "answer",sdp: expect.stringContaining(- "a=fmtp:111 minptime=10;useinbandfec=1;stereo=1;maxaveragebitrate=128000",+ "a=fmtp:111 minptime=10;useinbandfec=1;stereo=1;maxaveragebitrate=256000",),}));expect(answers[index]?.description.sdp).toBe(description.sdp);