Screen share 9: watching, subscriptions, stream volume, viewer chimes (#156) #206

Manually merged
charles merged 0 commits from screenshare-9-core-watching into screenshare 2026-11-12 05:57:05 +00:00
Owner

Stacked on: screenshare-8-core-stream-ports

What this builds (Screen share 9, spec §3.5 and §6.3 "Watch", "Subscriptions", "Remote stream state")

  • UserAction::{WatchStream, AddStream, StopWatching, StopWatchingAll, SetStreamVolume { key, percent }, SetStreamMuted { key, muted }}.
  • voice/stream/watch.rs: the watch list. A key is taken only if its streamer is in the key's channel right now and it is not this client's own key. Watch/Add outside the key's channel joins it (or moves there), and the join's op 4 carries the key. A key is pruned when its streamer leaves the channel, and all keys go when the connection leaves voice or moves. A key is rewritten when its streamer starts sharing from a new connection.
  • voice/connection.rs: every op 4 (join, move, flag change, resend after RESUMED/READY) carries viewer_stream_keys with the current flags (Link::sent replaces sent_flags). It only includes keys the gateway accepts: same guild and channel as the connection, and the streamer present there. This covers review focus 2.
  • voice/live.rs: screen-share video is subscribed iff watched, and its audio iff watched and not effectively deafened. Each is told once per publication. After Reconnected only the tracks that were being received are asked for again. Cameras keep the old "told false once" behaviour. The stream gain is stream_gain(vol, muted, output) = volume_gain(vol) × volume_gain(output), or 0 when muted, sent on PlaybackSource::Stream(identity).
  • voice/stream/audio_prefs.rs: StreamAudioPrefs (volume 0–200, muted, last used). They are kept in LocalSettings::stream_audio, kept across logout, and pruned on load and every 10 min.
  • Viewer chimes use a queue with a 180 ms debounce (1100 ms max wait) and a 900 ms cooldown. The last request wins, and the chimes are dropped while self-deafened, as in the fork's Sound.ts one-shot queue.
  • RemoteStream / RemoteStreamState::{Waiting, Buffering, Playing { w, h }, Ended, Failed { code }} per watched video sid; Streams::remote_for(&key).

Tests

  • crates/fluxer-core/tests/stream_watch.rs: the plan's 12 tests. I watched them fail (they did not compile) before the implementation, and they pass now.
  • Unit tests in audio_prefs.rs. The fluxer-platform settings round-trip test now covers [voice.stream_audio].
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green locally. No real-device tests apply to this task.

Deviations / things to look at

  • Store time: the store has no clock (#109), so the 6 h TTL is counted in "store time". This is a clock persisted with the prefs that the 10-min prune timer moves forward only while prefs exist. Time while the client is closed does not count. Stream keys name single connections, so stale entries are harmless.
  • New VoiceEvent::SubscriptionFailed { identity, sid, error } in port.rs: no existing event reports a subscription failure. fluxer-voice does not emit it yet; Screen share 16/17 should.
  • fluxer-platform/src/settings.rs (outside the Files list): I added the [voice.stream_audio] table so the prefs survive a restart. Without it, "persisted" would only reach LocalSettings.
  • Rewrite rule: it only fires for a connection that newly shares. A user sharing from two devices does not move the viewer between them, which the fork would do.
  • Buffering: VideoFrameInfo arrives only on the first frame and on size changes (Task 16), so Buffering means "no first frame within 5 s of subscribing". It is not a stall detector.
  • An existing voice_live test still holds: after Reconnected, unwatched screen tracks are not told again.

Closes #156

🤖 Generated with Claude Code

Stacked on: screenshare-8-core-stream-ports ## What this builds (Screen share 9, spec §3.5 and §6.3 "Watch", "Subscriptions", "Remote stream state") - `UserAction::{WatchStream, AddStream, StopWatching, StopWatchingAll, SetStreamVolume { key, percent }, SetStreamMuted { key, muted }}`. - `voice/stream/watch.rs`: the watch list. A key is taken only if its streamer is in the key's channel right now and it is not this client's own key. Watch/Add outside the key's channel joins it (or moves there), and the join's op 4 carries the key. A key is pruned when its streamer leaves the channel, and all keys go when the connection leaves voice or moves. A key is rewritten when its streamer starts sharing from a new connection. - `voice/connection.rs`: every op 4 (join, move, flag change, resend after RESUMED/READY) carries `viewer_stream_keys` with the current flags (`Link::sent` replaces `sent_flags`). It only includes keys the gateway accepts: same guild and channel as the connection, and the streamer present there. This covers review focus 2. - `voice/live.rs`: screen-share video is subscribed iff watched, and its audio iff watched and not effectively deafened. Each is told once per publication. After `Reconnected` only the tracks that were being received are asked for again. Cameras keep the old "told false once" behaviour. The stream gain is `stream_gain(vol, muted, output)` = `volume_gain(vol) × volume_gain(output)`, or 0 when muted, sent on `PlaybackSource::Stream(identity)`. - `voice/stream/audio_prefs.rs`: `StreamAudioPrefs` (volume 0–200, muted, last used). They are kept in `LocalSettings::stream_audio`, kept across logout, and pruned on load and every 10 min. - Viewer chimes use a queue with a 180 ms debounce (1100 ms max wait) and a 900 ms cooldown. The last request wins, and the chimes are dropped while self-deafened, as in the fork's `Sound.ts` one-shot queue. - `RemoteStream` / `RemoteStreamState::{Waiting, Buffering, Playing { w, h }, Ended, Failed { code }}` per watched video sid; `Streams::remote_for(&key)`. ## Tests - `crates/fluxer-core/tests/stream_watch.rs`: the plan's 12 tests. I watched them fail (they did not compile) before the implementation, and they pass now. - Unit tests in `audio_prefs.rs`. The `fluxer-platform` settings round-trip test now covers `[voice.stream_audio]`. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green locally. No real-device tests apply to this task. ## Deviations / things to look at - **Store time:** the store has no clock (#109), so the 6 h TTL is counted in "store time". This is a clock persisted with the prefs that the 10-min prune timer moves forward only while prefs exist. Time while the client is closed does not count. Stream keys name single connections, so stale entries are harmless. - **New `VoiceEvent::SubscriptionFailed { identity, sid, error }` in `port.rs`:** no existing event reports a subscription failure. `fluxer-voice` does not emit it yet; Screen share 16/17 should. - **`fluxer-platform/src/settings.rs`** (outside the Files list): I added the `[voice.stream_audio]` table so the prefs survive a restart. Without it, "persisted" would only reach `LocalSettings`. - **Rewrite rule:** it only fires for a connection that newly shares. A user sharing from two devices does not move the viewer between them, which the fork would do. - **Buffering:** `VideoFrameInfo` arrives only on the first frame and on size changes (Task 16), so `Buffering` means "no first frame within 5 s of subscribing". It is not a stall detector. - An existing `voice_live` test still holds: after `Reconnected`, unwatched screen tracks are not told again. Closes #156 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(proto,api): stream keys, instance limits, capability adverts and preview endpoints
All checks were successful
ci / Windows (x64) (push) Successful in 28m59s
ci / Linux (x86_64) (push) Successful in 37m2s
6ac431d9db
Refs #154

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat(core): stream state, ports and selectors
All checks were successful
ci / Linux (x86_64) (push) Successful in 13m48s
ci / Windows (x64) (push) Successful in 14m25s
0d406ebd96
Refs #155

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat(core): watching streams
All checks were successful
ci / Linux (x86_64) (push) Successful in 15m9s
ci / Windows (x64) (push) Successful in 13m43s
748af6f771
Watch, add and stop watching screen shares; every op 4 carries the
viewer keys the gateway accepts with the current flags; keys pruned when
the streamer leaves and rewritten on its new connection; screen-share
video/audio subscribed while watched (audio not while deafened); stream
volume and mute persisted with a 6 h TTL in store time; viewer chimes
debounced and cooled down; remote stream playback states.

Refs #156

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Author
Owner

Independent review: Screen share 9 (core watching), commit 748af6f

Scope: git diff 0d406eb..origin/screenshare-9-core-watching.

Local gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci passes in a clean review worktree (all steps; livekit-interop skipped as designed).

Checks

  1. Plan tests: all 12 named tests exist in crates/fluxer-core/tests/stream_watch.rs and check what the plan says. They use the spec values: 180 ms debounce, 900 ms cooldown, 5 s buffering, 6 h TTL and 10 min prune, gain = volume_gain(vol) × volume_gain(output) (0 when muted), video subscribed iff watched, audio iff watched and not deaf, and the own key is never watched or received.
  2. Interfaces: UserAction::{WatchStream, AddStream, StopWatching, StopWatchingAll, SetStreamVolume { key, percent }, SetStreamMuted { key, muted }}, StreamAudioPrefs (persisted, pruned on load and each tick), RemoteStream/RemoteStreamState (Waiting/Buffering/Playing{w,h}/Ended/Failed{code}) and Streams.remote: BTreeMap<sid, RemoteStream> all match the plan and spec §6.1. Buffering goes through Effect::Schedule.
  3. Invariants: fluxer-core gains no dependency and sees no pixels or samples. No LiveKit types appear in a public signature. No new unwrap/expect/indexing on server data. No secrets: the "status-token-fixture" string is a placeholder.
  4. Review Focus 2: announced() builds each op 4's viewer_stream_keys through key_valid_in: the key must be sendable, in the target's guild and channel, and its streamer's connection must be present in that channel. sync() compares the whole Announced, so a change to the flags or the keys sends an op 4 that carries both. watchable rejects the own connection's key. During a move or join, send_state(new_target) filters the old channel's keys out before prune_watching runs, so no bad key is ever sent. key_of_other_channel_never_sent covers the DM, orphan, other-guild and move cases.

Findings

  • minor (process): Touches fluxer-platform (settings.rs, README, tests), which is outside the task's Files list and a second crate. The plan does not mark the task as serialised. The change is needed for persistence and is backward compatible (#[serde(default)], and keys that do not parse are dropped). Note it in the PR body.
  • minor (follow-up): VoiceEvent::SubscriptionFailed is new in port.rs, but nothing emits it yet. Task 16/17 must report it, or Failed can never be reached. Please file a follow-up issue that links Task 16/17.
  • minor (behaviour divergence, documented): The key rewrite differs from the fork's migrateWatchedRemoteStreamConnection in two ways. First, it fires only when a connection newly shares; the fork also rewrites on any update from an already-sharing second device. Second, like the fork, it needs the old connection still listed as sharing. If the old connection's leave arrives before the new one starts sharing, the key is pruned rather than rewritten, and the viewer has to re-watch. The divergence is reasonable; please mention it in spec §14.
  • minor: Store-time prune ticks cause one SaveSettings every 10 min while any stream preference exists. This is harmless.

Verdict: approve. No blocking findings and local CI is green.

## Independent review: Screen share 9 (core watching), commit 748af6f Scope: `git diff 0d406eb..origin/screenshare-9-core-watching`. **Local gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` passes in a clean review worktree (all steps; livekit-interop skipped as designed). ### Checks 1. **Plan tests:** all 12 named tests exist in `crates/fluxer-core/tests/stream_watch.rs` and check what the plan says. They use the spec values: 180 ms debounce, 900 ms cooldown, 5 s buffering, 6 h TTL and 10 min prune, gain = `volume_gain(vol) × volume_gain(output)` (0 when muted), video subscribed iff watched, audio iff watched and not deaf, and the own key is never watched or received. 2. **Interfaces:** `UserAction::{WatchStream, AddStream, StopWatching, StopWatchingAll, SetStreamVolume { key, percent }, SetStreamMuted { key, muted }}`, `StreamAudioPrefs` (persisted, pruned on load and each tick), `RemoteStream`/`RemoteStreamState` (`Waiting/Buffering/Playing{w,h}/Ended/Failed{code}`) and `Streams.remote: BTreeMap<sid, RemoteStream>` all match the plan and spec §6.1. Buffering goes through `Effect::Schedule`. 3. **Invariants:** fluxer-core gains no dependency and sees no pixels or samples. No LiveKit types appear in a public signature. No new `unwrap`/`expect`/indexing on server data. No secrets: the `"status-token-fixture"` string is a placeholder. 4. **Review Focus 2:** `announced()` builds each op 4's `viewer_stream_keys` through `key_valid_in`: the key must be sendable, in the target's guild and channel, and its streamer's connection must be present in that channel. `sync()` compares the whole `Announced`, so a change to the flags or the keys sends an op 4 that carries both. `watchable` rejects the own connection's key. During a move or join, `send_state(new_target)` filters the old channel's keys out before `prune_watching` runs, so no bad key is ever sent. `key_of_other_channel_never_sent` covers the DM, orphan, other-guild and move cases. ### Findings - **minor (process):** Touches `fluxer-platform` (settings.rs, README, tests), which is outside the task's Files list and a second crate. The plan does not mark the task as serialised. The change is needed for persistence and is backward compatible (`#[serde(default)]`, and keys that do not parse are dropped). Note it in the PR body. - **minor (follow-up):** `VoiceEvent::SubscriptionFailed` is new in `port.rs`, but nothing emits it yet. Task 16/17 must report it, or `Failed` can never be reached. Please file a `follow-up` issue that links Task 16/17. - **minor (behaviour divergence, documented):** The key rewrite differs from the fork's `migrateWatchedRemoteStreamConnection` in two ways. First, it fires only when a connection *newly* shares; the fork also rewrites on any update from an already-sharing second device. Second, like the fork, it needs the old connection still listed as sharing. If the old connection's leave arrives before the new one starts sharing, the key is pruned rather than rewritten, and the viewer has to re-watch. The divergence is reasonable; please mention it in spec §14. - **minor:** Store-time prune ticks cause one `SaveSettings` every 10 min while any stream preference exists. This is harmless. **Verdict: approve.** No blocking findings and local CI is green.
charles manually merged commit 61a073cefa into screenshare 2026-11-12 05:57:05 +00:00
Sign in to join this conversation.
No description provided.