From 4a321b19ff8c829351cc73c43196a2f2adeca61f Mon Sep 17 00:00:00 2001 From: gramps Date: Mon, 31 Aug 2026 20:30:50 -0700 Subject: [PATCH] docs: rewrite HANDOFF for clean session end (fully pushed, project-wide read, no-suggestions note) --- HANDOFF.md | 126 ++++++++++++++++++++++------------------------------- 1 file changed, 52 insertions(+), 74 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index b71d432..b3be0d4 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -2,89 +2,54 @@ ## Branch / Commit State -**`main`**, working through TASK 21 (media source). Local commits ahead of -`origin/main` (not yet pushed — user pushes at agreed checkpoints): +**`main`**, clean working tree, **fully pushed to `origin/main`** (nothing pending). +Last work boundary: `097dd0d` (docs: hand off TASK 21 UI picker slice). No uncommitted +work; no local commits ahead of origin. + +Recent commit series (all pushed, before this session's end): +- `097dd0d` — docs: hand off TASK 21 UI picker slice (acquisition + loop wiring spec) +- `881addb` — TASK 21 slice 3: loop control in MediaVideoSource (process factory + Loop flag) +- `a2219be` — TASK 21 slice 2b: native-FPS pacing in MediaVideoSource (probe -> delay seam) +- `8fa7842` — TASK 21 slice 2a: native-FPS probe seam (ffprobe parse + derive sibling) +- `071ec8b` — TASK 21 slice 1 step 4: wire media into resolver + preview routing +- `480ead0` — TASK 21 slice 1 step 3: IMediaFrameSource + MediaVideoSourceManager - `a1d9751` — docs: ffmpeg decode-contract verification recipe + WSL CLR boundary - `8f49010` — TASK 21 Increment B: FFmpeg rawvideo video decoder -> VideoFrame -- `f89b9f9` — docs: default-device audio assumption (README + startup log) -- `e8ff4df` — TASK 22: global audio sync offset (positive delay at the mixer out) -Prior milestones pushed through `origin/main`: TASK 31 (`3bf053a..670fe3a`), plus -the full refactor series (Commit F `3107f92`, Commit G `85893ea`). +## Why the session ended + +User ready for a break after a substantial day. No mid-flight work — everything is +committed and pushed. This is a clean stopping point. ## What's In Flight -**TASK 21 (media source) — all headless-testable decoder/mechanism slices shipped (slice 1 + 2a + 2b + 3); the remaining UI-picker (acquisition) slice is handed off below — it is a GUI feature to build + verify on native Windows.** +Nothing actively mid-flight. The last TASK 21 work unit (the **UI picker / acquisition +slice**) is **handed off**, not in progress — spec reproduced in the section below. +It is a GUI feature that must be built + verified natively on Windows. -Increment A (the `Source` model: `MediaSourceType`, `SourceType.MediaSource`, -`MediaPath`/`MediaIsLooping`/`MediaVolume`/`MediaPlaybackState` + LayoutStore -persistence) and Increment B (the decoder `MediaVideoSource`) shipped earlier. +## Project-wide code-complete picture (2026-08-31, user's framing) -This session: -- Refactored `Services/MediaVideoSource.cs` onto the new - `Services/IMediaFrameSource.cs` (`Key`, `FrameAvailable`, `Completed`, - `StartAsync`/`StopAsync`; `Start`→`StartAsync`, `FrameReady`→`FrameAvailable`) - — behavior preserved, `MediaVideoSourceTests` updated and passing. -- Added `Services/MediaVideoSourceManager.cs` — app-wide decode-session - ownership refcounted by `MediaPath`, `Func` factory - seam, `AcquireAsync`/`ReleaseAsync`/`ReleaseAllAsync`/`GetLatestFrame`, frames - coalesced onto the UI dispatcher onto one shared `WriteableBitmap` per file, - `MediaFailed` + `PreviewBitmapChanged`. Structural mirror of `ScreenCaptureManager`. -- Added `ytLive.Tests/MediaVideoSourceManagerTests.cs` (5 unit + 1 integration: - single shared bitmap, coalesce-to-latest). **Verified: all 10 media tests pass - (5 manager + 3 reader + 1 decoder integration + 1), build 0 warnings.** +The user revisited the ongoing "how code-complete are we" question. Current agreed read: -Slice 1 step 4 (wire-in) shipped: `_mediaManager` wired in the core ctor -(`path => new MediaVideoSource(path, 1920, 1080, new FfmpegLocator(), new FfmpegDecodeProcess())`, -dispatched preview), `OnMediaPreviewBitmapChanged` sets `VideoImageSource` on every -`IsMediaSource` with a matching `MediaPath`, a `Source { IsMediaSource, MediaPath }` -case in `ResolveOutputFrame` feeds `_mediaManager.GetLatestFrame`, `Source.DisplaySource` -routes `VideoImageSource` for `MediaSource`, and the manager is disposed on shutdown. -Lives in the new `ViewModels/MainViewModel.Media.cs` partial. **Verified: 14/14 -media + DisplaySource tests pass, build 0 warnings.** +- **Feature/code completeness ≈ 88–92%**, after removing from consideration: + - **TASK 13 = MARCOM, not code** (social media launch kit) — does not count against code-complete. + - **TASK 10 (monetization / Polar billing / Velopack distribution + updater) — deliberately + parked by the user until it is the dead-last thing to do.** Not a blocker for feature completion. +- Remaining real code before feature-complete: + - **TASK 21 UI picker** slice (the handoff below) — the one genuinely open feature unit. + - **TASK 9** — visibility picker (drop the always-Private lock, let user pick + Private/Unlisted/Public) + a couple stream-management items. + - **TASK 4** — background removal (excluded by design) + a few capture-pipeline items. +- **Biggest actual risk is not code — it is the missing native-Windows verification pass.** + Real ffmpeg media decode/loop/pacing, recording, and the GUI suites have only ever run + headless in WSL or against fakes. Crossing-the-line "works on Windows" readiness is lower + than the code-complete number would suggest until that pass happens. -Next (slice 1 step 4's remaining open end): no session acquisition yet — nothing -`AcquireAsync`s a media path, so no frames flow until the UI picker (a later slice) -starts a session on add and releases on remove. +## @ User note — no suggestions for the time being -Slice 2a shipped: the native-FPS **probe seam** (not yet wired into pacing). -`Services/FfmpegFrameRateParser.cs` (pure — prefers `avg_frame_rate=` then -`r_frame_rate=`, rational `N`/`N/M`, unknown→null), `Services/FrameRateProbe.cs` -(`IFrameRateProbe` + `FfmpegFrameRateProbe` — derives sibling `ffprobe.exe` from -the located ffmpeg dir, reuses the `IDecodeProcess` seam for the ffprobe -subprocess text, null if ffprobe absent), and `FfmpegLocator.ProbeFileName` -(`ffprobe.exe`) + conditional extraction alongside ffmpeg.exe. Tests: -`ytLive.Tests/FfmpegFrameRateParserTests.cs` (6 pure units + 1 probe integration -via fake locator/process); `FfmpegLocatorTests` still green — 15/15 pass, build -0 warnings. Slice 2b shipped too: `MediaVideoSource` now takes optional -`IFrameRateProbe?` + `Func? delay` seams, -probes FPS once in `RunAsync`, and paces each emitted frame by 1/fps (unknown/ -absent probe → no pacing). New test `MediaVideoSource_PacesFramesByProbedFps` -(fake probe + recording delay, one delay per frame ≈1ms). Media tests 5/5, -build 0 warnings. - -Next (slice 3): loop control — SHIPPED. `MediaVideoSource` takes a -`Func` process factory (a single `Process` can't be re-`Start()`ed, -so each loop pass creates a fresh decoder) and wraps the decode in a -`do…while (Looping)` restart, keyed on the new `IMediaFrameSource.Looping` flag; -Production wiring in `MainViewModel` (media factory) now passes the factory AND -`FfmpegFrameRateProbe` (closing the slice-2b gap where production had no probe → -no pacing). Loop test `MediaVideoSource_LoopsUntilLoopDisabled` (single frame -re-emits, `Completed` only when loop cleared) — media tests 12/12 (6 source + 6 -manager), build 0 warnings. Open: wiring `Source.MediaIsLooping` into -`IMediaFrameSource.Looping` needs a manager-level per-path loop provider — lands -with the UI picker (acquisition) slice. - -**Landmine:** a stale `testhost` can lock `ytLive.Tests`'s `ytLive.dll` and break -`dotnet build` of the test project — kill it first (`cmd.exe /c "taskkill /PID N /F"`) -on MSB3027. Full-suite vstest hangs headless (RealAppHost/WASAPI) — only filtered -pure tests run in WSL; user verifies the GUI suites on native Windows PowerShell -(which may also hang if WASAPI startup blocks — pre-existing, not this change). - -## Next - -1. **(Handed off) UI picker slice** — the last TASK 21 work unit. GUI feature; build + verify natively on Windows. -2. Await user push checkpoint for the pending commits (TASK 22 + TASK 21 slices below). +The user asked to **stop with forward-looking suggestions** (they read as distracting). Do +not volunteer next-step options or "what's next" lists unless the user asks. Answer what is +asked; stay quiet on roadmap unless prompted. ## UI picker slice — handoff spec (2026-08-31) @@ -108,10 +73,23 @@ but a media Source has no way to start a session. Deliverables, in order: **Design notes to preserve:** `ResolveOutputFrame` reads `_mediaManager.GetLatestFrame(MediaPath)`; `OnMediaPreviewBitmapChanged` adopts the shared `WriteableBitmap` per path; `MediaFailed` → -`OnMediaFailed` (currently `Debug.WriteLine`, surface in UI). Composer scales any frame size. -Tmpl: the real-ffmpeg decode/loop/restart path is only exercised natively on Windows — first +`OnMediaFailed` (currently `Debug.WriteLine`, surface in UI). Composer scales any frame size +(media renders through the generic `frameFor(element)` path — no compositor change needed). +The real-ffmpeg decode/loop/restart path is only exercised natively on Windows — first GUI smoke test should add a short mp4, confirm it plays and previews, then crash further. +## Landmine + +- A stale `testhost` can lock `ytLive.Tests`'s `ytLive.dll` and break `dotnet build` of the + test project — kill it first (`cmd.exe /c "taskkill /PID N /F"`) on MSB3027. +- Full-suite vstest hangs headless (RealAppHost/WASAPI) — only filtered pure tests run in + WSL; user verifies the GUI suites on native Windows PowerShell (which may also hang if + WASAPI startup blocks — pre-existing, not this change). +- **WSL can only run the Windows-bound dotnet CLR shim** — it cannot spawn Linux ffmpeg/ffprobe + (Win32Exception 193). Verify ffmpeg contracts via shell/python; leave CLR→real-ffmpeg to the + native Windows suite. Linux static ffmpeg/ffprobe 7.0.2 live at + `/tmp/opencode/ffmpeg-7.0.2-amd64-static/`; `/tmp/opencode/clip.mp4` = 640x360 30fps 1s. + ## The directive (2026-08-31, user) Rewrite the project into functional components to aid AI retrieval —