Screen share 11: stream settings and encode parameters (#158) #228

Manually merged
charles merged 2 commits from screenshare-11-core-stream-params into screenshare 2026-11-12 08:39:49 +00:00
Owner

Stacked on: screenshare-10-core-go-live

What

Task 11 of the screen-share plan: stream settings and encode parameters in fluxer-core (spec §3.3, §6.3 "Encode parameters", §10 stream settings menu, §11 settings).

  • voice::stream::params: encode_params(&App, source_w, source_h, codec) -> EncodeParams and capture_target(&App) -> CaptureTarget, ported from the fork's ScreenShareOptions.ts. Covers presets as pixel budgets (aspect kept, even sides), effective fps 15/30/60, the mode presets with and without the entitlement, the free-tier clamp, the bitrate table and formula with ceiling scaling, the user bitrate (entitled only), the rung of a smaller source, the degradation rule, L1T3/L1T1 for AV1/VP9, EncoderBackend from encoder_mode, and the software-H.264 720p30 clamp. stream_settings_model(&App) follows the fork's StreamSettingsMenuContent / StreamSettingsMenuContentStateMachine: it gives the modes with their two-line descriptions per entitlement, the offered resolutions and frame rates, the premium badge, and QualityPick::{None, Premium, Write}.
  • voice::stream::entitlement: entitlement(&App) -> QualityEntitlement { higher_quality, bitrate_ceiling, premium_exists }. It reads the discovery limits (feature_higher_video_quality > 0; max_screen_share_bitrate floored, fallback 9 000 000, clamped to 1–50 Mbit/s). premium_exists is the fork's shouldShowPremiumFeatures.
  • VideoSettings gains the §11 fields: show_my_own_screen_share, pause_own_preview_on_unfocus, disable_pip_popout, content_hint, encoder_mode, scalability_mode, audio_source_mode, plus the include/exclude lists. VoiceSettingChange gains a variant for every screen-share field. Old settings files keep loading, and the retired low_240p becomes low_480p.
  • Go-live (golive.rs): the capture start uses capture_target and the publication uses encode_params. While live, SetVoiceSetting emits CaptureCommand::Update when the target changed and UpdateScreenShareEncoding when the params changed. A CaptureEvent::Started with a new size updates the encoder.

Tests

  • crates/fluxer-core/tests/stream_params.rs has 18 tests. They include all 13 the plan names (preset_dimensions_keep_aspect_and_even … old_settings_files_load) plus entitlement/ceiling, encoder backend, start, no-op-when-not-live and menu-model tests. There are also unit tests in params.rs.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green locally. No capture or hardware tests apply to this task.

Deviations / notes for review

  • Delivered size, not source size. CaptureEvent::Started reports the size the capture delivers, which is already scaled into the target box. It is not the source size. A frame that fills the box on one side therefore keeps the preset's bitrate rung, and only a frame smaller than the box on both sides counts as a "smaller source". Without this, a 16:10 screen at 1080p would get the 720p bitrate.
  • Even sides. Smaller sources are evened. The fork keeps odd sizes; EncodeParams documents even sides.
  • Changes outside the Files list (kept small):
    • session.rs keeps limits and premium_features from discovery. Nothing stored them before.
    • app.rs passes the entitlement into reduce_streams.
    • Streams.codecs: Option<LocalCodecs> stores VoiceEvent::CodecCapabilities. It is taken in reduce_settings, logged in or not, and kept across logout. The software-H.264 clamp needs it, and Screen share 12 can reuse it.
  • Limits context. User traits are empty because UserPrivate does not model traits yet. Guild features come from the selected channel's guild, as in LimitContext.current(). P2P is never true, because this client never joins peer-to-peer.
  • Source-list storage. The audio include/exclude lists are stored as one text value each (entries separated by U+001E, name=value by U+001F). This avoids a change to fluxer-platform's StoredValue.
  • Not in this task. disable_stream_previews (privacy) is left to Screen share 13, which lists that switch. The codec is still provisional until Screen share 12. persist.rs needed no change, because SetVoiceSetting is already saved.

Closes #158

🤖 Generated with Claude Code

Stacked on: screenshare-10-core-go-live ## What Task 11 of the screen-share plan: stream settings and encode parameters in `fluxer-core` (spec §3.3, §6.3 "Encode parameters", §10 stream settings menu, §11 settings). - `voice::stream::params`: `encode_params(&App, source_w, source_h, codec) -> EncodeParams` and `capture_target(&App) -> CaptureTarget`, ported from the fork's `ScreenShareOptions.ts`. Covers presets as pixel budgets (aspect kept, even sides), effective fps 15/30/60, the mode presets with and without the entitlement, the free-tier clamp, the bitrate table and formula with ceiling scaling, the user bitrate (entitled only), the rung of a smaller source, the degradation rule, L1T3/L1T1 for AV1/VP9, `EncoderBackend` from `encoder_mode`, and the software-H.264 720p30 clamp. `stream_settings_model(&App)` follows the fork's `StreamSettingsMenuContent` / `StreamSettingsMenuContentStateMachine`: it gives the modes with their two-line descriptions per entitlement, the offered resolutions and frame rates, the premium badge, and `QualityPick::{None, Premium, Write}`. - `voice::stream::entitlement`: `entitlement(&App) -> QualityEntitlement { higher_quality, bitrate_ceiling, premium_exists }`. It reads the discovery limits (`feature_higher_video_quality` > 0; `max_screen_share_bitrate` floored, fallback 9 000 000, clamped to 1–50 Mbit/s). `premium_exists` is the fork's `shouldShowPremiumFeatures`. - `VideoSettings` gains the §11 fields: `show_my_own_screen_share`, `pause_own_preview_on_unfocus`, `disable_pip_popout`, `content_hint`, `encoder_mode`, `scalability_mode`, `audio_source_mode`, plus the include/exclude lists. `VoiceSettingChange` gains a variant for every screen-share field. Old settings files keep loading, and the retired `low_240p` becomes `low_480p`. - Go-live (`golive.rs`): the capture start uses `capture_target` and the publication uses `encode_params`. While live, `SetVoiceSetting` emits `CaptureCommand::Update` when the target changed and `UpdateScreenShareEncoding` when the params changed. A `CaptureEvent::Started` with a new size updates the encoder. ## Tests - `crates/fluxer-core/tests/stream_params.rs` has 18 tests. They include all 13 the plan names (`preset_dimensions_keep_aspect_and_even` … `old_settings_files_load`) plus entitlement/ceiling, encoder backend, start, no-op-when-not-live and menu-model tests. There are also unit tests in `params.rs`. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green locally. No capture or hardware tests apply to this task. ## Deviations / notes for review - **Delivered size, not source size.** `CaptureEvent::Started` reports the size the capture delivers, which is already scaled into the target box. It is not the source size. A frame that fills the box on one side therefore keeps the preset's bitrate rung, and only a frame smaller than the box on both sides counts as a "smaller source". Without this, a 16:10 screen at 1080p would get the 720p bitrate. - **Even sides.** Smaller sources are evened. The fork keeps odd sizes; `EncodeParams` documents even sides. - **Changes outside the Files list (kept small):** - `session.rs` keeps `limits` and `premium_features` from discovery. Nothing stored them before. - `app.rs` passes the entitlement into `reduce_streams`. - `Streams.codecs: Option<LocalCodecs>` stores `VoiceEvent::CodecCapabilities`. It is taken in `reduce_settings`, logged in or not, and kept across logout. The software-H.264 clamp needs it, and Screen share 12 can reuse it. - **Limits context.** User traits are empty because `UserPrivate` does not model `traits` yet. Guild features come from the selected channel's guild, as in `LimitContext.current()`. P2P is never true, because this client never joins peer-to-peer. - **Source-list storage.** The audio include/exclude lists are stored as one text value each (entries separated by U+001E, `name=value` by U+001F). This avoids a change to `fluxer-platform`'s `StoredValue`. - **Not in this task.** `disable_stream_previews` (privacy) is left to Screen share 13, which lists that switch. The codec is still provisional until Screen share 12. `persist.rs` needed no change, because `SetVoiceSetting` is already saved. Closes #158 🤖 Generated with [Claude Code](https://claude.com/claude-code)
# Conflicts:
#	crates/fluxer-core/src/voice/connection.rs
Refs #157

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #157

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #158

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

Independent review: Screen share 11 (stream settings and encode parameters)

Reviewed git diff 32d0267ab..origin/screenshare-11-core-stream-params (one commit, f88c516) cold, against plan Task 11, spec §3.3/§6.3/§10/§11 and the fork (ScreenShareOptions.ts, VideoQualityEntitlement.ts, StreamSettingsMenuContent*.ts, PremiumUtils.ts, LimitConstants.ts).

1. Tests the plan names

All 13 are in crates/fluxer-core/tests/stream_params.rs and assert the spec values: presets 426×240 … 3840×2160, pixel budget with even sides; effective fps 15/30/60; Screen share 1080p30 / Gaming 1440p60, both 720p30 without the entitlement; free tier 480p/720p at 30 FPS or less; the full floor table (15/30/60) with 720p30 → 3 000 000, 1080p60 → 6 000 000 (floor above the formula), 4K60 formula cut at 9 000 000, ceiling scaling above 9 Mbit/s exactly as the fork's computeScreenShareBitrateBps; user bitrate only when entitled; smaller source takes a lower rung; degradation order (source rung / text-detail hint / < 500 000); L1T3/L1T1 for AV1/VP9 only; software H.264 held to 720p30; 240p → 480p; live change → CaptureCommand::Update then UpdateScreenShareEncoding; old settings files load and the new fields round-trip. There are five more: ceiling clamp 1–50 Mbit/s with fallbacks, encoder backend, start uses the settings, no effects when not live, and the menu model.

2. Interfaces

encode_params(&App, source_w, source_h, codec) -> EncodeParams, capture_target(&App) -> CaptureTarget, entitlement(&App) -> QualityEntitlement { higher_quality, bitrate_ceiling, premium_exists } (from WellKnown.limits kept in Session::limits), stream_settings_model(&App), the §11 VideoSettings fields and the VoiceSettingChange variants all exist and are re-exported from voice::stream / voice. EncodeParams follows the merged port.rs (no codec_preference), as it should. Nothing that Tasks 12, 13, 25 or 28 consume is broken. Streams::codecs (LocalCodecs) is a reasonable place for Task 12 to read the capabilities from.

3. Invariants

fluxer-core gains no dependency (Cargo.toml unchanged) and sees no pixels. Server data cannot panic it: limit values are filtered (non-finite or negative values take the fallback), floored and clamped before the cast; fit_to_preset uses u128/isqrt and saturating adds (tested with 0×0, 1×1 and u32::MAX). There are no secrets, and the fixtures use the existing example.com login. The stored source lists (U+001E/U+001F) go through TOML strings with escapes; unreadable entries are dropped.

4. Review Focus

None of the seven items belongs to Task 11.

Findings (all minor, none blocking)

  • minor: the capture target is the preset's box (max_width × max_height), while the fork scales to the preset's pixel budget with the aspect ratio kept. A non-16:9 source therefore comes out smaller than in the original. Under 1080p, a 3440×1440 ultrawide is sent at about 1920×804 (fork: 2224×930), and a tall 800×2000 window at about 432×1080 (fork: 800×2000, within budget). Worth a follow-up issue: the capture box could be derived from fit_to_preset once the source size is known, or the target could become a pixel budget.
  • minor: the documented fills_box heuristic lifts any frame that touches the box on one side to the preset's rung. A thin 1920×200 window under 1080p30 gets 4 500 000 bit/s, where the fork (240p rung) gives 500 000. That is acceptable given that the capture reports scaled frames, but it is a divergence and should be listed under spec §14.
  • minor: refresh_share sends CaptureCommand::Update only when the target changes. Changing AudioSourceMode, the include/exclude lists or the app/desktop audio switches while live therefore never reaches the capture, even though Update carries audio. Either send Update when the audio rule changes too, or document that audio changes apply from the next share.
  • minor: the entitlement is resolved from the selected channel's guild (the fork's LimitContext.current()), and is re-applied to a running share only on a settings change. If the user navigates to another guild with different limit rules while live, encode_params(&app, …) / capture_target(&app) change without the share being updated. Low impact; consider resolving it for the voice connection's guild while a share runs.
  • minor: stream_settings_model computes its selected values without the software-H.264 clamp. The fork's menu reads target, which includes the clamp, so with a software-only H.264 share the menu shows 1080p/60 selected while 720p30 is sent. This is cosmetic until Task 12 picks H.264.
  • note (no action needed): persist.rs is in the plan's Files list but was not touched. That is fine, because SetVoiceSetting already persists voice_settings and the platform stores names generically. The commit trailer is Opus 5.5 rather than the CLAUDE.md line, which is consistent with Task 10.

5. CI

FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in a fresh review worktree: green ("all steps passed"; the stream_params suite ran 18/18; livekit-interop skipped without FLUXER_LIVEKIT_TESTS, as usual).

Verdict: approve. No blocking findings and CI is green; the minor items can become follow-up issues.

## Independent review: Screen share 11 (stream settings and encode parameters) Reviewed `git diff 32d0267ab..origin/screenshare-11-core-stream-params` (one commit, f88c516) cold, against plan Task 11, spec §3.3/§6.3/§10/§11 and the fork (`ScreenShareOptions.ts`, `VideoQualityEntitlement.ts`, `StreamSettingsMenuContent*.ts`, `PremiumUtils.ts`, `LimitConstants.ts`). ### 1. Tests the plan names All 13 are in `crates/fluxer-core/tests/stream_params.rs` and assert the spec values: presets 426×240 … 3840×2160, pixel budget with even sides; effective fps 15/30/60; Screen share 1080p30 / Gaming 1440p60, both 720p30 without the entitlement; free tier 480p/720p at 30 FPS or less; the full floor table (15/30/60) with 720p30 → 3 000 000, 1080p60 → 6 000 000 (floor above the formula), 4K60 formula cut at 9 000 000, ceiling scaling above 9 Mbit/s exactly as the fork's `computeScreenShareBitrateBps`; user bitrate only when entitled; smaller source takes a lower rung; degradation order (source rung / text-detail hint / < 500 000); L1T3/L1T1 for AV1/VP9 only; software H.264 held to 720p30; 240p → 480p; live change → `CaptureCommand::Update` then `UpdateScreenShareEncoding`; old settings files load and the new fields round-trip. There are five more: ceiling clamp 1–50 Mbit/s with fallbacks, encoder backend, start uses the settings, no effects when not live, and the menu model. ### 2. Interfaces `encode_params(&App, source_w, source_h, codec) -> EncodeParams`, `capture_target(&App) -> CaptureTarget`, `entitlement(&App) -> QualityEntitlement { higher_quality, bitrate_ceiling, premium_exists }` (from `WellKnown.limits` kept in `Session::limits`), `stream_settings_model(&App)`, the §11 `VideoSettings` fields and the `VoiceSettingChange` variants all exist and are re-exported from `voice::stream` / `voice`. `EncodeParams` follows the merged `port.rs` (no `codec_preference`), as it should. Nothing that Tasks 12, 13, 25 or 28 consume is broken. `Streams::codecs` (`LocalCodecs`) is a reasonable place for Task 12 to read the capabilities from. ### 3. Invariants `fluxer-core` gains no dependency (Cargo.toml unchanged) and sees no pixels. Server data cannot panic it: limit values are filtered (non-finite or negative values take the fallback), floored and clamped before the cast; `fit_to_preset` uses u128/isqrt and saturating adds (tested with 0×0, 1×1 and u32::MAX). There are no secrets, and the fixtures use the existing `example.com` login. The stored source lists (U+001E/U+001F) go through TOML strings with escapes; unreadable entries are dropped. ### 4. Review Focus None of the seven items belongs to Task 11. ### Findings (all minor, none blocking) - **minor**: the capture target is the preset's *box* (`max_width × max_height`), while the fork scales to the preset's *pixel budget* with the aspect ratio kept. A non-16:9 source therefore comes out smaller than in the original. Under 1080p, a 3440×1440 ultrawide is sent at about 1920×804 (fork: 2224×930), and a tall 800×2000 window at about 432×1080 (fork: 800×2000, within budget). Worth a follow-up issue: the capture box could be derived from `fit_to_preset` once the source size is known, or the target could become a pixel budget. - **minor**: the documented `fills_box` heuristic lifts any frame that touches the box on one side to the preset's rung. A thin 1920×200 window under 1080p30 gets 4 500 000 bit/s, where the fork (240p rung) gives 500 000. That is acceptable given that the capture reports scaled frames, but it is a divergence and should be listed under spec §14. - **minor**: `refresh_share` sends `CaptureCommand::Update` only when the *target* changes. Changing `AudioSourceMode`, the include/exclude lists or the app/desktop audio switches while live therefore never reaches the capture, even though `Update` carries `audio`. Either send `Update` when the audio rule changes too, or document that audio changes apply from the next share. - **minor**: the entitlement is resolved from the *selected* channel's guild (the fork's `LimitContext.current()`), and is re-applied to a running share only on a settings change. If the user navigates to another guild with different limit rules while live, `encode_params(&app, …)` / `capture_target(&app)` change without the share being updated. Low impact; consider resolving it for the voice connection's guild while a share runs. - **minor**: `stream_settings_model` computes its selected values without the software-H.264 clamp. The fork's menu reads `target`, which includes the clamp, so with a software-only H.264 share the menu shows 1080p/60 selected while 720p30 is sent. This is cosmetic until Task 12 picks H.264. - **note** (no action needed): `persist.rs` is in the plan's Files list but was not touched. That is fine, because `SetVoiceSetting` already persists `voice_settings` and the platform stores names generically. The commit trailer is Opus 5.5 rather than the CLAUDE.md line, which is consistent with Task 10. ### 5. CI `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in a fresh review worktree: green ("all steps passed"; the stream_params suite ran 18/18; livekit-interop skipped without FLUXER_LIVEKIT_TESTS, as usual). **Verdict: approve. No blocking findings and CI is green; the minor items can become follow-up issues.**
charles manually merged commit 9ab00bc511 into screenshare 2026-11-12 08:39:49 +00:00
Sign in to join this conversation.
No description provided.