ATMlib Song Editor manual · v1.0.1

What is this?

The ATMlib Song Editor lets you compose chiptune music for the Arduboy and turn it into a .h file you can drop into your sketch. It runs in your browser. Nothing is uploaded anywhere: your song lives on your own computer.

ATMlib gives you four channels:

Each channel plays one sound at a time, like a single instrument. That is the whole trick of chiptune: a small sound chip, clever tricks, and a lot of character.

The editor only makes songs. Sound effects will get their own editor.

Your first song in 5 minutes

When you open the editor you already get a small example song. Press Space (or the yellow Play button) to hear it. Press it again to stop. Now make your own:

1. Press Reset or New in the top bar for a clean start. (Reset brings back the example, New gives you an empty song.)
2. Open the Drums tab on the left. Press ▶ next to a few grooves until you find one you like, then drag it onto the CH3 lane at the top. Drag it a few times to repeat it.
3. Go to the Patterns tab and press + Tone pattern. In the big piano roll at the bottom, click to put in some notes. Drag to the right while clicking to make a note longer.
4. Open the Instruments tab and press Use next to an instrument, for example "Pluck lead". Press ▶ to hear it first.
5. Drag your pattern from the Patterns list onto the CH0 lane. Press Play and listen.
6. Open Export (top right), press Copy or Download, and you have your song file.

The screen

The editor has three columns and a top bar.

Top bar

• Play / Stop and Tempo – how fast the song plays. See Limits.
• ↶ ↷ – undo and redo.
• New – an empty song. Reset – forget the autosave and go back to the example song. Open / Save – your project file. Import song.h – load an existing ATMlib song.
• Manual – this page.

Left column

Three tabs with the building blocks: Patterns (your own bits of music), Drums (ready-made drum parts and the drum kit) and Instruments (ready-made sounds).

Middle

The top half is the arrangement: four lanes, one per channel, where you line up your patterns in time. The bottom half is the pattern editor, where you write the notes of the pattern you have selected.

Right column

Three tabs: Song (name, tempo, loop, volume), Selection (details of whatever you have selected: transposition, instrument, effects) and Export.

Patterns

A pattern is a short piece of music, usually one bar or a few. You write it once and then place it in your song as often as you like. Placing the same pattern ten times costs almost nothing in the final file, so reuse is the way to keep songs small.

• + Tone pattern makes a pattern for melodies and bass (channels CH0 to CH2).
• + Drum pattern makes a pattern for drums (channel CH3 only).
• Click a pattern in the list to open it in the editor. Rename it, change its Length (in ticks) or press Duplicate, Clear or Delete above the editor.
• Patterns have a colour. You can change it in the Selection tab.

The length is counted in ticks. The editor uses 16 ticks per beat and 64 ticks per bar. A 64-tick pattern is one bar; a 128-tick one is two bars. The buttons 16, 32, 64 and 128 are shortcuts.

Writing notes (the piano roll)

When a tone pattern is selected you see a piano roll. High notes are at the top, time runs left to right.

One channel can only play one note at a time. If you put a note on top of another, the new one wins and the old one is shortened. That is how the hardware works, and it is why chords need a trick (see Instruments).

Typing notes with the keyboard

Click once in the roll to place the red cursor, then use the computer keyboard like a piano:

 W E   T Y U   O P
A S D F G H J K L ;
C D E F G A B C D E

Each key you press writes a note at the cursor and moves the cursor on by the length of your last note. Z and X go down and up an octave (the current octave is shown above the roll). The arrow keys move the cursor left and right. Delete removes the note at the cursor.

The range is C2 to D7. That is 63 notes, and it is all the chip can do.

Drums

Good drums are hard to build by hand, so the editor comes with ready-made drum parts. Open the Drums tab:

• Grooves are one-bar beats (Italo disco, house, rock, funk, breakbeat, waltz and more).
• Building blocks are small half-bar pieces to make your own beat from.
• Fills and rolls are for the end of a phrase: snare rolls, build-ups, a crash to mark a new section.

Press ▶ to listen. Drag a part onto the CH3 lane to use it, or press + to add it to your patterns list first. A good rhythm: use a groove three times, then a "+ roll" version as the fourth bar.

Changing a drum part

Select a drum pattern and you get a grid instead of a piano roll. Every row is a drum sound (kick, snare, hats, crash…). Click a cell to put a hit there, click it again to remove it. Hold the button and drag to paint several. You can also type: each row shows a letter (K kick, S snare, H closed hat, O open hat, C crash…). Press a letter and a hit appears at the cursor.

Only one drum can sound at a time. If two hits land on the same tick, the last one wins.

The drum kit

The channel is noise, and every drum is a burst of noise that gets quieter. At the bottom of the Drums tab, Kit voices lets you change how loud a drum starts (vol) and how fast it dies away (slide, more negative is shorter). A change affects every pattern that uses that drum. Reset kit brings back the defaults.

Instruments

An instrument decides how each note sounds: how loud it starts, how it fades, whether it wobbles or arpeggiates. Without an instrument, notes just play at one steady volume.

The Instruments tab has ready-made ones, grouped as Lead, Chord, Pad, Bass, Drum and FX. Press ▶ to hear a short demo, Use to give it to the pattern you have selected (or to a new pattern if none is selected). You can also drag an instrument onto a block in the arrangement.

About chords

A channel plays one note at a time, so a "chord" is an arpeggio: the chip plays the notes of the chord one after the other so fast that your ear hears them together. The Chord instruments do this for you: write the root note (for instance D), pick "Chord stab (minor)" and you get D minor. Use the "maj", "minor", "Maj7" and "m7" versions to colour your harmony.

Making your own

Select a pattern, open the Selection tab and scroll to Instrument. Here you can change:

Use ▶ Listen to test it. Copy as new keeps the original and gives you your own version.

The arrangement

The lanes at the top are your song in time, from left to right. Each coloured block is a placement of a pattern.

• Add: drag a pattern (or a drum part) from the left onto a lane. A red line shows where it will land. You can also double-click an empty lane to put the currently selected pattern at its end.
• Rearrange: drag a block to another spot, even to another lane of the same kind.
• Remove: click a block and press Delete, or use "Remove from lane" in the Selection tab.
• Zoom slider: make blocks wider or narrower.
• mute (on the left of each lane): silences that channel while you listen. It does not change the exported song.

Tone patterns go on CH0, CH1 or CH2. Drum patterns go on CH3. If you drop one on the wrong kind of lane, nothing happens.

Transposition

Click a block and open the Selection tab. Transpose shifts that placement up or down in semitones, without touching the pattern. Write a bass line once, then play it again two semitones higher for the chord change. The buttons add or subtract one octave (12).

Make this block unique

If a pattern is used many times and you want to change only one of them (say, a different last note in bar 4), press Make this block unique. That block gets its own copy to edit. The other blocks stay as they were.

Lanes of different length

In a looping song, all channels must be the same length so that they come back together. If one lane is shorter, the editor pads it with silence (the hatched area) when you export. You do not need to fill it yourself.

Effects

Besides the instrument, you can place single effects at a point in a pattern: a vibrato that starts halfway, a volume change, a pitch slide. Open the Selection tab and scroll to Effects in this pattern.

1. Click in the piano roll where the effect should start, to place the red cursor.
2. Choose the effect type and fill in its numbers.
3. Press Add at cursor.

Effects show as small flags in the strip at the top of the piano roll. Drag a flag to move it. Click one to select it, and use the ✕ in the list to remove it. Most effects have an "off" version to switch them off again.

Listening

• Play (or Space) plays the whole song. Looping songs repeat forever until you press Stop. A red line moves across the arrangement, and also through the pattern you have open in the editor.
• ▶ Pattern above the editor plays only that pattern.
• Clicking a note or a drum cell plays it.
• Changes you make while the song is playing are heard the next time you press Play.

What you hear is made by the real ATMlib playroutine, so it should sound the same on your Arduboy (the Arduboy's tiny speaker will of course colour it).

Export and use in a game

Open the Export tab. The editor builds the song and tells you the size in bytes and the number of tracks. Fix anything shown in red (a problem that stops the export, for example a note that would go out of range after transposition). Yellow messages are warnings.

Press Copy or Download to get your .h file. Put it next to your sketch and use it like this:

#include "mysong.h"

void setup() {
  ATM.setTempo(35);   // use the tempo shown in the Export tab
  ATM.play(mySong);   // use your song's name
}

The name in ATM.play(…) is the Name from the Song tab.

The editor writes the song the way a human would: short macros like ATM_NOTE_A5 and ATM_DELAY(16), with comments, and tracks sorted so loops are seamless. There is also a "raw bytes (hex)" option if you only want the numbers.

Song settings that affect the export

• Loop forever – on: the song repeats seamlessly, without a click or a gap. Off: the song plays once and stops. When it stops the last note is cut, so add a short rest at the end if you want it to ring out.
• Shrink song – makes the exported song smaller without changing how it sounds. First it removes commands that change nothing (a volume, slide or transposition that is already set when it is reached), then it moves runs of commands that repeat (inside one track or across tracks) into extra shared tracks, called with ATM_GOTO. Each removal and the end result are checked by simulating the song tick by tick: the sound must be identical and the call depth must stay within 7, otherwise the song is left as it was. The green line above the export shows the bytes saved, how many commands were removed and how many tracks were added. On the Sirene and Virus songs it saved 4 to 19 percent (Begemmed gained most).
• Put ATM_SET_TEMPO inside the song – normally off, because your sketch sets the tempo. Turn it on if the song should carry its tempo with it.
• In-game music volume – lowers all volumes by a percentage (60% is a good start) so the music does not drown out your sound effects. You can change the percentage later in your sketch's header.

Saving, opening and importing

• Autosave: the editor remembers your song in the browser. If you reload the page, it comes back. This is only stored in this browser on this computer, so do not rely on it for songs you care about.
• Save downloads a project file (.atmsong.json) with everything: patterns, instruments, arrangement. Keep these safe. Open loads one again.
• Import song.h reads an existing ATMlib song file and turns it into patterns you can edit. If the file holds several songs, a window lets you pick one (you can listen to each first). The import cannot know your original patterns, so it cuts the song into bars. The sound should be the same, but the result is usually larger and less tidy than a song you built in the editor. If the song has volume macros (MV/MS), it is imported at its current volume.
• Reset forgets the autosave and brings back the example song. New starts empty.

Keyboard shortcuts

The keys only work when you are not typing in a text box.

Limits and good habits

Tempo and time

Time is counted in ticks. The tempo is the number of ticks per second. At tempo 35 a bar of 64 ticks lasts about 1.8 seconds. A rough conversion: tempo × 3.75 ≈ beats per minute.

Size

An Arduboy has very little memory, and the song takes space in it. The Export tab shows the size. To keep it small:

• reuse patterns instead of writing out every bar;
• use transposition to play the same pattern in another key;
• keep the number of different effects per pattern low.

The editor already removes repeated commands and turns repeated bars into loops for you.

The chip's rules

• One note at a time per channel.
• Notes from C2 to D7 only (after transposition too).
• Volumes run from 0 to 63.
• CH3 is noise only, so drums go there, and nothing else.

Something is wrong

Made by TEAM a.r.g. If this tool is useful to you, a coffee is always welcome: