Rename Spout launcher as diagnostic

This commit is contained in:
Meta Vens 2026-05-19 09:04:02 +01:00
commit 94e76e09be
9 changed files with 14 additions and 13 deletions

View file

@ -83,7 +83,7 @@ Source-event analysis command:
Synchronized Aquarium/Spout publisher command:
```powershell
.\.venv\Scripts\python.exe .\scripts\stream_spout.py --source cultcache --frame-cache .\calibration\runs\visual-state.msgpack --audio-cache .\calibration\runs\audio-state.msgpack --audio-events-cache .\calibration\runs\audio-events.msgpack --sync-status .\calibration\runs\av-sync-status.json
.\.venv\Scripts\python.exe .\scripts\diagnostic_stream_spout.py --source cultcache --frame-cache .\calibration\runs\visual-state.msgpack --audio-cache .\calibration\runs\audio-state.msgpack --audio-events-cache .\calibration\runs\av-sync-status.json
```
## Invariants

View file

@ -63,7 +63,7 @@ shape removes independent per-kind storage from the live foundation.
- Live fallback-only RGB/Leap mode exists for deadline operation when OpenCV/MSMF/DirectShow reads block longer than the five-second reservoir. It keeps the reservoir and OBS output alive while real camera capture is moved to nonblocking ingress.
- OpenCV camera reads now run behind `LatestFramePump` workers so blocking drivers cannot freeze the fusion hot loop. The live deadline command uses lower per-frame sample density (`--rgb-room-step 16 --leap-step 16 --points 64`) so the reservoir/TAA path stays fresh enough for Spout to render visual points inside the five-second budget.
- `localcast.sensor_fusion.chirp_pose` converts live phase-field delay meaning for Kiyo/PS Eye microphone sources into camera-body range constraints and per-camera pose-correction estimates. It can load camera-mic and speaker geometry from the audio-field profile, with the example profile used as the live fallback until measured local geometry exists. `scripts/diagnostic_live_sensor_fusion.py` injects those constraints as `camera-chirp:*` and `camera-pose-correction:*` render points plus `chirp-camera-pose` LOD evidence.
- `scripts/stream_spout.py` runs the deadline Spout sender loop from the typed cache with typed and JSON heartbeat status.
- `scripts/diagnostic_stream_spout.py` runs the deadline Spout sender loop from the typed cache with typed and JSON heartbeat status. This is diagnostic/migration code, not production runtime.
- The deadline Spout renderer has a named `kiyo-mid-deru` virtual camera preset: eye at the midpoint between the two Kiyo-class cameras and target on the co-streamer body volume. It also applies a renderer-owned point budget with pinned calibration/cross-modal constraints, stable high-confidence anchors, and frame-varying remainder samples so downstream TAA/supersampling can accumulate detail without forcing every source claim into every OBS frame. Its JSON heartbeat reports the prefix counts that survived the render budget.
- `docs/obs-spout-streaming.md` documents OBS setup and the Aquarium replacement boundary.
- `docs/typed-visual-state.md` documents the CultCache/CultNet visual boundary.

View file

@ -30,10 +30,10 @@ OBS should be open before the sender starts if OBS is the SRT listener. If a sou
## Synchronization
The video SRT source is a timed media artifact in the Aquarium path, not just scenery in OBS. Keep the listener URL and latency aligned with `stream_spout.py`:
The video SRT source is a timed media artifact in the Aquarium path, not just scenery in OBS. Keep the listener URL and latency aligned with `diagnostic_stream_spout.py` while the diagnostic bridge still exists:
```powershell
.\.venv\Scripts\python.exe .\scripts\stream_spout.py `
.\.venv\Scripts\python.exe .\scripts\diagnostic_stream_spout.py `
--remote-video-url "srt://0.0.0.0:5100?mode=listener&latency=120000&timeout=5000000" `
--remote-video-latency-ms 250
```

View file

@ -11,7 +11,7 @@ This is the deadline stream surface. It is not a preview window and it is not a
```mermaid
flowchart TD
A["Sensor fusion producer"] --> B["CultCache render-frame doc"]
B --> C["scripts/stream_spout.py"]
B --> C["scripts/diagnostic_stream_spout.py"]
C --> D["ScreenBrushPacket lowering"]
D --> E["OpenGL texture/FBO"]
E --> F["Spout sender texture"]
@ -33,7 +33,7 @@ Install calibration/runtime dependencies once:
Start the Spout sender:
```powershell
.\.venv\Scripts\python.exe .\scripts\stream_spout.py `
.\.venv\Scripts\python.exe .\scripts\diagnostic_stream_spout.py `
--source cultcache `
--frame-cache .\calibration\runs\visual-state.msgpack `
--demo-if-missing `

View file

@ -75,7 +75,7 @@ flowchart TD
- `localcast.sensor_fusion.cultcache_docs` owns the typed CultCache document boundary for live visual state.
- `localcast.diagnostics.spout_output` owns the deadline OBS publication sink: render-frame packet in, GPU texture plus Spout sender heartbeat out. It is diagnostic/migration code, not the production visual authority.
- `scripts/sensor_fusion.py` owns CLI composition for offline observation files.
- `scripts/stream_spout.py` owns the live Spout sender loop for OBS.
- `scripts/diagnostic_stream_spout.py` owns the diagnostic Spout sender loop for OBS.
- `config/sensor-fusion.example.json` owns the declarative rig shape: capture hints, intrinsics, extrinsics, latency, and fusion thresholds.
## Cache Discipline

View file

@ -17,7 +17,7 @@ flowchart TD
Z["audio-events.msgpack"] --> Y
D --> Y
Y --> E["CultCache MessagePack store"]
E --> F["stream_spout.py"]
E --> F["diagnostic_stream_spout.py"]
F --> G["ScreenBrushPacket lowering"]
G --> H["Spout sender"]
H --> I["OBS Spout2 Capture"]
@ -84,14 +84,14 @@ frames presentable.
## Audio Synchronization
`stream_spout.py` can now read `calibration/runs/audio-state.msgpack` and `calibration/runs/audio-events.msgpack` while it renders the visual frame. It selects source events against `RenderFramePacket.audio_alignment_time_ns`, adds synchronized audio-event points to the render packet, and writes `calibration/runs/av-sync-status.json` with the active visual frame id, audio frame id, audio delta, event count, overlay count, and remote video sync status.
`diagnostic_stream_spout.py` can read `calibration/runs/audio-state.msgpack` and `calibration/runs/audio-events.msgpack` while it renders the diagnostic visual frame. It selects source events against `RenderFramePacket.audio_alignment_time_ns`, adds synchronized audio-event points to the render packet, and writes `calibration/runs/av-sync-status.json` with the active visual frame id, audio frame id, audio delta, event count, overlay count, and remote video sync status.
The audio bed still travels as `localcast.audio.spatial_frame`; the visual render packet only receives renderer-visible transient geometry. That keeps the machine legible: audio owns sound, source-event analysis owns acoustic facts, Aquarium owns the final pixel/audio package for OBS.
The neighbor SRT video feed is also a timed media artifact. For the deadline path, `stream_spout.py` records its URL and expected SRT latency in the sync status:
The neighbor SRT video feed is also a timed media artifact. For the diagnostic deadline path, `diagnostic_stream_spout.py` records its URL and expected SRT latency in the sync status:
```powershell
.\.venv\Scripts\python.exe .\scripts\stream_spout.py `
.\.venv\Scripts\python.exe .\scripts\diagnostic_stream_spout.py `
--source cultcache `
--frame-cache .\calibration\runs\visual-state.msgpack `
--audio-cache .\calibration\runs\audio-state.msgpack `

View file

@ -55,3 +55,4 @@
{"ts": "2026-05-19T07:52:44+00:00", "type": "implementation", "status": "ok", "note": "Native reservoir first cut complete: native/reservoir now uses one time-ordered rolling buffer with typed views, total/view length ABI, latest-by-kind/source lookup, and tests proving single-edge expiry plus stale late-sample exclusion. Python/OpenGL bridge remains next quarantine target."}
{"ts": "2026-05-19T07:57:59+00:00", "type": "implementation", "status": "ok", "note": "OpenGL Spout sink quarantined: localcast.sensor_fusion no longer exports spout_output surfaces; the old SpoutGL renderer now lives under localcast.diagnostics.spout_output and scripts/stream_spout imports it as diagnostic/migration code only."}
{"ts": "2026-05-19T08:01:04+00:00", "type": "implementation", "status": "ok", "note": "Python visual producer quarantined by name: scripts/live_sensor_fusion.py is now scripts/diagnostic_live_sensor_fusion.py, tests/docs import the diagnostic path, and future native/Aquarium work should delete or split its pure pieces rather than extend it."}
{"ts": "2026-05-19T08:03:24+00:00", "type": "implementation", "status": "ok", "note": "Diagnostic Spout launcher renamed: scripts/stream_spout.py is now scripts/diagnostic_stream_spout.py, keeping the OpenGL bridge visibly outside the production path while Aquarium Spout publication remains the target."}

View file

@ -149,7 +149,7 @@ research:
summary: docs/obs-spout-streaming.md
key_decision: >
The deadline OBS surface proved the need for a named Spout sender, but it
is not a foundation. `scripts/stream_spout.py`, SpoutGL/OpenGL rendering,
is not a foundation. `scripts/diagnostic_stream_spout.py`, SpoutGL/OpenGL rendering,
Python render-frame production, and JSON heartbeat stores are diagnostics
or migration fossils only. Production Spout publication belongs in
Aquarium, fed by the native rolling reservoir and typed CultNet documents.
@ -299,7 +299,7 @@ current_status:
time, target render size, Spout sender name, and point draw metadata for
Aquarium/Spout. A deadline OBS Spout sender is now live-shaped:
`scripts/diagnostic_live_sensor_fusion.py` now writes fused render frames into typed
CultCache state at `calibration/runs/visual-state.msgpack`. `scripts/stream_spout.py`
CultCache state at `calibration/runs/visual-state.msgpack`. `scripts/diagnostic_stream_spout.py`
consumes that CultCache document, lowers points into compact anisotropic
screen brush packets, uploads an OpenGL texture, publishes Spout sender
`LocalCastBridge Point Cloud`, and writes both typed status