sizzletracker-android/docs/DEVELOPER_HANDOVER.md

# Sizzletracker (Android) — Developer Handover

This document is written for a developer who is **new to Android** and needs to
understand, build, and extend this codebase. Read it top to bottom once; after
that it works as a reference.

---

## 1. What this app is

A retro, grid-based **music tracker** for Android. The visual language is a
monospace font + pixel blocks laid out on a strict grid (demoscene tracker
style). It is playable with **four equally-capable input methods**: touchscreen,
physical keyboard, gamepad, and MIDI (USB or Bluetooth).

The UI has four tabs:

| Tab | Package | What it does |
|-----|---------|--------------|
| **Tracker** | `ui/tracker` | Pattern grid (4 tracks) + arrangement piano-roll (8 lanes) |
| **Mix** | `ui/mixer` | 4-channel mixer: instrument + 4 FX, MIDI ch, volume, mute/solo |
| **Toolbox** | `ui/toolbox` | 16 slots of instruments/effects with a generated parameter editor |
| **Setup** | `ui/settings` | Project save/load, themes, gamepad & MIDI bindings |

---

## 2. How to build & run

Requirements: **Android Studio** (Koala / 2024.1 or newer) which bundles a
JDK 17 and the Android SDK.

1. Open the project root in Android Studio. It will detect the Gradle build.
2. If prompted, let it **create the Gradle wrapper** (or run
   `gradle wrapper --gradle-version 8.9` from a shell that has Gradle).
3. Let it download the SDK for `compileSdk 34`.
4. Pick a device/emulator running **Android 8.0 (API 26)** or newer and press
   **Run**.

> The command line here (`./gradlew assembleDebug`) needs the wrapper JAR, which
> is generated by step 2. The wrapper JAR is intentionally not committed as a
> binary; generating it is a one-time step.

Key versions live in **one file**: `gradle/libs.versions.toml` (the "version
catalog"). Change a number there and the whole project follows.

---

## 3. The big picture (architecture)

```
            ┌──────────── Input sources ────────────┐
  Touch ───▶│ (Compose gestures, call ViewModel)     │
  Keyboard ─▶ KeyboardInput ─┐                        │
  Gamepad ──▶ GamepadInput ──┤─▶ InputRouter (flow) ──┼──▶ AppViewModel
  MIDI ─────▶ MidiInput ─────┘                        │        │
            └───────────────────────────────────────┘        │ reads/writes
                                                              ▼
                                                          Project  (the song)
                                                              ▲
                                     reads on audio thread    │
                                          AudioEngine ─────────┘  ──▶ AudioTrack ──▶ speakers
                                          (own thread)
```

Three ideas hold it together:

1. **One neutral action type.** Every non-touch device is translated into an
   `InputAction` (see `input/InputAction.kt`) and pushed through `InputRouter`.
   The ViewModel reacts to those actions in exactly one place
   (`AppViewModel.onAction`). Touch gestures call the same ViewModel methods
   directly. That is *why* all four inputs are equally capable — features are
   implemented once.

2. **One song object.** `model/Project.kt` holds the entire song in memory. The
   UI edits it; the audio engine reads it; the file format serializes it.

3. **Two threads.** The UI runs on the main thread (Jetpack Compose). The sound
   runs on a dedicated high-priority thread inside `AudioEngine`. They share the
   `Project` object. Because the audio thread only ever *reads* simple `Int`/
   `Float` fields, we accept the occasional benign race instead of locking (locks
   would risk audio glitches). See §7.

---

## 4. Package/file map

```
com.reactorcoremeltdown.sizzletracker
├── SizzleApp.kt            Application = tiny DI container (Project, InputRouter, AudioEngine)
├── MainActivity.kt         Hosts Compose UI; forwards HW key/motion events; starts MIDI + service
│
├── model/                  Pure data, no Android imports (unit-test friendly)
│   ├── Music.kt            Pitch, TimeSignature, Scale (incl. scale-step logic)
│   ├── Pattern.kt          Cell, CellColumn, Pattern (4 tracks x N lines)
│   ├── Arrangement.kt      Arrangement (8 lanes x 256 beats), LoopRegion A/B
│   ├── Mixer.kt            Mixer, MixerChannel (4 channels)
│   ├── Toolbox.kt          ToolboxType (all instruments+effects), ParamSpec, ToolboxSlot
│   └── Project.kt          The whole song
│
├── input/                  The unified input layer
│   ├── InputAction.kt      The neutral action vocabulary
│   ├── InputRouter.kt      Flow-based message bus
│   ├── KeyboardInput.kt    KeyEvent  -> InputAction (+ a 2-octave typing piano)
│   ├── GamepadInput.kt     KeyEvent/MotionEvent -> InputAction (rebindable)
│   └── MidiInput.kt        MIDI bytes -> InputAction (USB & Bluetooth via MidiManager)
│
├── audio/                  The real-time sound engine (own thread)
│   ├── Transport.kt        TransportState snapshot published to the UI
│   ├── SynthVoice.kt       One NES-style voice: pulse/triangle/noise + ADSR
│   └── AudioEngine.kt      AudioTrack + sample-accurate sequencer + voice mixing
│
├── io/                     Human-readable text persistence
│   ├── PresetIo.kt         Instrument/effect preset  <->  KEY=VALUE text
│   └── ProjectIo.kt        Whole song  <->  .sng text
│
├── playback/
│   └── PlaybackService.kt  Foreground service: background playback + media notification
│
└── ui/
    ├── AppViewModel.kt     Screen state + THE single InputAction handler
    ├── App.kt              Tab shell
    ├── theme/Theme.kt      RetroPalette + monospace typography + SizzleTheme
    ├── components/Widgets.kt  RetroButton, RetroDropdown, SectionLabel, PixelGlyph
    ├── tracker/            TrackerScreen, PatternGrid, ArrangementRoll
    ├── mixer/MixerScreen.kt
    ├── toolbox/            ToolboxScreen, ParamControl
    └── settings/SettingsScreen.kt
```

---

## 5. Key concepts you must understand

### 5.1 Ticks, beats, bars
A tracker **line** (row) is one tick. The number of lines per beat is set by the
**time signature** (`model/Music.kt`):

- 3/4 → 3 lines per beat, lengths 12/24/48
- 4/4 → 4 lines per beat, lengths 16/32/64
- 5/4 → 5 lines per beat, lengths 20/40/80

`PatternGrid` tints every beat row and every bar row differently using
`line % linesPerBeat` and `line % linesPerBar`.

### 5.2 The "revision" redraw trick (and the strong-skipping rule)
The model classes are **plain** (not Compose-observable) so the audio thread can
read them cheaply. After any edit the ViewModel does `revision++`
(`AppViewModel.touched()`, exposed as `bumpForToolbar()` for direct model edits).

**The rule that makes this actually work:** the Compose compiler we use (2.0.20)
has **strong skipping** enabled by default. It will *skip* a composable whose
parameters are referentially unchanged — even "unstable" ones like `vm` — so a
`revision++` in a *parent* is NOT enough; a child that reads plain model data
would be skipped and only refresh on a tab switch (which recreates the subtree).

So: **every composable that reads plain, mutable model data must itself read
`vm.revision`** (e.g. `val rev = vm.revision`). Reading a snapshot state directly
subscribes that composable's restart scope, so `revision++` invalidates it
regardless of skipping. Where a composable has no `vm` (e.g. `SlotTile`), pass
`rev = vm.revision` as a parameter instead — a changed `Int` param defeats
skipping too. Observable state (cursor position, `transport`, `palette`) already
works without this because it is real Compose state.

If you edit the model and the screen doesn't update: (a) did you call a
`touched()`/`bumpForToolbar()` path, and (b) does the leaf that renders that data
read `vm.revision`? This was the cause of an early "UI only redraws on tab
switch" bug.

### 5.3 The note-entry gesture
Tap a cell → cursor moves there (`focusCell`). Drag up/down → `editFocused(dir)`:
- On the NOTE column, `Scale.step()` moves to the next in-scale pitch.
- On VELOCITY/CHANNEL it steps the number.
Every step fires a haptic tick. The same `editFocused` runs from keyboard PageUp/
Down, gamepad right-stick, and MIDI CC — one implementation, four inputs.

### 5.4 Toolbox devices are data, not classes
Instead of a class per instrument/effect, every device is one `ToolboxType`
enum entry that lists its `ParamSpec`s. A `ToolboxSlot` stores the chosen type +
a `name -> value` string map. The parameter editor UI and the preset text format
are both **generated** from that list. See §6 to add a new device.

---

## 6. How to extend

### Add a new instrument or effect
1. Add an entry to `ToolboxType` (`model/Toolbox.kt`) with its `ParamSpec` list.
2. Teach `AudioEngine` how to render/process it (today only `NES_SYNTH` is
   rendered; see `synthParamsForTrack`). Add a branch there.
That's it — the Toolbox picker, parameter editor, and preset save/load all work
automatically.

### Add a new input gesture/control
1. Add a case to `InputAction`.
2. Emit it from each source (`KeyboardInput`, `GamepadInput`, `MidiInput`) and/or
   a Compose gesture.
3. Handle it once in `AppViewModel.onAction`.

### Add a new color theme
Add a `RetroPalette` to `RetroPalette.ALL` in `ui/theme/Theme.kt`. It appears in
the Settings theme picker immediately.

---

## 7. Threading & performance notes

- The audio render loop is in `AudioEngine.renderLoop()` on a `MAX_PRIORITY`
  thread. It **must never allocate or block**. Keep it that way.
- Timing is derived from *counting audio samples* (`samplesPerLine`), not from
  timers, so playback never drifts.
- UI ⇄ audio sharing is lock-free by design (audio reads plain fields). This can
  produce a one-frame-stale read during a simultaneous edit — harmless for a
  tracker. If you ever add compound state that must be read atomically, publish it
  as an immutable snapshot (like `TransportState`) rather than adding locks.
- Block size is `BLOCK_FRAMES = 192` (~4 ms @ 48 kHz). Lower = tighter latency,
  higher = safer against underruns.
- **UI rendering**: the pattern grid (`PatternGrid`) and arrangement roll
  (`ArrangementRoll`) are each drawn as ONE `Canvas` with a cached
  `rememberTextMeasurer`, not a tree of per-cell composables. This is what keeps
  the grid smooth while the playhead moves — a single draw pass instead of
  recomposing hundreds of `Text` nodes each frame. If you add grid features, draw
  them in the Canvas rather than adding child composables.
- **Arrangement model**: each of the 8 lanes is tied to its own block (lane i ⟷
  block i; `Project.patterns` holds 8 blocks). Toggling a beat cell on lane i
  enables block i at that beat; the sequencer plays it when the playhead crosses.
  Tap a lane number (left column) to edit that block in the tracker above.

---

## 8. File formats

### Preset (`PresetIo`)
```
SIZZLE-PRESET 1
TYPE=NES_SYNTH
NAME=Lead
wave=Pulse25
attack=0.01
...
```
Copy/paste from the Toolbox parameter editor uses this exact text.

### Project `.sng` (`ProjectIo`)
Line-oriented, sectioned (`[PATTERN ...]`, `[ARRANGEMENT ...]`, `[MIXER]`,
`[TOOLBOX]`). Only non-empty cells are written. It is fully round-trip safe.

---

## 9. Current status — implemented vs. TODO

This is an honest map so you know where the edges are. The **architecture and
all four tabs are in place and interactive**; several deep features are scaffolded
with a clear seam to finish them.

### Implemented and working
- Full 4-tab UI, retro monospace theme (+ theme switching), tab navigation.
- Tracker pattern grid: beat/bar coloring, cursor, tap-to-focus, drag-to-edit
  with haptics, scale-aware note entry, transport toolbar, length/scale/root.
- Arrangement roll: 8 lanes, place/clear blocks, playhead follow, loop toolbar
  with A/B enable + repeat counts.
- Mixer: 4 strips, instrument/FX routing to toolbox, MIDI ch, volume, mute/solo.
- Toolbox: 16 slots, device picker, **auto-generated** parameter editor, preset
  copy/paste (text).
- Audio engine: dedicated thread, sample-accurate sequencer, NES-style synth
  (pulse/tri/noise + ADSR), per-track mute/solo/volume, live note audition.
- **Arrangement-driven playback** (milestone 1 ✓): the sequencer walks a
  pre-expanded beat playlist (with A/B loop repeats) across all 8 lanes; each
  lane keeps its own within-pattern cursor so multi-beat blocks advance through
  the pattern. Falls back to looping the active pattern when the arrangement is
  empty. Voices are a lane×track matrix so lanes layer polyphonically.
- **Per-channel effect DSP** (milestone 3 ✓): each mixer channel runs an insert
  chain built from its FX slots — Tape Delay, Digital Reverb, Filter (LP/HP/BP),
  Bitcrusher, and 10-band EQ are real processors in `audio/Effects.kt`. Effect
  parameters update live per audio block; add/remove rebuilds the chain.
- **Sampler instrument** ✓: WAV import (SAF file picker) + ad-hoc mic/USB
  recorder (`audio/SampleRecorder.kt`), decoded to a mono cache
  (`audio/SampleStore.kt`), played pitched + sliced by `audio/SampleVoice.kt`.
  Its editor (`ui/toolbox/SamplerEditor.kt`) shows a waveform with two draggable
  slice markers, start-octave + volume, and a two-octave audition keyboard. Each
  (lane, track) has both a synth and a sample voice; the channel instrument type
  selects which one a note triggers.
- Input: keyboard (nav + typing-piano + transport), gamepad (buttons + sticks +
  hat), MIDI in (note + CC, USB & BT), all via the unified router.
- **MIDI-learn & gamepad rebind** ✓: the Settings tab lists every bindable action
  with its current binding and a Learn button; arming it sets the router's
  `learnMode`, and the next unbound CC / gamepad button is written into
  `MidiInput.ccBindings` / `GamepadInput.bindings` (the handlers are now app
  singletons shared with Settings). Bindings are clearable per action.
- **MIDI effects (Transposer / Arpeggiator / LFO)** ✓: Transposer shifts notes by
  its semitone amount; the Arpeggiator octave-cycles a captured note
  (Up/Down/UpDown/Random, 1–4 octaves) at a tempo-synced division
  (`AudioEngine.advanceArps`); the LFO (`applyLfos`) modulates a chosen target
  parameter of another device around a captured centre (Sine/Tri/Saw/Square/S&H),
  with a target picker in its editor (`ui/toolbox/LfoEditor.kt`).
- **USB / audio device selection** ✓: Settings → Audio Devices lists the system's
  output and input devices; choosing one routes the engine's `AudioTrack` and the
  recorder's `AudioRecord` via `setPreferredDevice` (API 28+), so a USB DAC / USB
  audio interface can be used for playback and recording.
- **Full MediaSession** ✓: `playback/PlaybackService` is now a media3
  `MediaSessionService` hosting a session that wraps the engine via
  `EnginePlayer` (`SimpleBasePlayer`). This gives lock-screen controls,
  Bluetooth/headset media buttons, and the media notification for free, mirroring
  the on-screen transport.
- Persistence: preset text I/O, a full-fidelity internal project text format
  (`ProjectIo`, keeps mixer/FX/instruments), AND **desktop-compatible `.sng`**
  read/write (`io/SngFormat.kt`) matching the reference sizzletracker line format
  (`version`/`bpm`/`sig`, `block`…`endblock` with `roll`/`track`/steps) — covered
  by passing JVM unit tests in `app/src/test`.
- Background playback foreground service with Play/Pause/Stop notification.
- **Oboe / AAudio native output** ✓ (opt-in): `src/main/cpp/native_audio.cpp`
  opens a low-latency Oboe stream whose real-time callback pulls audio via JNI
  (`audio/NativeAudioBridge.kt`) from the SAME `AudioEngine.fillBlock` the
  AudioTrack loop uses — so both backends produce identical sound, only the
  delivery path differs. Toggle it in Settings → Audio Devices ("Low-latency
  engine (Oboe)"); it falls back to AudioTrack if the native lib is absent.
  Built via **NDK r27** (`ndkVersion` in `app/build.gradle.kts`) + CMake + the
  `com.google.oboe:oboe:1.10.0` prefab AAR. All packaged `.so` files are **16 KB
  page-aligned** (Android 15 / Google Play requirement): NDK r27 aligns ELF load
  segments to 16 KB and ships a 16 KB-aligned `libc++_shared.so`, Oboe 1.10.0's
  lib is aligned, our `CMakeLists.txt` also passes `-Wl,-z,max-page-size=16384`,
  and AGP stores each `.so` at a 16 KB-aligned offset in the APK. (Verify with
  `llvm-readelf -l <lib>.so` → LOAD `Align 0x4000`.)

### Scaffolded — remaining
1. **SF2 / XI loader instrument.** The Sampler (WAV) is done; the SoundFont/XI
   loader still falls back to the synth. Parse `.sf2`/`.xi`, feed the extracted
   PCM through the existing `SampleStore`/`SampleVoice` path. (This was not in the
   original milestone list; noted for completeness.)

All spec milestones are implemented. Next steps are polish/hardening: routing the
Oboe backend through the chosen output device (Oboe `setDeviceId`), a full C++
port of the synth/mixer to remove JVM/GC from the native audio callback, and the
SF2/XI loader above.

---

## 10. Testing suggestions
- Pure `model/` classes (`Scale.step`, `TimeSignature`, `Pattern.resize`,
  `ProjectIo` round-trip, `PresetIo` round-trip) are plain Kotlin — cover them
  with JVM unit tests first; they need no device.
- For the engine, render a few blocks with a known pattern and assert the voice
  triggers on the expected sample offsets.