Screen share 1: fluxer-video crate — frames, conversions, FrameBus, test pattern, preview JPEG (#148) #188
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "screenshare-1-video-frames"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What this builds
New crate
crates/fluxer-video(pure Rust; depends only onimageandthiserror; no OS, LiveKit or iced dependency):frame:VideoFrame { width, height, timestamp_us, data: FrameData },FrameData::{I420 { y, u, v, strides }, Nv12 { y, uv, strides }, Bgra { data, stride }, Rgba { data, stride }}withArc<[u8]>planes andu32byte strides;VideoFrame::{i420, nv12, bgra, rgba}constructors for tightly packed frames;validate(),FrameError,PixelFormat.convert:bgra_to_i420,i420_to_rgba,nv12_to_i420, plusto_i420/to_rgbafrom any format. They returnResult<VideoFrame, FrameError>.scale::area_downscale(&VideoFrame, max_w, max_h) -> VideoFrame: a box filter that keeps the aspect ratio and returns even dimensions.pattern::TestPattern::new(w, h).frame(n)andpattern::read_counter: a row of 2 sync cells and 16 counter bits, above 8 moving colour bars.jpeg::preview_jpeg/preview_jpeg_with(&frame, &PreviewBudget): the fork'spreviewEncoding.tsloop with theStreamConstants.tsvalues.bus:FrameBus(Clone + Send + Sync) withpublish,get,generation,removeandkeys, andVideoKey::{Remote { sid }, LocalCapture, Preview { stream_key }, Source { id }}.How it was tested
cargo test -p fluxer-video: 20 tests intests/{convert,bus,jpeg}.rs. They cover every test the plan names, plus odd sizes and padded strides, NV12, malformed frames (they return errors and never panic), a tight budget that lowers quality and then size, an impossible budget, the counter read back from a decoded JPEG, and checks that the bus does not keep replaced frames and that removed keys never reuse a generation.libwebrtc.a(webrtc-a545de4) and dumpedI420ToABGRover a 232k-point YUV grid andARGBToI420over a 140k-point RGB grid. I also dumpedARGBToI420chroma for 2,000 random 64x2 images, so the 2x2 chroma averaging was checked too. Our output matched every value exactly. The known-colour tests use values taken from that program.gettake the writer lock whilepublishslept 6 ms inside it, andbus_reader_never_blocks_writerthen failed with "329 reads blocked for 5 ms or more". The real implementation passes repeatedly at load average about 38.FLUXER_SCREENSHOT_TESTS=1 cargo xtask cipasses locally. No real-device tests apply to this task.Deviations from the plan
bgra_i420_round_trip_within_2_levels: "within 2 levels" cannot hold for every colour while staying bit-exact with libyuv, as the plan requires. libyuv's own BT.601 limited-range round trip loses up to 3 levels of red and 5 of blue on some saturated colours (measured on libyuv itself: about 12% of random colours are off by more than 2). The main causes are that libyuv caps UB at 128 instead of 2.018 × 64, and chroma is rounded to 8 bits. The test keeps its name and asserts:bus_reader_never_blocks_writer: on Linux the test measures blocked time (wall time minus on-CPU time and run-queue time from/proc/thread-self/schedstat) instead of wall time. A plain 5 ms wall-clock limit flaked on this loaded machine because of preemption, not because of locks. On other OSes it uses wall time and tolerates 3 slow calls.FrameBususesstdonly. The spec says "lock-free for the reader (one atomic swap per write)", but no task addsarc-swap. Each key has twoRwLockslots and an atomic current index. A writer fills the spare slot and flips the index, so a reader takes an uncontended read lock just long enough to clone anArc. Generations come from one counter for the whole bus and are taken under the per-key writer lock, so they only grow, even after a key is removed and published again.Result;area_downscalereturns a frame that already fits, or a malformed frame, unchanged;read_countergivesn mod 65536.Cargo.tomlneeded no change:crates/*is already a member glob, andimagealready hasjpeg. OnlyCargo.lockchanged outside the crate.Commit attribution is Claude Opus 5.5, the model that did the work; the repo
CLAUDE.mdnames Fable 5.2.Closes #148
🤖 Generated with Claude Code
Independent review: Screen share 1 (fluxer-video), commit
8b8a359I read the diff
53e3d60..origin/screenshare-1-video-framescold. It adds thefluxer-videocrate and a Cargo.lock entry.1. Plan tests. All eight named tests exist and pass. Plain reading of each:
i420_to_rgba_known_coloursmatches libyuv. I checked the blue value by hand: Y41/U239 gives B=251.area_downscale_keeps_aspect_and_even_dimscovers 1920x1080, 1366x768, 1001x3001, 4K and 7x5.pattern_counter_survives_blur_and_downscalereads the counter within ±1 after a blur and a downscale.preview_keeps_the_picturealso checks it after a real JPEG round trip.preview_jpeg_respects_size_and_bytes_budgetuses 4K noise and gets 640x360 within 1 000 000 bytes.bus_latest_frame_winsandbus_remove_forgets_keypass.bus_reader_never_blocks_writerwrites at 1 kHz for 2 s and checks monotonic generations and no stall over 5 ms.2. Interfaces. Every name in the Interfaces block exists as written:
VideoFrame,FrameData,convert::{bgra_to_i420, i420_to_rgba, nv12_to_i420},scale::area_downscale,pattern::{TestPattern, read_counter},jpeg::{preview_jpeg, JpegError},VideoKeyand the fiveFrameBusmethods.FrameBusisClone + Send + Sync. Choices the plan left open:Result<VideoFrame, FrameError>.u32.PreviewBudget,preview_jpeg_with,to_i420andto_rgba.These are fine for Tasks 3, 6, 16, 17 and 21.
3. Invariants.
image(workspace,jpegalready enabled) andthiserror. No OS, LiveKit or iced dependency, and no I/O.validate()first, so a malformed frame is anError is passed through unchanged. I found no panic path for decoder or server data. I also checked sizes like 4000x1 and a max of 1 inarea_plane's spans.4. Review Focus 6. The reader takes no writer mutex. It holds a per-slot read lock only for an
Arcclone, and frames are dropped outside the locks. One frame per key, and the latest wins. Generations come from a bus-wide counter, so a key that is removed and published again never reuses one.I checked the
Slot::publish/getinterleavings, including two publishes during one read. The retry when an emptied slot is no longer current is correct, and generations seen by a reader are monotonic.5. Local CI.
FLUXER_SCREENSHOT_TESTS=1 cargo xtask ciis green: "all steps passed", exit 0. A second run I started at the same time on the same target dir failedxtask --test packagebecause both runs used the same appimagetool.partialpath. Run alone, that test passes. It is unrelated to this diff.Findings
src/bus.rs,Slot::publish):generationis stored beforecurrentflips. During that window,generation(&key)can return g+1 whileget(&key)still returns frame g. Task 6 will comparegeneration(). If a widget records the g+1 fromgeneration()but uploads frame g, it will not redraw until the next publish. That matters for one-off keys (Preview,Source), where the next publish can be 60 s away or never. The window is tiny. Fix: storegenerationafter thecurrentflip (an early read then only causes a harmless extra redraw), or tell Task 6 to key its redraws on the generationgetreturns.src/bus.rs): apublishracing aremoveof the same key may write into the removed slot, so the frame is lost silently. Apublishafterremovebrings the key back. Both are acceptable, but the runtime (Task 21) must stop the producer before it removes a key. A line in the README would help.RwLockread sections instead. The README states this and it meets Focus 6. No change needed, just noting the deviation.CLAUDE.mdnames Fable 5.2. The integrator should decide which is right.Verdict: APPROVE. No blocking findings and local CI is green. I would like the
generationstore-order fix before Task 6 relies on it, but it does not block this PR.