Getting Started with RASTER Music Tracker (RMT)
RASTER Music Tracker (RMT) is the PC tracker behind a large share of modern Atari 8-bit game and demo music. Radek Štěrba (Raster of the Czech group C.P.U.) wrote it between 2002 and 2009. It runs on a Windows PC, plays your tune through POKEY and 6502 emulation as you edit, and produces modules that a 6502 player routine, supplied as assembly source, plays on the real machine.
What you'll learn: which RMT version to use, how to install it, how its four edit screens fit together, what instruments, tracks and the song list do, which export formats exist, and how to play a module from your own assembly program.
What you need: a Windows PC (or Linux/macOS with Wine), an assembler (MADS or XASM), and an emulator such as Altirra or atari800 for testing. For the POKEY background, read POKEY Sound Basics and Advanced POKEY first.
1. Which version?
| Version | Date | Notes |
|---|---|---|
| 1.28 | May 2009 | Raster's last official release; the de facto standard until about 2021 |
| 1.29 | 2010 | Raster's last source code, never released as a program |
| 1.30 | 2016 | Unofficial build by Rudla; resizeable window; needs Microsoft's MFC library |
| 1.31–1.33 | 2021–22 | Unofficial builds by VinsCool, who had been extending the player since 2021 |
| 1.34 | March 2023 | VinsCool's stable release |
| 1.36 / 2.0 | in development | Maintained by JAC! (Peter Dell) in the raster-atari-org GitHub repository |
The catch is player compatibility. Modules that use features added after 1.28 may not play correctly with the 1.28 player routine. VinsCool himself warned that his 1.34 driver uses more RAM and CPU. JAC!'s plan for RMT 2.0 is to load and save 1.28 files unchanged unless you choose the new format. For game music you will play with the standard routine, stay with the 1.28 feature set.
2. Installing
RMT needs no installer. Unzip the package into a folder and run Rmt.exe. The 1.28 package (rmt128.zip) contains:
Rmt.exeandrmt.ini(settings),songs/andinstruments/(examples in.rmtand.rtiformat),asm_src/: the player routinermtplayr.a65, the feature filermt_feat.a65and example programs,player/RMTPL107.XEX: a stand-alone Atari player for.rmtfiles,docs/: the operation manual (rmt_en.htm),changes.txtandoptimize.txt.
Sound needs extra DLLs. RMT has no built-in POKEY or 6502 emulation. It loads sa_pokey.dll (or Fox's apokeysnd.dll from the ASAP project, which takes priority if both are present) plus sa_c6502.dll. Without them it runs, but silently. The 1.28 zip does not include them: they were a separate download on Raster's "SA libraries" page. The 1.34 stable zip ships Rmt.exe together with sa_c6502.dll, sa_pokey.dll and mfc140.dll.
Linux and macOS: run it under Wine. VinsCool, a Wine user himself, bundled the Microsoft DLLs with his builds and reported that once all the files are present RMT "works perfectly through WINE". Builds from 1.30 on need the MFC runtime.
3. The screen and the four edit modes
RMT is keyboard-driven. Four function keys switch between its edit modes:
| Key | Mode | What you edit |
|---|---|---|
| F5 | TRACK EDIT | Notes in the track columns (F12 toggles track/instrument) |
| F6 | INSTRUMENT EDIT | The current instrument's parameters, table and envelope |
| F7 | INFO EDIT | Song name, speeds, mono/stereo |
| F8 | SONG EDIT | The song list: which track plays on which channel |
Playback keys work in every mode. F2 plays from the beginning, F3 from the cursor position, F4 loops the current set of tracks, and Esc stops and mutes everything. Hold Shift with F2–F4 and the cursor follows playback. Ctrl+1 to Ctrl+8 mute and unmute individual channels.
Notes are typed on a piano layout. On a QWERTY keyboard the Z–M row is the lower octave (S, D, G, H, J give the sharps), the Q–U row continues an octave higher, and Shift+Page Up/Page Down move the base octave. Alt+Backspace is undo.
4. Instruments
An RMT module holds up to 64 instruments. Each has:
- An envelope of up to 32 columns. Each column holds a left and a right volume, a distortion, a command with an
XYparameter, and filter and portamento flags. The envelope can loop, and VSLIDE/VMIN fade it after the first pass. - A table of up to 32 note or frequency offsets, stepped at TABLE SPD frames per step. This is how you build arpeggios and pitch effects.
- AUDCTL bits the instrument needs: 15 kHz clock, high-pass filters 1+3 and 2+4, joined 16-bit channels, 1.79 MHz clocks and the 9-bit poly. RMT manages AUDCTL automatically when several instruments need different settings.
- Effects: vibrato, frequency shift and their start delay.
The distortion values in the envelope are RMT's own: A is the pure tone, 8 is white noise, C and E are the two distortion-12 bass tables, and 6 gives a 16-bit bass that joins two channels (it only works on channels 2 and 4). Load the example .rti files from instruments/ to hear what each setting does before you build your own.
5. Tracks and the song
A track is one channel's pattern. A module can have 254 tracks, each with its own length (up to 256 lines) and optional loop point. Each line reads NNN TT V SS: a note from C-1 to C-6, an instrument number ($00–$3F), a volume ($0–$F) and an optional speed change.
The song list (F8) has up to 256 lines. Each line names the track number to play on each channel, four for a mono module and eight for stereo. A "go to line" entry (G in song edit, Ctrl+G from the track screen) makes the song loop. Reuse tracks freely: a bass line that repeats is entered once and listed many times. Ctrl+N puts a new empty track at the current song position, and Ctrl+M duplicates a track so you can vary a copy.
INFO EDIT sets the beat speed (1–255, in fiftieths of a second per line) and the instrument speed (1–4 updates per frame). Instrument speeds above 1 make the player run more than once per frame, which matters in section 7.
6. Exporting
File > Save writes the editable .rmt module. File > Export As offers:
- RMT stripped song file (
.rmt): only the data the player needs, relocated to an address you choose. The dialog also gives you a block ofFEAT_...definitions. Paste it between the BEGIN/END marks inrmt_feat.a65and the assembled player contains only the features this module uses. Raster's example inasm_src/optimcomes out 832 bytes smaller and noticeably faster. - SAP (
.sap): the Slight Atari Player format used by ASAP and the ASMA archive. You can define subsongs by song line. - XEX: a ready-to-run Atari program. Since 1.28 it adjusts its playing speed so tunes run at 50 Hz on both PAL and NTSC machines, or at 60 Hz if RMT is configured for NTSC.
- ASM simple notation (
.asm): note and duration tables for writing your own minimal player.
Newer builds add more formats. VinsCool's versions export LZSS register streams, for example. The Programming Music on the Atari guide explains why a game might prefer them.
7. Using the player in your own program
The player routine has three rules, stated in its own header. It needs 19 bytes of page zero to itself (203–221, $CB–$DD). It needs roughly 1K of variables and tables below its start address ($320 bytes for the mono build, $3C0 for stereo). And its start address PLAYER must be page-aligned (it is $3400 in the supplied file).
A .rmt file is already a standard Atari binary-load file with its own load header: $4000 for a normally saved module, or the address you chose for a stripped export. So you include it with headers switched off. (To put a full module somewhere else, export it stripped at the new address or use the rmt_relocator macro from the MADS examples.) This program plays the music.rmt example from the 1.28 package. It is Raster's music.a65 with a red band added that shows how much CPU time each call takes:
; Play an RMT module and show the player's CPU time as a red band
STEREOMODE equ 0 ; 0 = mono 4-track player
icl "rmtplayr.a65" ; RMT player, assembled at PLAYER ($3400)
opt h- ; .rmt is already an Atari binary file
ins "music.rmt" ; module loads at $4000 (set at export)
opt h+
MODUL equ $4000
VCOUNT equ $d40b
COLBK equ $d01a
COLPF2 equ $d018
CH equ $02fc
org $3e00
start ldx #<MODUL ; X/Y = module address
ldy #>MODUL
lda #0 ; A = starting song line
jsr RASTERMUSICTRACKER ; init (returns instrument speed in A)
lda #255
sta CH ; clear last key
loop lda #60 ; wait for scan line 120
wait cmp VCOUNT
bne wait
lda #$34
sta COLBK ; red band starts...
sta COLPF2
jsr RASTERMUSICTRACKER+3 ; play one frame
lda 712 ; restore colours from the
sta COLBK ; OS shadows: band ends here
lda 710
sta COLPF2
lda CH
cmp #28 ; Esc pressed?
bne loop
jsr RASTERMUSICTRACKER+9 ; silence all voices
jmp (10) ; back to DOS (DOSVEC)
run start
Assemble it with mads rmtdemo.asm -o:rmtdemo.xex in a folder holding rmtplayr.a65, rmt_feat.a65 and music.rmt. MADS accepts the XASM-syntax player unchanged: assembling Raster's original music.a65 with MADS produces a file byte-identical to the music.xex in the package. In atari800 the band is about 14 scan lines tall for this small module: roughly 1,600 CPU cycles, or about 5% of a frame.
The entry points are a jump table at PLAYER:
| Call | Does |
|---|---|
RASTERMUSICTRACKER |
Init: X/Y = module address (low/high), A = first song line. Returns the instrument speed in A |
RASTERMUSICTRACKER+3 |
Play one step: call once per frame, or 2–4 times for higher instrument speeds |
RASTERMUSICTRACKER+9 |
Silence: reset AUDCTL and SKCTL and zero all voices |
RASTERMUSICTRACKER+15 |
Sound effect (if FEAT_SFX is on): A = note, X = channel, Y = instrument × 2 |
For instrument speeds of 2–4, Raster's example spreads the calls evenly down the screen by stepping its VCOUNT target by 78, 52 or 39. STEREOMODE 1 builds the eight-track stereo player. Modes 2 and 3 play a four-channel tune spread across two POKEYs (L1 R2 R3 L4, or L1 L2 R3 R4). They rely on POKEY's address mirroring, so on a mono machine the same code simply plays in mono. See Stereo POKEY Programming for the hardware side.
Not writing in assembly? DMSC's rmt-cc65 project converts the player to CA65 syntax and includes examples in C and FastBasic, and RMT music has been used from Turbo-BASIC XL.
Troubleshooting
- The tracker is silent. The POKEY and 6502 DLLs are missing from the RMT folder.
- Weird noises, or the music stops after a few seconds in your game. Something else is writing to the player's page-zero bytes at $CB–$DD. One AtariAge user found exactly that: an old character-copy routine of his used one of those addresses. Also check that X holds the low byte and Y the high byte of the module address.
- The tune plays 20% fast on NTSC. Beat speeds are counted in fiftieths of a second. Calling the player once per 60 Hz frame speeds everything up, so skip every sixth call on NTSC machines.
- The tune plays too slowly or sounds smeared. The module uses instrument speed 2–4 and you call the player only once per frame.
- A 1.34 module sounds wrong with
rmtplayr.a65. It uses newer features. Use the player that matches the tracker version, or rework the tune in 1.28. - The music dies during disk loading. The OS SIO routines reset the sound registers. Playing through SIO needs a custom loader.
Further reading
- The RMT 1.28 operation manual (
docs/rmt_en.htmin the package) andoptimize.txt. - The RMT tracker and module-format documents in the raster-atari-org/RASTER-Music-Tracker repository on GitHub.
- De Re Atari (Atari, Inc., 1982), Chapter 7, for the POKEY features RMT instruments control.
- On this site: POKEY Sound Basics, Advanced POKEY, Programming Music on the Atari, Stereo POKEY Programming and the news item Raster Music Tracker 2.0 Plans Published.
- ASMA, the Atari SAP Music Archive, for thousands of RMT tunes to study.
Credits
- Picture: RMT's track screen in a recent 1.3x build, set up for an eight-track stereo module (L1–L4 left POKEY, R1–R4 right). — Screenshot of the RASTER Music Tracker main screen from the RMT documentation (raster-atari-org/RASTER-Music-Tracker on GitHub) (GPL-3.0 (repository licence))
- RMT - RASTER Music Tracker home page (Radek Sterba): version history, features, downloads — raster.infos.cz
- RMT 1.28 package (rmt128.zip): readme.txt, changes.txt, optimize.txt, rmt_en.htm operation manual 1.28.001, asm_src/music.a65, rmtplayr.a65, rmt_feat.a65 — raster.infos.cz
- SA libraries page (sa_pokey.dll, sa_c6502.dll) — raster.infos.cz
- RMT 1.34.00 stable package (file list) — wudsn.com
- GitHub raster-atari-org/RASTER-Music-Tracker: README.md, doc/rmt_versions.md, doc/rmt_note_keys.md, doc/img/questions_screen_sections.png (GPL-3.0) — GitHub project authors
- AtariAge — RASTER Music Tracker 2.0 - Technical Details (JAC!) — AtariAge forum members
- AtariAge — RMT Hacking Ideas and Progress (VinsCool, ivop; Wine, DLLs, 1.30/MFC) — AtariAge forum members
- AtariAge — How do I get music I made with RMT into my game? — AtariAge forum members
- AtariAge — RMT source code? (rmt-cc65, XASM syntax) — AtariAge forum members
- AtariAge — RMT stereo modes — AtariAge forum members
- AtariAge — RMT during SIO? — AtariAge forum members
- AtariAge — My first game (RMT works with Turbo-BASIC XL) — AtariAge forum members
