From e812f41ef1ca5ddd453d38efa4854c18ad4e51d9 Mon Sep 17 00:00:00 2001 From: BenStullsBets Date: Wed, 24 Jun 2026 08:19:41 -0700 Subject: [PATCH] docs: content-sourcing procedure + roadmap update + setup docstring (content pipeline Increment 1) Co-Authored-By: Claude Sonnet 4.6 --- docs/ROADMAP.md | 43 +++++++++++++++++++++------------ docs/content-sourcing.md | 29 ++++++++++++++++++++++ simulator/setup_scales_media.py | 22 +++++++++-------- 3 files changed, 69 insertions(+), 25 deletions(-) create mode 100644 docs/content-sourcing.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 2e51d15..dea5dac 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -170,21 +170,34 @@ every transition, so fast navigation stays responsive on placeholder media. contract** with the firmware (the keyboard/serial stand-in already works via a `Controls` stream). - **White-noise generation** — runtime white/pink noise for that content position. -- **Offline v2v variant pipeline** — author the pre-baked Right restyle variants - via the local flow-stabilized SD pipeline (now ~free, not a paid API — see the - scales-library/right-axis design §1/§4); a real multi-strength flow-stabilized - re-bake per base clip + the multilingual label/string tables + TTS. The - **scale-ring transitions** (forward/reverse per-edge morphs) are part of this - offline pipeline too. - - **Vertical slice done (session 0012):** the Right-variant half is - productionized and run for the **forest** scale — `simulator/bake_right_variants.py` - (the POC flow-restyle algorithm, repo-resident) bakes real strengths 1–4 on a - by-eye keyframe-strength ramp; forest now carries real Right variants in the - sim, so the dreamlike-axis look is judgeable on real footage. **Still - deferred:** real Right variants for cosmos/abyss (need their real strict-PD - bases sourced first) and the **real i2v ring transitions** (need a 2nd real - base + a generative-video model not in the POC). Plan: - [`2026-06-08-v2v-vertical-slice-forest-right-variants.md`](./superpowers/plans/2026-06-08-v2v-vertical-slice-forest-right-variants.md). +- **Content pipeline + label track** — source strict-PD neutral bases, run them + through the offline pipeline, and author the annotation tracks that drive the + Left-HUD overlay. The Right dream is now **real-time** (Kuwahara WebGL shader, + session 0013 — no per-clip ML bake), so the pipeline is + **source → crossfade-loop → master+proxy transcode → hand-authored / + motion-tracked labels → manifest**, not ML baking. Historical note: the + flow-stabilized SD-turbo v2v bake (session 0012, `simulator/bake_right_variants.py`) + was superseded when the operator found the baked-SD Right "too fluid" and the + design pivoted to the deterministic real-time dream; `bake_right_variants.py` + is now parked. Spec: + [`2026-06-24-content-pipeline-design.md`](./superpowers/specs/2026-06-24-content-pipeline-design.md). + + - **Increment 1 — deterministic tooling + 5-scale ring (session 0014) ✅ Done.** + `tools/pipeline/` (frame/loop/transcode/manifest, pure + unit-tested + an + opt-in integration test on real footage); the backward-compatible keyframed + annotation-track schema with client interpolation; and the **full 5-scale ring** + (cosmos → orbit → forest → reef → abyss) with orbit + reef as placeholder + scales alongside the existing cosmos/abyss/forest. Plan: + [`2026-06-24-content-pipeline-increment-1.md`](./superpowers/plans/2026-06-24-content-pipeline-increment-1.md). + + - **Increment 2 — hybrid motion-track pass + author mode (pending).** The + `tools/pipeline/track.py` classical OpenCV tracker + optional ML detect+track, + plus a simulator **author mode** for reviewing/editing annotation tracks in the + browser. Real strict-PD bases for all five scales sourced per + [`docs/content-sourcing.md`](./content-sourcing.md). + + - **Still deferred:** real **i2v ring transitions** (need a generative-video + model + adjacent real bases); Pi renderer + serial/firmware. - **Catalog model changes** — audio *source* + "neutral base" vs "altered variant" flag (sub-project 2 territory, design §13). diff --git a/docs/content-sourcing.md b/docs/content-sourcing.md new file mode 100644 index 0000000..1ad7966 --- /dev/null +++ b/docs/content-sourcing.md @@ -0,0 +1,29 @@ +# Content sourcing — strict-PD neutral bases + +For each scale, acquire a calm, neutral source clip from a **strict public-domain** +US-government source, verify the license, then run it through the pipeline. + +| Scale | Source | Where | +|--------|--------------------------------|------------------------------------| +| cosmos | NASA / Hubble / JWST | https://images.nasa.gov/ | +| orbit | NASA / ISS | https://images.nasa.gov/ | +| forest | NPS / USGS | https://www.nps.gov/ , https://www.usgs.gov/ | +| reef | NOAA Ocean Exploration | https://oceanexplorer.noaa.gov/ | +| abyss | NOAA Ocean Exploration | https://oceanexplorer.noaa.gov/ | + +**License check (mandatory):** confirm the asset is US-gov PD (17 U.S.C. §105) or +explicitly CC0. "Free stock" (Pexels/Pixabay/etc.) is royalty-free but NOT public +domain — do not use. Record a `Provenance` (tools/pipeline/provenance.py) per clip. + +**Run the pipeline** (replaces the placeholder bytes for a scale): + +```bash +python -c "from tools.pipeline.run import process_clip; \ + process_clip('downloads/.mp4', 'simulator/sample_media/', \ + start=, duration=, overlap=<0.5..1.0>)" +``` + +This writes `simulator/sample_media//base.mp4` (proxy) + `master.mp4`. Then +author the labels (Increment 2: the hybrid track pass + simulator author mode) or +hand-edit the annotation track for now (spec §4). The ring + manifest entry already +exist; `process_clip` only replaces the media bytes. diff --git a/simulator/setup_scales_media.py b/simulator/setup_scales_media.py index 9fe1dba..2c3a767 100644 --- a/simulator/setup_scales_media.py +++ b/simulator/setup_scales_media.py @@ -1,16 +1,18 @@ -"""Generate cheap placeholder media for the scale RING (scales design §3). +"""Generate cheap placeholder media for the full 5-scale RING (scales design §3). -The ring needs >=2 neutral scales to be demonstrable. This script produces -cheap, offline, synthetic placeholders for the two true-PD scales the ring adds — -**cosmos** (NASA/Hubble) and **abyss** (NOAA Ocean Exploration) — plus the short -zoom/warp **transition** clips between adjacent scales. Forest reuses the real -POC base from `setup_sample_media.py` (or a synthetic placeholder if absent). +Produces offline synthetic placeholders for all five ring scales — **cosmos** +(NASA/Hubble), **orbit** (NASA/ISS), **forest** (NPS/USGS), **reef** (NOAA Ocean +Exploration), and **abyss** (NOAA Ocean Exploration) — plus the short zoom/warp +**transition** clips between adjacent scales. Forest reuses the real POC base from +`setup_sample_media.py` (or a synthetic placeholder if absent); all others are +generated as labelled solid-tint clips. This is deliberately the CHEAP path: the manifest records the real true-PD -provenance (NASA 17 U.S.C. §105 / NOAA PD), but the bytes here are labelled -synthetic placeholders for look-tuning the ring navigation. The expensive real -multi-strength flow-stabilized Right re-bake is DEFERRED until the ring is liked, -so the new scales carry a raw base only (no Right variants). +provenance (NASA / NPS / USGS / NOAA, 17 U.S.C. §105), but the bytes here are +labelled synthetic placeholders for look-tuning the ring navigation. The Right dream +is real-time (Kuwahara WebGL shader), so no per-clip ML bake is needed; each scale +carries a raw base only. Real strict-PD bases replace these placeholders via the +content pipeline (see `docs/content-sourcing.md`). Usage: python simulator/setup_scales_media.py Requires: ffmpeg on PATH (or `pip install imageio-ffmpeg`).