Music Tracker

With the Music Tracker you compose the music for your game. A song is a list of rows that play one after another, from top to bottom. Each row has a column per channel (four tone channels and one noise channel) and a command column. Notes play with the song's instruments, each with its own wave, volume, envelope and LFOs.

It edits the .jms files in the Music folder. When you compile, the IDE turns them into the .jmu files that the Sound module loads. The scene editor uses them too: each room can have its own music.

There are three ways to open it:

• New Music, in the explorer menu (right-click) or on its button bar, or New, on the tracker's toolbar. It asks for a template and a name, creates the .jms and opens it. It goes into Music, or into the folder you have selected in the explorer.
• Double-click a .jms in the explorer.
• Home › View › Music, on the ribbon: it shows the tracker window (Music Editor), with the songs you already have open.

Each song opens in its own tab, and you can have several open. The tab shows a * while there are unsaved changes.

Prefer a step-by-step guide?

The Your first chiptune melody tutorial walks through the editor with screenshots: creating the song from a template, typing notes into the grid, tweaking an instrument, and playing it from your game.

A walkthrough

A short melody that loops in your game.

1. Create the song. In the explorer, right-click Music › New Music. Pick the Chiptune lead template and press OK. Type a name, for example Theme, and accept: the IDE creates Music/Theme.jms and opens it in the tracker.
2. Listen to it. Press F5. The row that is playing turns green, and the meters in the status bar move with each channel. F8 stops it.
3. Make room. Click row 007 and press Ins four times: four empty rows appear below it.
4. Record notes. Press REC. Click the Note cell of Tone 0 on row 008, and press E, W, Q and W. The tracker writes E-4, D-4, C-4 and D-4 with instrument 00, the one selected in KEYBOARD, and moves down a row with each note. Press REC again to stop recording.
5. Listen again with F5. The template comes with Loop song on: when it reaches the END on the last row, the song goes back to row 000.
6. Save with Ctrl+S. While there are unsaved changes, the button reads Save ●.
7. Put it in your game. In a room of the scene editor, pick it in Room › Music (The room and the game tells you how). In a game written in code, load it with Sound.loadMusic("Music/Theme.jmu"): see "From code" below. The IDE creates the .jmu when you compile.

Templates

New Music starts by asking for a template, in the New music — pick a template dialog:

Template	What it has	Tempo (ms)	Row ticks	Loop song
Empty	A single row, with END.	72	8	No
Basic 4/4 beat	Eight rows that alternate a C-2 on Tone 0 and the snare on Noise.	72	8	Yes
Chiptune lead	The C major scale, from C-4 to C-5, on Tone 0, with a bass on Tone 1 and a second voice on Tone 2.	72	6	Yes
Battle theme	A fast ostinato on Tone 0, with bass and snare.	48	4	Yes

All four come with the same instruments: 0 Pulse (pulse wave), 1 Bass (triangle), 2 Lead (saw) and 3 Snare (white noise, a short hit). Volume is 185, except in Battle theme, where it is 200. You can change everything afterwards.

Tools

Button	What it does	Key
New	Creates a song: the same as New Music in the explorer.
MIDI	Imports a MIDI file into the open song (see "Importing a MIDI file" below).
Validate	Checks the cells and compiles the song, without saving it. If all is well, the status bar shows its compiled size (valid - 170 bytes); if not, a message says what is wrong.	F9
Save	Saves the .jms. With unsaved changes it reads Save ●; with none, it is disabled.	Ctrl+S
Close Tab	Closes the tab. If there are changes, it asks whether to save them.
▶ (Play)	Plays the song from the start row: 000, or the one you mark in blue. If there are red cells, it doesn't play, and the status bar says how many there are.	F5
❚❚ (Pause)	Pauses the song; the second time, it resumes.	F6
■ (Stop)	Stops the song.	F8
REC	Records: the notes you play with the keyboard are written into the grid (see "Entering notes").
Insert row	Inserts an empty row below the cursor.	Ins
Delete rows	Deletes the selected rows. One row always stays.	Shift+Del
Duplicate rows	Copies the selected rows right below them.	Ctrl+D
Pitch + and Pitch -	Raise or lower the selected notes of the tone channels by a semitone. They don't touch the noise channel.	Shift+↑ and Shift+↓
+12 and -12	The same, by an octave.	Shift+PgUp and Shift+PgDn
Piano	The octave the on-screen keyboard starts at, from 0 to 3.	Ctrl+← and Ctrl+→

Play, Pause, Stop and the three row buttons are icons: their tooltip says what they do. When raising or lowering notes, those that would go past 0 or 127 stay at the limit.

The grid

Rows and time

The song plays from top to bottom, row by row, until an END or the last row. Every row lasts the same: Row ticks ticks of Tempo (ms) milliseconds. With 8 ticks of 72 ms, each row lasts 576 ms. If Loop song is on, at the end it goes back to the Loop row.

Every fourth row is lighter, and every eighth row lighter still: they help you count bars. During Play, the row that is playing turns green and the grid follows it. Double-clicking the number of a row marks it in blue: Play starts there.

Channels

Channel	What it plays	Its instruments
Tone 0 to Tone 3	Notes, with a square, triangle, saw, pulse or sine wave.	Of type tone.
Noise	Noise: percussion and effects.	Of type noise.

Each channel plays one note at a time: for a chord, put each note on a different channel.

The M and S buttons on each channel header mute it (M) or let it play alone (S): if any channel is on S, only those play. They help you hear a single line, and they are not saved. Alt+1 to Alt+4 and Shift+Alt+1 to Shift+Alt+4 do the same for Tone 0 to Tone 3.

The cells

Each channel has four columns:

Column	What it holds
Note	The note, with its English name and its octave: C-4, F#3. Natural notes take a -, and C-4 is MIDI note 60. A MIDI number from 0 to 127 also works. OFF cuts the note that is playing, and --- is nothing. On Noise, the noise period, from N01 to N255: N01 is the highest and, the higher the number, the lower the sound.
Inst	The instrument, by its Id. Empty (..), the channel keeps the one it had.
Vol	The note's volume, from 0 to 255. Empty, the channel keeps the volume it had: the last Vol, or the instrument's if you have just changed instrument.
Dur	How long the note lasts, as a code from 01 to 15, counted from the start of the row. Empty, the note goes on until the next note or an OFF on the same channel.

Dur codes 01 to 06 are 1 to 6 ticks; 07 is 8; 08, 10; 09, 12; 10, 16; 11, 20; 12, 24; 13, 32; 14, 48, and 15, 64. A long note can go past its row into the next ones.

Anything badly written gets a red underline, and the status bar says how many errors there are (● 2 errors). With errors, Play doesn't play.

The Cmd column

Cmd holds commands for the whole song. The cell drops down a list of examples: pick one and change the numbers. You can put several in a cell, separated by ;, and delay one within the row with @ and the tick: TEMPO 60; @4 VOL 120 changes the tempo when the row starts and the volume four ticks later. The tick goes from 0 to Row ticks minus one.

Command	What it does	Values
END	Ends the song. With Loop song, it goes back to Loop row. The rows below it don't play.
TEMPO ms	Changes Tempo (ms) from there on.	1 to 255
VOL v	Changes the overall volume.	0 to 255
STOPALL	Stops every channel.
TRANSPOSE n	From there on, the notes of the tone channels play n semitones higher, or lower if it is negative. TRANSPOSE 0 removes it.	-128 to 127
CHSTOP c	Stops channel c: 0 to 3 are the tone channels, and 4 is the noise channel.	0 to 4
DUTY c v	Changes the duty of the pulse wave on channel c.	c: 0 to 3; v: 1 to 99
TSLIDE c target ticks	Slides the note playing on channel c to target over that many ticks. The target is a note (C-5), a MIDI number or a frequency (440hz, 65.406hz).	c: 0 to 3; ticks: 0 to 255
NMODE mode	Changes the noise mode: white, periodic, short or dark.
NENV ticks	On the noise channel, how long each hit takes to fade out, if its instrument has no envelope.	0 to 255
NSLIDE period ticks	Slides the noise period to period over that many ticks.	period: 1 to 255; ticks: 0 to 255
NPER period	Changes the noise period.	1 to 255

Entering notes

There are two ways:

• With the keyboard. Press REC and put the cursor on a Note cell. Each key writes its note, puts the instrument selected in KEYBOARD into Inst and moves down a row. Without REC, the keys only play.
  • The keys are laid out like a piano: Z X C V B N M are the white keys of one octave, and S D G H J, the black ones; Q W E R T Y U and 2 3 5 6 7, the octave above.
  • The octave is the one shown as Input oct in the status bar: Ctrl+↑ and Ctrl+↓ change it, from 0 to 7. At 3, the default, Z is C-3 and Q is C-4.
  • On Noise, the keys write periods: from N01 (the Z) to N12 (the M).
  • If the KEYBOARD instrument is not of the channel's type (a noise instrument on Tone 0, for example), the note is written without an instrument, and the status bar says so.
  • 1 writes OFF and Backspace empties the note (---). Both move down a row, with or without REC.
  • Clicking a key of the on-screen keyboard is like pressing it.
• Typing the text. Press F2 on a cell (or, without REC, click the cell that is already selected), type and press Enter. This is how you enter Inst, Vol, Dur and Cmd. If you have several rows of that column selected, the value goes into all of them.

Selecting, copying and undoing

• Click the number of a row to select the whole row; with Shift, you select from the cursor's row down or up to that one. Dragging across the cells selects a rectangle.
• Del empties the selected cells. Ctrl+C, Ctrl+X and Ctrl+V copy, cut and paste as tab-separated text. Pasting starts at the cursor, and if it doesn't fit, rows are added at the end.
• Ctrl+F5 loops the selected rows. With a single row selected, it plays the whole song.
• Ctrl+Z undoes and Ctrl+Y (or Ctrl+Shift+Z) redoes, up to 99 steps per tab: notes, rows, instruments and settings.

Panels and options

SONG SETTINGS

Field	What it is
Tempo (ms)	How long a tick lasts, in milliseconds, from 1 to 255. The lower it is, the faster the song.
Volume	The overall volume of the song, from 0 to 255.
Row ticks	How many ticks each row lasts, from 1 to 65535.
Loop song	With enabled ticked, when it reaches END (or the last row) the song goes back to Loop row and never ends. Ctrl+L toggles it.
Loop row	The row it starts again from.
Copy ms (seekMusic)	Copies to the clipboard the millisecond at which the cursor's row starts, for Sound.seekMusic (see "From code"). It takes the TEMPO commands in the Cmd column into account.

Below it, a cheat sheet of the shortcuts.

KEYBOARD

The on-screen keyboard spans six octaves, starting at the C of Piano: at 3, the default, from C3 to C9. < and > move it by an octave. Click a key to hear it; with REC, it is also written. The keys you can play from the computer keyboard show their letter, and during Play the notes sounding on the tone channels light up.

The list next to < and > picks the instrument: the one the keys play with, and the one REC writes.

INSTRUMENTS

The table of the song's instruments. You can type in its cells, as in the grid; Type and Wave/Mode drop down their values.

Column	What it is
Id	The instrument's number, from 0 to 255: the one you type in Inst.
Name	Its name.
Type	tone, for Tone 0 to Tone 3, or noise, for Noise.
Wave/Mode	For tone, the wave: square, triangle, saw, pulse or sine. For noise, the mode: white (white noise), periodic (a short repeating pattern: it sounds almost like a note), short (it sounds metallic) or dark (smoothed white noise: duller).
Volume	Its volume, from 0 to 255.
Duty	The pulse width, from 1 to 99. It only matters with the pulse wave.
Atk ms, Dec ms, Sus % and Rel ms	The ADSR envelope (see Edit instrument below). Sus % goes from 0 to 255, not in percent.
Vib Dep, Vib dHz and Vib dly	The vibrato: depth, from 0 to 255; rate, in tenths of a hertz, and delay, in ms. tone only.
PWM d:r:dly	An LFO on the duty: depth, rate and delay, separated by :. tone only, and only audible with pulse.
Trm d:r:dly	The tremolo, an LFO on the volume, in the same way. For tone and noise.
Slide	noise only: target:ticks. Each hit slides its period to the target over that many ticks.
Test	Click the > to hear it: it plays C-4, or N08 for noise instruments.

The buttons on the header:

• Edit opens the selected instrument in Edit instrument.
• Add adds one: Instrument plus its number, of type tone, with a pulse wave.
• Dup copies the selected one, with a new Id and copy at the end of its name.
• Del deletes the selected one. If any cell uses it, it warns you first: those cells keep their Id, which no longer exists, and the song won't compile until you change them. A song must have at least one instrument.

Id numbers are never reused or renumbered: a new one is the highest plus one, and the Inst cells keep pointing at the same instrument.

Edit instrument

Edit opens the instrument in a dialog with the same values, shown visually and with sound preview. What you change sounds as soon as you play a key, and goes into the table when you press OK. Cancel, or Esc, leaves it as it was.

• Preset: a General MIDI family (from Piano to Sound Effects, plus Percussion (Drums) for noise instruments) and, in the list next to it, one of its instruments. When you pick it, the dialog loads its sound as a starting point. It keeps the Id and your name; if the instrument still has its default name, it takes the preset's.
• Name, Type and Wave: the name, tone or noise, and the wave (for noise instruments, the mode).
• OSCILLATOR: a drawing of the wave and two knobs, Volume (0 to 255) and Duty (1 to 99; hidden for noise instruments).
• ENVELOPE: the ADSR envelope. Atk ms is how long the note takes to rise; Dec ms, how long it takes to drop to Sus 0-255, the level it holds while it lasts (255 is its full volume), and Rel ms, how long it takes to fade out once cut. Drag the points of the graph (up to 4 seconds per segment) or type in the boxes (up to 65535 ms). With all four at 0, there is no envelope: a tone note plays at the same volume until it is cut.
• VIBRATO LFO (for tone): drag across the strip: up and down changes the depth, and sideways, the rate, up to 12 Hz. Or type in Depth, Rate (in tenths of a hertz) and Delay (in ms).
• NOISE SLIDE (for noise, in place of the vibrato): Target and Ticks, the Slide column of the table.
• PWM LFO (duty, pulse) (for tone) and TREMOLO LFO (amplitude): Dep, Rate and Dly, like the vibrato. At full depth, PWM moves the duty 40 points up and down, and tremolo brings the volume down to silence.
• PREVIEW: a two-octave keyboard, from C-3 to B-4. Click and drag across the keys. Test plays C-4 (or N08, for noise instruments) and Stop releases it.

The status bar

• On the left: the cursor's row and the last row, the channel and column, the note in the cell (with its MIDI number), Cursor (the millisecond at which the row starts), the tempo, Input oct (the computer keyboard's octave) and Piano view (the on-screen keyboard's).
• In the middle: a meter per channel, from CH0 to CH3 plus NSE, the noise channel.
• On the right: the state. ● ok or the errors, ► playing @ 22kHz, ■ stopped, the size after Validate…

The tracker plays at the sample rate of the active board profile, 22 kHz or 44 kHz (22 kHz if there is none), so you hear what it will sound like on that board. Sound explains it.

Importing a MIDI file

MIDI turns a .mid or .midi file into tracker rows. First open the song you want it in: importing replaces everything in it.

1. Press MIDI and pick the file.
2. The Import MIDI dialog says what the file holds (the MIDI type, the tracks, the notes, the tempo changes) and lists its 16 channels: how many notes each one has (Notes), the range of notes it covers (Range) and the number of its General MIDI instrument (Program). Adjust the options.
3. Preview plays the result without importing it, and Stop preview stops it.
4. Press Import. When it finishes, a summary says how many notes and drum hits went in and how many were left out.

Option	What it does	Default
Quantization	The grid step: 1/8, 1/16 or 1/32, which is two, four or eight rows per quarter note. Each note starts and ends on the nearest row.	1/16
Voice strategy	How it shares out notes that play at the same time among the four tone channels. Balanced voices picks the best ones on each row: first those from the same MIDI channel as that channel's previous note, then the long, loud and close ones. First 4 voices takes the first four. By MIDI channel gives a tone channel to each of the four MIDI channels with the most notes.	Balanced voices
Master volume	The song's Volume.	That of the open song
Import MIDI drums	Moves the percussion to the noise channel.	Yes
Loop imported song	Loop song. Without it, an END is added at the end.	That of the open song
Apply sustain pedal	Holds notes while the pedal is down.	Yes
Import pitch bend as slides	Turns pitch bend into TSLIDE commands.	Yes
Import modulation as vibrato	Gives a vibrato to the instrument of the channels that use the modulation wheel.	Yes
Target	Where each MIDI channel goes: Auto (decided by Voice strategy), Ignore, Tone 0 to Tone 3 or Noise Drums.	Auto; channel 10, Noise Drums

What it creates:

• Rows of 4 ticks, with the MIDI's tempo. Tempo changes go in as TEMPO on the row where they fall, one per row at most.
• One tone instrument for each General MIDI instrument that plays, with its name. Its Id is the program number, from 0 to 127. Percussion uses noise instruments 128 to 138 (MIDI Kick, MIDI Snare…), only those that play.
• The volume of each note, from its velocity and the MIDI volume controllers (CC7 and CC11).

Its limits:

• Only MIDI type 0 and 1, with time in pulses per quarter note: files that use SMPTE time are not imported.
• Four notes at a time on the tone channels and one hit per row on the noise channel. The rest is left out.
• 8192 rows at most.
• A tick goes from 1 to 255 ms: a tempo that doesn't fit stays at the limit.
• Modulation becomes a fixed vibrato on the instrument, and pitch bend becomes slides: they resemble the original, but they are not the same.

Importing replaces the song

The rows, instruments and settings of the tab are replaced by those of the MIDI file. Nothing is saved until you press Save, and Ctrl+Z undoes the import.

What it saves and what it generates

Save saves the song to its .jms, a JSON file. Home › Project › Save, on the ribbon, also saves the open songs that have changes.

.jms field	What it is
version, format	1 and "tracker".
tickMs, volume, rowTicks	Tempo (ms), Volume and Row ticks.
loop, loopStartRow	Loop song and Loop row.
instruments	The instruments, with id, name, type and volume; wave and duty, or noiseMode; and, if they have them, the envelope (attackMs, decayMs, sustain and releaseMs), the LFOs (vibratoDepth, vibratoRate and vibratoDelay, and the same with pwm and tremolo) and the noise slide (slideTargetPeriod and slideTicks).
rows	One entry per row: ch0 to ch3 and noise, with note (the MIDI number; period for noise) or off, inst, volume and dur; and cmds, its commands, each with its tick.

If a .jms can't be read as a tracker song, the tracker warns you and opens a default song in its place. If you save it, it replaces the file.

When you compile (Build › Compile, and also the scene editor's Play if any asset has changed), the IDE turns each .jms in the project into a .jmu, in Build/flash and with the same path: Music/Theme.jms ends up as Build/flash/Music/Theme.jmu. It converts every song, whether the game uses it or not, and first deletes whatever was in Build/flash/Music.

The .jmu is what the VM loads: a header (the version, Loop song, the tempo, the volume and, when looping, where it jumps back to), the instrument table (26 bytes each) and the notes and commands, very compact. It can't be larger than 65535 bytes. Validate tells you its size.

The Output lists each song as it is exported, with its size. A song with an error stops the compilation of the whole project, and the Output says which one and what is wrong; for example, "row 3 ch0: instrument 7 does not exist" (the row is the tracker's).

Save before you compile

When you compile, the IDE reads the .jms from disk: Compile doesn't save the tracker. Whatever you haven't saved doesn't reach the game. Validate, on the other hand, compiles what you see, without saving it.

Shortcuts

Shortcut	What it does
Ctrl+S	Saves the song.
F9	Validate.
F5	Plays the song from the start row.
Ctrl+F5	Loops the selected rows.
F6	Pauses, or resumes.
F8	Stops.
Ctrl+Z	Undo.
Ctrl+Y or Ctrl+Shift+Z	Redo.
Ctrl+L	Turns Loop song on or off.
Ins	Inserts an empty row below the cursor.
Shift+Del	Deletes the selected rows.
Ctrl+D	Duplicates the selected rows.
Del	Empties the selected cells.
Ctrl+C, Ctrl+X and Ctrl+V	Copy, cut and paste cells.
Shift+↑ and Shift+↓	Raise or lower the selected notes by a semitone.
Shift+PgUp and Shift+PgDn	Raise or lower the selected notes by an octave.
Ctrl+↑ and Ctrl+↓	Raise or lower the computer keyboard's octave (Input oct, from 0 to 7).
Ctrl+← and Ctrl+→	Move the on-screen keyboard (Piano, from 0 to 3).
Alt+1 to Alt+4	Mute Tone 0 to Tone 3 (M).
Shift+Alt+1 to Shift+Alt+4	Solo Tone 0 to Tone 3 (S).
Z S X D C V G B H N J M	One octave of notes, from the C of Input oct.
Q 2 W 3 E R 5 T 6 Y 7 U	The octave above.
1, on a Note cell	Writes OFF and moves down a row.
Backspace, on a Note cell	Empties the note and moves down a row.
F2	Opens the cell to type in it.
Click on a row number	Selects the whole row; with Shift, from the cursor's row.
Double-click on a row number	Marks it in blue: Play starts there.
Esc, in Edit instrument	Cancels.

The keys work while the tracker window is active. The note keys, 1, Backspace, Del and the copy and paste keys need the grid to be active, and you must not be typing in a cell.

From code

If the song is a room's music, you don't write anything: the code the scene editor generates plays it (The room and the game). If you load rooms as data, it doesn't play on its own: The code it generates explains it.

In a game written in code, load the .jmu with Sound.loadMusic and play it with Sound.playMusic:

use Sound

Sound.init()

if (Sound.loadMusic("Music/Theme.jmu")) then
    Sound.playMusic()            // loops if the song has Loop song on
end

func goToChorus()
    Sound.seekMusic(13824)       // the number, from Copy ms (seekMusic)
end

• loadMusic returns true if it could load the song. The path is the song's path in the project, with .jmu: Music/Theme.jms is loaded as "Music/Theme.jmu".
• playMusic() starts it from the beginning. With no argument, it loops if it has Loop song; playMusic(true) and playMusic(false) decide for you.
• seekMusic(ms) jumps to a point in the song. To get the number, put the cursor on the row and press Copy ms (seekMusic): it copies it to the clipboard.
• If you drag the .jms from the explorer into the code editor, a menu lets you pick Insert as Sound.loadMusic, Insert as load + play or Insert as Path, and writes the call for you, already with .jmu.

The other music functions (pauseMusic, resumeMusic, stopMusic, setMusicVolume, isMusicPlaying and unloadMusic), and how music shares the channels with sound effects, are in Sound. Tracker music doesn't replace recorded sounds: for those there is loadSample, on the same page.

Known issues

• The Play tooltip is out of date. It says "emits a 440Hz beep in 3.1; full mixer arrives in 3.2", but Play plays the whole song, with all its channels and instruments.
• The Sus % column is not in percent. In INSTRUMENTS, Sus % goes from 0 to 255, like Sus 0-255 in Edit instrument: 255 is 100 % and 128 is half. If you type 50 meaning half, the note stays at 20 %.
• The grid doesn't check everything. It underlines badly written cells in red, but not the values of commands (TEMPO 300, VOL 300, CHSTOP 7), a noise period above N255, or an Inst that doesn't exist or isn't of the channel's type. The compilation finds those, and then the whole compilation stops. Press Validate (F9) before compiling: it compiles the song and tells you what is wrong.
• With REC, the grid jumps to the top. While each note you record is sounding, Play's green mark shows on row 000 and, if the song doesn't fit in the window, the grid scrolls up to it. The note is written correctly, on the cursor's row.
• Undoing a note entered with the keyboard takes two Ctrl+Z. With REC, 1 or Backspace, the first one only takes the cursor back to the note, and the second one removes it.

All the known issues of JARU, together, are in Known issues.