Arduboy Tracker Music Library
Clone or download

README.md

#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

FILE/ARRAY FORMAT DESCRIPTION

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 LIST

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
 
225…251 RESERVED
 
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)

FX LIST

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
TBD TBD TBD TBD

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.