The Datafile PD-CD 2/DATAFILE_PDCD2.iso/strackers/_aptracker/!APTracker/Version1

Text File | 1993-08-23 | 41.9 KB | 705 lines

                            AP Tracker V 1.00
                           ===================

Use of the Help Facility

This is the in-built help system for APTracker. As with the rest of the
program, it is mouse-driven wherever possible, and its use should be mainly
self-explanatory. Use the up and down arrows in the bottom left to scroll
the text, and the "Exit" box to return to the main editing section. There
is also the "Marked Line" concept. This is a line which, basically, is
shown in yellow to distinguish it from the rest of the text. To jump to the
marked line, use the cryptically labelled "Jump to Marked" box. This will
probably not do anything at the moment, as the marked line is unset. To
set the marked line, you must search for something. To carry out a search,
click in the box which at the moment probably contains lots of full stops in
blue. A cursor should appear, and you can type in the text you wish to
search for (arrow keys, and Insert/Delete can be used). When this is done,
press Return to continue as before. Now, though, you can click on "Search",
and the first line containing the search text will become the marked line.
It may, though, be off the screen, so click on "Jump to Marked" to get to
it. Clicking on "Search" again will search downwards from the marked line
until it finds the next occurrence, and so on. To reset, or rather unset,
the marked line (to facilitate another search) click on "Clear Marked". One
further feature of the marked line is that it may be set manually by the
user. To do this, simply click on the relevant line of the text to mark it.
You will now be able to jump to this line instantly using "Jump to Marked".
Also, this text can be saved as a text file from the desktop, and then
either printed out or read in !Edit etc. if you prefer.

One important thing: there is a lot of text here (believe me, a LOT of text)
and so you may not want to read it all right away. The easiest way to get to
grips with the program is to basically try clicking different buttons on
different boxes on the main screen and see what happens, and by messing
around with existing tunes (though be careful not to overwrite the original
tune by saving your "alterations" to disc). Only when you want more detailed
information should you read this text, and selective use of the search
facility will help you to find what you want more quickly.

The Tracker Music Format

Those already familiar with the system of instruments, patterns, and
sequences should skip this explanation, which is meant for those who have
perhaps not encountered Tracker / Sound Tracker music before.

A piece of Tracker music is composed of several parts. Firstly, there is
a set of instruments (samples) which are used to play notes in the tune.
Secondly, there is a group of patterns, each of which is a collection of
notes, rather like bars in conventional music, though a little longer.
Lastly, there is a sequence table associated with the tune, which tells the
playing routine the order in which to play the patterns. APTracker allows
management of all three sections, with pattern and sequence editors and
facilities for loading instruments into a tune and saving from one (useful
for pinching other people's samples!). Numerically, there may be up to 36
instruments (in fact, there are always 36 instruments, but some may be
blank), 64 patterns in a tune, and 128 patterns in the sequence table.

Just a quick word on file formats. The recognised filetype for this type
of music is &CB6. However this covers Amiga SoundTracker and ProTracker,
which APTracker cannot edit directly, as well as Tracker format (files
starting with "MUSX") which it can. However, a converter is built into the
program, and dragging a SoundTracker / ProTracker file to the iconbar will
produce the message "Convert from Sound Tracker?". If you click on OK, the
tune will be loaded and converted, and will end up in memory the same as if
you had loaded it as a Tracker tune. Inevitably, the conversion will not be
perfect, as the formats vary slightly, but very rarely will the tune sound
any different. However, because "APTracker" can only save Tracker tunes, to
convert any music back to SoundTracker format (for instance to give to
someone with an Amiga), you will have to use Matthew Farrow's PD utility
"GetSTMod", which may be provided with "APTracker". This program will
convert tunes either to SoundTracker or Tracker, depending on the initial
format of the file, and is activated by dragging the relevant file to the
"GetSTMod" iconbar icon.

"APTracker" will also load and convert a few other types of files, Coconizer
Octalyser, and ProTracker type &701. This last type can be played by the
"!ProTrack" playing routine by Bass, but not with the standard playroutines;
until now of course! Coconizer trackfiles and songfiles (types &364 and
&365) can be loaded just by dragging them to the iconbar, though the latter,
of course, will have no samples present. However, Coconizer is a superior
format to Tracker in several ways, and so, again, the conversion will not
always be perfect (and obviously works best with tunes which started as
Tracker format but were then converted to Coconizer). Specifically,
Coconizer can play notes over a 7 octave range, whereas Tracker is limited
to just 3. It is, though, unusual for Coconizer tunes to use any/many notes
outside of the 3 octave range, and so most tunes convert OK. One thing to
note is that pitch slides are likely to come out slightly wrong, so you
should search for these after conversion, and fiddle around with them until
the tune sounds right. Octalyser files must initially have the normal
Tracker filetype &CB6 before they will be recognised. They too will be
automatically converted to Tracker format by "APTracker". However, the
Octalyser converter was written with access to just one Octalyser tune. If
anyone has any Octalyser modules or, better still, documentation, please
send me a copy (the conversion routine ignores most of the commands and just
makes, for example, an Octalyser "L" command into a Tracker "L" command;
which does nothing at all!). My address is at the end of this text.

All of these format conversions require, initially, about twice as much
memory as the actual tune, as the routines need two copies in memory - one
original and one converted. When conversion has taken place, though, memory
usage is returned to normal levels. If you wish to convert a tune over a few
hundred kilobytes, you may find this impossible on a 1Mb machine. If this is
the case, the best way round this is to simply get someone with a 2Mb +
computer to convert it for you, as the resulting converted file will end up
at about the same size as the original. There is no shortage of Tracker /
Sound Tracker tunes available for the Arc, with most public domain libraries
having many hundreds of them (mostly ported over from the Amiga).

Getting Started

You should already be able to load tunes into APTracker, and to access the
(non multi-tasking) pattern and sequence editor; you have to to be able to
read this. The iconbar icon for APTracker allows access to various
information sections regarding the currently loaded module (tune) via the
middle button, and also, with the right-hand button, entry to the main
editing section (which is, after all, what the program is for). By using the
left hand button (Select), a desktop player control panel will be displayed
and from here the tune can be played, stopped, and fast-forwarded or
rewound. Tunes can also be created from scratch, by selecting the "Create"
option on the main menu and choosing the number of voices you want (only
four or eight should really be used here, but you can use any number from 1
to 8 if you want).

The save submenu from the iconbar contains five options. "Tune" will let
you save your newly created works to disc. "Pattern" will allow you to save
just an individual pattern as a Data file. This can then be loaded into
another tune (or, indeed, the same one). "Patterns" is similar to "Pattern",
except that it will save out ALL the patterns from a tune into a given
directory, with filenames determined by the stem (which can be edited),
followed by the pattern number (e.g. "Pattern01", "Pattern02" ...). "Text
Dump" will save a text file about the currently loaded music to disc. You
may choose which information is written to this file, by setting the
relevant boxes on and off. Note that if you set "Patterns" to be on, the
save could well take quite a while, as every pattern is saved, in a format
identical to that displayed in the main editor. Finally, "Help" allows you
to save all this help data as a Text file. From here it can then either be
read using !Edit or similar or printed out.

Before you can start a piece of music, you need to have some instruments
loaded, which will be used to play the notes in the music. To load an
instrument, you must first bring up the iconbar menu, and go to the tune
submenu. Select "Samples", and a large window should open with 36 slots,
1 slot for each possible instrument. Initially, all of these spaces will be
blank (unless you are altering an existing piece of music). To load a sample
for use in your tune, simply drag it from a filer window to the space you
want it to occupy. After a short delay, its name should appear in the slot
(along with its length in bytes) and it can now be used in your tune. Note
that samples can be loaded over existing samples, and samples can be deleted
by moving to the relevant sample, pressing the middle mouse button, and
selecting "Delete". The "Volume" option leads to a window in which you can
set the default volume of that particular sample. 255 is the loudest, and
the scale is logarithmic. This value can be overridden at any time by a tune
with the "V" command, but by using a default value it is possible to make,
for instance, a bass rhythm quieter at a stroke and to hear the effect as
soon as you return to the main editing section. Although the program uses
tracker format samples, several other types can also be loaded (and will be
automatically converted to tracker format when in memory). These other types
are "Armadeus" (filetype &D3C), "DSEdit" (filetype &ED0), and raw sample
information (filetype &FFD; Data). The last of these can have 3 meanings,
linear signed, linear unsigned, or logarithmic. As no distinction is made
between these three types in their filetypes, you must tell the program what
to treat sample files of type Data as. Do this by selecting "Settings" from
the main icon bar menu, which should bring up a window. In this window are
three radio icons, allowing you to specify what Data samples are to be
interpreted as. If you do not actually know what type of sample it is, just
try loading it as all three different types, and test it in the main editing
section (see below) until it sounds right. Samples from "Coconizer" are
logarithmic, by the way, and so if you have lots of these samples, they can
all be used by "APTracker" very easily.

There are also four other options on the tune submenu, "Info", "Stereo",
"Copy", and "Amend". "Info" brings up an information window on the currently
loaded tune, and from this you can alter the music name and author fields
and also add extra patterns to the music (via "New Pattern"). When adding
new patterns to a tune, they will, by default, be 64 events "long" (which is
the standard). However, the length of new patterns can be set by the user,
via the Settings window, mentioned above. Having said this, you should
really stick to length 64 if possible, though "APTracker" allows other
lengths as the file format supports them. In the "Info" window, the sequence
length and number of patterns are also shown (which are not necessarily the
same), along with the length of the file in bytes and its approximate size
in kilobytes.

"Stereo" allows you to alter the default stereo position of each channel;
simply click on the relevant icon. There are seven possible values, 1 being
full left, 4 centre, and 7 full right. Stereo positions can also be set with
the "E" command in a pattern, and the parameter (1-7) has the same meaning.
Irrespective of the number of voices used in a tune, you will always be able
to set a stereo position for all 8 channels. If the music is currently
playing, altering the stereo values of each channel will take effect
immediately.

"Copy" works in conjunction with the "Save Pattern" feature mentioned above.
By dragging a Data file saved with this method to the icon bar, the copy
window should be opened (if it isn't, then the file is not pattern data).
From here, you can then overwrite an existing pattern (perhaps a blank one
you have just created for this purpose) with the one just loaded. In
addition to saving a pattern to disc, you can copy it directly to the copy
buffer (which acts just like you had just saved it to disc and then loaded
it in again) using the "Store" option.

"Amend" allows widespread editing of the currently loaded music, and three
operations may be performed from the "Amend Track" window. The first is
"Delete Pattern". This allows unwanted patterns to be removed from the music
file, which saves memory and disc space. To use this, first set the number
of the pattern to be deleted, then click on "OK". This will mot work,
however if the pattern occurs in the tune's sequence table, as this means
that it is actually used in the tune. If this error appears, then alter the
sequence (see later) to remove all occurrences of the pattern. Individual
voices can also be dealt with in the same way. First, set the operation to
be performed, by selecting either "Delete Voice" or "Insert Voice". Then,
set either the voice to be deleted, or the position at which the new voice
is to be inserted and click on "OK". If all is well, an hourglass should
appear, and the operation carried out. Obviously though, you cannot delete a
voice if there is only one voice in the tune already, and neither can you
insert one if there are already eight present. You should use this feature
with caution, as it will quite happily delete EVERY note on a given channel
throughout the whole tune without a second thought.

The remainder of these instructions deal with the editing section, how to
alter patterns and the sequence, etc., from the main editing screen
(displayed by pressing the right mouse button over the iconbar icon).

APTracker can, at any given time, be in one of four modes of operation,
corresponding to the 2 x 2 block of icons starting with "Play Tune". However
there are some things which are operable in any mode. The set of eight boxes
at the bottom of the screen represent the eight channels, of which any
number may be used by the currently loaded music. The smaller boxes above
them containing "Voice 1", "Voice 2" etc. show the state of the voices, and
each can either be "On" or "Mute". The significance of this is shown when
the tune is playing, and obviously no sound output will be generated from a
voice currently "Mute". To toggle the state of a voice, simply click on the
"Voice x" box which corresponds to it. The large box under "Instruments"
duplicates the samples window in the desktop, though only from the latter
can filing operations be carried out. The currently selected instrument is
shown in yellow in the centre of the window, and the arrows to the left and
right of "Instruments" can be used to alter this selection by scrolling up
or down. Alternatively, you may select a sample by just clicking on its
entry in the list, which you may prefer. Each sample has a Repeat Length and
a Repeat Offset associated with it, and these are shown below the instrument
names. To alter either of these (whose sum cannot exceed the sample length
shown to the right of the sample name) use the left and right arrows next to
the relevant value. To see the effect, go into "Test Samples" mode and try
playing some notes and altering these variables. "Debug" can also be toggled
on and off at any time, via the box showing its current status (just click
in it). Another operation which can be performed at any time is toggling
the keyboard sprite. By default this shows a blank 3-octave range, but by
clicking on it with Adjust (right mouse button), the alternative sprite is
displayed. This shows the equivalent keys for each note, and may be of use
when entering notes via this method (see later (quite a bit later ...)).

"Used" is a rather nice feature (even if I say so myself). It brings up a
page of information on the current tune, and shows how many times each note,
instrument, and command have been used. It is perhaps most useful for
instruments; those with a star to the left of them are those which actually
have some data associated with them, and so if a sample has a star but is
shown not to be used at all in the tune, it is wasting memory and so can be
removed (from the desktop).

The Four Modes of Operation

The first of these modes is "Play Tune", and does just that. The box below
"Edit Sequence" suddenly comes alive with ... well, two numbers actually,
the first being the current position in the sequence and the second being
the maximum position in the sequence. When the end of the tune is reached,
it loops round and starts again from position 1. To stop it playing,
therefore, you have to select another mode. You can also rewind, pause, or
fast forward the tune by clicking in the box below "Edit Sequence" with the
left, middle and right mouse buttons respectively. When in "Play Tune" mode,
you can also access the monitor by clicking on "Monitor", which basically
provides some bars which provide a graphical representation of the tune
currently being played. When paused, you can again move through the tune
using the left and right mouse buttons, but nothing is actually played
until the tune is unpaused by a further click of the middle mouse button.
When a tune is playing, Shift-F12 can be used to toggle between a standard
Tracker-type display of 9 rows of textual note data and a more traditional
musical stave notation. With the latter, however, only one voice may be
displayed at any one time (the one whose name is highlighted in red), and
which voice this is can be altered by pressing Shift plus either the left
or right arrow key.

"Play Pattern" does basically the same thing as "Play Tune", but instead of
playing the whole tune as given in the sequence table, it just plays the
current pattern (i.e. the one given next to "Pattern:" just above the
keyboard sprite). Again, it plays continuously until you select a new
mode of operation. Note that in this mode you cannot return to the desktop
or access the help facility (for good reasons).

"Test Samples" is the default mode of operation as it is the most passive.
Basically, it just allows you to see what the samples in the current tune
(or those you have just loaded) actually sound like. By clicking on the
3 octave keyboard sprite, the relevant note will be played using the
currently selected instrument (which can be altered with the arrows either
side of the "Instruments" box. When you play a note, its textual notation
(eg A-1, D#2) appears in the "N:" window on the left. This should help you
to familiarise yourself with the notation used. Also, when in this mode, the
sample names can be altered by clicking in the "I:" box, and altering the
existing name in the same way as setting up a search (above). As well as
using the mouse to play notes, you can use the keyboard equivalents, shown
by clicking Adjust on the keyboard icon.

Edit Pattern

This is the most important part of APTracker, and is thus necessarily more
complicated. Upon selecting this mode, a white bar cursor will appear at a
certain place in the current pattern (shown next to "Pattern:"). This cursor
covers one note on one voice, and can be moved with the cursor keys. The
note which is shown is displayed in the following format:

                A#2 4 S06

Each of these three parts controls a certain aspect of the note, namely:
      A#2 - this is the actual pitch of the note, and is the same as given
            in the "Test Samples" mode.
       4  - this refers to the instrument on which the note is to be played
            instrument numbers (0-9 and A-Z) are shown to the left of the
            name in the "Instruments" window.
      S06 - This is the effect part, and has two sections, the actual
            command (in this case S), and the variable upon which it acts
            (in this case 6). A table of what each command does is given
            below somewhere (try searching for "Commands").

The three parts of the note which the cursor is over are shown in an
expanded form just above the "Voice 1", "Voice 2", etc. boxes, and each can
be edited. To alter the pitch of the note is easy - just click on the
relevant place on the miniature keyboard shown. The instrument used is
assumed to be the current instrument, though by clicking on the window
which shows the instrument of the current note, that instrument is then
selected, which saves scrolling up and down the instruments window all the
time. The command and the variable can be altered separately using the
arrow icons next to them. For the command, Select will move through all
the possible values one at a time, whereas Adjust will jump between those
which are actually used (some are blank, and are either not used at all or
I don't know what they mean). The variable is a numeric value from 0 to 255
and clicking with Select will alter the value by 1, with the other two
buttons making the value change faster. The complete set of keyboard
controls for Edit Pattern mode are given below:

Arrow Keys      - Move cursor within current pattern
Shift + Arrows  - Move cursor more quickly (up/down only)
Ctrl  + ⇩ / ⇧   - Jump to new pattern
Ctrl  + ⇦ / ⇨   - Alter key selection (see below)
Page Up         - Move to top of current pattern
Page Down       - Move to bottom of current pattern
Insert          - Insert event at cursor within current voice
Delete          - Delete event at cursor from current voice
~               - Clear note of current event
Backspace       - Clear command / variable of current event
Home            - Cut pattern data for current voice
Copy            - Paste copied pattern data into current voice
Print           - Scroll down under special circumstances (see below)
Alt             - Select pattern last playing
Tab             - Store command + variable of current event
Enter           - Place stored command + variable into current event
Ctrl + F        - Find stored command in current tune
Ctrl + I        - Find next occurrence of selected instrument
F11             - Replace Instrument
F12             - Record Mode on/off
Shift-F12       - Toggle stave display on/off

Some of these functions probably need explaining a little more. To the
right of "Voice 8" is a small box containing, by default, "000". This is the
stored command, and offers a quick way of entering lots of identical
commands along with their variables (eg "484"). By pressing Tab, the command
and variable in the event which the cursor is currently over will be
transferred to the stored command box, and from now on, pressing "Enter" (or
clicking with the mouse in the stored command box) will place the command
and variable into the current cursor location. A further function of the
stored command is to search for instances of a given command in the current
tune. This time, only the command part (eg. "V" for set volume) is important
and pressing "Ctrl F" will cause the cursor to move to the next occurrence
of that command in the tune currently being edited. If the cursor remains
stationary, there is no further occurrence of that command. The search
proceeds horizontally along the voices, down the pattern, and through the
patterns in ascending numerical order. As the search works from the current
cursor location, to find all occurrences of a command, move to the start of
pattern 1. Note that you may have to create the command you wish to search
for first, place it in the stored command buffer, and press "Backspace" to
delete it again, before you can carry out the search. "Ctrl I" works
similarly, but is easier to set up. This time, the cursor will move to the
next occurrence of the currently selected instrument (if there is a next
occurrence). F12 is used to toggle "Record Mode" on and off. This allows the
music to be edited in "real-time", which may be useful. When on, notes can
be entered into the music as it is playing, allowing fast alignment of, for
example, drum beats. F11 performs a search and replace on the currently
selected instrument. This is confined to the current pattern, and works by
changing all occurrences of the current instrument to the first character of
the stored command (shown to the right of "Voice 8"). It is possible to
restrict the operation still further, as it is only applied to those voices
within the pattern which are "On" as opposed to "Mute".

A few of the keyboard controls mentioned above perform slightly different
actions when in musical stave display mode (toggled on and off by Shift-F12)
Although the up and down arrow keys may still be used to move through the
current pattern, it is more natural to use the left and right arrow keys,
and you may do this if you wish. To move between voices, Shift plus either
the left or right arrow must now be used. Also, the actual editing of notes
can now be performed using only the mouse. To enter a note using the current
instrument, simply click at the relevant place with the Select mouse button.
Holding down the button allows you to "drag" the note up and down the stave.
You may also toggle a sharp (if available) on and off for a given note by
clicking on it with Menu. Notes may be deleted entirely by clicking with
Adjust. The Tracker format is not really designed to be displayed on a
standard musical stave, and this shows in the translation (all notes the
same length, blank notes shown as rests), and of course stored commands and
variables are not shown except for the one note which the cursor is on.
However, it may prove useful for entering music from a musical stave, or for
the reverse operation - learning to play a Tracker tune on a conventional
instrument. Operations such as insert and delete and marked area functions
act as normal, the current cursor position taken to be the centre of the
stave (the purple/beige note). You may also jump to another point on the
stave by clicking on the relevant number at the base of the stave.

"Alt", select pattern last playing, will allow you to edit the pattern which
was playing when "Play Tune" was last selected. If, for example, you play a
tune which you are writing, and part of it sounds wrong, select "Edit
Pattern" mode, and press "Alt". The pattern which was wrong will then become
the one that you are editing, which may speed up the editing process and
saves you going through all the patterns to find which one is incorrect.

"Print" carries the intriguing description "scroll down under special
circumstances". These "special circumstances" are not really that special
actually - just when you have used "~", BackSpace, or have just entered
instrument / command data with the keyboard. If you carry out any of these
operations while holding down "Print", the operation will be carried out as
normal, but the cursor will be advanced one line; useful if you want to
change which sample a whole column of notes use, or clearing command data
for a certain voice etc.

The Marked Area

There is also another set of keys, f1-f8, which relate to the "marked area".
This is an area of any length covering one voice of one pattern, and is
shown in red during editing. When an area is marked in this way, various
operations can be performed on it. The keyboard controls are:

F1   -  Mark area (hold down and use up / down arrow keys)
F2   -  Clear area (so that nothing is marked)
F3   -  Copy marked area to current cursor position
F4   -  Replicate first event in marked area throughout whole area
F5   -  Decrease pitch of all notes by 1 (eg F#3 becomes F-3)
F6   -  Increase pitch of all notes by 1 (eg C#3 becomes D-3)
F7   -  Create downward volume scale in marked area
F8   -  Create upward volume scale in marked area

Shift + F1 - Go to marked area
Shift + F3 - Swap with marked area
Shift + F4 - Selective replicate

All of the above controls should be self-explanatory, except for f7 and f8.
These create volume scales, ie. series of Vxx commands. The value of xx is
determined by a starting value and a common difference. For example, if the
starting value is 6 and the common difference is 2, the commands will be
"V06", "V08", "V0A", "V0C" etc. The starting value is taken from the value
part of the stored command, and the common difference is taken from the
number of the currently selected instrument (sorry about the awkwardness,
but it was the only way I could think of doing it!). Note that the "Vxx"
commands will only overwrite either blank commands ("000") or other "V"
commands. Commands such as "102" will remain unchanged, and the volume
scale will continue around them. You may find it useful to make a keystrip
showing all these commands (a Draw file of one should be included), though I
have tried to arrange them logically. The Replicate feature works by copying
the event (note, sample, and command data) at the top of the marked area
throughout the whole of it. The selective replicate, on the other hand, just
copies part of the first event; the part highlighted in the keyboard
selector ("A-2 C S06").

Debug

The Debug feature may be of use when editing patterns too. It can be toggled
on and off by clicking on the "Debug" box, and when on it plays the note
that the cursor moved off from, either up or down. This may be of use in
isolating "dodgy" notes which sound off-key, though it should be noted that
it only plays the note and not any of the special effect commands (listed
below), and that it may not play notes at the correct speed. However, having
said that, it is quite effective, and as both Coconizer and AMFTracker have
this feature I thought I'd better put it in!

There is one further feature which can be used in conjunction with "Debug".
This involves the box to the left of "Voice 1" which contains either "One"
or "All", and can be toggled by clicking in the box with a mouse button. If
"One" is selected, then the debug works as described above. If the box shows
"All", however, then when moving up or down during editing, all the channels
will be played, just as when playing the tune normally. This feature also
takes account of the status of each channel, and so set any that you do not
wish to be played to "Mute". It has to be said that the speed of this
operation can vary considerably according to how many notes have to be
played simultaneously (on an Arm 2 at least), but it may nevertheless be of
use during editing. Of course, if you want to hear the whole pattern played
correctly, with effect commands etc., then use "Play Pattern", but the Debug
is useful for smoothing out just groups of notes or areas of patterns. The
"One" or "All" option also has an effect when using "Insert" or "Delete".
If "One" is selected, then they just insert or delete an event in the voice
in which the cursor at that time resides. If the option is set to "All",
though, an event will be inserted into or deleted from every voice.

There is also another way to enter event data; via the keyboard. As the same
set of keys is required for each part of the event, you must specify which
part of the event can be edited using the keyboard. To do this, click either
the left or right mouse buttons in the box beneath "Edit Pattern". The red
indicator should move left or right, indicating the selected part. Now, if
the instrument, command, or variable is selected, then pressing the relevant
key (0-9, A-F/Z) will enter that value in the relevant part of the event to
which the edit cursor refers. Note that each nibble (digit) of the variable
can be edited separately with this method. The keys below can be used to
enter notes of octave 1 (i.e. C-1 to B-1).

  S D   G H J     These keys are laid out in the same arrangement as an
 Z X C V B N M    octave on the keyboard sprite, and produce the same notes.

The other two octaves are dealt with similarly, with octave 2 using the same
arrangement of keys but starting at Q and ending at U, and notes of octave 3
using keys starting at I and ending at "Delete", including "BackSpace".
Octave 3, therefore, produces a keyboard clash, as "Delete" and "BackSpace"
have other functions; "Delete Event" and "Clear Command Data". There are two
ways around this problem, both of which involve using the toggle option to
the right of "Used". This option can either be "N" (notes) or "D" (delete).
If it is set to "D", "BackSpace" and "Delete" have their normal deletion
effects, and the two highest notes cannot be entered using the keyboard
(though they can be entered with the mouse as normal). If, however, it is
set to "N", then these two keys will have the effect of entering musical
notes (A#3 and B-3). The normal operations carried out by the keys can still
be performed though; simply press "Control" in conjunction with them. All
this may sound complicated, but is the result of a very delicate trade-off,
to make entry of notes easy both for those using the mouse and for those
using the keyboard, without sacrificing functionability (if such a word
exists). When entering notes from the keyboard, if there is already a sample
number attached to the current event, it will be left unchanged. If there is
no sample present, however, the currently selected one will be entered;
there is (as far as I know), no situation where a note would be needed but
no instrument number, though the reverse case is valid. As mentioned above,
a full list of which keys produce which notes is available by clicking with
Adjust over the keyboard sprite.

The only other relevant feature is the "Repeat:" value. This is edited
by clicking in the box with either the left or right mouse buttons, and
controls how fast the edit cursor moves up and down. This is useful when
used in conjunction with the "Debug" feature, as if it is set correctly then
the tune can be played at roughly the right speed when moving up and down
the current channel.

If you are creating a tune which runs at a speed other than 6 (the default)
then you are advised to place the relevant speed command (see below) at the
start of each pattern in the tune. This is so that when playing patterns
individually, the playing routine knows what speed to play them. The program
does its best to find the correct speed to play the tune when starting from
somewhere in the middle. However, use of the "J" command (see below) can
confuse it, and so you are advised to put speed commands at the start of
each pattern if you have used "J" at all.

Commands

The commands recognised by APTracker are:

0 - Arpeggio                           Variable: &XY.
    This plays the base note for one VSync, then the base note + Y semitones
    then the base note + X semitones, then the base note again, and so on
    continuously (at least I think it does; its something like that anyway,
    and each hex digit of the variable is interpreted separately).

1 - Pitch Slide Up (portamento up)     Variable: X
    While the note is playing, this makes the pitch increase by decreasing
    the sample period by X. This works on the note currently playing; it
    does not need to have a note value associated with it, and hence the
    pitch can be increased gradually for a number of events, with multiple
    use of this command.

2 - Pitch Slide Down                   Variable: X
    Basically as for 1, but the sample period is increased by X.

3 - Portamento                         Variable: X
    This has a similar effect to commands 1 and 2, but instead of playing
    the note associated with it, the pitch of the note is set as the target,
    and further "3" commands will alter the pitch by "X" in order to move
    towards this target (if X is not specified then the previous value is
    used).

4 - Vibrato                            Variable: &XY
    As with "Arpeggio", the two hex digits are used separately by vibrato.
    The effect produced is that of a warbling note; more specifically, the
    pitch of the note being played is increased and decreased. The first
    digit (X) gives the speed of the pitch change, and the second (Y) the
    size of the vibrato. A sinusoidally varying amount is subtracted from
    the pitch, and X determines the frequency of the sine wave used, and
    Y is the amplitude.

B - Break Pattern                      No variable needed
    This makes the tune jump to the next pattern, ignoring the rest of the
    current one which still has to run.

E - Set Stereo                         Variable: X
    Set the stereo position of the current voice to X (1-7).
    IMPORTANT - DO NOT USE "E" WITHIN A TUNE WITH A VARIABLE OUTSIDE THE
    RANGE 1-7. WITH 0, OR 8 AND ABOVE, THE PLAYER MODULE WILL CRASH AND THE
    CURRENT TUNE WILL BE LOST. YOU HAVE BEEN WARNED.

G - Volume Slide Up                    Variable: X
    Adds X to the volume every VSync.

H - Volume Slide Down                  Variable: X
    Subtracts X from the volume every VSync.

J - Position Jump                      Variable: X
    Jumps to the position X in the song (sequence table). Note that although
    "APTracker" shows the sequence as starting from 1, it actually starts
    from 0, and so to jump to what is apparently position 5, use "J04".

S - Set Speed                          Variable: X
    Sets the speed (number of VSyncs between events) to X. The default is
    6 and the fastest is 1.

V - Set Volume                         Variable X
    Alters the volume of the current voice to X (0-255), 0 being silent,
    255 the loudest.

The best way to really find out what each command does is to experiment
with it, perhaps by isolating one voice and using the "Play Pattern" mode -
most of the above I've just copied from the PlayRoutine version 4.09
documentation ...

Edit Sequence

The remaining part of a tune is the sequence table. As mentioned earlier,
this tells the playing routine what pattern to play when. To edit the
sequence table for the current tune, you must be in any mode but "Play
Pattern", and click on "Edit Sequence". This then leads into another screen
on which is shown the current sequence in the form of a long strip, and the
current set of patterns in a rectangular array. There is a cursor in the
centre of the sequence, above which is shown the current position, and two
other active boxes, Insert and Delete. To the left of these is shown the
current sequence length (1-128). To scroll through the sequence, use the
two arrows next to "Sequence", with either Select or Adjust. There will also
be a particular pattern selected out of those shown in the rectangular
array (though this will not be noticeable if there is only one pattern
available). To select a different pattern, simply click on it. Above the
patterns window, there is a box displaying "Occurrences:". This simply tells
you how many times the currently selected pattern occurs in the sequence.
This can be of use in identifying unused patterns for deletion, though this
should only be carried out when a tune is completely finished.

To enter the selected pattern in the sequence table, just click on the place
you want it (you may have to scroll through the sequence table first).
To alter the length of the sequence table, use Insert and Delete. Insert
will insert the currently selected pattern number at the cursor position,
and increase the length of the sequence table accordingly, whereas Delete
will obviously shorten the table. To return to the main edit screen, click
on "Exit".

One further feature which can be utilised in the "Edit Sequence" mode is
selecting a pattern with Adjust (the right mouse button) instead of Select
(the left one). This has the effect of selecting that pattern as normal, but
also inserting it into the sequence. You can, therefore, create a sequence
just by clicking with Adjust on the patterns in the right order. Also, using
the Menu (middle button) to select a pattern here will have the effect of
making it the one currently being edited. By selecting a pattern in this way
and then returning to the main editing section, you can examine, for example
patterns which seem to be used a lot or which are used at the end of the
music.


And Finally ...

There are probably a few things I have left out of these instructions,
either because I haven't put them in at time of writing, or I couldn't be
bothered (writing 40K of instructions is very boring). As always, the best
way is to experiment; my overall aim was to make the program easy to use
but not at the expense of functionality - always a delicate trade-off. I
know the main screen is a bit crowded, but I wanted to use standard Mode
15, as super-wide custom screen modes don't always come out properly on
some monitors (mine for instance). Machine code helps for speed, but means
that the program is a bit disjointed, and tasks which require altering the
memory allocation (adding a new pattern etc.) have to be done in Basic on
the desktop.

Write to me with any bug reports (APTracker has been rigorously(!) tested),
suggestions for version 2, or queries on how to use the program. I would
also be interested to hear any tunes which people have written with
"APTracker". If you send me any music you create (and tell me whether or not
you intend to make it public domain), I will hopefully return your disc with
other people's efforts. One of the aims of writing this program was to
banish forever the "Converted from Amiga" author field, and I'm sure it must
be possible to write good music on the Arc - especially with eight channels.
Anyway, my address is:

          Andrew Pepperell,
          20 Orchard Park,
          Grimoldby,
          Louth,
          Lincs.
          LN11 8TN.

Credits

"APTracker" uses the TrackerModule version 4.09 by Hugo Fiennes, Fabrice
Mercier and Matt Farrow for all the complicated stuff like playing samples
using DMA etc. The version of the module used is, strictly speaking, a
development one though, and so you should not use it or distribute it
yourself to others without permission.

"APTracker" is also aided by two PD utilities by Matt Farrow, "!GetSTMod"
for converting between Amiga format music and the Tracker format which
"APTracker" uses and back again, and "!SampConv" which can be used to
convert Tracker format samples into Armadeus, DSEdit, etc. format. I must
also thank Matthew Farrow for all his comments and suggestions, the most
sensible of which (!) managed to make it into the program.