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: schedule accepted implementation waves (#198)

AAA550308b406e7
diff --git a/docs/adr/0006-fixed-high-native-sender-canary.md b/docs/adr/0006-fixed-high-native-sender-canary.md
index 702c9d8d..6b0a35d3 100644
--- a/docs/adr/0006-fixed-high-native-sender-canary.md
+++ b/docs/adr/0006-fixed-high-native-sender-canary.md
@@ -180,8 +180,8 @@ failed stage while synchronously retaining a bounded final-negative snapshot:
the viewer keeps its existing waiting state, then close viewer 1 and prove
FIFO promotion plus decoding/rendering.
6. Keep this candidate STUN-only. Ordinary Native ICE never receives TURN
- candidates; a future selected-edge attempt requires its own generation-bound
- gate after SFU/UDP rather than widening or blocking the direct-path canary.
+ candidates; any selected-edge or Host-SFU TURN attempt requires its own
+ generation-bound gate and does not widen or block the direct-path canary.
A commit-bound, short-lived evaluation artifact may package the current source
to run these stages without a development toolchain. That artifact is not an
diff --git a/docs/project-memory.md b/docs/project-memory.md
index 0bd8d993..abb066b9 100644
--- a/docs/project-memory.md
+++ b/docs/project-memory.md
@@ -11,7 +11,9 @@ Last updated: 2026-08-22
- The stable routing invariants are one authoritative upstream per Viewer, an acyclic active graph, exact room/session/share/revision/generation authorization, media-proven make-before-break, and bounded success or failure.
- The accepted route model is one room controller with allocate/distribute, child reparent, and relay abdicate/drain operations. One Host publication may serve all SFU-fed Viewers; an SFU-fed Viewer may relay only with independent outbound proof; selected TURN changes an authorized edge transport and is not a topology node. A confirmed bad edge reparents only its child. A relay parent's own ingress failure first enters suspect/cordon and attempts local repair; only failed repair, independent downstream evidence, or explicit sender/resource failure drains its children. Host source failures use publication repair and child migration. Endpoint capacity, temporary overlap, SFU/TURN admission, exact fallback, media binding generations, and rollback are one bounded transaction model.
- Ordinary peer ICE is STUN-only. Credentials, room secrets, candidate details, and diagnostic data remain private and narrowly scoped.
-- Screen audio offers 64/128/256 kbps sender ceilings, defaults to 128, and locks the choice during a share. These are configuration ceilings, not fidelity claims.
+- Screen audio offers live-switchable 64/128/256 kbps sender ceilings and defaults to 128. The existing 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.
+- Video codec selection remains `automatic | H.264 | VP8`. The accepted first switching boundary is a generation-fenced renegotiation/republish transaction while sharing is explicitly paused; unpaused hot switching is later reuse of that transaction, not an independent mechanism.
+- A source-checkout LAN one-command launcher is accepted as a Web development/deployment convenience. It reuses the current Node/config/access/storage contract and does not claim to be a packaged client, TLS provisioner, NAT traversal tool, or public deployment service.
- Current UI, presence, route labels, and diagnostics describe observed state only; they do not create route authority.
## Current Source And Production
@@ -26,7 +28,7 @@ Last updated: 2026-08-22
## Current Priority
1. Keep this truth set and [the TODO ledger](./todo.md) concise and internally consistent.
-2. Rebuild only approved runtime changes from canonical `main@7426c3a`, validate cap `1/2/3`, quality ownership, route recovery, and bounded resources, independently review, then deploy with rollback evidence.
+2. Rebuild the accepted route runtime from the latest canonical `main`, while independently delivering the live audio-ceiling mutation and fresh-main LAN launcher. Follow with paused codec switching, evidence-led H.264 repair, release validation, deployment, and rollback evidence.
## Working Rules
diff --git a/docs/research/advanced-peer-distribution.md b/docs/research/advanced-peer-distribution.md
index e6031000..6a31d649 100644
--- a/docs/research/advanced-peer-distribution.md
+++ b/docs/research/advanced-peer-distribution.md
@@ -40,7 +40,7 @@ overhead. Protocol headers, retransmission, and TURN overhead are additional.
| Current full-stream browser chains | at most `2B` | zero except TURN edges | host up to two encoders; every relay encodes again |
| Native full-stream RTP relay | at most `2B` | zero except TURN edges | relay zero encode; native host can share one encode |
| Two encoded-object stripe trees | about `(1+r)B` | zero except TURN edges | host one encode; relay zero encode |
-| SFU virtual parent to bounded roots | measured `B_pub` | root-only; see low-server model | one publication may carry at most two active representations; physical encoder count remains measured evidence |
+| Host publication with bounded SFU subscriptions | measured `B_pub` | per-subscriber egress; see low-server model | one publication may carry at most two active representations; physical encoder count remains measured evidence |
| Full central SFU/MoQ fanout | about `B` | ingress `B`, egress `N*B` | comparison class, not the accepted fallback shape |
Useful last-hop traffic remains approximately `N*B`; these routes only decide
@@ -351,13 +351,17 @@ mismatches before a full reconnect. Jitsi Videobridge similarly defaults to a
reference boundaries, not universal prescriptions. Screener's separately owned
15-second initial deadline remains a candidate pending mobile-network evidence.
-The accepted Screener order is therefore: soft visible wait while initial ICE
-is still making progress; one ICE restart on hard failure; one same-parent PC
-rebuild; one different eligible peer parent; then SFU only after peer exhaustion.
-Each success cancels the remaining stages. Every completion is guarded by the
-current session, route revision, assignment/connection generation, and cooldown.
-Connected-but-bad media is a separate correlated-quality trigger and must not be
-treated as a connection retry.
+The peer-local repair phase is bounded: show progress while initial ICE still
+advances, attempt one ICE restart on hard failure, and rebuild the same logical
+edge at most once under current transport authority. If that edge remains
+unusable, emit one exact failed-edge event to the ADR-0005 controller. The
+controller may reparent the child, authorize selected TURN for an exact edge, or
+choose a Host-publication SFU ingress under current capacity and server
+admission; these are not a fixed global retry ladder. Each success cancels the
+remaining work. Every completion is guarded by the current session, route
+revision, assignment/connection generation, and cooldown. Connected-but-bad
+media is a separate correlated-quality trigger and must not be treated as a
+connection retry.
The first room-1 production trace on 2026-08-20 observed two short Host
participants while two roots remained for roughly 4.6 seconds; all ended with
@@ -372,22 +376,24 @@ addresses out of wire and logs.
## Automatic Route Controller Boundary
-The accepted product order is:
-
-`direct/peer UDP -> SFU roots -> optional exceptional-edge TURN -> wait/fail`
+The accepted controller preserves healthy peer edges and chooses transport per
+logical edge: direct/STUN first, then exact selected TURN when authorized. A
+server-fed ingress uses the room's single Host publication plus exact SFU
+subscriptions; it is not a fixed rung inserted between every peer edge and TURN.
+Every attempt ends in bounded success, wait, or failure.
Native full-stream relay and striped-object routes remain the bounded candidates
above; passing their own gates may change capability, but does not insert them
-into the current product ladder.
-
-The enabled SFU is normally a virtual parent for at most `R=2` roots, which
-retain bounded peer descendants. A viewer that cannot attach behind any healthy
-root may be separately admitted only under the explicit `E`/central-egress cap;
-this is an exceptional compatibility budget, not unbounded whole-room fanout.
-The SFU/UDP and optional selected-edge TURN transport accounting lives in
-[Low-Server-Cost Media Routes](./low-server-media-routes.md). ADR-0005's deployed
-controller handles failure and bounded admission; the current source also has
-the one-root healthy-reselection slice described below. None changes the sticky
+into the current route model.
+
+The SFU uses one authoritative Host publication and exact per-Viewer
+subscriptions. SFU-fed Viewers may retain bounded peer descendants when their
+outbound relay eligibility is independently proven. Server ingress/egress and
+TURN allocations use deployment-wide admission rather than a fixed root count
+or room-wide lease. The SFU/UDP and optional selected-edge TURN accounting lives in
+[Low-Server-Cost Media Routes](./low-server-media-routes.md). ADR-0005 owns the
+accepted target; the current source still contains legacy controller slices and
+the one-root healthy-reselection behavior described below. None changes the sticky
local reparenting candidate above.
The controller must be automatic and invisible. It uses explicit capability
@@ -406,19 +412,16 @@ the same two-window gate when a refreshed signaling session receives an
authoritative sticky SFU assignment. This avoids immediately reversing an
ordinary peer-to-SFU fallback, whose initial authenticated assignment was peer.
-The overlap edge is physical: an active Host SFU publication consumes one of
-the Host's two downstream media edges while the provisional peer offer consumes
-the other. A browser parent remains limited to one downstream edge during this
-probe even if its normal advertised relay capacity is two. Failed or stale
-probes restore the prior controller revision without writing ordinary
+The overlap edge is physical: an active Host SFU publication consumes one steady
+sender slot, and a media-producing provisional peer candidate consumes another.
+Every non-server parent uses deployment capacity `C in {1,2,3}` without a
+Browser tier. A free steady slot permits ordinary make-before-break; otherwise a
+single fenced `TransitionOverlapSlot` may raise the physical count only to
+`min(C + 1, 3)`. A full `C=3` endpoint must wait, use a bounded-gap transition,
+or fail before creating a fourth copy. Failed or stale probes restore the prior
+controller revision and release their reservation without writing ordinary
failed-parent state.
-Use make-before-break when a downstream slot is free. With all two slots in
-use, strict fanout means break-before-make; zero interruption, no standby, and a
-hard two-edge limit cannot all be guaranteed simultaneously. Sub-second recovery
-also requires a media/data heartbeat near 100-200 ms rather than the current
-30-second control heartbeat.
-
## Sources And License Boundary
Sources checked on 2026-08-20 and 2026-08-21:
diff --git a/docs/research/browser-screen-audio-quality.md b/docs/research/browser-screen-audio-quality.md
index 34ff829d..e7c0bb8e 100644
--- a/docs/research/browser-screen-audio-quality.md
+++ b/docs/research/browser-screen-audio-quality.md
@@ -46,10 +46,18 @@ stereo music in a 64--128 kbps sweet spot, and LiveKit 2.22.0 names 128 kbps
`musicHighQualityStereo`. Requested, applied, negotiated, and observed states
remain separate.
-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
+The advanced panel is named Share advanced settings. The 64/128/256 choice is
+a sender `maxBitrate` ceiling on the existing Opus path, so it can change during
+an active share through serialized `getParameters()`/`setParameters()` updates
+and readback; it does not require audio codec renegotiation. The existing wire
+distributes a last-wins desired profile; each endpoint applies it locally, keeps
+media and the old applied ceiling on failure, and does not claim room-wide
+convergence without a remote applied acknowledgement. On the declared
+Chrome/Edge screen-audio Host baseline, pinned LiveKit 2.22.0 can update the
+existing audio sender without republish. Firefox's initial publish path may also
+write the preset into Opus fmtp, so a sender-only increase is not claimed there
+until real readback and receive evidence pass. 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.
@@ -445,16 +453,18 @@ candidate on current Windows 11 with game parent and child audio, an independent
voice process, notifications, no render stream, and process restart. Windows 10
records the explicit unsupported/unresolved result rather than a fake fallback.
Direct is the primary route; one browser-relay and one
-SFU-root audio check cover route preservation, while selected-edge TURN needs
-only one post-SFU connectivity smoke. Correlate capture settings, negotiated codec/derived fmtp,
+SFU-subscription audio check cover route preservation. Test exact selected-edge
+TURN and Host-SFU TURN transport as separate authorized connectivity gates.
+Correlate capture settings, negotiated codec/derived fmtp,
actual outbound/inbound bitrate, loss, jitter, concealment, jitter buffer, and
A/V playout timing using a distinguishable stereo fixture plus game/film audio.
## UI And Voice Boundary
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
+The choice can change during the active share. P2P, browser relay, and SFU
+senders read the latest desired profile and keep endpoint-local applied
+readback rather than claiming one room-wide applied commit. 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.
diff --git a/docs/research/built-in-peer-ice-turn.md b/docs/research/built-in-peer-ice-turn.md
index e8cc7f2d..3c53d97e 100644
--- a/docs/research/built-in-peer-ice-turn.md
+++ b/docs/research/built-in-peer-ice-turn.md
@@ -11,17 +11,13 @@ transport design is owned by [ADR-0005](../adr/0005-automatic-hybrid-media-routi
## Decision
Do not deploy or continue the built-in participant-wide candidate. Ordinary
-peer connections remain STUN-only. Exact release `9461e20` implements this
-ladder:
+peer connections remain STUN-only. Exact release `9461e20` used its dated
+SFU-then-selected-TURN recovery slice; current route authority is ADR-0005.
-```text
-direct/peer UDP -> SFU/UDP virtual parent -> selected-edge TURN -> failure
-```
-
-TURN remains a compatibility transport, not a topology. Only the existing media
-controller may select one exceptional edge after direct/peer UDP and SFU/UDP
-have failed. No room, participant, or ordinary peer connection receives TURN
-candidates by default.
+TURN remains a compatibility transport, not a topology. The controller may
+authorize it only for an exact logical edge transport or the single Host-SFU
+publication path. No room, participant, or ordinary peer connection receives
+TURN candidates by default.
This supersedes this document's former recommendation to place STUN plus TURN on
every capable exact-room Web peer connection. Git history retains that analysis;
@@ -72,8 +68,8 @@ normally preferred. That does not make participant-wide TURN free:
- one participant credential can be reused by its holder until expiry;
- `setConfiguration()` affects future gathering and does not itself move an
existing connection, so refresh/recovery still needs lifecycle ownership; and
-- placing TURN on the initial peer PC allows it before the bounded SFU/UDP root,
- contrary to the accepted cost and topology order.
+- placing TURN on every initial peer PC bypasses exact edge selection and spends
+ relay resources before the controller has observed a failed direct transport.
The candidate was smaller in code because it delegated selection to standard
ICE, but it widened credential scope and idle server cost. Its failed direct
@@ -82,12 +78,13 @@ acceptance supplied no compensating runtime evidence.
## Selected-Edge Boundary
The deployed selected-edge replacement was designed as one coherent
-controller-owned change with a current consumer. The list below records that
-source boundary; fixed counts and ordering remain held:
+controller-owned change with a current consumer. ADR-0005 now owns path
+selection and resource accounting; the transport boundary retained here is:
- a complete default-off deployment tuple with an independent secret, one
explicit TURN/UDP URI, bounded TTL, quota, bandwidth, and relay-port limits;
-- issuance only after the current edge exhausts direct/peer UDP and SFU/UDP;
+- issuance only after the exact logical edge's direct/STUN transport fails and
+ the controller selects TURN; SFU subscription is a separate ingress choice;
- one in-memory negotiating attempt bound to room/share generation, viewer and parent
sessions, route revision, the replaced connection, and a server-generated new
connection identity;
@@ -120,14 +117,15 @@ exact-room peer assistance and SFU configuration. `HostPeer`, relay parents, the
Viewer child, and `HybridMediaRouter` share one generation contract; a config-only
or issuer-only partial deployment remains forbidden.
-## Acceptance Boundary
+## Retained Acceptance Boundary
-Before production enablement, one isolated canary must prove, in order:
+Current acceptance must independently prove:
1. ordinary direct/peer PCs contain no TURN candidates;
-2. a real SFU/UDP root reaches a decoded/rendered frame under the existing caps;
-3. after that edge's SFU/UDP failure, exactly one authorized parent/child pair
- rebuilds and selects relay;
+2. one exact authorized parent/child edge can rebuild, select relay, and reach a
+ decoded/rendered frame after its direct transport fails;
+3. Host-SFU publication ingress can independently select TURN when authorized,
+ without granting TURN to unrelated peer edges;
4. stale/replayed/wrong-session/wrong-revision/wrong-connection grants fail;
5. success stops further escalation, while expiry, coturn failure, disconnect,
and all-UDP-blocked cases terminate within the bounded window;
diff --git a/docs/research/low-server-media-routes.md b/docs/research/low-server-media-routes.md
index a90f010d..54b33468 100644
--- a/docs/research/low-server-media-routes.md
+++ b/docs/research/low-server-media-routes.md
@@ -110,11 +110,12 @@ physical hops, so NIC, service, and billing counters must never be folded.
If `E>0`, SFU root/exception egress is
`sum(B_i) + sum(B_exc,j)` and central SFU traffic is
`B_pub + sum(B_i) + sum(B_exc,j)`. Peer descendant upload remains
-`sum(B_edge)`. Any separately TURN-relayed LiveKit root/exception leg or
+`sum(B_edge)`. Any separately TURN-relayed LiveKit subscription or
controller-selected peer edge adds TURN ingress and egress equal to that leg's
-measured bitrate. The separately capped
-exceptions are therefore never hidden inside the normal `R<=2` root budget or
-the equal-representation formulas.
+measured bitrate. Server-fed subscriptions are never hidden inside endpoint
+child capacity or the equal-representation formulas. Their ingress, egress and
+TURN allocations are admitted explicitly; `R` is a measured scenario variable,
+not a fixed product root limit.
RTP/RTCP/SRTP, DTLS, ICE/TURN and IP headers, retransmission, FEC, and redundant
paths only add traffic. W3C candidate-pair byte counters exclude some transport
@@ -300,7 +301,7 @@ hundreds of sockets and probes.
discovery from the same application-controlled UDP socket. Browser
WebTransport is a client connection to a server, not a raw UDP socket or an
inbound peer listener. Native TCP/QUIC DCUtR results therefore do not reopen
- Screener's accepted UDP-only browser media ladder.
+ Screener's accepted browser media transport boundary.
- `iceCandidatePoolSize` only pre-gathers implementation-managed candidates for
future ICE use. It does not expose ports, create birthday probes, or repair an
endpoint-dependent mapping. Repeated refreshes and a large STUN list likewise
@@ -480,9 +481,10 @@ One bounded exact-room gate owns rollout evidence:
8 and 12 Mbps with one and two roots. Record CPU seconds/GiB, RX/TX bytes,
packets/s, RSS, host upload, p95/p99 forwarding latency, loss/recovery, and
final decoded quality.
-2. Cover representative consumer networks with STUN-only direct/peer first,
- then SFU/UDP. Only after both gates pass, force one controller-selected edge
- through TURN. All ordinary peer connections must remain STUN-only.
+2. Cover representative consumer networks with independent STUN-only
+ direct/peer, SFU/UDP subscription, exact selected-edge TURN, and Host-SFU TURN
+ gates. The test order does not define the controller's per-edge route choice.
+ All ordinary peer connections must remain STUN-only.
3. Measure allocation count/relay ports/RSS/CPU/latency for one and two selected
attempts, plus relay RX/TX/loss/latency. There is no participant-count idle
allocation target because ordinary peer PCs do not receive TURN candidates.
diff --git a/docs/research/peer-assisted-media.md b/docs/research/peer-assisted-media.md
index 48ee94ef..00c6f073 100644
--- a/docs/research/peer-assisted-media.md
+++ b/docs/research/peer-assisted-media.md
@@ -15,26 +15,25 @@ and [project memory](../project-memory.md).
Peer-assisted forwarding can reduce broadcaster fanout without making an SFU
carry every viewer's traffic. The release measurements below are historical
-evidence rather than current capacity policy. The smallest tested path uses only
-standard WebRTC media:
-
-1. the browser host sends its screen stream to at most two first-level viewers;
-2. each ordinary Browser Viewer may add the received remote `MediaStreamTrack`
- values to at most one downstream `RTCPeerConnection`; and
-3. the signaling server assigns one active upstream per viewer in a bounded,
- deterministic breadth-first DAG.
+evidence rather than current capacity policy. The accepted path uses standard
+WebRTC media, one active upstream per Viewer, a bounded acyclic peer graph, and
+one uniform non-server outbound capacity `C` configured as `1`, `2`, or `3`.
+Host publication and peer children consume physical sender slots under
+ADR-0005; SFU/TURN server resources use separate admission.
This path reuses WebRTC capture, codec negotiation, RTP, NACK/PLI/RTX, congestion
-control, jitter buffering, ICE, STUN, DTLS-SRTP, and browser rendering. A later
-controller-selected exceptional edge may also use TURN. Its
+control, jitter buffering, ICE, STUN, DTLS-SRTP, and browser rendering. An
+exact controller-authorized logical edge may also use selected TURN. Its
cost is unavoidable in ordinary browsers: every relay decodes and re-encodes
the screen stream. The first spike measures whether that cost is acceptable; it
does not hide it or claim shared encoding.
-The accepted flagship preference is `direct/peer UDP -> SFU-root fallback ->
-optional exceptional-edge TURN -> bounded failure`. Direct P2P remains the
-simplest path for one or two viewers. The experiment assigns the third and later
-viewers to peers automatically. ADR-0005 makes SFU capacity part of the flagship
+The accepted controller preserves healthy direct/peer UDP edges. Exact selected
+TURN may replace an authorized logical edge transport; one Host publication and
+per-Viewer SFU subscriptions provide server-fed ingress when selected by the
+same bounded controller. Direct P2P remains the
+simplest path while a healthy endpoint sender slot is available; later Viewers
+may be assigned to peers automatically. ADR-0005 makes SFU capacity part of the flagship
target while retaining peer descendants. The first production rollout used a
room-`1` exact smoke; participant entry was observed, but retained SFU media
remained unverified. Production later removed that room boundary.
@@ -220,9 +219,9 @@ experiment rather than something hidden by a scheduler. Ordinary Web clients
use the same capacity without UA or visibility classification; mobile devices
remain non-blocking compatibility observations.
-Per-edge ICE remains independent. Ordinary peer edges are STUN-only; after
-direct/peer UDP and SFU/UDP fail, a controller-selected exceptional edge may use
-authenticated TURN. Peer assistance therefore reduces normal server media
+Per-edge ICE remains independent. Ordinary peer edges are STUN-only; the
+controller may select authenticated TURN for an exact logical edge transport or
+the single Host-SFU ingress under the accepted route model. Peer assistance therefore reduces normal server media
traffic but cannot promise zero server traffic in restrictive networks.
## Implemented Bounded Quality Coordination
diff --git a/docs/research/realtime-quality-adaptation.md b/docs/research/realtime-quality-adaptation.md
index 7d820462..491f313c 100644
--- a/docs/research/realtime-quality-adaptation.md
+++ b/docs/research/realtime-quality-adaptation.md
@@ -195,6 +195,20 @@ browser default unchanged. LiveKit likewise keeps its default codec for
`automatic`, overrides it only for an explicit selection, and retains
`backupCodec=false`; there is no parallel backup-codec publication.
+Changing `RTCRtpTransceiver.setCodecPreferences()` affects later negotiation; it
+does not itself switch an established sender, and `replaceTrack()` only replaces
+a same-kind source. Mature WebRTC code such as Jitsi follows a codec preference
+change with renegotiation, while pinned LiveKit changes publication codec through
+its publish/republish lifecycle. Screener therefore starts with a paused-share
+transaction: fence the request by codec/media generation, serialize it with
+route mutation, renegotiate the frozen still-current peer/relay targets, and
+republish the SFU generation when present. A zero-target share only saves the
+future preference. Because paused tracks cannot prove decoded progress, proof
+occurs on resume; failure pauses again and runs a bounded old-preference
+rollback. Passing an empty codec list restores default browser preferences.
+This is a deliberate paused bounded-gap path. Unpaused make-before-break is a
+later extension rather than a second codec mechanism.
+
H.264 remains an explicit option because mature cross-device hardware
encode/decode paths may avoid an observed VP8 software-path cost. A controlled
Web comparison also found that forcing H.264 could lower downstream FPS with the
@@ -206,13 +220,20 @@ does not prove shared encode: separate browser PeerConnections may construct
separate encoders, and the SFU still publishes only the configured `q,h`
representations.
-The retained follow-up is one target-device H.264/VP8 comparison using these
-local diagnostics, not a new benchmark framework: actual codec/profile,
-encoder implementation, power efficiency, configured/source/send/receive FPS,
-interval encoded frames/encode time, and limitation reason. Missing
-implementation or power-efficiency fields remain unknown. No H.264 root cause
-or policy change is accepted until the controlled sample distinguishes capture
-starvation, software fallback, hardware queue/driver pressure, and congestion.
+The retained diagnostic keeps lifecycle and codec experiments orthogonal.
+Lifecycle runs fix `automatic`; each independently recreated affected state runs
+exactly one of observe, preview cycle, Host-peer rebuild, capture replacement,
+or Host reload. Codec A/B uses fresh Host/share/PeerConnection sessions for
+automatic, H.264, and VP8 and rejects an actual-codec mismatch. Quality claims
+require a headed run with the same real game, browser/driver, capture surface,
+and one wired direct Viewer. Capture A, sender B, and Viewer C samples must share
+the current generation and overlapping windows; identity polling must not
+advance their accumulators. Record actual codec/profile, configured/source/send/
+receive FPS, interval encoded frames/encode time, limitation reason, game FPS,
+and process-scoped GPU evidence. Missing implementation or power-efficiency
+fields remain unknown. No H.264 root cause or policy change is accepted until
+the controlled sample distinguishes capture starvation, software fallback,
+hardware queue/driver pressure, and congestion.
Open-source distribution is not itself a patent-license exemption. This Web
change only requests a codec already implemented by the browser/LiveKit path and
@@ -663,10 +684,12 @@ resolution, frame rate, or bitrate.
- `maxBitrate` and `maxFramerate` are ceilings. They are neither minimums nor
target guarantees, and the project does not use SDP bitrate hacks.
- The folded “advanced video” panel accepts only 720p/1080p/1440p, integer
- 15-60 fps, 2-12 Mbps, the three preferences, and Automatic/H.264/VP8. Codec
- selection is locked during a share and applies to the next one. The panel is
- now Share advanced settings and also offers 64/128/256 kbps audio sender
- ceilings, default 128, locked during the active share. Display capture does
+ 15-60 fps, 2-12 Mbps, the three preferences, and Automatic/H.264/VP8. The
+ first codec-switch product boundary is a generation-fenced renegotiation and
+ SFU republish while sharing is explicitly paused; pause or `replaceTrack()`
+ alone does not switch codec. The panel is now Share advanced settings and
+ also offers live-switchable 64/128/256 kbps audio sender ceilings, default
+ 128, on the existing Opus path. Display capture does
not standardize channel-count or sample-rate control. The peer receive
contract permits Opus `stereo=1;maxaveragebitrate=256000`, paired with pinned
LiveKit's explicit high-quality stereo/forceStereo option; the selected sender
@@ -756,6 +779,8 @@ is a separate optimization.
- [W3C Media Capture and Streams `getSettings()`](https://www.w3.org/TR/mediacapture-streams/#dom-mediastreamtrack-getsettings)
- [W3C WebRTC](https://www.w3.org/TR/webrtc/)
- [W3C WebRTC codec preferences](https://www.w3.org/TR/webrtc/#dom-rtcrtptransceiver-setcodecpreferences)
+- [W3C WebRTC sender track replacement](https://www.w3.org/TR/webrtc/#dom-rtcrtpsender-replacetrack)
+- [Jitsi codec preference and renegotiation](https://jitsi.github.io/lib-jitsi-meet/classes/JitsiConference._internal_.JingleSessionPC.html)
- [RFC 7742 WebRTC video codec requirements](https://www.rfc-editor.org/rfc/rfc7742.html)
- [Via LA AVC/H.264 licensing program](https://via-la.com/licensing-programs/avc-h-264/)
- [W3C WebRTC Statistics](https://www.w3.org/TR/webrtc-stats/)
diff --git a/docs/research/webrtc-p2p-screen-sharing.md b/docs/research/webrtc-p2p-screen-sharing.md
index db8ba27c..c9df8fae 100644
--- a/docs/research/webrtc-p2p-screen-sharing.md
+++ b/docs/research/webrtc-p2p-screen-sharing.md
@@ -19,9 +19,10 @@
| |
+---- ICE + STUN 尝试直接 UDP WebRTC ----------+
|
- +---- direct/peer UDP -> SFU root -> selected TURN edge
+ +---- logical edge: direct/STUN -> exact selected TURN transport
+ +---- source/ingress fallback: one Host publication -> SFU subscriptions
-2026-08-18 的历史目标顺序是 direct/peer UDP -> SFU virtual parent -> optional selected-edge TURN -> 明确失败;room `1` 只是首个 bounded production smoke,生产后来移除了 exact-room 边界并对所有房间运行 automatic controller。retained-media 验收仍未完成,未来 SFU/TURN 顺序与计账尚未接受。
+当前自动模型由 ADR-0005 持有:健康 direct/peer 边保持 sticky;selected TURN 只替换 exact logical edge 的 transport;需要 server-fed ingress 时由一份 Host publication 服务精确授权的 SFU subscriptions。每条路径受端点发送容量、独立 server admission、generation 和 bounded failure 共同约束。room `1` 只是首个 bounded production smoke,retained-media 验收仍未完成。
系统必须无感完成拓扑分配、恢复和必要迁移;大规模公开分享仍直接使用现有直播服务。
```
@@ -37,7 +38,7 @@
| 产品 | 已公开的可靠事实 | 对本项目的含义 |
| --- | --- | --- |
| Discord Go Live | 使用 WebRTC,但媒体发往 Discord RTC Worker 后再转发给观看者;官方明确这是为了路由控制和隐藏用户 IP。桌面端有原生 C++ media engine、自研捕获/编码、多后端回退和硬件编码。 | Discord 的稳定性并不是纯 P2P 或纯浏览器免费获得的。它是未来质量上限参考,不是首版拓扑参考。 |
-| TeamSpeak 6 | 官方技术回复说明用 WebRTC/ICE 做 P2P 屏幕分享;Windows 在 DX、Windows Game Capture 与传统捕获路径间选择。2026-04 官方称其 `turn.*` 主机实际仅启用 STUN,server-side SFU 仍在开发。 | 与当前目标接近,也解释了 direct-only/STUN-only 的部分可达风险;Screener 已部署 coturn 基线,旗舰迁移改由 SFU/UDP roots 兜底并把 TURN 设为可选兼容层。 |
+| TeamSpeak 6 | 官方技术回复说明用 WebRTC/ICE 做 P2P 屏幕分享;Windows 在 DX、Windows Game Capture 与传统捕获路径间选择。2026-04 官方称其 `turn.*` 主机实际仅启用 STUN,server-side SFU 仍在开发。 | 与当前目标接近,也解释了 direct-only/STUN-only 的部分可达风险;Screener 保持 direct/peer 优先,由同一 controller 为 exact edge 选择 TURN transport 或 Host-publication/SFU subscription。 |
| KOOK / Oopz | 官方 SDK 清单只足以证明屏幕分享接入声网相关能力,没有公开具体媒体拓扑。 | 可以参考交互,不能把它们写成已经证实的 P2P 或 SFU 案例。 |
来源:
@@ -58,7 +59,7 @@
- STUN 让客户端发现公网映射并产生 server-reflexive candidate。它不承载媒体,也不能保证穿过所有 NAT。
- ICE 测试 host、server-reflexive、peer-reflexive 和 relay candidates,并选择可工作的候选对。Trickle ICE 可以减少建连等待。
- TURN 在无法直连时转发完整媒体流,是 NAT 组件中真正产生高带宽成本的部分。
-- 当前媒体梯级是 direct/peer UDP -> SFU/UDP roots -> optional selected-edge TURN/UDP -> bounded failure。Ordinary peer 只接收 STUN;controller 只为当前异常 edge 的一次重建签发短期 TURN 凭据。每个 `RTCPeerConnection` 只检查实际配置的候选,全部 UDP 路径耗尽后明确失败。
+- 当前 controller 保持健康 direct/peer UDP 边;ordinary peer 只接收 STUN。selected TURN 只替换 exact logical edge 的 transport,Host 无 direct first-level path 时可用于唯一 Host-SFU publication;server-fed Viewer 使用该 publication 的精确 SFU subscription。每个尝试都受当前 generation、端点容量、server admission 和 bounded failure 约束。
不存在适用于所有用户的权威“P2P 直连率”。CGNAT、endpoint-dependent mapping、校园/企业防火墙、移动网络、IPv6 和地区运营商都会改变结果。首版必须通过 `getStats()` 统计自己的 `host/srflx/prflx/relay` 比例,而不是引用未经验证的行业百分比。
@@ -69,7 +70,7 @@ ICE 是按分享者与每一名观看者的网络组合独立选路,而不是
当前边界如下:
1. 将 direct UDP 设为最高优先级,成功者保持零媒体服务器路径。
-2. Ordinary peer ICE 为 STUN-only;UDP peer 失败时优先使用 SFU root,可选 coturn 只由 selected-edge grant/rebuild 授予异常连接。
+2. Ordinary peer ICE 为 STUN-only;controller 只为已选定的 logical edge 授予 selected TURN transport,或在需要 server-fed ingress 时授权当前 Host publication 的 SFU subscription,不能用固定全局梯级代替逐 edge 决策。
3. 通过统计确认最终选中的 candidate pair;LiveKit participant TURN 与 selected-edge coturn 分别记录,不能从应用计时顺序推断路径。
4. 网络切换或候选对失效时执行 ICE restart,超时后重建该 peer connection。
5. 在 UI 和诊断中区分“直连”“服务器中继”“正在恢复”和明确失败原因。
@@ -92,7 +93,7 @@ ICE 是按分享者与每一名观看者的网络组合独立选路,而不是
| --- | ---: | ---: | --- |
| P2P 星型 | `N * B` | 直连时接近 0 | 最符合成本目标;适合少量朋友 |
| P2P + TURN | 仍为 `N * B` | 每条中继约 `B` 入 + `B` 出 | 只解决不可达,不解决分享者上行 |
-| Peer-assisted 两链 | 分享端最多约 `2 * B` | 直连边接近 0;TURN 仍按边计费 | 每名 viewer 最多转发一份;标准 browser relay 逐跳解码/重编码 |
+| Peer-assisted tree | 分享端最多约 `C * B` | 直连边接近 0;TURN 仍按边计费 | 每个 endpoint 最多发送 `C` 份;标准 browser relay 逐跳解码/重编码 |
| 整房 SFU(仅对照) | 约 `B` | `B` 入 + `N * B` 出 | 分享者轻松,但服务器承担全部观看流量;当前 root-shape 目标另按 `B_pub`、`B_i` 和 `B_exc,j` 计量 |
| MCU | 约 `B` | 另有解码、合成、重编码 | 本场景没有合成需求,不采用 |
@@ -119,14 +120,14 @@ IETF 对 mesh/SFU 的拓扑说明见 [RFC 7667](https://www.rfc-editor.org/rfc/r
- 生产已移除 exact-room allowlist,所有房间由 bounded peer-assisted/SFU controller 自动路由;ordinary peer 仍使用 STUN-only ICE。
- 当前 PoC 默认允许八名观看者,部署者可配置 1 至 16,超额连接会被明确拒绝。该数值只控制接入,不代表 1:8 已通过性能验收;必须收集可用上行、实际发送码率、`qualityLimitationReason`、编码耗时和发送队列来确定真实可持续人数。
-- 每条 ordinary peer 链路独立使用 STUN-only ICE;只有控制器选中的异常 edge 才会获得短期 TURN credential。
+- 每条 ordinary peer 链路独立使用 STUN-only ICE;只有控制器选中的 exact logical edge 或 Host-SFU ingress 才会获得短期 TURN credential。
- Exact release `9461e20` 的所有房间在 peer recovery 与 alternate parent 耗尽后可准备最多两个 SFU/UDP roots;这是已部署事实,不是未来固定 root 数的授权。首次 room `1` smoke 已观察到 participant entry,但 retained media 尚未验收。
- 桌面和手机观看者使用同一个 Web 播放端;分享者不要求朋友安装完整客户端。
-当前接受的非服务器 endpoint downstream 默认值为二,并允许部署静态配置为一、二或三;分享端及 Viewer 遵守同一规则。ADR-0004 的可删除实验验证第三名及后续 viewer 可由客户端转发;ADR-0005 的自动 controller 最初在 room `1` 受限部署,现已覆盖所有房间。未来 SFU/TURN 层级、计账和 fallback 顺序尚未接受。retained SFU media、移动端矩阵和 broad rollout 仍未通过门槛;已关闭 PR #12 的显式整房 SFU 模式不再是当前方案。超过小房间上限时仍建议使用外部直播服务。观察项包括:
+当前接受的非服务器 endpoint downstream 默认值为二,并允许部署静态配置为一、二或三;分享端及 Viewer 遵守同一规则。ADR-0004 的可删除实验验证第三名及后续 viewer 可由客户端转发;ADR-0005 定义一份 Host publication、逐 Viewer SFU subscription、exact selected TURN edge transport 与独立 server admission,automatic controller 最初在 room `1` 受限部署,现已覆盖所有房间。retained SFU media、移动端矩阵和 broad rollout 仍未通过门槛;已关闭 PR #12 的显式整房 SFU 模式不再是当前方案。超过小房间上限时仍建议使用外部直播服务。观察项包括:
- 正常工作负载持续超过实测可承载的 P2P 人数。
-- 当前 edge 已耗尽 peer recovery、alternate parent 与 SFU/UDP;未来只有该 edge 可进入 selected-edge TURN 决策。
+- 当前 logical edge 的 direct/STUN transport 失败;controller 可为同一 edge 选择 selected TURN,或在 logical ingress 需要 server-fed source 时选择当前 Host publication 的 SFU subscription。
- 分享者上行安全余量不足。
- 分享者因 CPU/encoder 限制降质。
- 产品开始要求隐藏好友之间的 IP。
@@ -293,7 +294,7 @@ W3C TAG 的 capability URL 指南指出 URL 仍会出现在地址栏、历史、
来源(访问于 2026-08-19):[RFC 3986 section 3.5](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5)、[WHATWG WebSockets](https://websockets.spec.whatwg.org/#the-websocket-interface)、[RFC 6455](https://www.rfc-editor.org/rfc/rfc6455.html)、[RFC 6750 section 2.3](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.3)、[W3C Referrer Policy](https://www.w3.org/TR/referrer-policy/)、[W3C TAG Capability URLs](https://www.w3.org/TR/capability-urls/)、[HTML Web Storage](https://html.spec.whatwg.org/multipage/webstorage.html)、[Web Cryptography Level 2](https://www.w3.org/TR/WebCryptoAPI/)、[Node.js Crypto](https://nodejs.org/api/crypto.html)、[SQLite STRICT Tables](https://www.sqlite.org/stricttables.html)、[SQLite ALTER TABLE](https://www.sqlite.org/lang_altertable.html) 与 [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)。
-WebRTC 媒体本身使用 DTLS-SRTP 加密,但 direct P2P 仍可能让这组可信好友看到彼此网络地址。若房间政策要求完全隐藏 endpoint IP,ordinary direct/peer 不能满足,应使用明确的中央媒体路径或拒绝该连接;selected-edge TURN 仅是 SFU/UDP 失败后的兼容 transport,不是全房隐私开关。
+WebRTC 媒体本身使用 DTLS-SRTP 加密,但 direct P2P 仍可能让这组可信好友看到彼此网络地址。若房间政策要求完全隐藏 endpoint IP,ordinary direct/peer 不能满足,应使用明确的中央媒体路径或拒绝该连接;selected TURN 只隐藏获授权 edge 的 direct candidate,不是全房隐私开关。
## 编解码策略
@@ -399,8 +400,8 @@ WebRTC 标准没有承诺固定毫秒延迟。工程目标必须带网络条件
1. 首版坚持 P2P-first,但明确只服务小房间;默认接入上限为八名、可配置 1 至 16,真实 1:8 测量完成前不把它写成性能承诺。
2. Web 先行,目标 Windows Chrome/Edge;把 1080p60 写成 best effort,同时提供降档。
-3. 保留当前 STUN-only 应用配置直到 ADR-0005 迁移 gate 通过。旗舰先验证 direct/peer UDP 与 SFU/UDP roots;只有 controller 选中的异常 edge 才在两者失败后以新连接使用短期 authenticated TURN。普通 Web/Native PeerConnection 始终 STUN-only;coturn 只验证 credential 与 expiry,room/edge/revision 必须由应用重验。
+3. 保留 ordinary STUN-only 配置。Controller 对 exact logical edge 先验证 direct/STUN,再按 ADR-0005 选择短期 authenticated selected TURN;需要 server-fed ingress 时复用唯一 Host publication 和精确 SFU subscription,Host-SFU ingress 本身也可经 selected TURN。coturn 只验证 credential 与 expiry,room/edge/revision 必须由应用重验。
4. 观看端优先做成免安装响应式 Web;分享端先 Web 验证,再按捕获/音频实测升级 Electron。
5. 产品代码优先直接使用浏览器 WebRTC API;借鉴 MiroTalk BRO 和 Screego,不在许可证未定前直接 fork GPL/AGPL 代码。
-6. 分享端 hard fanout 为二;一至两名 viewer 走直接 P2P,第三名及以后只通过 ADR-0004 的 bounded peer-assisted spike 验证,不得隐藏回退为更多 host 连接。
-7. SFU 保持 root-only、可逆且非整房默认;旗舰部署通过 canary 后由 ADR-0005 控制器自动用作中央兜底。peer-assisted 若未通过逐跳重编码负载、延迟、兼容和换父门槛就整体放弃,不通过 encoded custom media、评分器、多树或自研 RTP 来挽救。
+6. 每个非服务器端点使用部署权威 outbound capacity `C in {1,2,3}`,默认二;peer child 与 Host publication 消耗 sender slot,上游接收不计数。分配、恢复和 server admission 由 ADR-0005 统一约束,不从一次历史 fanout 测量推导产品上限。
+7. SFU 保持一份 Host publication、逐 Viewer 精确 subscription、可逆且非整房默认;旗舰部署由 ADR-0005 控制器按 logical ingress 和 server admission 用作中央兜底。peer-assisted 若未通过逐跳重编码负载、延迟、兼容和换父门槛就整体放弃,不通过 encoded custom media、评分器、多树或自研 RTP 来挽救。
diff --git a/docs/status.md b/docs/status.md
index 9aa44cf4..3864eca8 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -17,15 +17,19 @@ This is the current execution index. Git history owns completed timelines; [veri
- The accepted endpoint direction is one steady outbound media-copy cap for every non-server endpoint: default `2`, static `1/2/3`, a peer child or Host publication consumes one slot, upstream receive is free, selected TURN replaces the same copy's transport, and no Browser/UA/visibility tier exists.
- Automatic P2P-first routing, one active upstream, an acyclic graph, exact identity/generation authority, media-proven make-before-break, and bounded failure remain accepted.
- The holistic assisted-route model is accepted: one controller performs allocation, child reparenting, and relay abdication/drain. One Host publication serves SFU subscriptions; TURN is an exact edge transport, not a topology node. Endpoint cap, transition overlap, media-binding generations, and independent SFU/TURN admission are governed by one bounded transaction and remain runtime validation work.
+- Live 64/128/256 audio-ceiling mutation, a source-checkout LAN one-command launcher, and paused-share video codec switching are accepted but not yet implemented on canonical `main`. H.264 startup blur/low-FPS reports remain an evidence-led diagnosis, not a presumed codec defect.
## Current Milestone
1. Rebuild the cap/accounting runtime from exact canonical `main`, preserving safe identity, media-proof, and rollback behavior.
-2. Validate cap `1/2/3`, child and parent quality ownership, constrained Host/SFU/TURN paths, bounded resources, and rollback before deployment.
+2. In independent fresh-main branches, deliver live audio-ceiling mutation and the scoped LAN one-command launcher.
+3. Add paused-share codec switching on the resulting generation/transition boundary, and reproduce the H.264 startup report before any codec-specific repair.
+4. Validate cap `1/2/3`, child and parent quality ownership, constrained Host/SFU/TURN paths, codec/profile mutation, bounded resources, and rollback before deployment.
## Active Boundaries
- `fix/configurable-relay-cap` is an old, incomplete draft and must not be merged as-is.
+- `feat/local-oneclick-bundle` is a stale-base donor only. Transplant its launcher logic and tests selectively; never import its old requirements, memory, status, access variable, or generated local state.
- Open PR #192 and the Native stack are evidence/research, not pending product releases.
- Deployed surfaces and retained candidates that still need product decisions are indexed only in [the TODO ledger](./todo.md); do not extend or roll them back automatically.
- Real SFU/TURN recovery, heterogeneous networks, mobile lifecycle, audio/A-V device behavior, and endurance/resource measurements remain external acceptance evidence, not blockers for unrelated reversible work.
diff --git a/docs/todo.md b/docs/todo.md
index 6b1ecb43..c778ba01 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -6,10 +6,25 @@ Only items in **Now** are executable after their stated decision gate. A branch
## Now
-1. **Migrate routing from accepted truth.** Rebuild the scoped runtime change from canonical `main@7426c3a`: every non-server endpoint defaults to steady outbound media-copy cap `2`, deployment accepts `1/2/3`, a peer child or Host publication consumes one slot, upstream receive is free, selected TURN replaces the same copy's transport, and no Browser tier exists. Replace split topology/route/transport authority and policy magic numbers with one controller, one committed ingress graph, typed reservations, and shared invariants. Keep `EdgeHealth` child-scoped; let the quality owner supply finite correlated windows and independent-edge corroboration for `RelayEligibility`, with no IP-ranking or room-wide score.
-2. **Validate and release.** Run focused state-machine tests, child-vs-parent quality ownership, cap `1/2/3` topology and recovery matrices, constrained Host/SFU/TURN paths, independent routing review, build/full gates, bounded production preflight, deployment, postflight, and rollback verification.
+1. **Route wave A: endpoint capacity and accounting.** From the latest canonical `main`, atomically bump the incompatible signaling wire and replace the Browser/role tiers with `ENDPOINT_MEDIA_COPY_CAPACITY=1|2|3`, default `2`. A peer child or Host publication consumes one steady sender slot, upstream receive is free, committed selected TURN replaces the same logical edge transport, and a media-producing candidate needs the one bounded overlap reservation. Reject an old client before room authority, reject a fourth Host copy when `C=3`, and keep parent-wide quality drain fail-closed until its accepted evidence owner exists. Do not merge the old configurable-cap worktree.
+2. **Switch screen-audio ceilings live.** Keep Opus fixed and serialize 64/128/256 kbps desired profile updates across every current Host, relay, and SFU audio sender. Each endpoint uses fresh `getParameters()`/`setParameters()` readback, ignores stale completions, retains media plus its prior applied value on failure, and applies the latest desired value to future edges. Do not add a remote applied-ack protocol or claim room-wide atomic convergence in this slice.
+3. **Rebuild the LAN one-command launcher.** From fresh canonical `main`, transplant only the useful launcher/tests/wrappers from `feat/local-oneclick-bundle`, replace its stale access variable with `SITE_ACCESS_PASSWORD`, keep local SQLite state out of Git, and verify startup, health, localhost Host, and LAN Viewer output on PowerShell and POSIX boundaries. This is a source-checkout launcher, not an installer or public deployment system.
+4. **Switch video codec while paused.** After the route/media-generation boundary is available, serialize the change with route mutation, freeze exact current route/media bindings, hold new joins, renegotiate P2P/relay and republish SFU while paused, then verify actual codec plus decoded frames on resume. A binding invalidated by leave or hard route failure exits this proof set and waits for routing to rebuild from the final committed preference after the bounded codec transaction settles. On failure pause again and perform bounded rollback; rollback proves the prior preference was reapplied plus a newly negotiated actual codec and decoded progress, not literal equality with the old actual codec. Zero targets update only the future-edge preference. Reset `automatic` with empty codec preferences. This is a paused bounded-gap transaction; unpaused make-before-break is a later extension.
+5. **Diagnose the production H.264/blur report.** Reproduce exact release `769de201f7cc` against current `main` on the same Host/browser/driver/game and one wired direct Viewer, changing one variable at a time. Implement a codec-specific repair only if codec/encoder evidence identifies it; otherwise fix the proven capture, sender, BWE, or lifecycle cause.
+6. **Route waves B-D: bounded fallback and controller convergence.** Replace the temporary fixed SFU subscriber guard with explicit deployment-wide SFU ingress/egress admission; then replace the temporary room-wide selected-lease guard with per-edge TURN allocation admission and exact accounting. Only after those resource owners exist, converge allocation, child reparent, and relay drain on one committed graph/controller. The temporary guards are safety boundaries, not accepted product limits, and must not be removed early.
+7. **Validate and release.** Run focused state-machine tests, child-vs-parent quality ownership, cap `1/2/3` topology and recovery matrices, constrained Host/SFU/TURN paths, audio/codec mutation, independent review, build/full gates, bounded production preflight, deployment, postflight, and rollback verification.
-The existing route implementation is an input to these tasks. Preserve its verified generation, authorization, make-before-break, and media-proof invariants while migrating capacity and fallback accounting.
+The existing route implementation is an input to these tasks. Preserve its verified generation, authorization, make-before-break, and media-proof invariants while migrating capacity and fallback accounting. The accepted model is the destination; each wave must remain safe and truthful on its own rather than installing a name-only controller or an unreserved overlap.
+
+## Accepted Later Roadmap
+
+These items are real product work, ordered after the current release boundary; they are not permission to resume an old branch wholesale.
+
+1. **Native shared encode, Windows first.** Prove one hardware encoder output can serve two independent Viewer transports and the Host-SFU publication while each connection retains its own RTP/RTCP, pacing, encryption, feedback, and upload accounting. Productize only after actual access-unit identity, Viewer2/FIFO, heterogeneous feedback, game-resource, browser/hardware, A/V, packaging, and licensing gates pass. Web Host/relay remains standard per-`RTCPeerConnection` encoding because no portable shared-encoder contract exists.
+2. **Mobile Viewer lifecycle.** Run Android Chrome and iOS Safari device matrices for autoplay gesture, foreground/background audio, foreground video recovery, lock/page reclamation, rotation, and Wi-Fi/cellular migration. Preserve the same media element and current reconnect path; do not promise background video composition or unsupported lock-screen behavior.
+3. **Distributable sender.** Turn a proven Windows native path into a signed, installable, updateable sender before expanding capture/audio backends to macOS and Linux. A source checkout or evaluation ZIP is not a self-contained cross-platform client.
+4. **Real network acceptance.** Measure standard ICE/STUN, IPv4/IPv6, independent STUN destinations, selected TURN, SFU ingress, and bounded failure across representative NATs and mobile networks. Do not implement browser port prediction, raw-IP ranking, or a room-wide quality score; parent choice uses exact edge evidence and the accepted route controller.
+5. **Platform output only when real.** Revisit AirPlay/Cast only when a target browser and physical receiver prove the live `MediaStream` contract. System mirroring remains external; no placeholder button, custom receiver, or server transcode is scheduled.
## Product Decisions Needed
@@ -20,8 +35,6 @@ The existing route implementation is an input to these tasks. Preserve its verif
| #171 diagnostic JSON export | Confirm a support workflow or remove the extra surface. |
| #181 selected-pair response counter | Keep as local observation or remove; it has no route authority. |
| #182 signaling watchdog | Confirm Host, mobile/background, and selected-edge session semantics before calling it complete. |
-| `feat/local-oneclick-bundle` | Decide whether local one-click startup belongs in the current Web roadmap. |
-| Windows/native sender work | Keep as later optimization unless a browser capability gap changes priority. |
These decisions are not permission to continue old branches, and current deployment remains unchanged until a scoped decision is made.
@@ -29,7 +42,7 @@ These decisions are not permission to continue old branches, and current deploym
- Open PR #192 measures synthetic flash/tone timing; it is not an A/V correction feature.
- The Native PR stack #16/#18/#22/#23/#25/#28 and related fanout branches are one research program, not six product TODOs.
-- Cap3, resource, route-recovery, Viewer-MBB, signaling-blackhole, Host-generation, SFU-shaping, NAT, mobile, and endurance artifacts remain bounded evidence. Merge or retain them only when a current decision consumes them.
+- Cap3, resource, route-recovery, Viewer-MBB, signaling-blackhole, Host-generation, SFU-shaping, NAT, mobile, and endurance artifacts remain bounded evidence. Merge or retain them only when a current decision consumes them. Browser NAT/port prediction, raw-IP ranking, AirPlay/Cast receivers, and mobile background guarantees are not implied by the current implementation batch.
- Real heterogeneous-network SFU/TURN, mobile lifecycle, audio/A-V device, and endurance/resource acceptance are scheduled at the relevant release boundary.
## Candidate Handling
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 cd363d3e..b7532078 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"
@@ -6,7 +6,7 @@
## 目标与边界
-产品面向一名分享者和小范围可信朋友的低延迟游戏画面分享。观看端使用普通桌面或手机浏览器;每条普通媒体边独立 ICE 并优先 direct/peer UDP。所有非服务器端点共享一个服务端权威稳态 outbound media-copy capacity,默认 `2` 且只允许静态配置 `1`、`2` 或 `3`;peer child 或 Host publication 各消耗一份,upstream receive 免费,selected TURN 只替换同一份 edge 的 transport,角色、浏览器、UA、设备和页面可见性不改变该值。活动媒体图无环,每名 Viewer 同时至多一个 active upstream。SFU subscriber egress、TURN allocation、temporary overlap 和 exact fallback sequence 由 ADR-0005 的整体模型统一定义。
+产品面向一名分享者和小范围可信朋友的低延迟游戏画面分享。观看端使用普通桌面或手机浏览器;每条普通媒体边独立 ICE 并优先 direct/peer UDP。所有非服务器端点共享一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;peer child 或 Host publication 各消耗一份,upstream receive 免费,selected TURN 只替换同一份 edge 的 transport,角色、浏览器、UA、设备和页面可见性不改变该值。活动媒体图无环,每名 Viewer 同时至多一个 active upstream。不兼容的 capacity 能力与单一 signaling wire 原子升级,旧客户端在取得房间 authority 前 fail closed。SFU subscriber egress、TURN allocation、temporary overlap 和 exact fallback sequence 由 ADR-0005 的整体模型统一定义。
本阶段必须形成完整的最小纵向链路:
@@ -36,6 +36,8 @@
不选 Go 的原因是 Node 不承载正常情况下的媒体流量,换语言不会减少分享者上行或 TURN 中继成本。不选 C++ 的原因是浏览器能力尚未被实测证明不足;只有捕获、应用音频或硬件编码出现明确瓶颈时才增加原生 helper。
+本地一键启动只包装当前 Node/Vite 源码应用,不创建第二套服务器。`npm run local` 和 PowerShell/POSIX wrappers 检查 Node 24 与依赖、选择可用端口、使用专用本地状态目录、生成或复用符合当前合同的 `SITE_ACCESS_PASSWORD`,启动后轮询现有 health endpoint,并打印 localhost Host URL 与 LAN Viewer URL。它明确报告 HTTP LAN、缺少公网 TLS、防火墙/端口映射和未配置 STUN/SFU/TURN 的边界;不自动修改系统网络设置,不把源码启动器称为安装包或互联网部署器。测试通过注入端口、网络接口和子进程边界验证配置与输出,不依赖真实公网。
+
## 系统结构
```mermaid
@@ -152,11 +154,11 @@ 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`;同时提供离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling。codec 与音频质量在分享中锁定并于下一次分享生效。它们只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率、声道或硬编。
+浏览器可返回更低设置,界面以 `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。音频 ceiling 可在直播中串行更新;视频 codec 首先支持在分享显式暂停时事务化切换。它们只是 ceiling 和浏览器偏好,不保证实际分辨率、帧率、码率、声道或硬编。
每次 `setParameters()` 都必须从当次 `getParameters()` 派生更新,然后读回 requested/applied `maxBitrate`、`maxFramerate`、`scaleResolutionDownBy` 和 degradation preference。浏览器负责具体降级,实际结果由 stats 观测;拒绝或浏览器改写必须进入可见状态,不能只写 `console.warn`。
-Web 视频端不做视频 SDP munging。`automatic` 不调用 P2P `setCodecPreferences()` 且不覆盖 LiveKit 默认 codec;显式 H.264/VP8 在首个 offer/publication 前应用,P2P 与 browser relay 仍保留完整 browser codec/repair 回退列表,SFU 始终保持 `backupCodec: false`。codec 改动不热切换现有连接。实际 outbound codec/profile、encoder implementation 与 stats 是结果真相;浏览器支持 H.264 不证明命中硬编。AV1 仍不得仅凭压缩率推断默认启用。唯一获准的 Web SDP 变换是下述 Viewer answer 的 Opus stereo receive preference,不得借此扩展视频码率、codec 或通用 munging。
+Web 视频端不做视频 SDP munging。`automatic` 以空 `setCodecPreferences([])` 恢复 P2P 浏览器默认且不覆盖 LiveKit 默认 codec;显式 H.264/VP8 在首个 offer/publication 前应用,P2P 与 browser relay 仍保留完整 browser codec/repair 回退列表,SFU 始终保持 `backupCodec: false`。暂停时的 codec 切换使用单调 codec-negotiation generation,并和 route mutation 串行:冻结 exact current route/media binding target,新 join 等待、leave 从 target 移除;P2P/relay 在暂停中显式重新 offer/answer,SFU 以新 publication generation republish。恢复 source 后,每名 target 从实际 inbound RTP stats 与 decoded-frame counter 生成专用 codec-transition proof;proof 精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation 与 codec-negotiation generation,不复用 Viewer quality evidence,也不改变 route authority。leave、hard failure 或 binding generation 变化会移除该 target 并把仍在线 Viewer 置为 `route-wait`;bounded codec transaction 先以剩余 target settle 并释放 route lock,随后 controller 使用最终 committed preference 恢复该 Viewer,防止 codec/route 互等。服务端只在全部 still-current target 的 actual codec 与 decoded progress 成立后提交 desired codec。失败立即重新暂停并按旧 preference 开启有界 rollback generation;rollback 证明 P2P 空/有序 preference 或 SFU fresh publish options 已恢复,并从新协商代次取得 actual inbound codec 与 decoded progress,不要求 actual codec 与旧观测字面相同。回滚失败则保持暂停和明确错误。零 target 只更新 future-edge desired codec。该 slice 是 paused bounded-gap mutation,不声称 make-before-break;`replaceTrack()` 或暂停本身不改变 codec,未暂停热切换后续复用同一事务。实际 outbound codec/profile、encoder implementation 与 stats 是结果真相;浏览器支持 H.264 不证明命中硬编。AV1 仍不得仅凭压缩率推断默认启用。唯一获准的 Web SDP 变换是下述 Viewer answer 的 Opus stereo receive preference,不得借此扩展视频码率、codec 或通用 munging。
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 始终可用。
@@ -170,13 +172,13 @@ Web display-audio 请求显式关闭 `echoCancellation`、`noiseSuppression`、`
Host 本地预览直接绑定现有 capture stream,不创建 viewer、`RTCPeerConnection` 或额外媒体边,也不产生 TURN/SFU/应用服务器出口。预览仍可能有本地合成、缩放和 GPU 显示成本;在同一动态场景对预览开/关采集 Host CPU、GPU、encode time 和实际 FPS。只有稳定收益且捕获、编码和远端画面不变时,才把直播后的默认动态预览改为静止缩略图或隐藏并允许按需展开;隐藏预览绝不停止 capture track 或 sender encode。
-部署版 `769de201f7cc` 的模糊、游戏低帧、持续 `bandwidth` 提示和 Host 刷新恢复都只作为同一 release 的用户报告。首轮复现必须在相同机器、Chrome/Edge、驱动、游戏场景和单个有线 direct Viewer 上对照该 release 与最新 `main`,并分别执行只重建受影响 `HostPeer`、只替换 capture、完整 Host 重建和预览开/关;任何一次只改变一个变量。若实际 codec/encoder 不变而 BWE/发送恢复,则下调 codec 根因优先级;只有编码成本异常时才进入受控 codec spike。
+部署版 `769de201f7cc` 的模糊、游戏低帧、持续 `bandwidth` 提示和 Host 刷新恢复都只作为同一 release 的用户报告。首轮复现必须在相同机器、Chrome/Edge、驱动、游戏场景和单个有线 direct Viewer 上对照该 release 与最新 `main`。生命周期实验固定 `automatic`,每个独立 affected baseline 只运行 observe、受影响 `HostPeer` rebuild、capture replace、Host reload 或 preview cycle 中一个动作;codec A/B 另以全新 Host/share/PeerConnection 会话分别请求 automatic/H.264/VP8 并校验 actual codec。质量判断只使用同一 generation 且时间重叠的 capture A、sender B、Viewer C 窗口;stats identity poll 不推进采样 accumulator,可选 encoder 字段缺失保持 unknown。若实际 codec/encoder 不变而 BWE/发送恢复,则下调 codec 根因优先级;只有编码成本异常时才进入受控 codec repair。
`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=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 将 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;非服务器端点容量为 C 时最多 C × 128/C × 256 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`。
+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 是不同修复机制,保留前者不声称实际启用、替代或等价于后者。直播中只改变档位时,不重新协商 Opus 或 republish;服务端沿现有 quality wire 保存 last-wins desired profile,各客户端 sender-mutation queue 从 fresh parameters 更新当前 P2P、relay 和 SFU audio sender并立即 readback,过期 completion 不覆盖新值,未来 sender 读取最新 desired profile。应用失败保留该 sender 的旧 applied 值和媒体并显示告警;无远端 applied 回执时 Host 不宣称全房原子收敛。Pinned LiveKit 2.22.0 的当前 Chrome/Edge screen-audio baseline 可直接更新现存 audio sender;其他浏览器以实际 readback 为准。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;非服务器端点容量为 C 时最多 C × 128/C × 256 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`。
Viewer 本地连接详情只从当前 route 的唯一 inbound screen video/audio stats 读取同步证据:`audio estimatedPlayoutTimestamp - video estimatedPlayoutTimestamp` 表示当前发送端时间线差;音视频 jitter-buffer delay 取相邻窗口累计 delay/count 的比值;音频 concealment 取相邻窗口 concealed/total sample 与 event 增量。每个媒体种类用 stats id、SSRC 和 track identifier 共同守住区间身份,换流或累计计数回退时先重新基线,字段缺失或分母为零时保持未知。该证据不进入 signaling、质量上报或持久化,也不设置 `jitterBufferTarget`、Web Audio 或任何媒体控制参数;真实同步仍由同一持久 `MediaStream`/媒体元素和 WebRTC playout 负责。
@@ -360,7 +362,7 @@ Host 与 relay Viewer 复用同一个纯 presentation reducer 保存远端 `View
服务端维护每个房间唯一的版本化 route owner。候选 parent 可以形成图,但 committed media graph 必须无环;Host 没有 upstream,每名 Viewer 同时只有零或一个 active upstream,且每个 active Viewer 必须沿 peer edges 到达 Host 或沿当前 authoritative Host publication 到达 source。加入、容量释放、节点离开、当前边失败和已接受的 path-health evidence 才能触发一次有界重选,未受影响分支保持 sticky。
-所有非服务器端点共享一个 server-authoritative steady outbound media-copy capacity:默认 `2`,只允许静态配置 `1`、`2` 或 `3`。peer child 或 Host publication 各占一份,upstream receive 免费,committed selected TURN 只替换同一份 edge transport;SFU subscriber egress 与 TURN allocation 使用独立 server admission。客户端 capability 只能收紧该值,不能按角色、浏览器、UA、设备或页面可见性建立另一套 policy。代码通过一个 named config 和 shared guard 执行,不在 Host、Viewer、active、recovery 或 migration 分支重复 magic number。
+所有非服务器端点共享一个 server-authoritative steady outbound media-copy capacity:唯一配置 `ENDPOINT_MEDIA_COPY_CAPACITY` 默认 `2`,只接受 `1`、`2` 或 `3`,不兼容旧键。peer child 或 Host publication 各占一份,upstream receive 免费,committed selected TURN 只替换同一份 edge transport;SFU subscriber egress 与 TURN allocation 使用独立 server admission。客户端 capability 只能收紧该值,不能按角色、浏览器、UA、设备或页面可见性建立另一套 policy。代码通过一个 shared accounting guard 执行,不在 Host、Viewer、active、recovery 或 migration 分支重复 magic number;client/server/native wire 随该能力原子升级。首个迁移波次在独立 server admission 就绪前保留现有 SFU subscriber 与 room-wide selected-lease 安全护栏,但不把其固定值当作产品 policy;`C=3` 满载时必须在发出会产生第四份 Host media copy 的 token/grant 前明确等待或失败。
普通 Web relay 把收到的 remote track 加入独立 downstream `RTCPeerConnection`,因此可能逐跳解码和重编码;浏览器不保证跨连接 shared encode。每条 ordinary child 是独立网络副本,实际 encode time、CPU/GPU、bitrate、loss、frame rate、depth 和 recovery 必须测量。
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 9a4bb5ad..cfd21559 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"
@@ -24,10 +24,10 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 观看端本地音量:播放控制栏提供 `0%` 至 `100%` 音量条和静音按钮,只改变当前浏览器的媒体元素,不修改 Host 音轨、编码、房间状态或其他观看者。切流、换父和 ICE 恢复保留当前页面内的值;刷新后不持久化。静音保留上次非零音量,拖动到非零值自动取消静音。
- 本地昵称与房间成员:用户可设置一个只保存在当前浏览器同源 `localStorage` 的显示名,界面统一称为“昵称”;默认以只读文本显示,铅笔编辑按钮紧贴昵称,点击后才进入编辑。Viewer 顶部标题直接显示“{Host 名称} 的屏幕”,不得在下方重复一行 Host 名称。信令只在当前在线 socket 会话内保存和广播 NFC 规范化、最多 24 个 Unicode code points、拒绝控制/换行/双向覆盖符与孤立 surrogate 的纯文本标签,不写 SQLite 或日志。空值使用通用角色 fallback。Web Host 与 Viewer 都必须看到全部当前在线 Viewer 的权威总数与 roster,不能拿最多两条 Host 媒体直连数冒充在线人数;presence 更新也不得创建媒体连接。展示身份默认只显示名称;仅当房内出现同名时追加当前房间 `peerId` 的至少六字符短后缀,并只在同名项后缀碰撞时有界延长。显示名、后缀和 `clientId` 都不是账号、授权身份或全局 UUID,重复名称允许且不得参与授权、路由或质量决策。Web Host 与 Viewer 通过同一 opt-in participant roster 看到 Host 名称;Native 使用同一版本化鉴权 wire,但不发送 presence capability,也不接收 Web roster。
- 一对多观看:房间 admission 与端点下游容量分别配置,超额加入必须明确拒绝。Production 当前默认 8、显式接受 1 至 16;未来默认值和上限是独立产品决策,必须经过相应资源、质量、深度和恢复验收,不能从端点 cap 或一次短跑推导。
-- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,默认 `2`,只允许静态配置 `1`、`2` 或 `3`;peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算,committed selected TURN 只替换同一份 logical edge 的 transport。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。并行产生媒体的 candidate 必须持有唯一的 `TransitionOverlapSlot`,并在 commit 后回到稳态上限;SFU subscriber egress 与 TURN allocation 由独立 server admission 记账。
+- 端点发送容量:所有非服务器端点使用同一个服务端权威稳态 outbound media-copy capacity,由唯一部署项 `ENDPOINT_MEDIA_COPY_CAPACITY` 配置,默认 `2` 且只接受 `1`、`2` 或 `3`;不读取旧键或保留第二套 tier。peer child 或 Host 的唯一 SFU publication 各消耗一份,上游接收不消耗该预算,committed selected TURN 只替换同一份 logical edge 的 transport。客户端只能声明不高于部署值的可用容量,角色、浏览器、UA、设备类型和页面可见性不产生不同上限。并行产生媒体的 candidate 必须持有唯一的 `TransitionOverlapSlot`,并在 commit 后回到稳态上限;SFU subscriber egress 与 TURN allocation 由独立 server admission 记账。该不兼容能力变化与单一 signaling wire 原子升级;旧客户端在取得房间或 route authority 前 fail closed。
- P2P 优先:每条普通逻辑媒体边先尝试 direct/peer UDP,服务器不得默认中转可直连媒体。更多观看者优先沿满足统一端点容量的无环 peer 图分布;每名 Viewer 同时至多一个 active upstream,失败时只影响需要重选的分支。
- NAT 与传输边界:STUN 必须可用,所有 ordinary peer `RTCPeerConnection` 只接收 STUN ICE servers,普通边不得预发 TURN candidate。所有恢复和候选授权必须绑定 exact room/share generation、endpoint session、route/assignment generation 与 connection identity;成功即停止,失败、超时或绑定失效即撤销,全部可用路径耗尽后明确等待或失败。已接受的顺序是保持既有 logical edge,必要时 direct/STUN 后使用 exact selected TURN;只有 logical ingress 不可用时才使用当前 Host publication 的 SFU subscription。Host 无 direct first-level path 时优先一条可经 TURN 的 Host-SFU publication,而不是逐 Viewer 建 Host-TURN peer 边。凭据不得进入 URL、日志、浏览器持久化或 SQLite;HTTPS/WSS 继续独立使用 TLS/TCP。
-- 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择;分享期间可直接换档或应用有界高级设置,不重新选择来源或重建健康连接,codec 在直播中锁定并于下一次分享生效。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。
+- 质量控制:保留 1080p60(8 Mbps)、1080p30(5 Mbps)、720p30(3 Mbps)三档推荐上限,三档与高级设置初始值统一采用 `balanced`(平衡)与 `automatic`(自动编码),`maintain-resolution`(清晰优先)、`maintain-framerate`(流畅优先)和 H.264/VP8 保留为显式选择。分享期间可直接换视频档位和 64/128/256 kbps 音频 sender ceiling,不重新选择来源或重建健康连接;视频 codec 首个可交付切换边界是在分享已显式暂停时执行有界重协商,未暂停热切换是后续复用同一事务的扩展。Peer-assisted relay 与已配置的 SFU 必须接收同一个严格校验的房间级权威设置,覆盖当前和以后建立的 sender;普通 P2P 信令结构保持不变。任何设置都只是浏览器上限和偏好,具体降级由浏览器决定;必须读回实际 sender 参数并通过 stats 观测结果、显示参数拒绝、改写和持续受限原因。不做自定义动态 FPS、综合评分或周期性全房间调档。
- 路径隔离双表示:direct/peer 继续使用每条 PeerConnection 独立的 stock WebRTC GCC,不把任何 viewer 反馈合成全房目标。每条 SFU path 从 `HIGH` ceiling 开始;优先用 pinned LiveKit 2.22.0/1.13.5 的标准两层 screen-share simulcast,在 Dynacast off 下常驻 exactly `HIGH+LOW`,让内建 per-subscriber BWE 独立降层和恢复。若该 gate 通过,Screener 不实现媒体层 selector。首 gate 使用 zero-descendant SFU leaf;root-with-children 的自动 downshift 与有界迁移是 default-on 前独立硬门。只有内建选择不满足门槛时才用标准 subscriber quality 显式限制,常驻成本不合格时再测标准 sender 手动启停。`LOW` 停编只是资源优化;active representation/layer 硬上限为二,禁止按 viewer 增长。必须实测实际接收层、硬件编码证据、游戏 FPS/p1 low、CPU/GPU、区间 encode cost、上传和分层 bytes。当前 Web P2P simulcast 缺少 receiver 选 RID 和跨 PeerConnection shared-encode 契约;当前 Web/LiveKit SVC 也缺少 direct/peer 独立选层与可移植硬件保证,且 pinned screen share 强制三层 temporal-only `L1T3`,二者按现契约静态 no-go。全部标准路径失败后才考虑 custom/native dual encode。没有合格 hardware/power-efficient 路径或额外表示破坏游戏/上传预算时 fail closed:保护健康路径并明确显示弱路径降级或不可用。
- 路径级质量状态:应用的 `HIGH`/`FALLBACK` 非对称窗口只决定拓扑资格和诊断,不命令正常的媒体层切换,也不计算综合分数。`EdgeHealth(parent, child)` 只控制该 child 的换父;`RelayEligibility(parent)` 仅适用于 relay parent,按 `eligible -> suspect -> draining -> ineligible` 控制其是否接收新 child 以及是否排空现有 children。质量 owner 根据不同 downstream edges 的当前可观察证据和端点容量要求足够的独立关联;同一 edge 的 C+B 只处理该 child。relay parent 自身 ingress 失败先触发本地修复并进入 `suspect`,只有修复失败、明确 sender/resource failure 或独立 downstream edges 确认转发仍失效时才 drain,不等待不存在的第二个 child;Host source 走 publication repair/child migration,不走 parent reparent。退位时仍健康的 ingress 保留,失效 ingress 在同一 bounded target 中替换或移除;无目标 child 进入有界等待或失败,更长的稳定证明和 cooldown 后才恢复 `eligible`。Viewer 请求必须鉴权、限频、去重,并由 sender 的 GCC/Transport-CC、实际码率、RTT、丢包、重传、编码限制、协商 codec/profile/parameters 与 viewer 解码、丢帧、冻结证据交叉验证;不能仅凭自报生效,也不得上传 raw SDP、candidate 地址或原始设备/网络标识。
- 断线恢复:临时网络变化只触发整体路由模型授权的有限恢复动作;任一步成功即停止,失败最终进入明确等待或有界失败。`connecting`/`checking` 先显示不改变拓扑的慢连接状态,硬超时必须由真实移动网络证据确定。所有异步结果受 session、route revision、assignment/connection generation 约束,未受影响分支保持健康,Host 只看到不含 URL、地址、token 或原始错误的阶段信息。质量证据只改变 edge 或 parent eligibility,不创建第二个 route controller。
@@ -36,13 +36,13 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 站点访问:生产部署必须配置独立的 `SITE_ACCESS_PASSWORD` 控制建房、Host 信令角色和所有 code-only Viewer 入口;只有本地开发/测试可显式关闭。非空值接受 8 至 128 个可见 ASCII bytes,不能复用 TURN、LiveKit、TLS 或其他部署 secret。`POST /api/site-access` 验证成功签发 12 小时、无服务端会话状态的 HttpOnly、`SameSite=Strict` site-access cookie。有效 room-scoped fragment grant 可绕过站点 gate 直接进入对应房间;其余 `/r/{code}`、`/join` 和 public-watch 必须先持有效站点 cookie,之后才检查房间 public/private policy 和房间密码。失败统一且不得泄露房间是否存在或 policy;建房 HTTP 只认该 cookie。已移除的旧环境变量、endpoint 和 cookie 不保留兼容。不引入账号、JWT、服务端 session Map 或通用 logout。
- 房间级观看授权:新房间默认生成含 256-bit 随机量、限时且可撤销的 room-scoped Viewer grant;服务端只保存完整 grant 的 SHA-256 摘要。到期阻止以后鉴权/重连,但不为已鉴权 Viewer 设置踢出定时器;即时清退使用 rotate/revoke。浏览器从 URL fragment 严格读取 grant 后,只写该房间的 `sessionStorage` 并立即用 `history.replaceState` 清除 fragment;刷新和页面内重连可继续。私密房间缺失 grant 时必须先通过站点访问,再提供正确房间观看密码;任一缺失都 fail closed。grant 不得进入 `localStorage`、cookie、query、WebSocket URL、Referrer、日志或错误。Host 可 rotate 或 revoke;revoke 只锁定 grant 路径,已配置的房间密码仍是独立的后续进入方式。新 grant 摘要成功提交后必须清除 Viewer grace/路由、终止旧授权代次的信令和媒体并断开全部旧 Viewer,数据库写失败则不得改变连接。public-watch 是显式、可逆的 room policy,只放宽房间级观看,不绕过站点访问。
- 最小持久化:`ROOM_DATABASE_PATH` 可选且必须与 `SITE_ACCESS_PASSWORD` 同时配置。两者都存在时,SQLite 只持久保存从 `1` 开始自增的房间 ID、Host token 摘要、nullable Viewer grant 摘要,以及 nullable 48-byte Viewer-password material(16-byte salt + 32-byte scrypt verifier);数据库 `CHECK` 约束非空 BLOB 长度,不新增用户、成员或 session 表。明文房间密码只短暂存在于当前页面和鉴权/派生调用内存,不进入 URL、cookie、浏览器持久存储、日志或 SQLite。持久房间停止后仍显示等待状态;私密邀请按期限或 Host rotate 更新。旧 schema 行在原子迁移时必须 fail-closed 为没有可用明文 grant 的锁定私密状态,Host rotate 后才能生成新邀请。
-
### P1 - 重要功能
+- 本地一键启动:提供基于当前源码 checkout 的跨平台单命令 LAN 启动器,而不是安装包、云部署器或公网穿透工具。它复用唯一 Node 应用、当前 `SITE_ACCESS_PASSWORD`/SQLite/config 合同,自动选择可用端口并打印 localhost Host URL、LAN Viewer URL 和健康结果;Host 使用 secure-context 可接受的 localhost 或部署者提供的 HTTPS,LAN Viewer 可在已声明的本地 HTTP 边界访问。启动器不得伪造 TLS、防火墙、路由器端口映射、STUN、SFU 或 TURN 已配置,也不得复活已删除的环境变量;Node 24 与依赖安装仍是明确前置条件。
- 私密房间双入口:private room 接受现有 `/r/{code}#v={grant}` 合法邀请直接进入,或“站点访问 + 房间号 + 该房间观看密码”。没有 grant 的 `/join` 或 `/r/{code}` 先显示明确标为“站点访问”的整站验证,通过后才显示明确标为“加入房间”的当前房间密码输入;有效 site-access cookie 直接跳过第一步,但两类密码不得复用、代填或互相替代。Host 可设置、轮换或移除房间观看密码。密码接受 1 至 64 个可见 ASCII 字符;异步 scrypt 全局最多执行 2 个、等待 16 个派生。站点口令和房间密码都不得进入 URL/query/storage/log/SQLite;不存在、错误密码、队满和正确密码后的满房都返回通用结果。
- 统一自动路由:旗舰部署开启 `PEER_ASSISTED_MEDIA` 后,所有正常房间使用同一个服务端 route controller,并各自保存 assignment、session、route revision、assignment generation、connection identity、media-binding generation 和容量状态。controller 只执行 allocate/distribute、child reparent 和 relay abdicate/drain;合格父节点可形成候选图,但 committed media graph 必须无环、每名 Viewer 同时至多一个 active upstream,且每个 active Viewer 必须沿 peer edges 到达 Host 或沿当前 authoritative Host publication 到达 source。加入、容量释放、节点离开、当前边失败或已接受的 path-health evidence 只开启一次有界重选;其余健康分支保持 sticky,不做常驻多源、周期评分或全房重平衡。迁移保留旧边,只有 exact current candidate 取得 live track、正 RTP 和 decoded-frame progress 后才原子 commit;失败、超时、代次变化或授权撤销销毁候选并保留或恢复旧权威。普通 peer 始终 STUN-only。SFU/TURN overlap 和资源准入由同一 typed ledger 与事务约束。该能力不增加 UI、用户选择、百分比发布或第二套路由器。
-- 质量控制扩展:推荐档位仍是默认入口;“分享高级设置”只允许 720p/1080p/1440p 分辨率 ceiling、15 至 60 的整数 FPS ceiling、2 至 12 Mbps 视频码率 ceiling、清晰/平衡/流畅三种偏好、`自动 | H.264 | VP8` 编码选择,以及离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling;初始值采用 `balanced`、`automatic` 与 128 kbps。视频档位在直播中显式应用;codec 与音频档位在直播中锁定并于下一次分享生效,避免控件产生连续控制流量。所有当前及以后建立的 Web Host、Browser relay 与 SFU sender 必须请求并读回同一房间锁定的 64/128/256 kbps 上限,实际码率仍由浏览器拥塞控制和 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 套到电影或游戏音频。
+- 质量控制扩展:推荐档位仍是默认入口;“分享高级设置”只允许 720p/1080p/1440p 分辨率 ceiling、15 至 60 的整数 FPS ceiling、2 至 12 Mbps 视频码率 ceiling、清晰/平衡/流畅三种偏好、`自动 | H.264 | VP8` 编码选择,以及离散的 `64 kbps 省流 | 128 kbps 音乐默认 | 256 kbps 极高音质` 屏幕音频 sender ceiling;初始值采用 `balanced`、`automatic` 与 128 kbps。视频档位和音频档位在直播中显式应用;音频变更只更新固定 Opus 路径的 sender ceiling,不是 codec 切换。所有当前及以后建立的 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。只有稳定收益且捕获、编码和远端画面不受影响时,才允许直播开始后默认显示静止缩略图或隐藏动态预览并提供按需展开;未测前不宣称收益。
- Peer-assisted 媒体路径:所有非服务器 endpoint 都受同一个服务端权威稳态 outbound media-copy capacity 约束,默认 `2` 且可静态配置为 `1`、`2` 或 `3`;peer child 与 Host publication 都按实际发送副本计数。每名 Viewer 任一时刻只有一个 active upstream,活动媒体图保持无环;只在离散事件中做有界分配或换父。浏览器把收到的标准 remote track 加入独立下游 `RTCPeerConnection` 时会逐跳解码并分别重编码,必须测量而不能称为 shared encode。服务端只在有界房间内存中保存严格校验的质量设置,不写入 SQLite。
@@ -54,14 +54,14 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 分享端桌面封装:用 Electron 固定 Chromium 版本、改善选源/热键/系统音频体验,同时保留 Web 观看端。
- Windows 应用音频:Windows 11 Native sender 使用本地 opaque window target 绑定 HWND、PID 与进程创建时间,只捕获所选游戏及其子进程的音频,避免把语音聊天或通知声一并分享;“全部系统声音”只能由分享者显式选择。普通 Windows 10 不具备当前 process-loopback API 门槛,必须明确标为未解决/不支持而不是伪兼容。浏览器无法证明或隔离任意进程音频时必须如实提示,原生捕获失败、无声或进程退出不得静默扩大为整机捕获。
- 受限网络增强:短期鉴权 TURN 只有在完整、默认关闭的部署配置和当前 route controller 明确授权时可用;普通 peer PC 从创建起保持 STUN-only,不得向整个 participant、房间或所有 peer connections 预发 TURN candidates。凭据必须绑定 exact room/share/session/route/connection generation,短期有效、内存态、受配额约束且不进入 URL、日志、浏览器持久化或 SQLite。TURN 只替换授权 edge 的 transport;Host 无 direct first-level path 时可作为单条 Host-SFU ingress 的 transport。TURN 不得被描述为更高清的传输方式。
-- Web 编码选择:分享高级设置提供 `自动 | H.264 | VP8`,默认自动使用浏览器/LiveKit 协商;显式选择只在下一次分享前用标准 codec preference 生效。直播中控件锁定并明确提示停止分享后可修改。P2P/浏览器 relay 保留完整 repair 与其他 codec 回退列表,SFU 保持 `backupCodec = false`,不维护第二套应用编码链。实际 codec/profile、encoder implementation 与 stats 是结果真相;H.264 可选不等于浏览器必走硬编,AV1 仍不得仅凭压缩率推断默认启用。
+- Web 编码选择:分享高级设置提供 `自动 | H.264 | VP8`,默认自动使用浏览器/LiveKit 协商;首次分享前直接应用,分享中只在 Host 已显式暂停后允许切换。暂停切换与 route mutation 串行,使用 generation-fenced P2P/relay 重协商和 SFU republish;恢复播放后才以实际 codec 与 decoded-frame progress 验证,失败重新暂停并有界回滚。P2P/浏览器 relay 保留完整 repair 与其他 codec 回退列表,SFU 保持 `backupCodec = false`,不维护第二套应用编码链。实际 codec/profile、encoder implementation 与 stats 是结果真相;H.264 可选不等于浏览器必走硬编,AV1 仍不得仅凭压缩率推断默认启用。
### P2 - 可选功能
- 证据驱动的动态 relay capacity:当前只接受统一静态容量 `1`、`2` 或 `3`,默认 `2`,不按角色、设备或 UA 分类。若未来引入运行时升降,必须由独立需求、稳定的 sender/transport evidence、cooldown 和服务端 hard ceiling 共同定义;当前协议能力字段不自行授权动态策略。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 独立采用默认 `automatic`、可显式选择 H.264/VP8 的标准协商路径,不允许运行时静默改用软件编码、显示器画面或系统混音。一名普通 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、TURN/SFU/peer route、Host fanout 或服务端媒体分发;Google Cast receiver 需要可获取的媒体 URL,当前 P2P `MediaStream` 不满足该输入,因此不加入 Cast SDK/receiver。
-- 多地区 SFU-root 调度,以及可选 TURN 兼容层的按地区、运营商可达率。
+- 多地区 server-assisted ingress/egress 调度,以及可选 TURN 兼容层的按地区、运营商可达率。
## 非功能需求
@@ -125,7 +125,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
### 一对多与带宽保护
-- Given 部署的非服务器端点稳态 outbound media-copy capacity 为 `C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Host 或任一 Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,committed selected TURN 不重复计数,角色、浏览器和 UA 不改变 `C`;并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。
+- Given `ENDPOINT_MEDIA_COPY_CAPACITY=C`,其中 `C` 只能是 `1`、`2` 或 `3` 且默认 `2`,When Host 或任一 Viewer 建立、恢复、重鉴权或迁移媒体路径,Then peer child 与 Host publication 的稳态实际发送副本总数不超过 `C`,upstream receive 不计数,committed selected TURN 不重复计数,角色、浏览器和 UA 不改变 `C`;并行候选只有持有 `TransitionOverlapSlot` 时才可达到 `min(C + 1, 3)`,并在 commit/abort 后释放。When 此能力合同上线,Then client/server/native wire 同一 release 原子升级,旧 wire 在房间授权前得到明确 mismatch,且 `C=3` 满载 Host 在取得第四份 publication/token/grant 前明确等待或失败。
- Given peer-assisted 路径分别运行 1、3、5、8 名观看者,When 用户加入、容量释放、节点离开、重鉴权或当前 edge 失效,Then 服务端只为新 Viewer、等待 Viewer 或失去 parent 的 subtree root 选择一个 active parent;每名 Viewer 同时至多一个 active upstream,活动图无环,其余健康边保持 sticky。没有可用 parent 时明确等待或拒绝,不主动重平衡或引入常驻多源媒体。
- Given 一名分享者和八名观看者,When 在受控网络中运行已记录的质量档位,Then 记录每条边的拓扑深度、候选类型、码率、编码/解码负载、分享端与 relay 上行、首帧和玻璃到玻璃延迟;该条在真实矩阵完成前保持未验收。
- Given candidate 改变房间 admission 默认值或上限,When 在目标数量与代表性路径上运行规定时长并注入 relay departure、重连和一个弱路径,Then 每名观看者持续解码、每个非服务器端点不超过配置容量、深度与故障半径有界、未受影响 subtree 不迁移,并记录端点与中央服务的 CPU、GPU、内存、上行、出口、帧率、丢包率、冻结和恢复;任一门槛失败时不得切换默认值。
@@ -149,7 +149,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- 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 部署版出现游戏低帧、持续 `bandwidth` 限制或只有 Host 刷新才能恢复,When 归因该报告,Then 用同一机器、浏览器、驱动、场景和单个有线 direct Viewer 对照精确 release `769de201f7cc` 与最新 `main`,依次比较受影响状态、只重建该 `HostPeer`、只替换 capture、完整 Host 重建和本地预览开/关;记录实际 codec/encoder、A+B/C、游戏 FPS、CPU 与 GPU encode 使用,不能把部署版报告直接归为最新代码缺陷。
+- Given 部署版出现游戏低帧、持续 `bandwidth` 限制或只有 Host 刷新才能恢复,When 归因该报告,Then 用同一机器、浏览器、驱动、游戏场景和单个有线 direct Viewer 对照精确 release `769de201f7cc` 与最新 `main`。每次从独立重新确认的 affected state 只执行 `observe`、重建该 `HostPeer`、替换 capture、Host reload 或本地预览 cycle 中一个动作;codec A/B 另用新的 Host/share/PeerConnection 分别请求 `automatic/H.264/VP8` 并校验实际 codec,不把 codec 变更混入生命周期动作。记录 capture A、sender B、Viewer C 的同代重叠窗口、游戏 FPS、CPU 与进程级 GPU encode;可选 encoder implementation/power-efficient 字段缺失只记 unknown,不能把部署版报告直接归为最新代码或 H.264 缺陷。
- Given 分享过程中切换 Wi-Fi/有线网络,When ICE 连接失败,Then 客户端触发 ICE restart,并在成功或超时后给出明确状态。
- Given 当前路径仍可播放且控制器准备迁移 logical parent 或替换 transport,When 候选路径拥有模型授权的 overlap 资源,Then 旧路径保持权威,直到候选的 exact current generation 出现正向 RTP、解码帧进展和 live video 后才原子提交;ICE `connected` 单独不能触发切换。
- Given 候选没有准入资源,或 provisional 路径失败、超时、代次过期、参与者变化、房间停止、权限撤销或 session 被替换,When 本次机会结束,Then 原路径和未受影响 branches 继续工作,临时资源被销毁,重试遵守模型定义的有界策略。
@@ -158,6 +158,8 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
- Given 浏览器返回分享音轨,When 开始发布,Then 应用设置标准 `contentHint = "music"` 作为内容意图元数据;该值可读回,但不作为 Opus、码率、声道、采样率、FEC、DTX 或立体声的质量证据。
- Given Web Host、浏览器 relay 或 selected-edge 建立或替换分享音轨,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 选择 `自动 | H.264 | VP8` 的不同值,When 执行首个视频 codec 切换闭环,Then 为该请求分配单调 codec-negotiation generation,并与 room route mutation 串行;事务开始时冻结 exact current route/media binding target,离开的 Viewer 从 target 移除,新加入者等待事务结束。暂停期间对 target 的 P2P/relay path 完成显式 offer/answer 重协商,并对 SFU 路径完成新的 publication generation/republish;选择 `automatic` 时以空 codec preference 恢复浏览器默认。暂停帧不能充当媒体证明:恢复 source 后,每名 still-current target 发送一个只属于 codec transaction 的 proof,精确绑定 room/share、Viewer session、assignment/connection/media-binding/publication generation、codec-negotiation generation、实际 inbound codec 与 decoded-frame baseline/delta;该 proof 不进入 EdgeHealth 或 route-quality 判断。若 leave、hard failure 或任何 exact binding 变化使 target 失效,服务端把它移出本事务并标为 `route-wait`,codec 事务在 deadline 内以剩余 target settle 后释放 route lock,controller 再用最终 committed preference 为仍在线 Viewer 恢复路径。只有服务端校验全部仍在 target 内的 proof 后才提交 desired codec。失败时立即重新暂停,按旧 preference 开启有界 rollback generation;rollback 必须证明旧 preference 已重新应用(P2P 空/有序 preference 或 SFU fresh publish options),并由新协商代次报告实际 inbound codec 与 decoded-frame progress,不要求 actual codec 字面等于历史值。回滚失败则保持暂停并显示明确失败,不允许 stale generation 恢复播放。零 current Viewer 或事务中全部离开时直接提交 future-edge desired codec,无需伪造 frame proof。`pause`、`replaceTrack()` 或仅调用 `setCodecPreferences()` 均不能冒充已完成切换;本 slice 是明确的 paused bounded-gap 事务,未暂停 MBB 热切换留作后续扩展。
- 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、降噪或来源标签伪称已隔离。
@@ -166,6 +168,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting
### 仓库可移植性
- Given 在新的 Windows、macOS 或 Linux 工作副本中克隆仓库,When 打开项目,Then 需求、调研、项目记忆、`AGENTS.md` 与 `.codex/` 均存在且处于 Git 跟踪状态,不依赖原开发机器的绝对路径或密钥。
+- Given 已完成 `npm ci` 的 Node 24 source checkout,When 在 Windows PowerShell、macOS 或 Linux 执行本地启动命令,Then launcher 选择可用监听端口、在 Git 忽略的受限状态目录生成或复用当前 `SITE_ACCESS_PASSWORD` 与 SQLite、等待现有 health endpoint 成功,再打印精确匹配该端口的 localhost Host URL、LAN Viewer fragment-invite origin 和 site password;health/spawn 失败必须终止 child 且不显示 ready。Given 没有 HTTPS、STUN/SFU/TURN、防火墙或公网配置,Then 输出明确只承诺 trusted-LAN HTTP Viewer 与 localhost Host,不修改系统网络、不声称跨网可用。重启复用本地 password/rooms,多网卡或显式 public URL 必须与实际 listener port 一致。
## 待确认事项