AMCAF Extension V1.40 Manual  Index

Protracker Music Commands

As the AMOS Tracker commands are really crap and contain a lot of bugs, of course there is a replacement for them in the AMCAF extension.

Since version 1.1 there are new commands even to replay sound effects during the normal protracker music.
The AMOS Music Extension is rather obsolete now.

Here a brief list of all advances of the AMCAF commands:

instruction: replay a module
Pt Play bank
Pt Play bank,songpos

Pt Play stars a Protracker music module which has be situated in memory bank number 'bank'.
Optionally, you can specify a song position, which the music should be played from.

Before you start the music with Pt Play you should choose either Vertical Blank-Timing or CIA-Timing for the module using Pt Cia Speed.

With help of the Pt Instr Play instruction you can replay any instrument of the music track.
This method has the advantage that you can reuse a sample that occurs in the music for your sound effects.

If you want to use the instruments only, without replaying the music, you can call the Pt Bank command instead.
The music will be turned off again with a call to the Pt Stop instruction.

instruction: stop the current music module
Pt Stop

This command stops the current music module. You can restart the music with the Pt Continue command from the very position you stopped it.

instruction: restart a previously stopped protracker music
Pt Continue

This command restarts the protracker music at that point it has previously been stopped using Pt Stop.
Do not attempt use Pt Continue without having started the music once with Pt Play.

instruction: set the volume of the protracker music
Pt Volume value

The Pt Volume instruction sets the volume of the music. The parameter 'value' may range from 0 (silent) to 64 (full volume).

instruction: toggle the audio channels
Pt Voice bitmask

This command defines the channels which should be used for the music and which should be free for e.g sound effects.

The 'bitmask' parameter contains -similar to the AMOS Voice command- four bits, that are assigned to one channel each.
If a bit is set, this channel can be heard. Pt Voice %1111 turns on all sound channels.

instruction: change the replay speed of a protracker module
Pt Cia Speed bpm

With the help of this command, you can set the speed for replaying the Protracker modules.
However, the music may change the speed on it's own if it has been composed for CIA-Timing.

The parameter 'bpm' set the number of beats per minute or if you specify a value of zero, the timing will be switched from CIA-Timing to Vertical Blank Timing.
Then the bpm rate is automatically set to exactly 125 and all CIA-Timing from the module are ignored if such appear in the music.

CIA-Timing causes some problems in conjunction with AMOS sprites, which show up as a flickering at regular intervals.
If you work with sprites you should switch back to VBL-Timing where possible using Pt Cia Speed 0.

If a music module is not replaying correctly using VBL-Timing, i.e it is running to fast or slow, you must switch to Cia-Timing.
This can achieved with a Pt Cia Speed 125 command directly in front of a Pt Play instruction.
The default is CIA-Timing with 125 bpm.

instruction: play a chunk of memory as a sound sample
Pt Raw Play voice,address,length,freq

This command corresponds to the normal AMOS command Sam Raw. Pt Raw Play replays a piece of memory as an audio sample.

The 'voice' parameter sets the channels to use, 'address' contains the starting address of the memory block.
'length' is the length of the sample in bytes and 'freq' holds the replaying speed in Hertz.

instruction: set the bank to use with pt instr play
Pt Bank bank

This command is used if you want to play back instruments from a music module but the music bank has not yet been specified with Pt Play.

instruction: play an instrument of a protracker module
Pt Instr Play instnr
Pt Instr Play voice,instnr
Pt Instr Play voice,instnr,freq

The Pt Instr Play instruction replays an instrument of the current Protracker music module.

The 'voice' parameter contains a bitmask that says on which channels the instrument number 'instnr' should be played.
If it is omitted, the sound effect is output on all four channels. 'instnr' must range between 1 and 31.
The optional argument 'freq' holds the frequency which should be used for the sample.

If you want to replay a sample repeatedly, just specify a negative value for 'instnr'.
The volume of the instrument can be set with the Pt Sam Volume command.

Before you can replay an instrument of a module, you first have to specify the bank that holds the music.
This can be achieved either by a call to Pt Bank or Pt Play.

instruction: set the bank to use with amos samples
Pt Sam Bank bank

If you want to replay standard AMOS samples with AMCAF, you have to inform AMCAF about the Sample-Bank, which contains the sound effects.
And that's exactly what Pt Sam Bank does. 'bank' holds the bank number of the AMOS sample bank.

Please remember, that you can replay the instruments of music modules directly.

instruction: replay a sample from an amos sample bank
Pt Sam Play samnr
Pt Sam Play voice,samnr
Pt Sam Play voice,samnr,freq

The Pt Sam Play command plays a sample out of an AMOS sample bank. The advantage to the normal Sam Play instruction is that the sounds 'interact' with the Protracker music.
Moreover, no notes are missed out, like AMOS does this on accelerated Amigas.

The 'voice' parameter contains a bitmask, that describes, on which channels the sample number 'samnr' should be replayed.
If it is omitted, the sound effect will be played on all four sound channels. The optional argument 'freq' holds the replaying speed, that shall be used.

If you want the sample to be looping, just give a negative value for 'samnr'. The volume of the sample can be changed using Pt Sam Volume.

instruction: stop the sfx on specific audio channels
Pt Sam Stop voice

This command stops a sound effect on the channels, which are defined in the bitmap 'voice'.
This is valid for samples started by Pt Sam Play, Pt Instr Play and Pt Raw Play.

instruction: set the volume of a sound effect
Pt Sam Volume volume
Pt Sam Volume voice,volume

This instruction sets the volume for the following sample replays. The 'volume' parameter must range from 0 to 64.
If you specify the optional parameter 'voice', the command only has effect on the currently played sample, but not on the following samples.

instruction: change the replaying speed of a sample
Pt Sam Freq chan,freq

This command changes the frequency of the sample currently being played on channel chan to the new frequency in freq.
If no sample is currently played on this channel, it will have no effect nor will it have effect on the protracker music.

function: return the current vumeter value
vol=Pt Vu(channel)

This command allows you to read the current volume of channel number 'channel'.
If a new note is played, 'vol' contains the volume level else 0.

function: check for signals from the music
signal=Pt Signal

The various music trackers Soundtracker, Noisetracker, Startrekker or Protracker feature effect commands e.g.
To change the volume of a note, or for portamento. Example for a Protracker noteline:

00 C-1 1000 --- 0000 G-2 2000 --- 0000
   ^ ^ ^
   | | `-----------------------------------------------.
   | `---------------------.                           |
   `--------------.        |                           |
   Plays the note C in the 1st octave using instrument 1.

Additionally, you can use effects, e.g like in this line here:

00 C-1 1C20 --- 0F04 G-2 2E00 --- 0801
        ^^^      ^^^      ^^^      ^^^
Set $20  Speed  Filter Off  \|/
         (=32)  4 VBLs              Y

Now this is an effect, which is unused in all trackers. It has been left free to synchronize various events to the music.
The value behind the '8' is directly transferred to Pt Signal, when the music reaches the specific point.
Warning: The value used in Protracker is entered as hex number.

With this technique you can wait for a special acoustic signal, or sync some kind of musician bobs to the music.

If there is no signal waiting, zero is returned in the variable 'signal'. After using Pt Signal, the old signal will be cleared.
Pt Signal can only keep one value at once, i.e if the last value hasn't been read out, the next signal will overwrite the last one and is therefore lost.

If the end of the music is reached an $FF signal is sent automatically.

function: return the current song position
songpos=Pt Cpattern

This function returns the current pattern/song position.
This can be used to restart a song at a given position when you stopped the music with Pt Stop.

function: return the current pattern line
row=Pt Cpos

This function returns the current 'row' of the songs current pattern. The returned value is a number between 0 and 63.

function: return the current instrument being played
num=Pt Cinstr(chan)

Pt Cinstr returns the instrument being played on music channel chan. num is therefore a value between 0 and 31.
A value of 0 tells you, that no sample has been trigged at that very moment.

function: return the frequency of the current instrument
num=Pt Cnote(chan)

Pt Cnote returns the frequency of an instrument being played on music channel chan at that very moment.

function: return the address of an instrument
address=Pt Instr Address(instnr)

This command returns the starting address of the music instrument with the number 'instnr' of the current Protracker module.

function: return the length of an instrument
length=Pt Instr Length(instnr)

This command returns the length of the instrument 'instnr'.

function: return the address of the pt-database
address=Pt Data Base

This command returns the starting address of the internal data table of the protracker replay routine. Please don't write into this area randomly.