Support split WebRTC timing and THWC frame chunks

[jarcherNV]

Add shared WebRTC runtime hooks for integrations whose input sampling cadence differs from their output video cadence. The session manager now uses optional input FPS, input frame count, and steady output frame count hooks while keeping the legacy runtime methods as defaults.

Add periodic WebRTC performance logging, support THWC uint8 realtime frame chunks, and relax block KV cache rolling so cache sizes do not need to be divisible by chunk size.

Cover the shared behavior with focused realtime, WebRTC manager, and KV cache tests.

[greptile-apps]

Greptile Summary

This PR adds optional split-clock hooks to BaseWebRTCSessionManager so integrations whose input sampling cadence differs from their output video cadence can provide separate FPS, input-frame-count, and steady-output-frame-count values while legacy single-clock runtimes continue to work unchanged. It also relaxes BlockKVCache to allow non-divisible total_size / chunk_size, adds THWC uint8 frame-chunk dispatch, and introduces periodic WebRTC performance logging.

• Split-clock hooks (peek_input_fps, peek_next_input_num_frames, peek_steady_output_num_frames) use getattr/callable guards in the manager and fall back to the existing peek_next_chunk_num_frames / peek_steady_chunk_num_frames Protocol methods, making the change fully backward-compatible.
• KV cache relaxation removes the (window_size + sink_size) % chunk_size == 0 assertion; _roll_local_window_left now accepts any 0 < shift_size ≤ chunk_size overflow, and the (1, 16) parametrize entry covers the first non-divisible case in CI.
• THWC uint8 support adds shape[-1] == 3 and shape[1] != 3 to disambiguate THWC from TCHW, with TCHW preferred when both dims equal 3 and a dedicated test confirming the tie-break.

Confidence Score: 5/5

Safe to merge; all changed paths are well-tested and the fallback chain ensures no regressions for existing runtimes.

The split-clock hooks use a getattr/callable guard pattern that is entirely additive and backward-compatible. The KV cache divisibility relaxation is mathematically sound — the shift-size assertion in _roll_local_window_left bounds overflow to ≤ chunk_size by construction, and the non-divisible (sink=1, window=16) parametrize case exercises the first non-trivial rolling transition. The THWC dispatch adds a shape[1] != 3 guard that resolves the pre-existing ambiguity noted in prior review threads. New tests cover all three feature areas with focused, targeted cases.

No files require special attention.

Important Files Changed

Filename	Overview
flashdreams/flashdreams/core/attention/kvcache.py	Removes divisibility assertion and relaxes _roll_local_window_left to handle arbitrary overflow ≤ chunk_size; math verified correct for non-divisible total sizes.
flashdreams/flashdreams/serving/realtime/media.py	Adds THWC uint8 dispatch in tensor_chunk_to_rgb_frames with shape[1] != 3 guard; previous thread ambiguity addressed and covered by new tests.
flashdreams/flashdreams/serving/webrtc/manager.py	Adds split-clock accessor helpers with getattr/callable fallback guards and periodic perf logging; resampler and video track wired to separate input/output frame counts.
flashdreams/flashdreams/serving/webrtc/runtime.py	Documents optional split-clock Protocol methods; existing required methods unchanged.
flashdreams/tests/test_kvcache.py	Extends parametrize to include non-divisible (sink=1, window=16) case; CUDA-graph parametrize likewise extended.
flashdreams/tests/test_realtime_serving.py	New tests cover THWC uint8 chunks, TCHW preference when width equals 3, and bfloat16 promotion; all existing tests retained.
flashdreams/tests/test_webrtc_manager.py	New tests cover split input/output frame counts, periodic perf logging, and step-action path; generation-worker error-handling tests retained.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Manager as BaseWebRTCSessionManager
    participant Runtime as WebRTCSessionRuntime
    participant Resampler as KeyboardResampler
    participant Track as BufferedVideoTrack

    Client->>Manager: create_answer(offer_sdp)
    Manager->>Runtime: peek_steady_output_num_frames()
    Runtime-->>Manager: output_num_frames
    Manager->>Track: "BufferedVideoTrack(fps=output_fps, maxsize=output_num_frames)"
    Manager->>Runtime: peek_input_fps()
    Runtime-->>Manager: input_fps
    Manager->>Resampler: "KeyboardResampler(fps=input_fps)"
    Manager-->>Client: answer SDP

    loop Generation Worker (per chunk)
        Manager->>Runtime: peek_next_input_num_frames()
        Runtime-->>Manager: input_num_frames
        Note over Manager: sleep(input_num_frames / input_fps)
        Manager->>Resampler: sample_chunk(input_num_frames)
        Resampler-->>Manager: segments, frame_times
        Manager->>Runtime: generate_chunk(segments, frame_times)
        Runtime-->>Manager: WebRTCStepResult(num_frames, video_chunk)
        Manager->>Track: enqueue_chunk(video_chunk)
        Note over Manager: Log perf every N chunks
        Manager->>Client: "chunk_done(num_frames=result.num_frames)"
    end

Loading

_{Reviews (2): Last reviewed commit: "Address GitHub PR review feedback" | Re-trigger Greptile}

[gtong-nv]

LGTM