wz-phone/docs/PRD/reports/T5.2-report.md

T5.2 — VideoQualityController with per-mode allocation gates

Status: Approved Agent: Kimi Code CLI Started: 2026-05-12T17:25Z Completed: 2026-05-12T18:00Z Commit: 2e0bdc5 PRD: ../PRD-video-quality-priority.md

What I changed

• crates/wzp-video/Cargo.toml:12 — Added wzp-proto dependency so the controller can use BandwidthEstimator and PriorityMode.
• crates/wzp-video/src/controller.rs — New file. VideoQualityController with:
  • VideoTarget struct: { bitrate_kbps, fps, width, height }
  • allocate() — per-mode budget split: AudioFirst (24 kbps floor), VideoFirst (video floor first), ScreenShare (16 kbps audio clamp), Balanced (15/85 split)
  • derive_target() — static step table mapping budget → resolution/fps (8 steps from 1280×720@30 down to 240×180@5)
  • smooth() — clamps bitrate changes to 2× per second
  • tick(now_ms) — allocates, derives, smooths, returns target
  • set_mode() / update_network() — thread-safe atomic setters
  • set_target() default no-op added to VideoEncoder trait
• crates/wzp-video/src/encoder.rs:43-46 — Added set_target(&mut self, _target: &VideoTarget) default method to VideoEncoder trait.
• crates/wzp-video/src/lib.rs:9-17 — Added pub mod controller; and re-exported VideoQualityController, VideoTarget.
• Tests: 8 new tests covering all 4 allocation modes, step table, smoothing, and mode roundtrip.

Deviations from the task spec

Skeleton task. Followed PRD-video-quality-priority.md sections "Allocation gates" and "VideoQualityController". The PRD pseudocode shows encoder.set_target(target) inside tick(); the actual implementation returns VideoTarget from tick() and provides set_target() on the encoder trait so callers apply it. This keeps the controller testable without a real encoder.

Verification output

$ cargo test -p wzp-video --lib
test result: ok. 40 passed; 0 failed; 0 ignored

$ cargo build -p wzp-video -p wzp-proto -p wzp-relay -p wzp-client -p wzp-android -p wzp-codec -p wzp-desktop
# Finished successfully (59.82s)

$ cargo fmt --all -- --check
# pass

Test summary

• Tests added: 8 (audio_first_reserves_floor, audio_first_floor_not_below_bwe, screen_share_clamps_audio, balanced_split, derive_target_disabled_below_floor, derive_target_lowest_step, derive_target_highest_step, smoothing_limits_jump, mode_roundtrip)
• Tests modified: 0
• cargo clippy -p wzp-video --all-targets -- -D warnings: pass
• cargo fmt --all -- --check: pass

Risks / follow-ups

1. VideoEncoder::set_target() is a no-op default — Platform encoders (VideoToolbox, MediaCodec) need to override this to actually reconfigure bitrate/resolution/fps.
2. Step table is H.264-only — When H.265/AV1 land (T5.4+), the step table may need different thresholds per codec.
3. ScreenShare slide fallback not yet implemented — T5.3 will add EncoderMode::SlideFallback triggered when video budget < 150 kbps.
4. Controller not yet wired into call engine — SetPriorityMode signal (T5.1) and VideoQualityController::tick() need to be plumbed into wzp-client/src/call.rs and the Android/desktop engines.

Reviewer checklist (filled in by reviewer)

• Code matches PRD intent
• Verification output is real
• No backward-incompat surprises
• Tests cover the new behavior
• Approved