
System PlayTrack version 1.06 Mk II
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 David J Seery 1993

Licence agreement
-----------------
In common with all my software, this program and its associated documentation
and support programs are legally classed as Freeware which means that
although I retain copyright the software may be freely copied and distributed
providing that certain conditions are met.  These conditions are:

        o       The name and address given at the end of this file
                should not be changed.
        o       The copyright messages in the program and documentation
                should not be altered or removed.
        o       No one should make any financial profit out of
                distributing the software.

It should be pointed out that !PlayTrack is *not* Public Domain as this term
means that the author gives up all rights over the software.

The author asserts the moral right to be identified as the author of this
software, and reserves the right to change the conditions of this licence
at any time without prior notice.

Disclaimer
----------
This software is provided "as is"; no warranty, express or implied, is given
as to the merchantability of this software or its fitness for any given
purpose.  No responsibility can be taken by either the author or any
distributers of this software regarding loss of time, data, profits, staff,
media, or anything else due to the direct or indirect use or misuse of
this software.

Although the software has been tested thoroughly it should be said that the
testing was carried out on a base model machine - an A310 with a single
floppy and Risc OS 2, with 1Mb, so no guarantees as regards multiscan
monitors, Risc OS 3, A4s etc., can be made.  However as !PlayTrack does
everything legally it should work on any configuration.

-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

Introduction
------------
!PlayTrack was written to fill a gaping hole in Archimedes SoundTracker
(and Tracker) playback routines: there are virtually no players around that
can give the (experienced) user analysis and details on the Tracker module
being played, while allowing a more basic user to use the software at a
simpler level.

!PlayTrack was written with the object of achieving both of these goals and
in its present incarnation is a fairly good player but it should be noted
that you can't actually write or score music with !PlayTrack: only playback
what somebody else has actually written.

The controls provided by the system are deliberately like a cassette or
video recorder: fast forward, rewind, pause, stop, and play, all are
supported along with a (crude) volume control.

In this document, we will examine the menu that !PlayTrack provides
(there is only one main menu: the iconbar menu) and then each window in
turn, explaining its features and how to use it, and perhaps at this point
it would be advantageous to list the features that !PlayTrack provides.

        o       Rewind, Pause, Stop, Play and Fast Forward
        o       Pattern position counter
        o       Internal speaker toggle
        o       Mute button
        o       Volume control
        o       Module and tune statistics
        o       8 channel playback and stereo positioning
        o       Independant stereo
        o       Detailed samples list
        o       User controlled tune buffer
        o       A variety of user preferences
        o       A machine code redrawn 8 channel vu-meter
        o       Display sample waveform and hear sample
        o       Cathode Ray Oscilloscope display
        o       Tune monitor
        o       Save tune as Relocatable Module

This is, of course, only a brief list.

1.1 The Main Menu
-----------------
The main menu is accessed from the iconbar and contains the entries
Info, Open, Save, Stop, and Quit.  The first and last are largely self
explanatory and are the standard Risc OS functions of this type.
Open leads to a menu with 10 entries which allows you to open any of
!PlayTrack's windows.  A keyboard short cut is also listed opposite each
item.  The Save option leads to a dialogue box which will be explained in
the section on saving a tune as a relocatable module; Stop halts the current
tune according the the user preferences which are set in the Preferences
dialogue.

The menu is fairly short as !PlayTrack's main features are accessed from the
windows, and so it is to these that we must turn out attention.

2.1 The Control Window (Shift-F1)
---------------------------------
Along the top of this window are the five control icons for controlling the
tune currently playing; below this is a position counter showing the current
position (left) and the total number of positons (right).  Opposite this
the tune name is displayed when one is playing.  Two toggles control the
state of the internal speaker and the mute condition.  When the mute toggle
is on, no sound is played, but when it is off (the normal condition) sound
is buffered normally.  The red bar at the bottom of the window is the
(crude) volume control, however for some unknown reason the sound tends to
get "scratchy" as the volume decreases.  I'm working to fix this but I
can't seem to get anywhere.  Ideas, anyone?

The control window is opened automatically when a tune is loaded.

2.2 The Tune Information Window (Shift-F2)
------------------------------------------
This window is "static" which means it merely provides information about
the tune and the user cannot interact with it.  The window lists the
filename of the tune, and its size (both in bytes and kilobytes); the
number of voices, patterns, and its speed; the tune name and its author;
and the instruments and format it is in.

The tune information window is opened automatically when a tune is loaded.

2.3 The Stereo Positioning window (Shift-F3)
--------------------------------------------
This window affords the user overall control over the stero positioning.
Unlike a lot of playback programs, and the poor Amoeba, !PlayTrack allows
full 8 channel independant stereo (for tunes that use 8 channels!).
Channels 1 to 4 are displayed along the top, with channels 5 to 8 at the
bottom of the window.  Each channel can have 7 positions within its
predetermined range; alter this by clicking on the left or right arrow on
the appropriate side of the stereo positon display.

!PlayTrack is the only SoundTracker playback routine that I know of (in the
PD) that has "sophisticated" facilities (that is, it isn't just a front end)
that can handle 8 channel trackers.

2.4 The Samples Window (Shift-F4)
---------------------------------
This window allows you to view all the samples that a tune uses, but like
the tune information window it is static and therefore non-interactive.
The information listed for each tune is its number, name, volume, and
length.

2.5 The Buffer Control Window (Shift-F5)
----------------------------------------
!PlayTrack maintains a buffer in RMA (the Relocatable Module Area) into
which it loads tunes to be played.  The advantage of this mechanism is that
the tune is assured of workspace in which it can be played.  This might
not be available were !PlayTrack not to maintain this buffer.
The major disadvantage is that the buffer has to be as large as your
largest tune, and it is therefore not sensible for me to set the buffer to,
say 400k (as big as my biggest tune) if the largest you have is 128k.

The buffer is therefore "dynamic", this means that you can alter it during
the life of the program, although not, for obvious reasons, while a tune
is playing.  To alter the size of the buffer, type the number you want
into the writable icon at the top of the window and either press return
or click on the "Intialise Buffer" bar.  This bar will slab in and the size
of the buffer will be adjusted.  You can save this permanantly from the
Preferences window.

Also displayed in this window is a "used" and "free" section so you can see
how much you need to alter the buffer by, if need be.

2.6 The Preferences Window (Shift-F6)
-------------------------------------
This window allows you to specify your own personal preferences to set
!PlayTrack up to your way of working.  The options available are:

        o       Load and Play
                If set, after loading the tune will play.
                Default: On
        o       Set clock rate
                If set, the sound system DMA clock will be set to the
                value in the writable icon on startup.
                Default: Off
        o       Delete track on Stop
                If set, the track will be deleted when stop is clicked,
                otherwise playing will cease and the counter be reset
                to 0.
                Default: On
        o       Auto filetype as STModule
                Tracker or SoundTracker tunes are available filetyped
                as a variety of types, and it helps if all are a uniform
                type.  !PlayTrack uses &CB6, STModule, as its standard
                format and if this is set, then all tunes will be
                set to this type after loading them.
                Default: Off
        o       Mahoney & Kaktus scan
                If set, the 31 instrument format will be detected by an
                ASCII 'x' character in this file; otherwise a scan
                for the "M.K." string will be performed.  This string
                was introduced by Mssrs. Mahoney & Kaktus when they
                expanded the SoundTracker standard.
                Default: Off

These options can be saved permanantly by clicking the Save icon.  The
buffer size is also saved with the options file.

2.7 The Vu-Meter (Shift-F7)
---------------------------
This is simply an 8 channel vu-meter with no really fancy touches or graphics
but it does it's job.  One of the things to be improved, if I ever get
round to it.  Looks pretty and impresses the boss.

2.8 The Sample Waveform Window (Shift-F8)
-----------------------------------------
This is a useful tool for users who like to tinker, but it has a serious
value as well.  While a tune is playing (or even paused) you can type a
sample number you have looked up in the Samples window into the writable icon
and press return: the waveform for the sample will then be drawn.  It will
be too long to fit onto the screen, so a scrolling window is supplied
instead.  The two vertical lines, if present, mark out the sample repeat
start and end positions.

You can also hear the sample by clicking on the hear button.

2.9 The Cathode Ray Oscilloscope Window (Shift-F9)
--------------------------------------------------
This (tiny) window displays the output from the channel displayed in the
title bar on its rather garish green surface.  Still, that is what CRCs
look like, so who am I to argue?

You can increment the channel number by pressing Select over the window,
and decrement it by Adjust.

2.10 The Monitor (Shift-F10)
----------------------------
This is a bit of a stopgap until I can get a machine code one written,
but it works, and that is the main thing!

3.1 Saving a tune as a Relocatable Module
-----------------------------------------
You can save a tune as a relocatable module be either accessing the save
window from the menu, or via F3.  The two toggle icons allow you to specify
whether you would like the tune to autoplay after loading, and whether you
want any * commands to be implemented.  After setting up your choices,
drag the save icon to a directory viewer and the file will be saved.
After this you just need a copy of the TrackerModule (from inside !PlayTrack)
and you can then "play" the Relocatable Module.

The main use for this, I think, will be for programmers wanting to
incorporate Tracker tunes into their games, but who don't know how.  You
can easily do this using the Relocatable Modules and if you need to pause
or stop the tune, the * commands will allow you to do this.

4.1 The Keyboard Shortcuts
--------------------------
The F key shortcuts are only available if the pointer is in a PlayTrack
window, this is because we don't want to pinch other program's keypresses!
The full list is:

    F1   -   Internal speaker toggle
    F2   -   Mute toggle
    F3   -   Save dialogue
    F4   -   Rewind
    F5   -   Pause
    F6   -   Stop
    F7   -   Play
    F8   -   Fast Forward
    F9   -   Volume Down
    F10  -   Volume Up
    F11  -   Reset (Internal speaker off, mute off, volume to 100%, play on,
                    counter reset to 0)

And for Shifted function keys:

    F1   -   Control window
    F2   -   Tune information
    F3   -   Stereo
    F4   -   Samples
    F5   -   Buffer
    F6   -   Preferences
    F7   -   Vu-meter
    F8   -   Sample Waveform
    F9   -   CRO
    F10  -   Monitor

Pressing the function key for a corresponding window when it is open will
close the window, so it acts like a toggle or flip-flop if you are used
to electronic terms.

4.2 The !Music Directory
------------------------
Also supplied with !PlayTrack is a directory called !Music which is really
a place to put your Tracker files.  You may need more than one if you've
got a lot on floppies.  It keeps your root directory neat and tidy and
looks good too!  Double click it to open up the directory viewer, as usual.

5.1 The End (!!)
----------------
That is about all for this release: I hope you enjoy using the software
and find it useful.
Bug reports, comments (always welcome), ideas (please!), or anything else,
should be addressed to:

  David J Seery
  15 Farm Walk
  Bents Farm Estate
  Littleborough
  Lancashire
  OL15 8LJ

If you want a reply, please include a stamped, self-addressed envelope.
Failure to enclose one may lead to a failiure to reply!
