# 64k Demo Project

## Goal
- Produce a <=64k native demo binary
- Same C++ codebase for Windows, macOS, Linux

## Graphics
- WebGPU via wgpu-native
- WGSL shaders
- Hybrid rendering: Rasterized proxy geometry + SDF raymarching

## Audio
- 32 kHz, 16-bit stereo
- Procedurally generated samples
- Real-time additive synthesis from spectrograms (OLA-IDCT, Hann analysis window, 50% overlap, rectangular synthesis)
- Variable tempo system with music time abstraction
- Event-based pattern triggering for dynamic tempo scaling
- Modifiable Loops and Patterns, w/ script to generate them (like a Tracker)
- Unified AudioEngine for lifecycle management

## Constraints
- Size-sensitive
- Minimal dependencies
- Explicit control over all allocations

## Style
- Demoscene
- No engine abstractions

---

## Current Status

- **Timing System:** **Beat-based timelines** for musical synchronization. Sequences defined in beats, converted to seconds at runtime. Effects receive both physical time (constant) and beat time (musical). Variable tempo affects audio only. See `doc/BEAT_TIMING.md`.
- **Workspace system:** Multi-workspace support. Easy switching with `-DDEMO_WORKSPACE=<name>`. Organized structure: `music/`, `weights/`, `obj/`, `shaders/`. Shared common shaders in `src/shaders/`. See `doc/WORKSPACE_SYSTEM.md`.
- **Audio:** Sample-accurate sync. Zero heap allocations per frame. Variable tempo. OLA-IDCT synthesis (v2 .spec): Hann analysis window, rectangular synthesis, 50% overlap, click-free. V1 (raw DCT-512) preserved for generated notes. .spec files regenerated as v2.
- **Shaders:** Parameterized effects (UniformHelper, .seq syntax). Beat-synchronized animation support (`beat_time`, `beat_phase`). Modular WGSL composition with ShaderComposer. 27 shared common shaders (math, render, compute). Reusable snippets: `render/scratch_lines`, `render/ntsc_common` (NTSC signal processing, RGB and YIQ input variants via `sample_ntsc_signal` hook), `math/color` (YIQ/NTSC), `math/color_c64` (C64 palette, Bayer dither, border animation).
- **3D:** Hybrid SDF/rasterization with BVH. Binary scene loader. Blender pipeline.
- **Effects:** CNN post-processing: CNNEffect (v1) and CNNv2Effect operational. CNN v2: sigmoid activation, storage buffer weights (~3.2 KB), 7D static features, dynamic layers. Training stable, convergence validated. **CNN v3 Phases 1–5 complete:** `CNNv3Effect` C++ class (5 compute passes, FiLM uniform upload, identity γ/β defaults). Parity validated: enc0 max_err=1.95e-3, dec1 max_err=1.95e-3, final max_err=4.88e-4 (all ≤1/255). Key fix: intermediate nodes declared at fractional resolutions (W/2, W/4) via `NodeRegistry::default_width()/default_height()`. See `cnn_v3/docs/HOWTO.md`.
- **Tools:** CNN test tool operational. Texture readback utility functional. Timeline editor (web-based, beat-aligned, audio playback).
- **Build:** Asset dependency tracking. Size measurement. Hot-reload (debug-only). WSL (Windows 10) supported: native Linux build and cross-compile to `.exe` via `mingw-w64`.
- **Sequence:** DAG-based effect routing with explicit node system. Python compiler with topological sort and ping-pong optimization. 12 effects operational (Passthrough, Placeholder, GaussianBlur, Heptagon, Particles, RotatingCube, Hybrid3D, Flash, PeakMeter, Scene1, Scene2, Scratch). Effect times are absolute (seq_compiler adds sequence start offset). See `doc/SEQUENCE.md`.
- **Testing:** **36/36 passing**.

---

## Next Up

**Active:** CNN v3 training (`train_cnn_v3.py`), Spectral Brush Editor
**Ongoing:** Test infrastructure maintenance (35/35 passing)
**Future:** Size optimization (64k target), 3D enhancements

See `TODO.md` for details.

---

## Documentation

**Essential:**
- `doc/ARCHITECTURE.md` - System architecture and design decisions
- `doc/HOWTO.md` - Common operations and workflows
- `doc/CONTRIBUTING.md` - Development protocols

**Technical Reference:**
- Core: `ASSET_SYSTEM.md`, `SEQUENCE.md`, `TRACKER.md`, `3D.md`, `cnn_v1/docs/CNN_V1_EFFECT.md`, `cnn_v2/docs/CNN_V2.md`
- Formats: `SCENE_FORMAT.md`, `MASKING_SYSTEM.md`
- Tools: `BUILD.md`, `WORKSPACE_SYSTEM.md`, `SIZE_MEASUREMENT.md`, `cnn_v1/docs/CNN_TEST_TOOL.md`, `tools/timeline_editor/README.md`

**History:**
- `doc/COMPLETED.md` - Completed tasks archive
- Git log for detailed change history