Skip to content

BETA

Replay Guide

Version 0.9.0

This guide shows how to play a song exported from RhYMe in your own Atari ST program, such as a demo, a game or a music compilation.

Tip

The export dialogs and song settings mentioned here are described in the user manual (Help > User Manual), under Menus & Toolbars and Main Window.

Choosing an Export

File > Export for Atari ST offers four exports:

Export What you get Use it for
SNDH Container The song and its replay routine in one file Playing the song in your own program
Atari ST Program A program that plays the song Playing the song by itself, for example in a music compilation
YMXS Structure The song as text, without a replay routine Building the files yourself with the YMXR tools
YM6 File The chip's registers for every song tick Playing the song in a YM player

For your own program, use the SNDH container. It contains everything the song needs: the replay routine, the song data and the memory the routine works in.

To put several songs in one file, export a playlist with File > Export for Atari ST in the playlist's menu (see Several Songs in One File).

Before You Export

Check these settings in the song's properties, in the right panel of the main window:

  • Timers (T-A, T-B, T-D, T-C): the timers the song may use. Clear any timer your program needs, for example for raster effects.
  • T-C: leave this clear when the song plays at a tick rate other than the target's vertical blank (VBL) rate.
  • Timer channels (Ch-A, Ch-B, Ch-C): the channels that may use a timer.
  • Tick frequency: how often your program calls the song. For 50 Hz, choose PAL rather than Custom: PAL matches the speed of an Atari ST, so the song plays at the same speed in the tracker as on the machine. Both are exported as 50 Hz, the vertical blank rate on a color monitor.

In the SNDH Container export dialog:

  • Replay clock: how the replay routine is triggered each frame, Timer C or Vertical blank. Automatic picks Timer C, unless the song already occupies Timer C.
  • Force play from VBL: with Automatic, a PAL song whose effects would use Timer D uses Timer C instead and plays from the vertical blank, so Timer D stays free for your program. It is cleared at first; check it if your program needs Timer D.
  • Lean timer ticks: makes the song's timer interrupts cheaper, which helps most with samples. The downside is that these interrupts keep the interrupt level raised, so other interrupts wait until each one ends, and that the MFP is in automatic end-of-interrupt mode while the song plays, so any other MFP interrupt handlers in your program must work in that mode too.
  • Pack the file: recommended. An SNDH file includes the replay routine's work memory, which is empty, so packing makes the file much smaller. Your program then unpacks the file before playing it (see Packed Files). Leave this option unchecked if you intend to play the file from a GFA BASIC program (see GFA BASIC).

Calling the SNDH File

An SNDH file starts with three entry points. Call them with jsr, in supervisor mode.

Entry Address What it does
Init file + 0 Starts song number d0.w (counting from 1) and sets up the required timers
Exit file + 4 Silences the YM2149 and gives the timers back
Play file + 8 Plays one song tick
  • Call Play once per song tick, at the song's rate (see Playback Rate).
  • Each entry point preserves all registers.
  • Calling Init while a song is playing stops that song first.
  • Play and Exit do nothing when no song is playing.

Load the file at an even address.

Assembly Example

This example plays song 1 from the vertical blank. That suits a song exported at PAL or 50 Hz and played on a color monitor. The syntax should be compatible with Devpac, vasm and rmac.

; Call in supervisor mode.
music_on:
        moveq   #1,d0               ; song 1
        bsr     tune                ; Init
        move.l  $70.w,old_vbl       ; save the system's VBL handler
        move.l  #vbl,$70.w          ; install ours
        rts

music_off:
        move.l  old_vbl,$70.w       ; put the system's handler back
        bsr     tune+4              ; Exit
        rts

vbl:    movem.l d0-a6,-(sp)
        bsr     tune+8              ; Play
        movem.l (sp)+,d0-a6
        move.l  old_vbl(pc),-(sp)   ; go on to the system's handler
        rts

old_vbl:
        dc.l    0

        even
tune:   incbin  "SONG.SND"          ; the SNDH file, not packed
        even

From user mode, such as in a GEM program, call music_on and music_off through Supexec:

        pea     music_on
        move.w  #38,-(sp)           ; Supexec
        trap    #14
        addq.l  #6,sp

Always call music_off before your program ends.

GFA BASIC

GFA BASIC cannot install an interrupt handler, so it cannot call Play on every song tick by itself. The GFA BASIC host routine does that for you: it starts the song, calls Play from Timer C at the song's rate, and stops the song when you tell it to. Download it as GFAHOST.INL.

Export the SNDH file with these settings:

  • Pack the file: cleared. The host routine plays the file where it is and cannot unpack it.
  • Replay clock: Timer C, with T-C cleared in the song. The host routine plays the song from Timer C.

Put the host routine and the SNDH file in two INLINE lines, the host routine first. To load a file into its line, put the cursor on the line and press Help.

The host routine has two entry points. Call both in supervisor mode:

Entry Address Registers
Start host% d0: the song number (from 1), d7: the song's rate in Hz, a6: the SNDH file
Stop host%+4 None

Call them with RCALL, which fills the registers from an array: elements 0 to 7 go into d0 to d7, and elements 8 to 14 into a0 to a6.

INLINE host%,154
INLINE sndh%,20000            ! the size of your SNDH file
DIM reg%(15)
'
reg%(0)=1                     ! d0: song 1
reg%(7)=50                    ! d7: the rate, from the file's TC tag
reg%(14)=sndh%                ! a6: the SNDH file
super%=GEMDOS(32,L:0)         ! supervisor mode
RCALL host%,reg%()            ! start
~GEMDOS(32,L:super%)          ! user mode
'
PRINT "Press a key to stop."
~INP(2)
'
super%=GEMDOS(32,L:0)
RCALL host%+4,reg%()          ! stop
~GEMDOS(32,L:super%)
END
  • Always stop the song before the program ends, even after an error. Otherwise Timer C is left pointing into memory the program no longer uses.
  • The host routine turns the key click off while the song plays, and turns it back on when the song stops.
  • An INLINE line takes at most 32,700 bytes. For a larger SNDH file, load it into reserved memory instead:
size%=33000                   ! the size of your SNDH file
RESERVE FRE(0)-size%-256
sndh%=MALLOC(size%)
BLOAD "SONG.SND",sndh%
' ... start, play and stop as above ...
~MFREE(sndh%)
RESERVE

Playback Rate

Play must be called at the song's rate. The SNDH header tells you the rate, and what to call Play from:

  • TC and the rate, such as TC50: call Play from a timer.
  • !V and the rate, such as !V50: call Play from the vertical blank. The song uses Timer C.

The vertical blank runs at 50 Hz on a PAL color monitor, 60 Hz on an NTSC color monitor and 71 Hz on a monochrome monitor. So it plays a 50 Hz song at the right speed only on a PAL color monitor.

A timer plays the song at the right speed on any monitor. Use a timer the song does not use. Timer C runs at 200 Hz, so for a 50 Hz song, a handler chained to the system's Timer C handler can call Play on every fourth tick.

A song exported at any other rate, such as 60 Hz or a custom rate, needs a timer.

Hardware Used by the Song

While a song is playing, leave these alone:

  • The YM2149. The song writes all three channels and the mixer on every song tick.
  • The song's timers. The FLAG tag in the SNDH header lists them: a, b, c and d for Timers A to D (y stands for the YM2149). Init takes these timers, interrupt vectors included, and Exit restores them. Other timers are left untouched.
  • The MFP's end-of-interrupt mode. Keep the mode the operating system sets. With Lean timer ticks, Init changes it and Exit restores it.

The song's timer interrupts must be served without delay. Disabling interrupts, or raising the interrupt level to 6 or higher, for long stretches makes samples and effects stutter.

To see how much processor time the song takes, export it as an Atari ST Program with Show CPU load while playing checked, and run it.

End of a Song

A song with a loop point plays forever. A song without one plays once and then goes silent.

  • The FRMS tag gives the length of each song in song ticks, as a 32-bit value, or 0 for a song that loops. Count your calls to Play to know when the song ends.
  • The TIME tag gives the same length in seconds.
  • The replay routine also sets a state bit when the song ends. The YMXR binary specification says where to find it (see Building the Files Yourself).

Several Songs in One File

A playlist exported as an SNDH container contains every song in the playlist, numbered from 1 in playlist order. Pass the number to Init. The ## tag gives the number of songs, and the !#SN tag their titles.

Every song keeps the rate it was written at. When the rates differ, the file is called at one rate that is a multiple of all of them, such as 300 Hz for songs at 50 and 60 Hz, and each song plays only on the calls its rate needs. The TC tag then gives that shared rate: call Play from a timer at that rate, whichever song is playing. The FRMS tag then counts these calls rather than the song's ticks, while TIME still gives the length of each song in seconds.

Packed Files

With Pack the file, the SNDH file is packed with ICE. It then starts with ICE! and cannot be called directly: unpack it with an ICE 2.4 unpacking routine and call the unpacked copy.

The unpacked file is much larger than the packed one, because the replay routine's work memory is back in it. Bytes 8 to 11 of the packed file give the unpacked size, as a 32-bit value. Reserve that much memory at an even address and unpack the file there.

Building the Files Yourself

The YMXS Structure export writes the song before any tool has processed it. The tools that make the other exports come with RhYMe, in the application's tools/ymxs folder (on macOS, inside the application bundle):

ymxs-to-sndh < song.ymxs > song.sndh
ymxs-to-prg  < song.ymxs > SONG.PRG
ymxs-to-ymxr < song.ymxs > song.ymxr

ymxs-to-ymxr writes a YMXR tune file: the song data without a replay routine, for use with your own copy of the YMXR player. The two projects document the player and the files:

Credits

The replay routine in every SNDH container and program is the YMXR player, and the song data is packed with DTX and ST4, which is based on ZX1. You may use them in your own programs, commercial ones included, as long as your program's documentation credits them. For example:

Music played with the YMXR player by Robbert van Dalen. Song data packed with ZX1 by Einar Saukas, through ST4 and DTX by Robbert van Dalen.

The GFA BASIC host routine was written by gwEm.