83385 packages online


No screenshot available
Short:ProTracker player w/ support for ext. sfx
Author:Frank Wille
Uploader:frank phoenix owl de
Download: - View contents

While developing the games Sqrxz and Solid Gold I needed a Protracker
player which can insert sound effects from the game into the current song.
I ended up in writing a completely new player based on the original
replayer source which came with ProTracker 2.3.

This player is quite optimized and has some useful features for game

- Insert external sound effects into the replayed module.

- Can also play sound effects while music is stopped or not even initialized.

- A fast master volume for the replayed music.

- No busy waiting. DMA and repeat pointers are set with timer interrupts.

- E8 command can be used as a trigger for your main program.

- Lots of tables for best performance. No multiplications or divisions.

The sound fx system gives you the possibility to play samples on a channel
of your choice or on the channel which the player thinks is the best one.

It may be a channel which is currently not replaying music and/or has
the longest period of silence ahead. This has the effect that the replayed
song is often not disturbed at all.

Up to four sound effects can be played at the same time and any of them
has its own priority, which is especially useful when trying to play
several sounds on the same channel. You may for example define that a
shooting-sound has a higher priority than a jumping-sound.

For automatic channel selection you can additionally reserve specific
channels for music only, or define the maximum number of channels which
may be used for sound effects at once.

The master volume is always applied to the music, but does not affect
external sound effects at all.

How to use:

1. Selecting the data model

ptplayer.asm can be configured to support two data models:

a) By default ptplayer.asm assembles into a single code section. The
   interface functions set up a local base register to access data.
   This requires a working RS directive, which is provided by many
   assemblers, like e.g. vasm, PhxAss, Devpac, Basm, AsmOne, SNMA.

b) By defining the SDATA symbol ptplayer.asm assembles into a code
   section and a small-data section (called __MERGED). All interface
   functions expect that the base register A4 is set up with the
   small-data base pointer (provided by the linker through _LinkerDB).
   It uses the NEAR directive, which might work with vasm and PhxAss only.

2. Select minimal or full ptplayer

ptplayer builds with all features by default. By defining the symbol
MINIMAL you get just a standard Protracker player, without the ability
to insert external sound effects or to control the master or sample
volumes. This approximately halves the code size.

3. Common usage

a) Install a Level-6 interrupt handler for CIA-B timer interrupts
   by calling mt_install_cia(). Do this once, during program init.

b) For every new MOD file to play initialize it with mt_init().
   Most common case is to pass a pointer to the MOD in A0 and set A1
   and D0 to zero, which will play the song from the beginning.
   Everything is initialized for replay now, but nothing is played.

c) Set the byte-variable mt_Enable to non-zero to start the replay.
   Clearing that variable again pauses the song.

d) Stop playing and set all volumes to zero by calling mt_end().

e) Finally, in the cleanup routine of your program, remove the Level-6
   interrupt handler again and reset all CIA registers by calling

Exported functions:

Note that the leading underscore disappears when a symbol is referenced
from C. CUSTOM is the custom-chip register set base address $dff000.

_mt_install_cia(a6=CUSTOM, a0=VectorBase, d0=PALflag.b)
  Install a CIA-B interrupt for calling _mt_music or mt_sfxonly.
  The music module is replayed via _mt_music when _mt_Enable is non-zero.
  Otherwise the interrupt handler calls mt_sfxonly to play sound
  effects only. VectorBase is 0 for 68000, otherwise set it to the CPU's
  VBR register. A non-zero PALflag selects PAL-clock for the CIA timers
  (NTSC otherwise).

  Remove the CIA-B music interrupt, restore the previous handler and
  reset the CIA timer registers to their original values.

_mt_init(a6=CUSTOM, a0=TrackerModule, a1=Samples|NULL, d0=InitialSongPos.b)
  Initialize a new module.
  Reset speed to 6, tempo to 125 and start at the given song position.
  Master volume is at 64 (maximum).
  When a1 is NULL the samples are assumed to be stored after the patterns.

  Stop playing current module.

_mt_soundfx(a6=CUSTOM, a0=SamplePointer,
            d0=SampleLength.w, d1=SamplePeriod.w, d2=SampleVolume.w)
  Request playing of an external sound effect on the most unused channel.
  This function is for compatibility with the old API only.
  You should call _mt_playfx instead. !MINIMAL only.

channelStatus = _mt_playfx(a6=CUSTOM, a0=SfxStructurePointer)
  Request playing of a prioritized external sound effect, either on a
  fixed channel or on the most unused one.
  Structure layout of SfxStructure:
    APTR  sfx_ptr  (pointer to sample start in Chip RAM, even address)
    WORD  sfx_len  (sample length in words)
    WORD  sfx_per  (hardware replay period for sample)
    WORD  sfx_vol  (volume 0..64, is unaffected by the song's master volume)
    BYTE  sfx_cha  (0..3 selected replay channel, -1 selects best channel)
    UBYTE sfx_pri  (unsigned priority, must be non-zero)
  When multiple samples are assigned to the same channel the lower
  priority sample will be replaced. When priorities are the same, then
  the older sample is replaced.
  The chosen channel is blocked for music until the effect has
  completely been replayed.
  RETURN VALUES: A pointer to a channel-status structure (see ptplayer.h)
  when the sample is scheduled for playing, and NULL when the request was
  NOTE: Always make sure the first two bytes of your sound effect sample
  are zero!
  !MINIMAL only.

_mt_musicmask(a6=CUSTOM, d0=ChannelMask.b)
  Bits set in the mask define which specific channels are reserved
  for music only. Set bit 0 for channel 0, ..., bit 3 for channel 3.
  When calling _mt_soundfx or _mt_playfx with automatic channel selection
  (sfx_cha=-1) then these masked channels will never be picked.
  The mask defaults to 0. !MINIMAL only

_mt_mastervol(a6=CUSTOM, d0=MasterVolume.w)
  Set a master volume from 0 to 64 for all music channels.
  Note that the master volume does not affect the volume of external
  sound effects (which is desired). !MINIMAL only.

_mt_samplevol(d0=SampleNumber.w, d1=Volume.b)
  Redefine a sample's volume. May also be done while the song is playing.
  Warning: Does not check arguments for valid range! You must have done
  _mt_init before calling this function!
  The new volume is persistent. Even when the song is restarted.
  !MINIMAL only.

  The replayer routine. Is called automatically after _mt_install_cia.

Exported byte-sized variables:

  Set this byte to non-zero to play music, zero to pause playing.
  Note that you can still play sound effects, while music is stopped.
  It is set to 0 by _mt_install_cia.

  This byte reflects the value of the last E8 command.
  It is reset to 0 after _mt_init.

  This byte defines the number of channels which should be dedicated
  for playing music. So sound effects will never use more
  than 4 - _mt_MusicChannels channels at once. Defaults to 0.
  !MINIMAL only.

There is also a header file for C compilers, called ptplayer.h.
It depends on the SDI_compiler.h header file, which implements
portable macros for defining compiler-specific register arguments.
Get it from Aminet:


Written by Frank Wille in 2013, 2016, 2017, 2018, 2019, 2020.
I, the copyright holder of this work, hereby release it into the
public domain. This applies worldwide.

If still in doubt, please read the included file "LICENSE".


- Try not to break channels with sound effects, which are currently
  playing a looped sample.
- Sound effects can also be started when the music is not playing

- Do not trash d2/a2 in mt_init().
- Unused samples with length 0 are played like a 1-word null-sample,
  for compatibility with other players.
- Make sure all samples start with two zero-bytes.

- For better maintenance there is only a single source text now. The
  default is a PC-relative, single-section version, which uses a local
  base register. Small data mode can be enabled by defining SDATA.
- mt_install_cia() also initializes the channel structures, like mt_init()
  does. So it should be possible to play sound effects without loading
  a tracker module.
- New sound effects system, which truly supports playing multiple sound
  effects per frame (e.g. stereo). It also supports priorities and
  channel selection.
- New exported function mt_playfx() which passes a pointer to an sfx
  structure, includes the new parameters like channel and priority.
  The old API through mt_soundfx() is still supported and emulated by
- New exported function mt_musicmask() defines which specific channels
  are dedicated for music and won't be used for sound effects.
- New exported variable mt_MusicChannels defines a limit for the
  maximum number of channels to be used for sound effects in parallel.

- Only few assemblers support the BASEREG directive, so I decided
  to rework the code and make it more portable. This version is tested
  with Devpac, vasm, PhxAss, Barfly-Asm, SNMA, AsmOne, AsmPro.
- All exported symbols (functions and variables) have got a leading
  underscore now, to make them directly accessible to C programs.
  So in assembler you have to call _mt_init now, while in C you can
  call mt_init().

- Included C header file, ptplayer.h, provided by BSzili.
- Fixed bug where other level 6 interrupts could trigger sample replay.
- Eliminated relocations in the fine-tune table, by replacing pointers
  with word-offsets (asman).
- More optimizations in the Timer B interrupt handlers and made it
  PC-relative (asman).
- Include a public domain license.

- Make it work with broken mods, which have a sample repeat length of zero.
- Never break looped samples with sound effects, except we have looped
  samples on all four channels at once!
- New variable _mt_SongEnd to automatically stop the song when having
  played the last position. Don't use it! Doesn't work perfectly yet.

- No longer clear the first word of each sample for idle looping.
  Either we have a good Amiga tracker MOD with repeat-length one, which
  already cleared that word, or we have a PC tracker MOD with a zero
  repeat length. In the latter case the idle loop will now point to
  address $0. Make sure that the word at this address is cleared!
- Treat samples with a length of one word the same as with zero length
  as a workaround for broken PC trackers.
- Changed APTR to void* in the C headers, for better Kickstart 1.x
  OS header file compatibility.
- Fixed detection of negative fine-tuning (broken due to optimizations
  in V5.1).

- _mt_musicmask works as documented now! Sound effects will never play
  on the masked channels. Previously it was rather a hint not to use them.
- Fixed sign-bug in tremolo/vibrato command 7xx (Antiriad/EAB).
- New function _mt_samplevol may be used to redefine a sample's volume.
- _mt_playfx now returns a pointer to the selected channel status structure
  when the sample was scheduled for playing and returns NULL when ignored.
- Wait 576 ticks for audio DMA instead of 496, which fixes issues with
  low notes on a few A1200 configurations. (No, this doesn't harm the
  player's performance, as it is a timer interrupt.)
- Defining the symbol MINIMAL lets you assemble a minimal version of
  the player, without the ability to insert sound effects and without
  master-volume or changing samples volumes.
- Improved interrupt handling, following a suggestion of Ross/EAB.
- Minor optimizations.

Contents of mus/play/ptplayer.lha
---------- ----------- ------- ------- ------ ---------- ------------ ----------
[generic]                  183     380  48.2% -lh5- fae4 Aug 29  2016 cia.i
[generic]                 1312    4533  28.9% -lh5- 9e4e Aug 29  2016 custom.i
[generic]                  690    1211  57.0% -lh5- 3e9d Jun 28  2018 license
[generic]                18342   75347  24.3% -lh5- 0b9e Sep 12 12:40 ptplayer.asm
[generic]                 2170    5765  37.6% -lh5- 51b1 Sep 11 20:10 ptplayer.h
[generic]                 5050   12239  41.3% -lh5- 267d Sep 12 12:40 ptplayer.readme
---------- ----------- ------- ------- ------ ---------- ------------ ----------
 Total         6 files   27747   99475  27.9%            Sep 13 00:22

Aminet © 1992-2021 Urban Müller and the Aminet team. Aminet contact address: <aminetaminet net>