# How To

Quick reference for common tasks.

---

## Building

### Workspace Selection
```bash
# Main demo (default)
cmake -S . -B build -DDEMO_WORKSPACE=main
cmake --build build -j4
./build/demo64k

# Test demo
cmake -S . -B build_test -DDEMO_WORKSPACE=test
cmake --build build_test -j4
./build_test/test_demo
```

### Debug Build
```bash
cmake -S . -B build
cmake --build build -j4
./build/demo64k
```

**CLI Options:**
- `--fullscreen` - Fullscreen mode
- `--resolution WxH` - Window resolution (e.g., 1920x1080)
- `--seek TIME` - Start at time (seconds)
- `--hot-reload` - Watch config files for changes
- `--dump-wav [FILE]` - Render audio to WAV file
- `--dump-wav-start TIME` - Start WAV dump at time (seeks first)
- `--dump-wav-duration TIME` - Limit WAV dump duration

### Production Builds
```bash
# Size-optimized (development)
cmake -B build -DDEMO_SIZE_OPT=ON && cmake --build build -j4

# 64k target (full checks, no debug)
cmake -B build -DDEMO_STRIP_ALL=ON && cmake --build build -j4

# Final release (no checks, absolute minimum)
./scripts/build_final.sh
```

### Developer Build
```bash
cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
cmake --build build -j4
```

### Headless Testing
```bash
cmake -B build_headless -DDEMO_HEADLESS=ON && cmake --build build_headless -j4
./build_headless/demo64k --headless --duration 30
```
See `doc/HEADLESS_MODE.md`.

### Size Measurement
```bash
./scripts/measure_size.sh
```
Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`.

### WSL (Windows Subsystem for Linux)

Requires **WSL2** with a Ubuntu/Debian distro. Two modes:

#### Mode 1: Native Linux Build

Install system packages:
```bash
sudo apt-get update
sudo apt-get install -y \
    build-essential cmake git python3 \
    libglfw3-dev libxinerama-dev libxcursor-dev libxi-dev libxrandr-dev
```

Install `wgpu-native` (no apt package; download prebuilt from GitHub):
```bash
curl -L -o wgpu_linux.zip \
  https://github.com/gfx-rs/wgpu-native/releases/download/v0.19.4.1/wgpu-linux-x86_64-release.zip
unzip wgpu_linux.zip -d wgpu_tmp
sudo cp wgpu_tmp/libwgpu_native.so /usr/local/lib/
sudo cp wgpu_tmp/wgpu.h wgpu_tmp/webgpu.h /usr/local/include/
sudo ldconfig
rm -rf wgpu_linux.zip wgpu_tmp
```

Build and run:
```bash
cmake -S . -B build
cmake --build build -j4
./build/demo64k
```

> **Note:** Display output requires WSLg (built into Windows 11; also available on
> updated Windows 10 builds via the Microsoft Store WSL update). Vulkan GPU
> passthrough must be enabled — check `wsl --version` to confirm WSLg is active.

#### Mode 2: Cross-Compile Windows `.exe` from WSL

Install the MinGW-w64 cross-compiler:
```bash
sudo apt-get install -y mingw-w64
```

Fetch prebuilt Windows libraries (GLFW, wgpu-native DLLs):
```bash
./scripts/fetch_win_deps.sh
```

Build:
```bash
./scripts/build_win.sh
```

Output: `build_win/demo64k.exe` — copy to Windows and run directly.

---

## Testing

### Run All Tests
```bash
cmake -B build -DDEMO_BUILD_TESTS=ON
cmake --build build -j4
cd build && ctest
# OR: make run_all_tests
```

### Run Subsystem Tests
```bash
make run_audio_tests    # Audio system tests
make run_gpu_tests      # GPU/shader tests
make run_3d_tests       # 3D rendering tests
make run_assets_tests   # Asset system tests
make run_util_tests     # Utility tests
```

### Run Specific Test
```bash
./build/test_synth
```

---

## Training

### CNN v1 (Legacy)
```bash
# Patch-based (recommended)
./cnn_v1/training/train_cnn.py \
  --input training/input/ --target training/output/ \
  --patch-size 32 --patches-per-image 64 --detector harris \
  --layers 3 --kernel_sizes 3,5,3 --epochs 5000

# Export shaders
./cnn_v1/training/train_cnn.py --export-only checkpoints/checkpoint.pth
```

### CNN v2 Training

```bash
# Default pipeline (train → export → validate)
./cnn_v2/scripts/train_cnn_v2_full.sh

# Quick debug (1 layer, 5 epochs)
./cnn_v2/scripts/train_cnn_v2_full.sh --num-layers 1 --epochs 5

# Custom architecture
./cnn_v2/scripts/train_cnn_v2_full.sh --kernel-sizes 3,5,3 --epochs 500

# Validation only
./cnn_v2/scripts/train_cnn_v2_full.sh --validate

# All options
./cnn_v2/scripts/train_cnn_v2_full.sh --help
```

**Defaults:** 200 epochs, 3×3 kernels, 8→4→4 channels, patch-based (8×8). Outputs ~3.2 KB f16 weights.

**Manual export:**
```bash
./training/export_cnn_v2_weights.py checkpoints/checkpoint.pth \
  --output-weights workspaces/main/cnn_v2_weights.bin
```

See `cnn_v2/docs/CNN_V2.md` for architecture details and web validation tool.

---

## Timeline

### Manual Editing
Edit `workspaces/main/timeline.seq`:
```text
SEQUENCE 0.0 0
  EFFECT + HeptagonEffect source -> sink 0.0 60.0
```
Rebuild to apply. See `doc/SEQUENCE.md` for v2 format details.

### Visual Editor
```bash
open tools/timeline_editor/index.html
```
Features: Drag/drop, beat-based editing, audio playback, waveform visualization, snap-to-beat, NODE declarations, buffer chain visualization. See `tools/timeline_editor/README.md`.

---

## Audio

### Rendering Audio to WAV

```bash
# Render full demo
./build/demo64k --dump-wav output.wav

# Render specific time range
./build/demo64k --dump-wav output.wav --dump-wav-start 10 --dump-wav-duration 5

# Render first 30 seconds
./build/demo64k --dump-wav output.wav --dump-wav-duration 30
```

### API Usage

```cpp
#include "audio/audio_engine.h"

audio_init();
static AudioEngine g_audio_engine;
g_audio_engine.init();
g_audio_engine.update(music_time);
g_audio_engine.shutdown();
audio_shutdown();
```

See `doc/TRACKER.md` for music system.

### Regenerating .spec Files

Converts `.wav`/`.aif` files from `tools/originals/` into `.spec` files in `workspaces/main/music/`.

```bash
# Build spectool first (requires DEMO_BUILD_TOOLS=ON)
cmake -S . -B build -DDEMO_BUILD_TOOLS=ON
cmake --build build -j4 --target spectool

# Generate all spectrograms
./scripts/gen_spectrograms.sh
```

Requires `ffmpeg` for `.aif` input files. Output uses v2 format (OLA, Hann, hop=256).

### Decoding .spec to WAV

To verify or inspect a `.spec` file as audio:

```bash
./build/spectool --wav input.spec output.wav
```

Produces a mono 16-bit PCM WAV at 32 kHz using IDCT-OLA synthesis (no synthesis window —
the analysis Hann window is its own reconstruction filter at 50% overlap).

---

## Assets

Edit `workspaces/main/assets.txt`, then rebuild:
```bash
cmake --build build -j4
```
See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.

---

## CNN Testing

### Offline Shader Validation

```bash
# CNN v2 (recommended, fully functional)
./build/cnn_test input.png output.png --cnn-version 2

# CNN v2 with runtime weight loading (loads layer config from .bin)
./build/cnn_test input.png output.png --weights checkpoints/checkpoint_epoch_100.pth.bin

# CNN v1 (produces incorrect output, debug only)
./build/cnn_test input.png output.png --cnn-version 1

# Adjust blend (0.0 = original, 1.0 = full CNN)
./build/cnn_test input.png output.png --cnn-version 2 --blend 0.5

# Debug hex dump (first 8 pixels)
./build/cnn_test input.png output.png --cnn-version 2 --debug-hex
```

**Status:**
- **CNN v2:** ✅ Fully functional, matches CNNv2Effect
- **CNN v1:** ⚠️ Produces incorrect output, use CNNv1Effect in demo for validation

**Note:** `--weights` loads layer count and kernel sizes from the binary file, overriding `--layers` and forcing CNN v2.

See `cnn_v1/docs/CNN_TEST_TOOL.md` for full documentation.

---

## Modifying Build System

- **Add build option:** Edit `cmake/DemoOptions.cmake`
- **Add source files:** Edit `cmake/DemoSourceLists.cmake`
- **Add test:** Edit `cmake/DemoTests.cmake`
- **Add tool:** Edit `cmake/DemoTools.cmake`
- **Add library:** Edit `cmake/DemoLibraries.cmake`

See `doc/CMAKE_MODULES.md` for full architecture and shared macros.

---

## Additional Documentation

- **Build System:** `doc/BUILD.md` - Multi-platform, size optimization
- **CMake Modules:** `doc/CMAKE_MODULES.md` - Module architecture, shared macros
- **Tools:** `doc/TOOLS_REFERENCE.md` - spectool, coverage, Windows cross-compile
- **Shaders:** `doc/SEQUENCE.md` - Timeline format, shader parameters
- **3D:** `doc/3D.md` - Hybrid rendering, scene format
- **Hot Reload:** `doc/HOT_RELOAD.md` - Debug file watching