Getting Started with RASTER Music Tracker (RMT)

RASTER Music Tracker main screen: song name and speed at the top, eight empty track columns labelled TRACK L1 to L4 and R1 to R4 below

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.exe and rmt.ini (settings),
  • songs/ and instruments/ (examples in .rmt and .rti format),
  • asm_src/: the player routine rmtplayr.a65, the feature file rmt_feat.a65 and example programs,
  • player/RMTPL107.XEX: a stand-alone Atari player for .rmt files,
  • docs/: the operation manual (rmt_en.htm), changes.txt and optimize.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 XY parameter, 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 of FEAT_... definitions. Paste it between the BEGIN/END marks in rmt_feat.a65 and the assembled player contains only the features this module uses. Raster's example in asm_src/optim comes 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.htm in the package) and optimize.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