<!-- SPDX-FileCopyrightText: 2026 Reactorcoremeltdown -->
<!-- SPDX-License-Identifier: GPL-3.0-or-later -->

# Sizzletracker — User Guide

Sizzletracker is a retro, demoscene‑flavoured **music tracker for Android**. You
sequence notes on a fixed‑width grid, build a song out of reusable pattern
**blocks**, and play everything through built‑in synths, samplers and effects — a
low‑latency native audio engine driving it all. Everything can be driven equally
by **touch, a physical keyboard, a gamepad, or MIDI**.

> **Screenshots** in this guide were taken on a phone in the *Vintage Beige*
> theme. Your colours will differ if you pick another palette, and any floating
> buttons you see over the app in a shot belong to a different app, not
> Sizzletracker.

---

## Contents

1. [Requirements & install](#requirements--install)
2. [Core concepts](#core-concepts)
3. [Getting around: the four tabs](#getting-around-the-four-tabs)
4. [Tracker tab](#tracker-tab)
5. [The punch‑in keyboard](#the-punch-in-keyboard)
6. [Arrangement](#arrangement)
7. [Mix tab](#mix-tab)
8. [Toolbox tab](#toolbox-tab)
   - [Instruments](#instruments)
   - [Effects](#effects)
   - [Presets](#presets)
9. [Setup tab](#setup-tab)
10. [Input devices & hold‑to‑repeat](#input-devices--hold-to-repeat)
11. [Files, projects & sharing](#files-projects--sharing)
12. [Recording](#recording)
13. [Default control maps](#default-control-maps)
14. [Tips & troubleshooting](#tips--troubleshooting)

---

## Requirements & install

- **Android 8.0 (Oreo) or newer.** The app relies on the native MIDI API and
  low‑latency AAudio, which need this floor.
- Audio uses **Oboe** (low‑latency) with an automatic fallback to the standard
  path if Oboe can't start on your device.
- Installed as an APK (e.g. from a personal F‑Droid repository). Package id:
  `space.rcmd.android.sizzle`.

---

## Core concepts

A few ideas make the whole app click:

- **Tracks vs. channels.** The pattern grid has four vertical **tracks** (columns
  of notes). Each note carries a **MIDI channel** number; that channel decides
  which **mixer channel (bus)** actually sounds it. So *where* a note sits in the
  grid is independent of *which instrument* plays it — routing is by channel.
- **Blocks.** A **block** is a short pattern. You compose blocks in the Tracker,
  then lay them out over time in the **Arrangement** to form the full song.
- **The Toolbox** holds up to 16 **devices** — instruments (Synth, Sampler,
  SF2/XI) and effects (delay, filter, reverb, MIDI arpeggiator, …). The Mix tab
  assigns one instrument and up to four effects to each of the four channels.
- **Four equal inputs.** Touch, keyboard, gamepad and MIDI are all translated
  into the same internal actions, so every feature works from every device.

---

## Getting around: the four tabs

The bottom bar switches between the four main screens:

| Tab | What it's for |
|-----|---------------|
| **Tracker** | Enter notes, edit patterns, arrange blocks into a song |
| **Mix** | Assign instruments/effects to channels, set levels, arm recording |
| **Toolbox** | Create and edit the 16 instrument/effect devices, manage presets |
| **Setup** | Projects, audio routing, themes, input bindings, MIDI panic |

---

## Tracker tab

<img src="screenshots/01-tracker.png" width="300" alt="Tracker tab">

The top of the screen is the transport and editing toolbar; below it is the
pattern grid; below that (in portrait) is the Arrangement.

**Transport row**

- **⧉ STOP** — stop playback. Pressing STOP again when already stopped rewinds to
  the start.
- **▶ PLAY / ❚❚ PAUSE** — start or pause. When the arrangement is empty, the
  currently‑edited pattern loops so the Tracker is always audible while you work.
- **– / + BPM** — nudge the tempo. Hold to repeat.
- **SIG** — time signature (beats per bar / beat unit).

**Pattern row**

- **BLK** — which block you're editing.
- **LEN** — the block's length in lines.
- **SCALE** — the musical scale used when entering/transposing notes (e.g.
  *Chromatic*). Note edits snap to this scale.
- **ROOT** — the scale's root note.

**Editing row**

- **SEL** — start/extend a selection.
- **✂ / ⧉ / 📋** — cut, copy, paste the selection.
- **✕** — clear the focused cell(s).
- **OFF ===** — place a **note‑off** on the focused track (see below).
- **SKIP** — how many lines the cursor jumps after each note entry (step size).
- **KBD** — show/hide the punch‑in keyboard.

**The grid**

Each row is one line (numbered in hex on the left). Each of the four tracks shows
three columns:

- **Note** — e.g. `C‑4`, or `···` when empty, or `===` for a note‑off.
- **Velocity** — how hard the note plays (hex), or `..` when empty.
- **Channel** — the MIDI channel that routes the note to a mixer bus.

The **cursor** highlights the focused cell; tap a cell to move there. The
**playhead** row is highlighted while playing. Beat and bar lines are tinted so
you can read the meter at a glance.

**Scrolling & follow.** During playback the grid auto‑centres on the playhead;
flick up/down to detach into free **inertial scrolling**; switching to another
block re‑attaches the auto‑follow.

**Note‑offs are tied to their track.** A `===` cell has no note, velocity or
channel of its own — it simply releases whatever that track last started. This is
how you end a sustained note cleanly.

---

## The punch‑in keyboard

Tap **KBD** to reveal a two‑octave on‑screen piano fixed at the bottom.

<img src="screenshots/02-tracker-keyboard.png" width="300" alt="Punch-in keyboard">

The bar above the keys sets what you're punching in:

- **CH** — the MIDI channel written into new notes (routes them to a mixer bus).
- **OCT** — the octave pair shown on the two rows.
- **VEL** — the velocity written into new notes.

Playing a key enters a note at the cursor and advances by the **SKIP** amount.
The same keyboard is also used purely to *audition* instruments in the Toolbox.

---

## Arrangement

Below the grid is the Arrangement — a timeline of your blocks.

- Rows are **lanes** (independent parts that play together); columns are beats.
- Paint a block into a lane so it sounds at that point; a **contiguous run** of the
  same block plays it through beat‑by‑beat.
- **M** mutes a lane.
- **LOOP** loops the arrangement; **A** / **B** define two loop regions, each with
  its own repeat count (the **–/×N/+** controls).
- **FILL** helps lay a block across a span quickly.

The canvas extends up to 256 bars, so full songs fit.

---

## Mix tab

<img src="screenshots/03-mix.png" width="300" alt="Mix tab">

Four channels, side by side. For each channel:

- **INSTRUMENT** — the Toolbox device that makes its sound.
- **FX 1–4** — up to four insert effects, applied in order.
- **MIDI CH** — which MIDI channel this bus listens on. Notes whose channel
  matches play here. (Set two buses to the same channel to layer them.)
- **VOLUME** — drag the fader.
- **LIM** — a per‑channel soft‑clip limiter.
- **M / S** — mute / solo.

The strip along the top controls **recording** of the master output:

- **● ARM** — arm recording; capture begins when you press play.
- **TAIL** — how many bars of effect tail to keep after the sequencer stops.
- **DIR** — the destination folder for the rendered file.
- **master → WAV** — the master bus is captured to a stereo WAV.

---

## Toolbox tab

<img src="screenshots/04-toolbox.png" width="300" alt="Toolbox grid">

A 4×4 grid of 16 device slots. Filled tiles show the device name and whether it's
an instrument (**INS**) or effect (**EFF**).

**Tile gestures**

- **Single tap an empty tile** → choose a device to load.

  <img src="screenshots/05-device-picker.png" width="300" alt="Device picker">

- **Single tap a filled tile** → open its editor.
- **Long‑press a filled tile** → clear it (a confirmation appears first, since
  clearing discards the device and its settings and can't be undone).

The keyboard pinned at the bottom of the Toolbox auditions the current device.

### Instruments

**Synth** — a three‑oscillator subtractive synth (Minimoog‑style): three
oscillators → mixer → resonant low‑pass filter (with its own envelope and key
tracking) → amplifier, plus a tempo‑synced LFO and a small modulation matrix. The
editor is paged (swipe, or tap the dots): **Oscillators**, **Filter**, **Amp +
LFO**, **Mod**.

<img src="screenshots/06-synth-editor.png" width="300" alt="Synth editor — oscillators">

Controls are **rotary knobs**: slide a finger up/down to change a value (a full
sweep spans a comfortable travel distance, so fine tweaks are easy), and
**double‑tap a knob to reset** it to its default. Factory presets include
chiptune tones and a darkwave/industrial set (plucky basses, cutting leads, and
harsh detuned deep basses for layering).

**Sampler** — a 16‑pad drum/sample bank. Each pad maps to a consecutive note from
C2 upward.

<img src="screenshots/08-sampler-editor.png" width="300" alt="Sampler editor">

Per pad you can **IMPORT WAV**, **RECORD**, **CLIP** (trim with the waveform
markers), **NORMALIZE**, or **CLEAR**, and set a per‑pad **volume**. Tap a pad in
the grid to play and select it.

**SF2 / XI Loader** — loads a single sample/instrument from a SoundFont (`.sf2`)
or FastTracker (`.xi`) file, pitched across the keyboard from its root note.

<img src="screenshots/07-soundfont-editor.png" width="300" alt="SF2/XI loader editor">

It has a volume **ADSR envelope** and an optional **LOOP** (sustains the sample
until note‑off) with an adjustable crossfade (**XFADE**) to smooth the loop seam.

### Effects

Insert effects (assign them to a channel's FX slots in the Mix tab):

| Effect | What it does |
|--------|--------------|
| **Tape Delay** | Up to four tempo‑synced tape "heads", with feedback, dry/wet and tape character (saturation, darkening, wow/flutter) |
| **Filter (LP/HP/BP)** | Resonant low/high/band‑pass filter with warmth and a signal‑triggered cutoff envelope |
| **10‑Band EQ** | Ten‑band graphic equaliser |
| **Bitcrusher** | Bit‑depth and sample‑rate reduction with drive |
| **Ambience Reverb** | A multi‑algorithm reverb with many factory spaces |
| **MIDI Arpeggiator** | Turns held notes into tempo‑synced octave patterns |
| **MIDI Transposer** | Shifts incoming notes by octaves/semitones |
| **MIDI LFO** | Modulates a chosen parameter of another device |

The Tape Delay editor, as an example — drag a head's fader to set its time, tap
its number to switch it off/on:

<img src="screenshots/09-tape-delay-editor.png" width="300" alt="Tape Delay editor">

> **MIDI effects vs. audio effects.** The Arpeggiator, Transposer and LFO shape
> notes/parameters before the sound is made; the rest process audio. All are
> managed the same way — as devices you drop into a channel's FX slots.

### Presets

Every device editor has a preset bar at the top:

- **PRESET** dropdown — load a saved preset.
- **SAVE** — save the current settings as a named preset.
- **DELETE** — remove the selected preset (asks to confirm).
- **IMPORT** — load a preset from a file (Sampler presets can be imported from a
  `.zip` bundle that carries the sample).
- **SHARE** — send the preset via the system share sheet.

Presets are plain text (`.szp`), stored per device type in the app's storage.
Factory presets are seeded automatically and reappear as new ones ship, but ones
you delete stay deleted.

---

## Setup tab

<img src="screenshots/10-setup.png" width="300" alt="Setup tab">

- **MIDI PANIC — ALL NOTES OFF** — instantly silences every voice. Use it if a
  note ever hangs.
- **Project** — save / new / delete full projects on the device, and **Export /
  Import `.sng`** for desktop interchange. (See [Files](#files-projects--sharing).)
- **Audio Devices** — route **Output** and **Input** to USB or built‑in.
- **Color Theme** — pick a palette, or **Export / Import `.szt`** themes. Stock
  themes can't be deleted; imported ones join the list.

Scrolling down reveals the input‑binding editors:

<img src="screenshots/11-setup-bindings.png" width="300" alt="Setup — input bindings">

- **Gamepad Bindings** — rebind buttons and button‑combos (chords).
- **Keyboard Hotkeys** — rebind physical‑keyboard keys.
- **MIDI Bindings** — MIDI‑learn: map any knob/pad to an action.

---

## Input devices & hold‑to‑repeat

Sizzletracker treats **touch, keyboard, gamepad and MIDI** as equals — every
action is available from each.

- **Touch** — tap the grid, drag faders/knobs, play the on‑screen keyboard.
- **Physical keyboard** — a built‑in "tracker piano" for note entry (see the map
  below) plus rebindable hotkeys for navigation, transport and editing.
- **Gamepad** — face buttons, shoulders, D‑pad and both analog sticks are all
  bindable and can be combined into chords (hold one control as a modifier).
- **MIDI** — notes play live; Control‑Change messages drive bound actions, and
  unmapped ones can be MIDI‑learned in Setup.

**Hold‑to‑repeat.** Holding a **navigation** control now auto‑repeats it — cursor
Up/Down/Left/Right, column moves, and value increment/decrement. It fires once,
then accelerates while held, and stops on release. This works identically on the
keyboard, the gamepad (buttons, D‑pad **and** analog sticks) and a momentary MIDI
control — so scrolling through a long pattern or ramping a value is a single hold.
One‑shot actions (play, stop, tab switch, note/clear) still fire once even if held.

---

## Files, projects & sharing

| Format | Contains | Use it for |
|--------|----------|-----------|
| **Full project** | Notes, blocks, arrangement **+ mixer, FX, instruments and sample assignments** | Your working song on this device |
| **`.sng`** | Notes, blocks, arrangement only | Desktop‑compatible interchange |
| **`.szp`** | One device's settings (Sampler as a `.zip` with its sample) | Sharing instrument/effect presets |
| **`.szt`** | A colour palette | Sharing themes |

Projects auto‑save, so a crash or process death resumes where you left off.
Export a `.sng` before wiping data if you want a portable copy of the song.

---

## Recording

1. In the **Mix** tab, set **DIR** (destination) and **TAIL** (bars of effect
   tail to keep), then press **● ARM**.
2. Press **PLAY**. Capture starts with playback and records the **master** bus.
3. Recording ends automatically the set number of tail bars after the sequencer
   stops. The finished stereo **WAV** is written to your chosen folder.

---

## Default control maps

### Keyboard

**Hotkeys** (rebindable in Setup → Keyboard Hotkeys):

| Key | Action |
|-----|--------|
| Arrow keys | Move cursor (hold to repeat) |
| Tab / Shift+Tab | Next / previous column |
| Space | Play / pause |
| Enter | Stop |
| L | Toggle loop |
| Page Up / Page Down | Increment / decrement value (hold to repeat) |
| Delete | Clear cell |
| `` ` `` (grave) | Note‑off |
| – / = | Octave down / up |

**Tracker piano** (fixed, for note entry):

- Lower octave: `Z S X D C V G B H N J M`
- Upper octave: `Q 2 W 3 E R 5 T 6 Y 7 U`

### Gamepad (default layout)

| Control | Action |
|---------|--------|
| A / B | Play‑pause / Stop |
| X / Y | Clear / Toggle loop |
| L1 / R1 | Previous / next tab |
| D‑pad / Left stick | Navigate (hold to repeat) |
| Right stick ↑ / ↓ | Increment / decrement (hold to repeat) |

Bind a control *while holding another* to create a chord (e.g. "A + Left").

### MIDI

Note‑on/off play live. Bind Control‑Change numbers to actions in **Setup → MIDI
Bindings** (or MIDI‑learn them). Momentary nav CCs auto‑repeat while held.

---

## Tips & troubleshooting

- **A note is stuck.** Setup → **MIDI PANIC** silences everything immediately.
- **No sound from a track.** Check the note's **channel** matches a mixer
  channel's **MIDI CH**, that the channel has an **instrument**, and that it isn't
  **muted** (or another channel **solo**ed).
- **Crackles/dropouts.** The engine adapts its buffer automatically; make sure no
  other heavy app is competing, and try routing output to a different device in
  Setup → Audio Devices.
- **A preset/instrument you want to keep.** Clearing a tile can't be undone —
  **SAVE** it as a preset first. Long‑press asks before clearing for this reason.
- **Moving a song to another app.** Export a **`.sng`** (notes/blocks/arrangement
  are desktop‑compatible); keep a **full project** for the device‑specific mix and
  samples.
- **Auditioning fast.** Open any instrument in the Toolbox and use the pinned
  keyboard; hold nav controls to move around quickly thanks to hold‑to‑repeat.

---

*Sizzletracker is free software, licensed GPL‑3.0‑or‑later.*
