Development Runbook

Development Runbook

Step-by-step guide for local development and iteration.

Environment Setup

1. Clone and Install

cd [home-path]
git clone <repo-url> computational-choreography
cd computational-choreography

# Create virtual environment
python3.10 -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env
# Edit .env with your settings

2. Verify IAC Driver (macOS)

# List MIDI devices
python -c "import mido; print(mido.get_output_names())"

# Should see: ['IAC Driver Bus 1', ...]

3. Generate Synthetic Data

make setup-data
# Creates 10 synthetic sessions in data/raw/

---

Training Models

Train RPS Encoder

python training/trainers/train_rps.py \
  --config training/experiments/exp_baseline.yaml \
  --epochs 50 \
  --checkpoint-dir training/checkpoints/rps

Expected output:
- `rps_epoch_50.pt` (~ 2 MB)
- Coherence loss < 0.1

Train GRU Mapper

python training/trainers/train_mapper.py \
  --config training/experiments/exp_baseline.yaml \
  --epochs 100 \
  --checkpoint-dir training/checkpoints/mapper

Expected output:
- `mapper_epoch_100.pt` (~ 5 MB)
- Control MSE < 0.05

(Optional) Train Lookahead

python training/trainers/train_lookahead.py \
  --config training/experiments/exp_baseline.yaml \
  --epochs 75

---

Running Inference

Simulation Mode (no real sensors)

python inference/realtime_loop.py \
  --mode simulation \
  --session data/raw/session_001_frames.parquet \
  --bridge midi \
  --output data/processed/sim_output.parquet

What it does:
1. Replays synthetic session at 100 Hz
2. Encodes → RPS → GRU → controls
3. Emits MIDI CC to IAC Driver
4. Logs controls to `data/processed/sim_output.parquet`

Live Mode (real sensors)

python inference/realtime_loop.py \
  --mode live \
  --sensor mocopi \
  --bridge midi

What it does:
1. Connects to mocopi suit (UDP)
2. Real-time encoding → controls
3. Emits MIDI CC to Strudel

---

Starting Strudel

Option A: strudel.cc

1. Open https://strudel.cc
2. Paste contents of `sound/strudel/patches/core_patch.strudel.md`
3. Enable Web MIDI → select "IAC Driver Bus 1"
4. Click "Run"

Option B: Local Embed

cd sound/strudel/web_embed
python -m http.server 3000
# Open http://localhost:3000 in Chrome

---

End-to-End Test

bash scripts/run_end_to_end.sh --mode simulation

Flow:
1. Starts Strudel embed (if configured)
2. Runs `realtime_loop.py` with test session
3. Monitors MIDI traffic
4. Generates evaluation report

---

Debugging Tools

MIDI Monitor

python -m mido.ports
# Lists active MIDI connections

# Monitor CC messages
python services/simulators/midi_cc_stream.py --listen

Web Logger

cd services/web_logger/server
npm start

# Open http://localhost:8080
# Visualizes sensor streams + controls in real-time

Replay Controls

python scripts/replay_controls_to_midi.py \
  --input data/processed/sim_output.parquet \
  --device "IAC Driver Bus 1"

---

Common Issues

"No MIDI device found"

Fix:
1. Open Audio MIDI Setup
2. Enable IAC Driver
3. Restart Python interpreter

"RPS coherence < 0.5"

Fix:
- Check that synthetic sessions have diverse motion
- Increase RPS training epochs
- Lower learning rate

"Controls not updating in Strudel"

Fix:
- Verify CC numbers in `control_map.yaml` match Strudel code
- Check latency offset: `configs/strudel.yaml`
- Add `console.log(cc.control(21).value)` in Strudel pattern

"High latency (> 100 ms)"

Fix:
- Reduce GRU window size
- Disable lookahead model
- Lower buffer size in Strudel

---

Making Changes

Update Control Mapping

1. Edit `configs/control_map.yaml`
2. Edit `sound/strudel/patches/*.pattern.js`
3. Reload Strudel (Cmd+Enter)
4. Test with: `python scripts/replay_controls_to_midi.py --test-tone`

Retrain Mapper

1. Edit `training/trainers/train_mapper.py` (adjust architecture)
2. Run training: `make train-all`
3. Test: `python inference/realtime_loop.py --mode simulation`
4. Evaluate: `python evaluation/groove_report.py`

Add New Gesture

1. Add label to `models/gesture/labels.json`
2. Generate training data with gesture annotations
3. Retrain: `python training/trainers/train_gesture.py`
4. Add action to `configs/control_map.yaml`
5. Implement in `inference/realtime_loop.py`

---

Commit Workflow

# 1. Run linting
make lint

# 2. Run tests
make test

# 3. Stage changes
git add .

# 4. Commit (imperative, scope-first)
git commit -m "Add filter sweep gesture macro"

# 5. Push
git push origin feature-branch

---

Performance Profiling

CPU

python -m cProfile -o profile.stats inference/realtime_loop.py --mode simulation
python -m pstats profile.stats
> sort cumtime
> stats 20

Memory

python -m memory_profiler inference/realtime_loop.py --mode simulation

Latency

python scripts/replay_controls_to_midi.py --latency-test
# Measures sensor-to-MIDI round-trip

---

Next Steps

• Add video pose estimation (MediaPipe)
• Implement adaptive training (online learning)
• Build multi-dancer sync protocol
• Export models to ONNX for iOS deployment