API

API

Create one ATMsynth and call these from the sketch. Every method except play() can be compiled out with an ATM_FUNC_* flag in ATMconfig.h; calling a removed method is a compile error.

Channels: CH_ZERO (0), CH_ONE (1), CH_TWO (2), CH_THREE (3). Defaults at compile time: CH0 pulse, CH1 square, CH2 saw, CH3 noise (change them in ATMconfig.h and rebuild).

Sound effects

There are two ways to play a sound effect over a running song. The sketch examples/soundEffects/sfxDemo has 45 effects in each style, in the same order, so you can compare them with the A and B buttons (A = poke, B = playSfx, LEFT / RIGHT = next effect, UP = next song, DOWN = pause). The screen shows the name and byte size of each effect.

playSfx

A one-track effect is a PROGMEM byte list that ends with ATM_STOP_CHAN. ATMcmds.h provides a wrapper:

ATM_SFX_TRACK(sfxJump,
  ATM_VOL(50),
  ATM_SL_VOL((uint8_t)-3),   // fade out
  ATM_GLIS(0x01),            // glide up one semitone per 2 ticks (ATM_GLIS(0) = glissando OFF, so use 0x01 or more for upward; 0x80 = down, 1 tick per semitone)
  ATM_NOTE_C4,
  ATM_DELAY(14)
);
// expands to: const uint8_t sfxJump[] PROGMEM = { ..., ATM_STOP_CHAN };

Play it with ATM.playSfx(sfxJump, CH_ONE);. The effect takes the channel for its duration, silences the song on that channel (even while the song is paused) and gives the channel back when it ends. Nothing else is needed: no mute calls. The usual pattern is to put hits on the noise channel (CH_THREE) or on a voice that is quiet in the song. playSfx() also works with no song playing.

• Timing follows the song tempo. Delays are in ticks, so the same effect lasts about 30 % shorter in a song at 52 than in a song at 38. Do not put ATM_SET_TEMPO in an effect: it changes the tempo of the song as well.
• One track, no calls. GOTO and REPEAT need other tracks, so an effect is a flat list of commands.
• One slide slot per channel (section 4.5): SL_VOL and SL_FRQ replace each other. For a pitch sweep with a fade use GLIS plus SL_VOL.

Poke

The effect writes the oscillator registers directly, once per frame, instead of going through a track. examples/soundEffects/sfxDemo/sfx.h is the player (about 70 lines; copy it with the sketch). An effect is a list of segments and an end marker:

SFX_SEG(m, SFX_HZ(1320), SFX_SL(0), 4)    // m = volume shift 0..3, start Hz, slide Hz/frame, frames
SFX_SEG(m, SFX_HZ(1760), SFX_SL(0), 14)
SFX_END

Volume at each frame is min(63, framesLeft << m), so every segment fades out; m sets how long it stays loud (3 = short and loud, 0 = long and soft). A segment is 4 bytes, plus 1 for the end marker. Play it with sfxPlay(effect, channel) and call sfxUpdate() once per frame (it must be 60 times a second, e.g. right after nextFrame()).

• Units. The oscillator frequency unit is 31250 / 65536 = 0.4768 Hz; SFX_HZ() and SFX_SL() convert. Keep the pitch between 40 Hz and 7800 Hz and the slide within about +-240 Hz per frame (SFX_SL is applied four times per frame).
• Mute. The player mutes its channel with ATM.muteChannel() so the playroutine does not overwrite the values. The playroutine clears every mute when a song restarts a loop, so the mute is re-asserted every frame (that is why sfxUpdate() must run every frame), and each mute change is wrapped in cli() / SREG because the playroutine runs in an interrupt.
• Noise channel (CH3). Never write osc[3].freq: it holds the noise shift register. The player only sets the volume there (halved).
• A running song is required. The poke only works while the playroutine interrupt is running, so not after a one-shot song has ended; use playSfx there.
• While paused. ATM.pause() makes the playroutine set the volume of every channel without a playSfx to 0 about 38 times a second, which would chop a poked effect. The demo starts a 4-byte silent playSfx on the effect's channel first (ATM.playSfx(pokeHold, ch) with ATM_SFX_TRACK(pokeHold, ATM_VOL(0), ATM_DELAY(40))), which keeps the playroutine off that channel.
• Starting a poke effect while a playSfx runs on the same channel (or the other way round) makes one of them silent. The demo stops the poke effect (sfxStop()) before playSfx.

Keep the music quieter than the effects

In-game music should play at about 60 % of the volume used for title music whenever the game uses sound effects; effects at full volume are otherwise lost behind the song. Title or menu music (no effects) can stay at 100 %. Do not scale the volume with a runtime control; scale the numbers in the song at compile time, which costs no bytes:

#define MUSIC_VOL_PCT 60                       // 100 = original
#define MV(v) ((v) * MUSIC_VOL_PCT / 100)
// the fade step, scaled the same way and never below 1 (a 0 would stop the fade)
#define MS(n) ((uint8_t)-((((n) * MUSIC_VOL_PCT + 50) / 100) < 1 ? 1 : (((n) * MUSIC_VOL_PCT + 50) / 100)))

ATM_VOL(MV(34)), ATM_SL_VOL(MS(2)), ...        // instead of ATM_VOL(34), ATM_SL_VOL((uint8_t)-2)

Scale both: if only ATM_VOL is scaled, every note starts lower but fades at the old rate and dies sooner, so the song sounds clipped and drier. Scaling the fade step too keeps the shape. A fade step of 1 cannot be made smaller, so very slow fades (SL_VOL(-1)) still end somewhat earlier at 60 % than in the original. All five songs in sfxDemo/ use these macros (MUSIC_VOL_PCT is at the top of song.h); extras/tools/gen_demo_songs.py emits them.

Cues

Put ATM_CUE(id) anywhere in a score (2 bytes) and poll it from the sketch:

uint8_t id = ATM.check();      // returns the last cue and clears it
if (ATM.check(3)) {
  // last cue was 3: e.g. fire a sprite frame (check(id) does not clear)
}

A cue is overwritten by the next one if the sketch does not poll often enough. Escaper Droid puts ATM_CUE(1) in its kick track so a droid sprite dances on the beat.

Config

Compile-time config

Waveforms, effects, functions and octaves are fixed at compile time. Copy docs/ATMconfig.h into the sketch folder as ATMconfig.h, edit it and rebuild. Every flag defaults to on, including when the sketch has no ATMconfig.h. 1 or TRUE compiles a feature in, 0 or FALSE leaves it out.

• Waveforms: ATM_WAVE_CH0 to ATM_WAVE_CH3 = ATM_WAVE_PULSE (0), ATM_WAVE_SQUARE (1), ATM_WAVE_NOISE (2, use on CH3), ATM_WAVE_SAW (3) or ATM_WAVE_OFF (255, no mixer for that channel = smaller ISR and fewer cycles). If no channel is noise, the LFSR is left out of the ISR.
• ATM_ALT_WIRING: 0 = stock Arduboy speaker on OCR4A only; 1 = also drive OCR4D (homemade or dual-pin wiring).
• Effects, functions, octaves: switches such as ATM_FX_ARP, ATM_FUNC_SFX, ATM_OCTAVE_6. ATM.play() is always compiled. ATM_FUNC_PLAYPAUSE needs pause and resume.

The full template, docs/ATMconfig.h (you can also download ATMconfig.h):

#ifndef _ATMCONFIG_H_
#define _ATMCONFIG_H_

// Waveforms are fixed at compile time. Change these, then recompile.
// ATM_WAVE_PULSE  0
// ATM_WAVE_SQUARE 1
// ATM_WAVE_NOISE  2   (use on channel 3; ATM_NOISE() is a song macro)
// ATM_WAVE_SAW    3
// ATM_WAVE_OFF    255  (no mixer for this channel — smaller ISR)

#ifndef ATM_WAVE_PULSE
#define ATM_WAVE_PULSE  0
#define ATM_WAVE_SQUARE 1
#define ATM_WAVE_NOISE  2
#define ATM_WAVE_SAW    3
#define ATM_WAVE_OFF    255
#endif

#ifndef ATM_WAVE_CH0
#define ATM_WAVE_CH0 ATM_WAVE_PULSE
#endif
#ifndef ATM_WAVE_CH1
#define ATM_WAVE_CH1 ATM_WAVE_SQUARE
#endif
#ifndef ATM_WAVE_CH2
#define ATM_WAVE_CH2 ATM_WAVE_SAW
#endif
#ifndef ATM_WAVE_CH3
#define ATM_WAVE_CH3 ATM_WAVE_NOISE
#endif

// Example: drop ch2 from the mixer
// #define ATM_WAVE_CH2 ATM_WAVE_OFF

// 0 = stock Arduboy speaker on OCR4A only
// 1 = also drive OCR4D (homemade / dual-pin wiring)
#ifndef ATM_ALT_WIRING
#define ATM_ALT_WIRING 0
#endif

// ---------------------------------------------------------------------------
// Effects, functions, octaves. 1 or TRUE = compile in. 0 or FALSE = leave out.
//
// WARNING: the tracker still writes the same song bytes. Nothing is stripped
// from a score. If a flag is 0 and a song or SFX still uses that effect,
// function, or octave, the sketch breaks: the player ignores the command and
// does not consume its parameter bytes, a removed function will not compile,
// and an excluded note is silent. That is the sketch author's responsibility.
//
// A sketch with no ATMconfig.h compiles all of these in. The 1s below match that.
// ATM.play() is always compiled. ATM_FUNC_PLAYPAUSE needs PAUSE and RESUME.
// ---------------------------------------------------------------------------

// Effects (command + per-tick code, and the channel fields they need)
#ifndef ATM_FX_VOLUME
#define ATM_FX_VOLUME 1       // ATM_VOL
#endif
#ifndef ATM_FX_VOL_SLIDE
#define ATM_FX_VOL_SLIDE 1    // ATM_SL_VOL / ATM_SL_VOL_ADV / ATM_SL_VOL_OFF
#endif
#ifndef ATM_FX_FREQ_SLIDE
#define ATM_FX_FREQ_SLIDE 1   // ATM_SL_FRQ / ATM_SL_FRQ_ADV / ATM_SL_FRQ_OFF
#endif
#ifndef ATM_FX_ARP
#define ATM_FX_ARP 1          // ATM_ARP / ATM_ARP_OFF
#endif
#ifndef ATM_FX_NOISE
#define ATM_FX_NOISE 1        // ATM_NOISE / ATM_NOISE_OFF (retrigger)
#endif
#ifndef ATM_FX_TRANSPOSE
#define ATM_FX_TRANSPOSE 1    // ATM_ADD_TRA / ATM_SET_TRA / ATM_TRA_OFF
#endif
#ifndef ATM_FX_TREMOLO
#define ATM_FX_TREMOLO 1      // ATM_TREM / ATM_TREM_OFF
#endif
#ifndef ATM_FX_VIBRATO
#define ATM_FX_VIBRATO 1      // ATM_VIB / ATM_VIB_OFF
#endif
#ifndef ATM_FX_GLISSANDO
#define ATM_FX_GLISSANDO 1    // ATM_GLIS / ATM_GLIS_OFF
#endif
#ifndef ATM_FX_NOTE_CUT
#define ATM_FX_NOTE_CUT 1     // ATM_CUT / ATM_CUT_OFF
#endif
#ifndef ATM_FX_CUE
#define ATM_FX_CUE 1          // ATM_CUE command (stores the byte)
#endif
#ifndef ATM_FX_TEMPO
#define ATM_FX_TEMPO 1        // ATM_ADD_TEMPO / ATM_SET_TEMPO in the score
#endif
#ifndef ATM_FX_GOTO_ADV
#define ATM_FX_GOTO_ADV 1     // ATM_GOTO_ADV
#endif
#ifndef ATM_FX_STOP
#define ATM_FX_STOP 1         // ATM_STOP_CHAN
#endif

// Functions (calling one that is 0 is a compile error)
#ifndef ATM_FUNC_STOP
#define ATM_FUNC_STOP 1       // ATM.stop()
#endif
#ifndef ATM_FUNC_PAUSE
#define ATM_FUNC_PAUSE 1      // ATM.pause()
#endif
#ifndef ATM_FUNC_RESUME
#define ATM_FUNC_RESUME 1     // ATM.resume()
#endif
#ifndef ATM_FUNC_PLAYPAUSE
#define ATM_FUNC_PLAYPAUSE 1  // ATM.playPause() — needs PAUSE and RESUME
#endif
#ifndef ATM_FUNC_MUTE
#define ATM_FUNC_MUTE 1       // ATM.muteChannel()
#endif
#ifndef ATM_FUNC_UNMUTE
#define ATM_FUNC_UNMUTE 1     // ATM.unMuteChannel()
#endif
#ifndef ATM_FUNC_SFX
#define ATM_FUNC_SFX 1        // ATM.playSfx()
#endif
#ifndef ATM_FUNC_TEMPO
#define ATM_FUNC_TEMPO 1      // ATM.setTempo()
#endif
#ifndef ATM_FUNC_CUE
#define ATM_FUNC_CUE 1        // ATM.check() / ATM.check(id)
#endif

// Notes. Each flag is one octave of the 1..63 note numbers.
// C2-B2, C3-B3, C4-B4, C5-B5, C6-B6, C7-D7. Excluded notes are silent.
#ifndef ATM_OCTAVE_2
#define ATM_OCTAVE_2 1        // C2-B2
#endif
#ifndef ATM_OCTAVE_3
#define ATM_OCTAVE_3 1        // C3-B3
#endif
#ifndef ATM_OCTAVE_4
#define ATM_OCTAVE_4 1        // C4-B4
#endif
#ifndef ATM_OCTAVE_5
#define ATM_OCTAVE_5 1        // C5-B5
#endif
#ifndef ATM_OCTAVE_6
#define ATM_OCTAVE_6 1        // C6-B6
#endif
#ifndef ATM_OCTAVE_7
#define ATM_OCTAVE_7 1        // C7-D7
#endif

#endif

Song format and commands

2. Song data format

2.1 Layout

2.2 Byte layout and rules

byte 0               N = number of tracks
bytes 1 .. 2N        N x uint16 little-endian: offset of each track,
                     relative to the first byte AFTER the 4 channel-entry bytes
next 4 bytes         entry track number for CH0, CH1, CH2, CH3
then                 track data, tracks back to back, in table order

• Header cost = 1 + 2N + 4 bytes. Every extra track costs 2 bytes of table plus its closing RETURN. The 250-byte budgets are tight mostly because of this.
• Tracks are addressed by index 0..N-1 (max 255 tracks).
• A called track ends with ATM_RETURN. An entry track of a looping song ends with ATM_GOTO(<itself>) (section 6). An entry track of a one-shot song ends with ATM_STOP_CHAN. An unused channel points at a track that holds only ATM_STOP_CHAN (1 byte).
• The song array must be const uint8_t PROGMEM.

3. Command reference

Values are from ATMcmds.h (the source of truth). Sections 3.1 and 3.3 are the byte-level spec (opcode ranges and effect numbers, with the bytes each one uses); 3.2 and 3.4 are the practical macro reference.

3.1 Opcode map

3.2 Core macros

Reserved range. Command bytes 225..255 are reserved and ignored. The former 0xFF "embedded data" command (length + data bytes for the host) has been removed from the library; use ATM_CUE(v) (0x57, v, effect 23, read with ATM.check()) to signal the sketch instead. The Bytes columns match the // uses N bytes comments in ATMcmds.h.

3.3 Effect numbers (full detail)

Every effect is 64 + n, i.e. 0x40 + n, followed by its parameter bytes.

Thoughts on effects:

Note: These are the primitives to be implemented in the playroutine effects processor. Most will have several effect command numbers associated with them for various aspects of the same primitive. Effects can be combined but not stacked, but some combinations may have undesired/interesting interference.

• Volume slide: a gradual increasing or decreasing of the volume.
• Frequency slide: a gradual increasing or decreasing of the frequency.
• Arpeggio: a group of notes which are rapidly and automatically played one after the other.
• Retriggering (on note or by automation): oscillators are restarted either automatically or at the start of each new note.
• Transposition (also for microtonals): play notes in a different key, or fine tune notes to provide microtonals; frequencies that are in between notes.
• Tremolo: a slight, rapid and regular fluctuation in the amplitude/volume of a note.
• Vibrato: a slight, rapid and regular fluctuation in the pitch of a note.
• Glissando: controls if and how a gradual frequency slide "snaps" to adjacent notes.
• Note cut (with delay and automation): provides a method to stutter and adjust note timing.

3.4 Effect macros (all are 64+n, i.e. 0x40+n)

3.5 Writing rules for the .h

• Negative arguments need a cast: ATM_SL_VOL((uint8_t)-5), ATM_ADD_TRA((uint8_t)-4). Plain -5 fails strict C++ narrowing.
• Sharps: ATM_NOTE_F5_, never ATM_NOTE_F#5.
• Use the macro for every note and delay; comment each track.

How the playroutine behaves

4. How the playroutine really behaves

All of this is from ATMlibimpl.h. A Python model of it is extras/tools/atmsim.py.

4.1 Tick order and delay

Each tick, for channel 0, 1, 2, 3 in that order: apply effects (slides, arpeggio, ...), then, if the channel's delay is 0, run commands until one sets a delay. ATM_DELAY(d) makes the note/state last exactly d ticks. When a delay expires, the next command runs in that same tick, so chained delays and calls cost no extra tick.

4.2 Notes, volume and transposition

• A note value 1..63 sets the pitch to note + transposition at the moment of the note-on. Changing the transposition later does not move a sounding note.
• Keep note + transposition inside 1..63. With all octaves compiled in, the pitch table is read without bounds checking, so out-of-range values read garbage.
• At every note-on the volume is reset to the last ATM_VOL(v) value, but only when the active slide is a plain ATM_SL_VOL/none (config byte 0). With SL_VOL_ADV or any frequency slide active the volume is not reset. This is what makes "VOL(38) + SL_VOL(-2)" a plucky lead: every note starts at 38 and decays by 2 per tick.
• Volume range 0..63 per channel. The noise channel's volume is halved in the mixer. Very loud sums of all channels can distort.

4.3 Calls, the call stack and the track-0 trap

• GOTO/REPEAT push a return frame (counter, track, position). Maximum depth 7.
• A call to the track the channel is currently in does not push; it just restarts that track, in the same tick, without touching volume or any other state. This is what the self-loop of section 6 is built on. (Because every channel starts with "current track = 0", the very first GOTO(entry) of a channel whose entry track is not 0 does push one frame, once; count it in the depth limit.)
• Every channel starts with "current track = 0", whatever its entry track is. So a channel that calls track 0 from its entry track does not push a frame. When track 0 then returns with an empty stack, it simply restarts itself forever. Rule: never call track 0 from another track. Track 0 may be used only as a channel entry (CH3 in Quest Theme) or as a dummy that nobody calls (the older songs have a "silent" track 0). An entry track 0 that ends with ATM_GOTO(0) is fine: that is a call to the track it is already in (see below). Measured example: the rejected pixelchase.h had its melody bar as track 0. In the simulator CH0 plays bars 1-6 correctly, then repeats bar 1 forever and never stops, while the other three channels stop at tick 511 and the song never restarts.
• RETURN with a repeat counter above 0, or with an empty stack, restarts the current track instead of leaving it. So ending an entry track with RETURN instead of STOP loops that track forever.
• REPEAT(n,t) runs t n+1 times. Nested repeats are fine (counters are saved in the frame).

4.4 Stop, end of song and looping

• STOP sets the channel volume to 0 (ch->vol = 0, ATMlibimpl.h, case 95) and parks the channel with an endless delay. When all four channels have stopped:
• if the sum of the four GOTO_ADV restart tracks is 0 (or GOTO_ADV was never executed) the song ends;
• otherwise every channel jumps to its restart track and the song continues.
• This restart is the cause of the loop "hop". The channels that stopped first are silent (volume 0) from their STOP until the last one stops, and the restart itself costs one more tick, so every loop contains a tick in which all four channels are silent. The period is exactly right, but the seam is audible (about 30 ms at tempo 34). This was found by ear on Italo Night, Escaper Droid, Neon Heart, Quest Theme, Star Light and the first version of the in-game songs.
• Looping songs therefore must not stop at all. Loop with a self-GOTO at the end of every channel's entry track (section 6). Do not use STOP, do not use GOTO_ADV.
• One-shot songs end with STOP on every channel and contain no GOTO_ADV (Midnight Run, a 3-minute one-shot, has none. When Claude once left it in, the song restarted).
• Background, only for old files: the restart is decided right after the last channel stops, inside the channel loop. If the last channel to stop is not CH3, the channels after it start the new loop one tick earlier than the ones before it, so all four channels had to stop on the same tick. The restart does not reset volume, slides, arpeggio or transposition. Both facts are irrelevant for a self-loop, but the second one still holds: state persists across the loop, so set what you need at the start of each channel's main track (typically ATM_SET_TRA(0)).

4.5 Slides

SL_VOL(s) changes volume by s every tick. SL_FRQ(-127) on a square note makes the classic pitch-drop kick (Italo Night). After SL_FRQ the volume is not re-applied at note-on, so set ATM_VOL explicitly before the note.

4.6 Arpeggio

ATM_ARP(a, y) plays three notes in rotation from the note you start:

• a = AAAABBBB: second note = base + A semitones; third = second + B.
• y = FEDttttt: D (0x20) = restart the rotation at every note-on; E (0x40) = no third note (two-note arp); ttttt = ticks per step minus one. 0x20 means one tick per step (about 11 rotations per second at tempo 34); 0x21 two ticks, etc.
• Chord values (README extras/notesInChords.md + inversions):

• Inversions keep the stabs in one register. Italo Night plays every chord from around G3..B3 using 0x34 / 0x35 / 0x54 with a changing base note.
• Do not combine ATM_ARP with transposition on the same channel. During arpeggio steps the playroutine adds the transposition a second time (ATMlibimpl.h, the line ATM__FREQ(arpNote + ch->transConfig) while arpNote already includes it). Put the arpeggio on one channel with explicit root notes, and use transposition on other channels.
• ATM_NOTE_x after ATM_ARP sets the base note; a new note restarts the rotation when 0x20 is set.

4.7 Noise channel (CH3)

CH3 is noise; drums are made purely with VOL + SL_VOL + DELAY (no notes needed). Volume is halved in the mixer. See section 8.1 for the approved recipes.

4.8 Known traps in the library files

• ATM_DELAY(0) is the STOP byte.
• Note 1 is C2 (ATM_NOTE_C2). Older documents called it C1 or C4: the name is a label, see section 5.2.
• README says tempo values are 0..127 and "the higher the tempo, the more CPU".

4.9 Effect details verified in ATMlibimpl.h (used by Cutlass Cove)

Per tick, per channel, the order is: noise retrigger, glissando, volume/frequency slide, arpeggio/cut, tremolo/vibrato, then the command stream.

• One slide slot per channel. SL_VOL, SL_VOL_ADV, SL_FRQ, SL_FRQ_ADV share a single slide. Starting one replaces the other. Cannon boom on the bass: ATM_SL_FRQ(-24) for 16 ticks, then ATM_SL_VOL(-3) both ends the pitch slide and starts the volume decay.
• Positive volume slides are not clamped at 63 (a dangling else in the library: only freq is clamped above). vol is a byte, so a fade-in must be stopped on purpose (ATM_SL_VOL_OFF, or a new ATM_SL_VOL) before it reaches 63. Negative slides clamp at 0. Same for tremolo.
• Fades: ATM_VOL(0), ATM_SL_VOL_ADV(1, 8) adds +1 every 9 ticks and, because the config byte is non-zero, notes do not reset the volume, so the fade runs straight through note-ons. Fade-out: ATM_SL_VOL_ADV((uint8_t)-1, 5) from a starting ATM_VOL. SL_VOL_ADV and SL_FRQ set the config byte, so afterwards use plain ATM_SL_VOL(x) (which sets config 0) before expecting note-on volume resets again.
• Frequency slide SL_FRQ(s) moves the frequency by s Hz per tick (table of extras/frequencyToTone.md); clamped 0..9397.
• Tremolo is a triangle LFO on the volume: the first half goes down. ATM_TREM(1, 15) = sea swell with a 32-tick period. ATM_TREM(6, 0) on a rising volume (VOL(10), SL_VOL(2)) = a snare roll in 8 bytes; end it with ATM_TREM_OFF.
• Vibrato is the same on the frequency. A new note restarts the frequency, the LFO phase carries on, so the vibrato stays bounded.
• Glissando ATM_GLIS(x): moves the note by one semitone every (x & 0x7F)+1 ticks, upward, or downward when bit 7 is set (0x82 = down, 3 ticks per step); stops at 1 and 63. End it with ATM_GLIS_OFF. Loop trap: the glissando step counter is not reset by ATM_GLIS_OFF or by a new note, it just freezes. If the glissando runs for a number of ticks that is not a multiple of its period (x & 0x7F)+1, the next run starts at a different phase and every loop pass shifts by a tick or more (found in Orbital Rush: GLIS(0x02) = period 3 over 64 ticks). Pick a period that divides the run length (GLIS(0x01), 0x03, 0x07 over 64 ticks). The same holds for the vibrato/tremolo period (section 6). Check with the simulator that pass 1 and pass 2 are identical tick by tick.
• Note cut is a repeating gate: after the note-on it sounds for n+1 ticks, is silent for n+1 ticks, then sounds again. With ATM_CUT(0x23) and 8-tick notes you get 4 ticks on, 4 off, exactly staccato. Notes longer than 2(n+1) ticks come back to life, so keep the notes at one length. With a non-zero transposition the "silence" plays note number = transposition* (the table is read at index 0+tra, negative = garbage), so use CUT only where transposition is 0.
• Noise retrigger ATM_NOISE(x) (x = entry point * 4 + speed; 0x14 = point 5, speed 0) reseeds the LFSR every tick = low rumble (thunder). It shares reCount with the volume buffer, so use it on CH3 where no notes are played, and call ATM_NOISE_OFF afterwards.
• Cue: ATM_CUE(v) stores one byte; ATM.check() returns it and clears it, ATM.check(id) tests without clearing. A cue is overwritten by the next one if the sketch does not poll often enough. Put cues on a track that is already part of the beat sequence (2 bytes per marker).
• Tempo changes are global (any channel); put them on CH3 so the tick domain stays easy to read. Ticks are all that other channels count, so a tempo change never breaks the alignment.

5. Timing, tempo and pitch

5.1 Tempo

• Default tempo (no SET_TEMPO) is 25. cia = 15625 / tempo.
• Empirical rule (measured on real hardware): ticks per second ≈ the tempo value. An offline emulator that gives 2 ticks per second per tempo unit plays twice as fast as the hardware. Hence the house rule: double the emulator's tempo value.
• With 16 ticks per beat: BPM = tempo x 3.75. Examples: 24 -> 90, 30 -> 112.5, 32 -> 120, 34 -> 127.5, 36 -> 135, 40 -> 150.
• Song length in seconds ≈ ticks / tempo. Quest Theme: 1024 ticks / 34 ≈ 30 s.

5.2 Pitch

• The note names are not concert pitch. Working assumption used in all approved songs (stated in the Italo Night header): the table frequency is halved by the 31250 Hz mixing, so a note sounds about an octave above its name and about 80 cents flat (ATM_NOTE_A2 ≈ 210 Hz).
• What matters is relative pitch and register. Registers (by label) that worked: lead A4..D6, chord arps G3..E4, bass A2..A3 (plus transposition), drums on the noise channel.

6. Hop-free loops: the self-loop (the most important section)

Let the loop be L ticks long (Quest Theme: 16 bars x 64 = 1024).

The method

1. Every channel's entry track ends with ATM_GOTO(<that same track>) instead of ATM_STOP_CHAN. A call to the track you are already in does not push the call stack: it jumps back to the first command of the track in the same tick. No tick is lost, nothing is silenced, volume and slides simply carry on.
2. Every channel contains exactly L ticks of delay (not L-1). The last note of the last bar keeps its full delay.
3. No ATM_STOP_CHAN, no ATM_GOTO_ADV, no trimmed delay, no _last variant tracks.
4. An unused channel's entry track holds a single ATM_STOP_CHAN (1 byte); it is silent from tick 0, which is what you want.
5. State persists across the loop (volume, slide, transposition, arpeggio). Set what the pass depends on at the start of each entry track (typically ATM_SET_TRA(0)), and let the state at the end equal the state at the start.

Song x[] = {
  ...
  //"Track 3" lead
  ATM_VOL(38),
  ATM_SL_VOL((uint8_t)-2),
  ...bars...
  ATM_GOTO(3),   // loop: restart this track (no STOP, no gap)

Why the old method hopped is in 4.4 (STOP sets volume 0 and the restart tick is silent on all channels). The self-loop never stops, so there is no seam to hear. Confirmed by ear on the real hardware.

Details that matter

• Delay sum: if one channel sums to L+1 or L-1 it drifts by one tick against the others every loop. The simulator catches it (see below).
• Call depth: an entry track other than 0 pushes one frame on its first GOTO(itself) (every channel starts with "current track = 0"). Entry track 0 (CH3 in Quest Theme) pushes none. Count this against the limit of 7.
• Intro + body: give every channel an entry track E = [GOTO intro, GOTO loopT] and a loop track loopT = [GOTO body, GOTO loopT]. The intro plays once; the loop track repeats the body forever and calls itself. The body must start by setting everything it depends on (ATM_VOL, ATM_SL_VOL, ATM_SET_TRA, ATM_ARP). Star Light (extras/tools/gen_starlight.py) is built this way. A leftover slide counter of the intro can change a volume by a few units for a few ticks in the first body pass only; the note events are identical.
• Cost: GOTO is 2 bytes where STOP was 1 (+1 per channel), GOTO_ADV (5 bytes) disappears, and every _last variant track (10 to 40 bytes plus 2 in the table) disappears because the last bar is the same as every other pass of that bar. Converting Italo Night saved 89 bytes (558 to 469), Escaper Droid 89, Neon Heart 89, Star Light 147.
• Tempo command in the loop: a song whose drum track (the usual CH3 entry, track 0) begins with ATM_SET_TEMPO re-executes it every pass. It sets the same value, so it is harmless.

Proof, not belief. Simulate three loops (extras/tools/atmsim.py, extras/tools/gen_quest.py). All of these must hold:

• restarts == [] and no STOP after tick 0 (an unused channel's STOP at tick 0 is fine)
• for every tick t >= L: TIMELINE[t] == TIMELINE[t-L] for all four channels (volume, and frequency whenever the volume is not 0; a silent channel's last pitch is irrelevant)
• the note events of loop 1, 2 and 3 are identical
• max call depth <= 7

Converting an old STOP + GOTO_ADV song: convert.py (extras/tools/convert.py) does it automatically: it adds 1 to the last executed delay of every channel (the old loop was L-1 ticks of delay plus one restart tick), turns the entry track's final STOP into GOTO(entry), deletes GOTO_ADV, merges the tracks that became identical, and checks the result against the old song with the simulator and the real ATMcmds.h.

One-shot songs: no self-loop, no GOTO_ADV; channels end with ATM_STOP_CHAN and may end at different times; the song ends when the last one stops. For fades use ATM_VOL steps per section or ATM_SL_VOL.

Songwriting guide

Audience: a person or an AI starting from zero. Every statement here was checked against the ATMlib source (ATMcmds.h, ATMlibimpl.h) and against songs that were tested on hardware (Italo Night, Escaper Droid, Midnight Run, Quest Theme, Star Light). Where something is an empirical finding rather than source code, it says so.

How to use this part: give an AI assistant this README plus the ATMlib folder, and say what you want (style, key, length, byte budget, loop or one-shot). It should read sections 0, 4, 6 and 9 first.

Loops: all loops use the self-loop method of section 6 (no ATM_STOP_CHAN, no ATM_GOTO_ADV). The older STOP + GOTO_ADV loop leaves one silent tick at the seam, audible as a "hop"; the self-loop fixed it (confirmed by ear). extras/tools/convert.py converts old songs.

0. Start here

0.1 House rules for songs in this project (always apply)

1. Double the tempo. Wherever an emulator or offline analysis says 17, write ATM_SET_TEMPO(34). On the real Arduboy the song plays at about tempo-value ticks per second (see 5.1). Quest Theme uses 34.
2. Deliver only the song .h. No WAV file unless asked.
3. Write songs as commands, e.g. ATM_NOTE_A4, ATM_DELAY(8), ATM_VOL(38). Never write track bodies as raw hex. The small header (track count, track addresses, channel entry tracks) is hex, exactly as in the reference song.h.
4. Byte budget means the whole array, including the header. "Max 250 bytes" = sizeof(song) <= 250.
5. Loops must be hop-free. A STOP + GOTO_ADV restart silences all four channels for one tick (about 30 ms) at every loop, and it is clearly audible. Make every loop a self-loop: each channel's entry track ends with ATM_GOTO(<itself>) and every channel sums to exactly L ticks. See section 6.
6. Tempo belongs to the sketch when the author says so. If the sketch sets it from the sketch (ATM.setTempo()), leave ATM_SET_TEMPO out of the song (quest.h has none now: without it the song plays at ATMlib's default of 25, not 34).
7. Quality bar: Italo Night, Midnight Run and Quest Theme are the reference songs; the in-game loops (section 8.7) are the reference for tiny budgets. Pixel Chase was rejected: too plain, and actually broken (section 12).
8. Game music at 60 %. Songs meant for in-game use with sound effects are written (or scaled) to about 60 % of the volume of title music, with ATM_VOL(MV(n)) and ATM_SL_VOL(MS(n)) (see Sound effects). Title music stays at 100 %.

0.2 Starter prompt for a fresh session

0.3 The workflow in ten lines

1. Read ATMcmds.h for the real opcode values. Never guess them (section 12, mistake 1).
2. Decide: tempo (doubled), key, number of bars, loop or one-shot, byte budget.
3. Time grid: 16 ticks = 1 beat, 64 ticks = 1 bar (used by all approved songs).
4. Plan every channel in ticks. For a loop of L ticks every channel must contain exactly L ticks of delay, and its entry track must end with ATM_GOTO(itself) (section 6). No STOP, no GOTO_ADV, no trimmed last delay, no _last tracks.
5. Write the song with a generator script (named tracks, automatic track numbers and offsets). extras/tools/gen_quest.py is a complete example.
6. Run the simulator (extras/tools/atmsim.py): no channel ever stops (except an unused one at tick 0), the song never restarts, the per-tick timeline repeats exactly with period L, call depth is at most 7, no note out of range.
7. Print the notes per bar and check harmony and register by eye.
8. Emit the .h with ATM_* macros and compile it against the real ATMcmds.h, then compare the compiled bytes with the generator's bytes (extras/tools/check_header.cpp).
9. Check the byte budget.
10. Deliver the .h only, with a short summary (form, channels, size).

1. Mental model

• ATMlib is a 4-channel tracker-style music player for the Arduboy. Default voices: CH0 PULSE, CH1 SQUARE, CH2 SAW, CH3 NOISE. Waveforms are fixed at compile time (ATMconfig.h), not per song.
• Time is counted in ticks. Tempo sets the tick rate.
• A song is a set of tracks (byte sequences, like subroutines). Each channel starts at one entry track and runs commands one after another. Tracks can call other tracks (GOTO = call and return, REPEAT = call n+1 times).
• Almost everything is state that persists until you change it: volume, volume slide, transposition, arpeggio. This is the source of most bugs and most savings.
• A note plays until the next note or the next VOL(0). A DELAY makes the channel wait; the sound keeps going meanwhile.

7. Fitting a byte budget

Costs: note 1, delay 1, VOL/SL_VOL/SET_TRA/ADD_TRA/SET_TEMPO 2, ARP 3, GOTO 2, REPEAT 3, RETURN/STOP 1, plus 2 per track in the table and 5 for the header.

What saves bytes (in the order that mattered):

1. Transposition instead of copies. One 2-bar riff (30 B) plays over every chord with SET_TRA/ADD_TRA (2 B per use). The bass bar is written once in the key of A and transposed the same way.
2. REPEAT for identical bars: 3 bytes for any number of repeats.
3. Shared tracks pay off when a pattern of length L >= 5 is used at least twice.
4. Relative transposition cycles: a track of [riff][ADD_TRA(5) riff][ADD_TRA(-5) riff] returns to its start key, so the whole cycle can be re-played in another key by one SET_TRA.
5. Inline tiny things (a 4-byte track costs 6 with its table entry).
6. Drums: one 24-tick core shared by every half-bar, called with REPEAT(30, ...).
7. Chords as explicit long notes with an arp: NOTE, DELAY(64), NOTE, DELAY(64) is 4 bytes per two bars.

Quest Theme budget (233 bytes, self-loop): header 29 B, drums 39 (entry + core + half), lead 68, chords 41, bass 56. (The old STOP + GOTO_ADV version was 247 B: it needed the 5-byte GOTO_ADV, a trimmed bass_bar_last track and STOPs.)

7.1 Making a song smaller without changing it (Italo Night: 469 B to 365 B)

italoDiscoCompressed (examples/loops/italoDiscoCompressed) plays exactly like italoNight and is 104 bytes smaller (22 %). Counting from the first version: 558 B (STOP + GOTO_ADV), 469 B (self-loop), 365 B (compressed). The work is structure, not notes. In order of savings:

1. Inline every track that is called once. A track used once costs its table entry (2), its RETURN (1) and the call (2): 5 bytes for nothing. The 558 B version of Italo Night had 33 tracks (header 71 bytes); the compressed one has 16 (header 37 bytes).
2. Use the entry track as the body. With the self-loop (section 6) the lead is one track: all 8 bars in a row, then ATM_GOTO(itself). The bass and chords are the same. No _last tracks, no trimmed last delays.
3. Share a track only when it pays. A track of length L used u times costs L + 1 + 2 + 2u against u x L inline, so it wins when (u - 1) x L > 2u + 3: two uses need L >= 8, three uses L >= 5.
4. Repeat bigger blocks. The drums play 4 bars, twice. Put those 4 bars in one track (REPEAT(6, pair), beat A, roll, delay) and call it with REPEAT(1, half): the second half costs nothing. The same applies to the chords (REPEAT(3, beat_X) per bar).
5. Share the common head. Every chord stab starts with the same kick (ARP_OFF, SL_FRQ, VOL, NOTE, DELAY, VOL(0), DELAY, SL_VOL, VOL). It is one kick track called by the five beat tracks. After the self-loop the 4th beat of the last bar is the same beat track as the others, so it needs no special case.
6. Transpose instead of copy, and share the start of near-identical beats. One bass bar track, eight SET_TRA, GOTO bar pairs (4 bytes per bar). The bass beats silence, root, octave, root and silence, root, root, octave both start with VOL(0), DELAY(4), VOL(63), root, DELAY(4): that head is one 8-byte track, the two beats only add their last two notes (5 bytes saved). Where several pieces differ only at the end, share the head. Snare roll: the slide is set once, the roll is inlined in the drum half (it is only used there), and equal neighbours collapse into one REPEAT (two equal bars next to each other: REPEAT(1, bar)).
7. Drop commands that do nothing. Slides, volume and arpeggio are state that persists, so a second SL_VOL(-3) or ARP_OFF with the same value is dead weight. Only remove one after the simulator proves the timeline is unchanged.

What did not pay. Sharing the lead between bars: bars 1 to 4 have the same rhythm (12, 12, 8, 12, 12, 8) but different intervals (E C A, F C A, E C G, D B G), so a shared track would need a different transposition and one changed note per bar, and the extra track costs more than the 5 to 9 bytes it saves. Look for repetition in the byte stream, not in the rhythm: a candidate is only worth a track when the same sequence of commands (or the same sequence shifted by a constant) appears with (u - 1) x L > 2u + 3.

How to be sure it is the same song (the check used here, all four must hold):

• all note events of the new song equal those of the old song, tick for tick;
• the per-tick TIMELINE (volume and frequency of the 4 channels) equals the old one. When the old song is a STOP + GOTO_ADV loop, compare over one pass and expect differences only in the old silent restart tick. A silent channel's frequency may differ (inaudible);
• loops 1, 2 and 3 of the new song are identical, restarts == [], no STOP after tick 0, call depth <= 7;
• the compiled header equals the generator's bytes.

7.2 Shrinking a finished song automatically (Tracker editor button Shrink song)

The two biggest savings of 7.1 can be found by a program. Both are lossless: the result must play exactly like the original.

1. Remove commands that change nothing. Try deleting each VOL, SL_VOL, SL_FRQ, SET_TRA, ARP, VIB, TREM, GLIS and similar command, one at a time. Keep the deletion only when the simulated sound is identical (volume and frequency of the channel on every tick, plus every note event). A repeated SET_TRA(0), a VOL that is already set, or a slide that is set again with the same value are typical. Tempo, STOP, GOTO, REPEAT and RETURN are never touched.
2. Share repeated runs. Any run of two or more commands that appears at least twice, in one track or across tracks, becomes a new track called with GOTO. A run of L bytes used u times saves u x L - (L + 1 + 2 + 2u) bytes, and only runs with a saving above zero are shared. The best run goes first, then the search starts again, until nothing pays. New tracks are appended at the end, so no existing track number changes. Not shared: REPEAT, RETURN, STOP, tempo commands, and a GOTO to its own track or to an entry track. Channel state (volume, slide, arpeggio, transposition) survives a call and a return, so a run does the same thing wherever it is called, but every level of sharing adds one to the call depth: the result is rejected above 7.

Do the first pass first: removing dead commands makes more runs identical. Then check the result like in 7.1 (events, per-tick timeline, loops, depth <= 7, compile). The editor does all of it itself and refuses the result if any check fails.

Where it helps most: songs written from a generator or by hand with many repeated VOL / SL_VOL / SET_TRA heads (drum hits, chord stabs). A song that is already compressed by hand (like italoDiscoCompressed) gains little.

In the tracker editor: Export tab, tick Shrink song. The green line shows the bytes saved and how many dead commands were removed and tracks added. The setting is saved with the song. For a hand-written song.h: the same two passes exist as small Python scripts (shrink.py for generator songs, shrinkmusic.py and prunemusic.py for a ready-made music.h, kept with the project scripts); both use atmsim.py for the check.

8. Composition recipes that worked

8.1 Drums (CH3 NOISE), copied from Italo Night

16-tick beats, all with VOL + SL_VOL + DELAY:

Beat A (beats 1, 3) = kick(4) + closed hat(4) + open hat(8). Beat B (beats 2, 4) = snare(8) + open hat(8). Fills: replace beat 4 of bar 4 and bar 8 with the roll.

8.2 Kick on a tonal channel (Italo Night CH1)

ATM_ARP_OFF, ATM_SL_FRQ((uint8_t)-127), ATM_VOL(30), ATM_NOTE_D3_, ATM_DELAY(4), ATM_VOL(0), ATM_DELAY(4). Needs ARP_OFF first. Use when a channel is free of arpeggios.

8.3 Bass (CH2 SAW)

VOL(63), SL_VOL(-5); one beat track, bar = REPEAT(2, beat) + beat4, with a variation on beat 4 (root, root, octave); the whole bar is written once in the key of A and transposed per chord. * Italo Night beat (16 ticks): VOL(0) DELAY(4) (duck under the kick), VOL(63), root(4), octave(4), root(4). * Quest Theme beat (16 ticks): root(8), octave(8); beat 4: root(8), root(4), octave(4).

8.4 Lead (CH0 PULSE)

VOL(38), SL_VOL(-2): every note starts loud and decays. Write a 1- or 2-bar riff and transpose it per chord. Which riffs survive transposition: use the pentatonic notes of the chord. * Minor key, chords i, iv, v (root offsets 0, +5, +7): minor pentatonic degrees 0, 3, 5, 7, 10 stay inside the key on all three chords. Avoid the 2nd degree on the v chord. * Major key, chords I, IV, V: major pentatonic degrees 0, 2, 4, 7, 9. * A riff containing the third only transposes cleanly between chords of the same quality. Otherwise leave the third out or write explicit notes.

8.5 Arpeggio chords (CH1 SQUARE)

• Stabs (Italo Night): SL_VOL(-3), VOL(24), ARP(0x34, 0x20), NOTE, DELAY(8) once per beat, after the kick.
• Held chords (Quest Theme): VOL(30), SL_VOL(-1), ARP(0x34, 0x20), then NOTE root, DELAY(64) once per bar; the arpeggio shimmers and fades, then re-articulates on the bar.
• Root notes explicit (no transposition on this channel, see 4.6).

8.6 Form

• 8 bars (Italo Night, Escaper Droid): one pass of the chord progression, ~15 s at tempo 17/34.
• 16 bars (Quest Theme): the same 8-bar cycle twice, second time lifted a whole step with one SET_TRA(2), ending on a pivot chord (Em: chord iv of Bm and chord v of Am) so the loop returns smoothly.
• Chord progressions used: Am | F | C | G | Am | F | G | E (Italo Night; bass transposition offsets from A: 0, -4, +3, -2, 0, -4, -2, -5), D | G | A | D | D | Bm | A | D (Escaper Droid; offsets from D: 0, +5, +7, 0, 0, +9, +7, 0), Am Am Dm Dm Am Am Em Em then +2 (Quest Theme).

8.7 Tiny in-game loops (50 to 100 bytes)

The 30-song sketch. All small in-game loops now live in ONE sketch, examples/loops/inGameSongs (song.h holds a PROGMEM pointer array, the A button switches song, the screen shows the name and its byte size, B pauses). Songs 1-5 are the five below, 6-10 chiptune, 11-15 Sega, 16-20 NES, 21-25 C64, 26-30 Game Boy style, each 50 to 100 bytes (list in section 13). Remember that Arduino keeps a stale build folder: if the IDE still shows 25 songs after an update, clean the build.

Volume. These loops are written at full volume. If the game also plays sound effects, scale them to about 60 % (see Sound effects, "Keep the music quieter than the effects").

The five songs in ingame5.h (Meadow Waltz 94 B, Lantern Lake 73 B, Sunday Market 89 B, Pixel Breeze 87 B, Music Box Tide 87 B) were written to show how little a pleasant, smooth, looping background track needs. What they share:

• No drums unless the groove needs them (Lantern Lake, Meadow Waltz, Pixel Breeze, Music Box Tide have none; Sunday Market uses one 16-tick brush track with REPEAT). Harmony and a good bass do the work.
• Self-loop on every channel (section 6): the entry track is the whole part and ends with ATM_GOTO(itself). With only 3 or 4 tracks the header is 11 to 15 bytes.
• Unused channels point at a 1-byte ATM_STOP_CHAN track.
• One long note per bar + an arpeggio is the cheapest chord: ATM_ARP(0x34, 0x23) once, then NOTE, DELAY(64) per bar = 3 bytes per bar. Slow arps (0x23: 4 ticks per step) sound dreamy; fast ones (0x20) sound like stabs.
• Soft decay instead of drums for rhythm: ATM_VOL(30), ATM_SL_VOL(-1) makes every note a bell.
• One riff, many chords: Pixel Breeze plays one 6-note pentatonic riff over C G F C with one cycle track moved by ATM_ADD_TRA; the bass calls the same track from ATM_SET_TRA(-24).
• Rhythmic tricks that cost nothing: 3-3-2 bossa grid (24+24+16 ticks); 5 against 3 phasing (a 5-note pattern of 8-tick notes against a 3-note arp at 8 ticks per step realigns every 120 ticks, exactly at the chord change, Music Box Tide).
• Waltz = 36 ticks per bar (3 beats of 12), loop 288 = 8 bars.
• Tempo is the hardware value here (20 to 32); ATM_SET_TEMPO costs 2 bytes, leave it out if the sketch calls ATM.setTempo().

Complete example, Lantern Lake (73 bytes, D minor, tempo 20, loop 256 ticks = 12.8 s). Each channel is one self-looping track:

Song lanternLake[] = {          // total song in bytes = 73
  0x04,                         // Number of tracks
  0x00, 0x00,                   // Address of track 0   //0
  0x18, 0x00,                   // Address of track 1   //24
  0x2D, 0x00,                   // Address of track 2   //45
  0x3B, 0x00,                   // Address of track 3   //59

  0x00,                         // Channel 0 entry track (bells)
  0x01,                         // Channel 1 entry track (pad)
  0x02,                         // Channel 2 entry track (bass)
  0x03,                         // Channel 3 entry track (silent)

  //"Track 0" bells  [24 bytes] - two bell strikes per bar, one per half bar
  ATM_SET_TEMPO(20),
  ATM_VOL(30),
  ATM_SL_VOL((uint8_t)-1),
  ATM_NOTE_A5, ATM_DELAY(32),
  ATM_NOTE_F5, ATM_DELAY(32),
  ATM_NOTE_D6, ATM_DELAY(32),
  ATM_NOTE_A5_, ATM_DELAY(32),
  ATM_NOTE_A5, ATM_DELAY(32),
  ATM_NOTE_C6, ATM_DELAY(32),
  ATM_NOTE_G5, ATM_DELAY(32),
  ATM_NOTE_E5, ATM_DELAY(32),
  ATM_GOTO(0),            // loop: this very track

  //"Track 1" pad  [21 bytes] - slow arpeggio chords: Dm | Bb | F | C
  ATM_VOL(26),
  ATM_TREM(1, 7),
  ATM_ARP(0x34, 0x23),
  ATM_NOTE_D4, ATM_DELAY(64),
  ATM_ARP(0x43, 0x23),
  ATM_NOTE_A3_, ATM_DELAY(64),
  ATM_NOTE_F4, ATM_DELAY(64),
  ATM_NOTE_C4, ATM_DELAY(64),
  ATM_GOTO(1),

  //"Track 2" bass  [14 bytes] - one soft root per bar
  ATM_VOL(30),
  ATM_SL_VOL((uint8_t)-1),
  ATM_NOTE_D3, ATM_DELAY(64),
  ATM_NOTE_A2_, ATM_DELAY(64),
  ATM_NOTE_F3, ATM_DELAY(64),
  ATM_NOTE_C3, ATM_DELAY(64),
  ATM_GOTO(2),

  //"Track 3" silent  [1 byte] - unused channel stops at once
  ATM_STOP_CHAN,
};

All three musical channels sum to exactly 256 ticks (8 x 32, 4 x 64, 4 x 64). The pad's arpeggio is set before the first note and its two chord qualities are set before their notes (minor 0x34, major 0x43); the second pass starts with the arpeggio still on 0x43 from the last bar, but ATM_ARP(0x34, 0x23) at the top of the track resets it before the first note, so every pass is identical. A WAV preview of all five songs was made with a small offline synth (pulse 25 %, square, saw, noise; tick rate = tempo), not with ATMlib itself.

9. Tooling

All scripts live in extras/tools/ (Python 3, plus g++ for the byte check). Run them from that folder, with ATM_SRC pointing at ATMlib/src.

Verification checklist (all must pass)

• [ ] sizeof(song) within the byte budget
• [ ] loops: restarts == [] and no STOP after tick 0 (unused channels excepted); no ATM_GOTO_ADV
• [ ] loops: every channel's entry track ends with ATM_GOTO(itself), and every channel sums to exactly L ticks
• [ ] loops: TIMELINE[t] == TIMELINE[t-L] for all t >= L (volume, and frequency while audible)
• [ ] loops 1, 2, 3 have identical note events
• [ ] max call depth <= 7
• [ ] no track calls track 0
• [ ] every note + transposition is within 1..63
• [ ] compiled header bytes == generator bytes (extras/tools/check_header.cpp)
• [ ] tempo is the doubled value (in-game songs: the stated hardware value)
• [ ] one-shots only: every channel ends with STOP, no GOTO_ADV

10. Output file template

#ifndef SONG_H
#define SONG_H

// ---------------------------------------------------------------------------
//  "Title" - style, key, bars, bytes
//  Play with:   #include "quest.h"      ATM.play(questTheme);
//  Timing : ATM_SET_TEMPO(34) (doubled). 1 beat = 16 ticks, 1 bar = 64 ticks ...
//  Form / channels. Loop: every entry track ends with ATM_GOTO(itself), no STOP, no hop.
// ---------------------------------------------------------------------------

#include <ATMcmds.h>

#ifndef Song
#define Song const uint8_t PROGMEM
#endif

Song questTheme[] = {     // total song bytes = 233
  0x0C,                       // Number of tracks
  0x00, 0x00,                 // Address of track 0   0   drums
  ...                         // one line per track
  0x03,                       // CH0 entry -> track 3 (lead)
  0x06,                       // CH1 entry
  0x07,                       // CH2 entry
  0x00,                       // CH3 entry
  //"Track 0" drums  [10b]
  ATM_SET_TEMPO(34),
  ATM_REPEAT(30, 2),   // 31x drum_half
  ATM_GOTO(1),   // -> drum_core
  ATM_DELAY(8),
  ATM_GOTO(0),   // loop: this very track
  ...
};

#endif

extras/tools/gen_quest.py writes exactly this.

11. Using a song in a sketch

See Quick start and API at the top of this file. In short: #include "song.h", create ATMsynth ATM;, call ATM.play(<array name>) in setup().

Folder layout (current): ATMlib/examples/loops/<name>/ for songs that loop forever (Italo Night, Italo Disco Compressed, Escaper Droid, Neon Heart, Quest Theme, Star Light, inGameSongs), ATMlib/examples/songs/<name>/ for one-shots and long songs (Cutlass Cove, Midnight Run, Orbital Rush), ATMlib/examples/soundEffects/ for effects (sfxDemo: 45 poke + 45 playSfx effects and 5 songs). Each song is an Arduino sketch folder with <name>.ino, song.h, ATMconfig.h, bitmaps.h: duplicate an existing folder, rename the folder and the .ino (the Arduino IDE wants both to match), put the data in song.h and change ATM.play(<name>).

Several songs in one sketch: keep the song arrays in PROGMEM pointer arrays (see examples/loops/inGameSongs).

12. Mistakes made on this project (do not repeat)

1. Invented opcodes. A first Pixel Chase draft used guessed byte values (0xC0 for volume ...). They collide with the delay range 0xA0..0xDF. Always take values from ATMcmds.h.
2. Track 0 called (section 4.3). Looks fine in a tick counter, sounds like a stuck melody on hardware. A simulator that models the call stack catches it.
3. REPEAT(n) is n+1 runs. REPEAT(7, beat) made a 128-tick bar instead of 64.
4. GOTO_ADV in a one-shot song makes it restart. (Looping songs must not use it either, see mistake 11.)
5. Off-by-one loops: with the self-loop every channel must sum to exactly L; one channel off by a tick drifts against the others. (The old rule was L-1; do not mix the two.)
6. Tempo not doubled.
7. Invalid names/arguments: ATM_NOTE_F#5, ATM_NOTE_OFF, negative arguments without (uint8_t).
8. Plain, short, hex-looking songs are not accepted. Use the Italo Night structure: real melody, kick/hat/snare with fills, transposed bass, chord stabs, a form with a destination.
9. Combining ATM_ARP with transposition on one channel (detunes the arpeggio).
10. Trusting a counter instead of a model. Verify with the simulator and by compiling.
11. Looping with STOP + GOTO_ADV. Every loop has one tick in which all four channels are silent (STOP sets volume 0, the restart tick plays nothing). The period was exact and the simulator's "all stops on tick L-1" check passed, yet a "hop" was audible in every song. The model has to check what is audible (the per-tick timeline), not only when events happen. Fixed by the self-loop (section 6).
12. Believing "gapless on paper". The first attempt at a gapless version (trimming one tick and keeping STOP) was wrong for the same reason; only removing STOP from the loop removes the seam.

Song catalog

13. Catalog of the existing songs

ATM Tracker Editor

Tracker editor

A single-file HTML tracker for this library (atm-tracker-editor.html; the project lives in the trackerEditor repository). Open it in a browser. Current release: 0.1.7.

Modes. You always start in SONG; switch with the header buttons.

• SONG: four channel lanes. Patterns appear as blocks (width = tick length); unique patterns have unique colours, copies share one. Drag a pattern from the left list onto a lane to append it. Blocks pack left with no gaps; delete one (x) and the rest slide left. Click a block to enter PATTERN mode for that clip.
• PATTERN: one lane. Record writes notes and advances the cursor (hold a key to grow the tick length). Edit writes and plays notes but keeps the cursor (move it with Left / Right). Drag a note to move it (its length comes along; if the landing gap is shorter the note is clipped); drag the right edge to change its length.
• SOUNDFX: one pattern, one voice, no arrangement blocks. Choose Play as CH0 to CH3 in the header (pulse / square / tone / noise). Export is ATM_SFX_TRACK for ATM.playSfx(sfxTrack, ch). Switching between SONG and SFX asks for confirmation and starts from scratch.

Load accepts JSON and song.h files written with ATM commands. Macros such as ATM_NOTE_A5_, ATM_SET_TRA(-5), ATM_SL_VOL(-4) are expanded. With several arrays in one file, the first valid score header is imported as four channel patterns on the song timeline. Very nested GOTO / REPEAT songs are flattened onto a 64-tick grid per channel so you can edit them.

Export as commands or hex: a SONG becomes const uint8_t score[] PROGMEM for ATM.play(score), an SFX becomes ATM_SFX_TRACK. Rests and holds become ATM_DELAY; the arrangement becomes ATM_GOTO chains of pattern tracks. Tick Shrink song in the Export tab to make the song smaller without changing how it sounds (dead commands removed, repeated runs shared in extra tracks, see section 7.2).

Playback in the editor is Web Audio, not cycle-accurate to the AVR interrupt routine. For a device-faithful listen, compile a hex and run it in an emulator such as Ardens, or on hardware.

Keyboard: Space = play / stop; Left / Right = cursor in Pattern / Edit; Up / Down = piano octave; Del = clear the selected note; A-L + sharps / Z-M and Q-U = piano. Web MIDI is supported, and a computer-keyboard piano sits under the grid.