#ATMlib
ATMlib stands for Arduboy Tracker Music and is based on Squawk a minimalistic 8-bit software synthesizer & playroutine library for Arduino, created by Davey Taylor aka STG.
While Squawk provides a very nice synth, it wasn't optimized for a small footprint. Songs are not very efficient in size, so Joeri Gantois aka JO3RI asked Davey to help him work on a new songformat and so ATMlib was born.
Contributers:
- Davey Taylor - ATMsynth - Effects
- Joeri Gantois - Effects
| Section | Field | Type | Description |
|---|---|---|---|
| Track table | Number of tracks and their addresses | ||
| Track count | UBYTE (8-bits) | Number of tracks in the file/array | |
| Address track 1 | UWORD (16-bits) | Location in the file/array for track 1 | |
| … | … | … | |
| Address track N | UWORD (16-bits) | Location in the file/array for track N (0 … 255) | |
| Channel entry tracks | For each channel, track to start with | ||
| Channel 0 track | UBYTE (8-bits) | Starting track index for channel 0 | |
| … | … | … | |
| Channel 3 track | UBYTE (8-bits) | Starting track index for channel 3 | |
| Track 0 | Commands and parameters for track 0 | ||
| Command 0 | UBYTE (8-bits) | See command list | |
| and its Parameters | none/variable | See parameter list for each command | |
| … | … | … | |
| Command N | UBYTE (8-bits) | ||
| and its Parameters | none/variable | ||
| … | … | … | … |
| Track N | Commands and parameters for track N (0-255) |
| Command (X) | Parameter | Type | Description |
|---|---|---|---|
| 0 0x00 |
Stop playing | ||
| 1…63 0x00+X |
note (X) | UBYTE (8-bits) | Start playing note [X] where 1 is a C1. See Frequency to Tone Note: everytime a note is played, volume is re-triggered |
| 64…159 0x40…0x9F |
Configure effects (fx) | ||
| See fx list | none/variable | Effect is [X - 64] | |
| 160…223 0x9F+t |
Ticks (t) | UBYTE (8-bits) | Delay for [X - 159] or [t] ticks Note: delay of 0 does not exist and maximum is 64 ticks |
| 224, Y 0xE0, Y |
Ticks (Y) | VLE (8/16-bits) | Long delay for [Y + 65] ticks Note: LONG delay starts at 1 higher than SHORT delay |
| 252, N 0xFC, N |
Track N | UBYTE (8-bits) | Call/run/goto specified track Track index where N is the number of the track to go to |
| 253, Y, N 0xFD, Y, N |
Repeated call/run/goto specified track | ||
| Loop count (Y) | UBYTE (8-bits) | Repeat [Y + 1] times (total) | |
| Track N | UBYTE (8-bits) | Track index where N is the number of the track to go to | |
| 254 0xFE |
Return/end of track marker | ||
| 255, L, D 0xFF, L, D |
Binary data | ||
| Length L | VLE (8/16-bits) | Length in bytes of data to follow | |
| Data D | variable | Binary data chunk (notify host application) |
| Effect | Parameter | Type | Description |
|---|---|---|---|
| 64+0 64 0x40 |
set Volume (X) | UBYTE (8-bit) | Set volume to [X]. Note: If the combined volume of all channels exceed 255 there may be rollover distortion. This should not be disallowed, as it may be usesful as |
| 64+1 65 0x41 |
slide Volume ON (X) | UBYTE (8-bit) | Slide the volume with an amount (positive or negative) of [X] for every tick. Note: This results in a fade-in or fade-out effect. There should be a non- |
| 64+2 66 0x42 |
slide Volume ON advanced (X) (Y) |
UBYTE (8-bit) UBYTE (8-bit) |
Slide the volume with an amount (positive or negative) of [X] for every [Y] ticks. [Y] includes 2 parameters: RRtttttt R = reserved and t = ticks. |
| 64+3 67 0x43 |
slide Volume OFF | Stops the volume slide | |
| 64+4 68 0x44 |
slide Frequency ON (X) | UBYTE (8-bit) | Slide the frequency with an amount (positive or negative) of [X] for every tick. Note: The amount of slide is limited between -127 to 127 |
| 64+5 69 0x45 |
slide Frequency ON advanced (X) (Y) |
UBYTE (8-bit) UBYTE (8-bit) |
Slide the frequency with an amount (positive or negative) of [X] for every [Y] ticks. [Y] includes 2 parameters: RRtttttt R = reserved and t = ticks. |
| 64+6 70 0x46 |
slide Frequency OFF | Stops the frequency slide | |
| 64+7 71 0x47 |
set Arpeggio (X)(Y) | UBYTE (8-bit) UBYTE (8-bit) |
Next to the current playing note, play a second and third note [X] for every [Y] ticks. [X] includes 2 parameters: AAAABBBB, where AAAA = base + amount to |
| 64+8 72 0x48 |
Arpeggio OFF | Stops the arpeggio | |
| 64+9 73 0x49 |
SET Retriggering noise ON (X) | UBYTE (8-bit) | Noise channel consists of white noise. By setting retriggering [X] it swithes the entrypoint at a given speed. [X] includes 2 parameters: AAAAAABB , where AAAAAA |
| 64+10 74 0x4A |
Retriggering noise OFF | Stops the retriggering for the noise on channel 3 | |
| 64+11 75 0x4B |
add Transposition (X) | UBYTE (8-bit) | Shifts the played notes by adding [X] to the existing transposition for all playing notes. Note: The amount of shift is limited between -127 to 127. However there |
| 64+12 76 0x4C |
set Transposition (X) | UBYTE (8-bit) | Shifts the played notes by setting the transposition to [X]* for all playing notes. Note: The amount of shift is limited between -127 to 127. However there should |
| 64+13 77 0x4D |
Transposition OFF | Stops the transposition | |
| 64+14 78 0x4E |
set Tremolo (X)(Y) | UBYTE (8-bit) UBYTE (8-bit) |
[X] sets Depth. [Y] includes 4 parameters RxxBBBBB R = Retrig, x = reserved , B = rate Note: Tremolo and Vibrato can NOT be combined in the same |
| 64+15 79 0x4F |
Tremolo OFF | Stops the tremolo | |
| 64+16 80 0x50 |
set Vibrato (X)(Y) | UBYTE (8-bit) UBYTE (8-bit) |
[X] sets Depth. [Y] includes 4 parameters RxxBBBBB R = Retrig, x = reserved , B = rate Note: Tremolo and Vibrato can NOT be combined in the same |
| 64+17 81 0x51 |
Vibrato OFF | Stops the vibrato | |
| 64+18 82 0x52 |
SET Glissando (X) | UBYTE (8-bit) | [X] includes 2 parameters: Vttttttt V = value ( 0 = go 1 note up, 1 = go 1 note down) and t = amount of ticks, between each step |
| 64+19 83 0x53 |
Glissando OFF | Stops the Glissando | |
| 64+20 84 0x54 |
SET Note Cut (X) | UBYTE (8-bit) | [X] sets the equal amount of ticks between note ON and OFF |
| 64+21 85 0x55 |
Note Cut OFF | Stops the Note Cut | |
| … | … | … | … |
| 64+92 156 0x9C |
ADD song tempo (X) | UBYTE (8-bit) | adds [X] to the tempo of the song. Total value should be between 0 - 127 Note: the higher the tempo to more CPU it takes. |
| 64+93 157 0x9D |
SET song tempo (X) | UBYTE (8-bit) | (re-)sets [X] as the tempo of the song. Standard is 25. Value should be between 0 - 127 Note: the higher the tempo to more CPU it takes. |
| 64+94 158 0x9E |
GOTO advanced (W) (X) (Y) (Z) |
UBYTE (8-bit) UBYTE (8-bit) UBYTE (8-bit) UBYTE (8-bit) |
Note: handy command for having an intro and a repeating song part For channel 0 go to track W For channel 1 go to track X For channel 2 go to track Y For channel 3 go to track Z |
| 64+95 159 0x9F |
STOP current channel | channel is no longer being processed Note: if all channels have reached STOP, the song ends |
|
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.