Playing Chaos Music Composer Tunes in Your Own Programs

Atari BASIC screen after RUN: STARTED, STARTED AGAIN (IGNORED), SIN(1)=0.841470987, STOPPED, STOPPED AGAIN (IGNORED), RESTARTED, READY

Chaos Music Composer (CMC), Janusz Pelc's 1992 tracker for LK Avalon, was one of the standard ways to put music into Polish and other European Atari software of the 1990s. A tune made with it can be dropped into a game, a demo or even an Atari BASIC program. The software page for Chaos Music Composer describes the editor. This guide is about the other side: getting a finished .CMC file to play from your own code.

What you'll learn: what's inside a .CMC module, how the replay routine is called, a complete assembly example that plays music from the vertical blank interrupt, an Atari BASIC example that starts and stops music with USR, and how to move a module to a different address.

What you need: a .CMC module and a replay routine. For the assembly examples you need the MADS assembler. Its distribution has an examples/players/cmc_player_relocator folder containing cmc_player.asm (the replay routine), cmc_relocator.mac (a relocation macro) and a demo tune, tekkno.cmc. Both examples below were assembled with MADS and run in the atari800 emulator (NTSC XL, Atari BASIC revision C, DOS 2.5) with POKEY register recording switched on, so that the sound output could be checked frame by frame.

1. Two pieces: the module and the replay routine

The composer saves two kinds of file, and both are ordinary DOS binary-load files:

  • The module (.CMC): the notes, instruments and song order. It is assembled for a fixed address, which you choose in the editor with CTRL+A before saving.
  • The replay routine (.REP): about 2 KB of machine code that reads the module and writes to POKEY. In the editor, CTRL+M saves it. It suggests the address just after the music, which you can change, and it uses the name of the last loaded or saved tune with the extension .REP.

You can also use the source version in the MADS folder, cmc_player.asm. Its header calls it "cmc player v 2.1 by Marcin Lewandowski, based on cmc player v 2.0 by Janusz Pelc". With the source you can assemble the routine wherever you like and link it straight into your program.

2. Inside a .CMC module

After the 6-byte DOS header ($FF $FF, start, end), the module has a fixed layout. These offsets were published in the Polish magazine Tajemnice Atari (23/93) and quoted on the atari8 mailing list in 1997. The player source and the tekkno.cmc file agree with them:

Offset Contents
$000–$012 Title, used to identify the file (" cmc data file " in inverse video in tekkno.cmc)
$013 Tempo
$014–$053 Low bytes of the addresses of patterns 0–63 ($FF = unused pattern)
$054–$093 High bytes of the same addresses
$094–$12F Instrument definitions and accents
$130–$1FF Instrument pitch definitions
$200–$254 Song: track (channel) 1
$255–$2A9 Song: track 2
$2AA–$2FE Song: track 3
$300– Pattern data

In tekkno.cmc, loaded at $5E00, the tempo byte is 5 and pattern 0's pointer is $6100, which is exactly offset $300. The player confirms this layout: on initialisation it sets the pattern-table pointer to the module address + $14 and the song pointer to the module address + $200, and it steps between song columns in units of $55.

Pattern data is a byte stream:

Byte Meaning
$00–$19 Switch to instrument n for the notes that follow
$40–$7E A note, in semitones from C1 to D6, plus $40
$80–$BD A run of empty lines, plus $7F (so $81 = two lines)
$FF End of pattern

Pattern 0 of tekkno.cmc begins 00 44 81 44 81 44 82 44 80 …, which decodes as: instrument 0, a note, two empty lines, the same note, and so on.

Song columns list pattern numbers, plus a few command bytes. The player treats $8F and $EF as the ends of songs when it counts its way to song n, and $CF as a tempo change whose value is in the next column. One file can hold several songs, separated by the editor's "end of song" commands.

Because the module holds absolute pattern addresses, you can't just load it somewhere else. Section 6 shows how to relocate it.

3. The replay routine's entry points

The routine starts with three JMPs:

Address Entry Use
REPLAY+0 BASIC Called with USR from BASIC (section 5)
REPLAY+3 Control Initialise, choose a song, stop and so on, with a command in A
REPLAY+6 Play Call once per frame to play the next tick

The control entry takes these commands, according to the composer's documentation:

A X / Y Action
$70 X = module address low, Y = high Initialise. This must be the first call
$00 X = song number (first song = 0) Play a song from its start
$10 X = position in the song Play from a position
$2n X = pitch, Y = instrument Play a single note on channel n (sound effects)
$30 X = tempo Set the tempo
$40 — Stop
$50 — Interrupt (stop the song but let ringing instruments die away)
$60 — Continue

The examples here use $70, $00 and $40. The others are listed as documented but weren't tested.

The routine uses zero-page locations $FC–$FF as pointers, but both the control and play entries save and restore them. It also writes 3 to SKCTL ($D20F) when it initialises.

4. Example 1: music from a deferred VBI (assembly)

The usual approach is to initialise once, choose a song, and then call REPLAY+6 from the vertical blank interrupt so that the music plays on its own while your program runs. This complete MADS program does that:

; play a CMC tune from a deferred VBI - tested with MADS + atari800
SETVBV  = $E45C
XITVBV  = $E462
MSX     = $4000          ; where the module will live

        cmc_relocator 'tekkno.cmc', MSX   ; patch pattern pointers for $4000
        org MSX
        .sav [6] ?length                  ; emit the relocated module

        org $2000
main    ldx <MSX                ; A=$70: initialise, X/Y = module address
        ldy >MSX
        lda #$70
        jsr cmc_player+3
        lda #$00                ; A=$00: play song, X = song number (0 = first)
        tax
        jsr cmc_player+3
        lda #7                  ; install deferred VBI (A=7, Y=lo, X=hi)
        ldy <vbi
        ldx >vbi
        jsr SETVBV
        jmp *                   ; main program carries on here

vbi     jsr cmc_player+6        ; one tick of the player per frame
        jmp XITVBV

        icl 'cmc_player.asm'
        run main
        opt l-
        icl 'cmc_relocator.mac'

Put cmc_player.asm, cmc_relocator.mac and tekkno.cmc in the same folder as this source, then assemble it with mads vbi.asm -o:vbi.xex. The player lands at $2021 and the relocated module at $4000–$4D0C. When it ran in atari800, the POKEY log showed the tune starting within the first second. All four channels were in use: channels 1 and 3 each used more than 200 different pitch values, while channels 2 and 4 held a handful of pure tones. AUDCTL switched between 0 and 2, so the tune uses POKEY's high-pass filter.

Two points to remember:

  • One call per frame sets the speed. On a 50 Hz PAL machine the music plays one sixth slower than on a 60 Hz NTSC one. The examples here were run on NTSC only. Most CMC tunes were written on PAL machines in Europe.
  • The MADS demo program uses a different method. It waits for VCOUNT ($D40B) to reach 16 and calls the player from its main loop. That's fine for a stand-alone player, but in a game the VBI method leaves the main loop free.

5. Example 2: music from Atari BASIC

The REPLAY+0 entry is written for USR:

X=USR(REP,SONG,MUS)   : REM start song number SONG (first = 1) of the module at MUS
X=USR(REP)            : REM stop

The start call waits for a vertical blank, chains the player into the deferred VBI vector (VVBLKD, $224) and starts the song. The stop call puts the old vector back and sends the stop command. The music then plays by itself while your BASIC program runs. Note that the song numbers start at 1 here, but at 0 in the assembly interface.

First, both files have to be in memory somewhere BASIC won't overwrite them. For the test, the player and module were built as one DOS binary file with no run address. The player was placed at $7000 and the module at $7900, both well below the BASIC screen:

; replay routine at $7000 and the module at $7900, as one DOS binary file
; (no run address: load it from DOS, then go back to BASIC)
MSX     = $7900
        cmc_relocator 'tekkno.cmc', MSX
        org MSX
        .sav [6] ?length
        org $7000
        icl 'cmc_player.asm'
        opt l-
        icl 'cmc_relocator.mac'

Copy the file to a DOS 2.5 disk. Boot with BASIC, type DOS, choose L (binary load) and give the file name, then choose B to return to BASIC. Then run:

10 REP=28672:MUS=30976
20 X=USR(REP,1,MUS):? "STARTED"
30 X=USR(REP,1,MUS):? "STARTED AGAIN (IGNORED)"
40 FOR I=1 TO 200:A=SIN(I):NEXT I
50 ? "SIN(1)=";SIN(1)
60 X=USR(REP):? "STOPPED"
70 X=USR(REP):? "STOPPED AGAIN (IGNORED)"
80 FOR I=1 TO 100:NEXT I:X=USR(REP,1,MUS):? "RESTARTED"

REP and MUS are $7000 and $7900 in decimal. The program ran as expected, and the POKEY log showed music during line 40, a short silence after line 60, then music again, which carried on after READY. Three details are worth knowing:

  • Starting twice or stopping twice did no harm with this v2.1 routine. Its BASIC entry checks whether VVBLKD already points to the player, and ignores a second start or a stop when nothing is playing. Users of the composer's own .REP files have long warned that starting or stopping twice can hang the machine, so with an older routine, keep strictly to on, off, on.
  • Floating point is safe. The player borrows $FC–$FF, which the floating-point routines also use, but it saves and restores them. The SIN loop ran while the music played and gave the right answer.
  • Protect the memory. A long BASIC program, big arrays or a graphics mode with a large screen can grow into $7000. Either lower MEMTOP (location 741–742) before loading, or choose addresses just below the screen for the mode you use.

6. Moving a module to another address

The editor's CTRL+A sets the address before saving. For a file you already have, MADS's cmc_relocator macro does the work while you assemble: it reads the module and corrects the DOS header. It adds the difference between the old and new addresses to each of the 64 pattern pointers, and leaves unused ($FFxx) entries as $FFFF. Then .sav [6] ?length writes out the corrected module without its old header, right where you org it. The pattern pointers are the only absolute addresses in the module, so nothing else needs changing.

To relocate a module without MADS, apply the same rule yourself: for each of the 64 entries at $14/$54, if the high byte isn't $FF, add (new − old) to the 16-bit address.

Troubleshooting

  • No sound at all: check that $70 (initialise) was called with the module's actual address, that the module was relocated to where it was loaded, and that the play routine really is being called every frame.
  • Garbage or a crash when starting: the module overlaps the player, the screen or your program, or it was loaded at a different address from the one it was saved for.
  • It plays but some notes are wrong: some files with the .CMC extension are really variants, such as the "CMR" format with a different bass table. The standard player gets their bass notes wrong. Modern tools like the ASAP player and the CMX editor can handle the variants. Converting a tune to a register dump (SAP, LZSS) can also lose CMC's "two-tone filter" effect unless the dump player supports it.
  • An instrument sounds wrong on channels 2–4: in the composer, instruments and patterns marked with ! work properly only on the first channel. Special modes such as "synthesizer" and 16-bit tones need channel 1.
  • Tempo differs from the composer's: PAL versus NTSC, as described in section 4.

Further reading

  • The Chaos Music Composer command list (LK Avalon; English notes by Jiri Bernasek, 1993), which covers the editor keys and the replay-routine interface.
  • Tajemnice Atari 23/93, the source of the module-format table.
  • The MADS distribution, examples/players/cmc_player_relocator.
  • On this site: Chaos Music Composer, Getting Started with RASTER Music Tracker (RMT), Vertical Blank Interrupts: Running Code 60 Times a Second, POKEY Sound Basics.

Credits