NinjaTracker
Music player

Contents

• Preface
• How to use it
• How to convert and play an Amiga MOD
• A bit of history
• Some (technical) details
• Changelist

Preface

How to use it

Boot the disk. Press 1, 2 or 3 to play a music.

How to convert and play an Amiga MOD

Either convert MODs with our online tool. Or launch MODConvert II. With this program, you can convert Amiga Modules into NinjaTracker format. There are some in the Modules folder. When you choose one, you will be presented with this screen:

Use the arrow keys (up/down) to scroll through all instruments.

When you press F, you can see all effects available. An asterisk marks what this MOD is using. More information on effects can be found here: modformat.txt.

Use N to convert to NinjaTracker format. In the next screen, press 1 to convert the instruments in a wave file. Make sure you name the music file "songname.ssm" and the wave file "songname.w" and save both into the same folder.

Now you can return to the main menu of the disk and press 4. Enter the pathname of the converted module,e.g. "converted/songname" and the module will play. Have fun!

A bit of history

The biggest problem playing Amiga MOD files is the amount of sound data that these files include. The Apple IIGS only has a measly 64k ensoniq doc sound ram, and even that cannot be used without obeying some rules.

1989 - The first Tracker for the Apple IIGS, SoundSmith, only allowed instruments that would fit into the sound ram. Also there was no way to import Amiga MOD files into it.

1991 - FTA released Noise Tracker, which for the first time allowed to play music with much larger instruments than would fit in the 64k sound ram. This was done by "swapping" sound data in and out of the sound ram all the time. Unfortunately, this costs a lot of processor time. Since the Apple IIGS is very slow, you can play a song but not do much else.

Also, Noise Tracker had direct Amiga MOD import. And if the samples would fit into the sound ram, the music player ran very fast. We used it in our first demo.

1992-1994 - There was a surge of Amiga MOD players for the Apple IIGS: soniqTracker by Tim Meekins, MODZap by Ian Schmidt, Beatbox by Alvin Tan and Brian Ballwebber and Shellplay by Brian C. Bening (see also Deskplay).

Unfortunately, none of the authors shared the source code, so we had to have our own player.

Some (technical) details

• The source code is available on the NinjaTracker disk.
• NinjaTracker is basically an extension to the SoundSmith player.
• All of the instruments have to fit inside the 64k sound ram of the Apple IIGS.
• The file format of NinjaTracker is the same as SoundSmith, except that the effects are those specified in the Amiga module format. So in theory, it might be possible to edit NinjaTracker songs with SoundSmith. The Info folder on the disk has more information.
• Instruments in an Amiga MOD can have repeat pointers: A module composer can define, for each instrument, the starting position and the length that should be repeated when the instrument is to be looped (played continously). Since the ensoniq chip cannot handle bytewise playing of sounds, MODConvert splits up the instrument into two: The instrument and the loop.
  
  In order to play a loop, the instrument is played with the even osciallator (A) in swap mode, and the odd oscillator (B) is set up to play the loop. So when A has played its part, B will start automatically and an interrupt occurs. That interrupt allows the player to set A to play the loop, too.
  
  Why is this done in this complicated way when there is the free-run mode? It has turned out that the free-run mode does not sound as good as the swap mode (don't know why).
• Most effects are available. Refer to the source code of the player to see what's there.
• Instrument (sample) lengths.
  Because of the IIGS sound hardware, the instrument data has to obey a number of rules. When you convert a MOD with MODConvert, everything is taken care of. However, with many MODs, the instrument size will exceed the 64k available. This error can also occur even when there seems to be enough space.
  1. MODConvert has to append 8 zero bytes to every instrument so that the sound chip knows when to stop playing. So when MODConvert shows a sample length of $4EE, the converted size will be $4F6 bytes.
  2. Instruments have to be aligned according to its normalized length. These can be 256 ($100), 512 ($200), 1024 ($400), 2048 ($800), 4096 ($1000), 8192 ($2000), 16384 ($4000) or 32768 ($8000) bytes. So a sample with $4EE length has to be 2048 ($800) byte aligned.
  3. MODConvert has to split looped instruments into instrument and loop. For both, the rules above are applied.
• MODConvert can convert up MODs with up to 14 channels. There is an identifier in the data which is used to indicate how many channels are used. By default, MODs have 4 Channels with the identifier of "M.K.". MODConvert also supports the following:
  2CHN, 5CHN, 6CHN, 7CHN, 8CHN, 9CHN,
  01CH, 02CH, 03CH, 04CH, 05CH, 06CH, 07CH, 08CH, 09CH, 10CH, 11CH, 12CH, 13CH, 14CH,
  01CN, 02CN, 03CN, 04CN, 05CN, 06CN, 07CN, 08CN, 09CN, 10CN, 11CN, 12CN, 13CN, 14CN
• When you boot the NinjaTracker disk and select a song to play, the memory layout is this:
  

  $0F0000	NinjaTracker player program
  $100000	Music file (the .ssm file)
  $120000	Wave file (the .w file)

• The current version of KEGS (v0.91) and ActiveGS (ActiveGS Win32/Plugin v3.7.1019 BETA) have some issues with looped instruments. Maybe it's the interrupt that individual instruments use? So the best, as always, is to play it 'on the metal'.

You can check out what the player is doing by launching the NF Assembler. Select "Enter Debugger" from the menu. Then, choose "Intercept Sound" from the Special menu:

The blue border indicates when the player is handling it's interrupt.

Next, choose "View DOC registers..." from the same menu:

Each line in this screen consists of a pair of oscillators: Even (left) and odd (right). The diamond icon indicates that the oscillator is currently playing. Inverse Oscillator numbers fire an interrupt. For more information on the registers, check out the Apple IIGS Hardware Reference Chapter 5, Apple IIGS Sound.

Changelist