___   ___          _____         ____
        |\  /| /   \ |   \   |   |   |   | |    (
        | \/ |(     )|    )  |   |   |   | |     ¯-_
        |    | \___/ |___/   \___/   |   | |___ ____)

	      The ModUtils package consists of
	   ModPlay, ModRip, ModAlloc and ModWipe
		   which were written by
		       Ben Hutchings
		      and released in
		      September 1994




LEGAL


The contents of this package are the files:
    InstallBB, InstallBBWB, InstallBBWB.info, ModAlloc,
    ModAlloc.BB, ModAlloc.info, ModPlay, ModPlay.info,
    ModRip, ModRip.info, ModUtils.doc, ModUtils.doc.info,
    ModWipe, ModWipe.info.

These files are all copyright (c) Ben Hutchings 1994, but
they may be freely distributed provided
(i)   no charge is made for them above the costs of
      duplication, distribution and the media used,
(ii)  all the listed files are kept together, and
(iii) the files are unaltered.
The exception to (iii) is that the files may be distributed
in a compressed form as long as the original files can be
retrieved from this form unchanged.

Software released under these conditions is often known as
Freeware.

The included file reqtools.library was written by Nico
François, who owns the copyrights to it. Although it is part
of the package it may be copied separately.

I reject any responsibility for any undesirable consequences
whatever of the use of this software. This includes, but is
not limited to, secondary consequences, personal injuries or
other kinds of side effects.



INTRODUCTION


I wrote these programs after finding my existing module
software inadequate and out-dated. I hope you find them as
useful as I have.

If you are familiar with music modules, skip to the
documentation for the individual programs. If not, read on.

Music modules are files containing descriptions of one or
more sounds and a list of notes and effects to play with
them. One of the earliest programs to produce music modules
was Soundtracker, which produced simple files containing
sampled waveforms (that is, digital records of real instru-
ments and noises) plus a number of blocks of note codes, and
a list defining the order they should be played in (so that
blocks could be repeated).
Then a program called Noisetracker was released which had
added features and used roughly the same file format, so
that it could read in modules produced by Soundtracker.
Since then numerous improved versions have been produced
and Soundtracker has been replaced by Protracker. Despite
all these changes the file format has remained the same
except that extra codes for the new musical effects have
been added. So there are huge numbers of modules out there
which can all be handled by the same player program. Not
only this, but the same file format is also supported by PC
and Archimedes programs among others. A friend of mine has
about 100 modules of this type on a PC CD-ROM. If you have
DOS2DOS, MessyDOS, or CrossDOS (supplied with all Amigas
since late '92) then you will be able to use these modules
as well as those on normal Amiga disks!
Many demos and games use Soundtracker or compatible modules
because it is much easier to use a standard program to make
music than to write a special routine for each tune. So if
you can get the module out of the game (a process known as
'ripping') then you can listen to your favourite game tunes
while doing something else like word-processing or writing
a program (the player will continue to work even if you're
running AMOS). I should add at this point that ripping is
sometimes illegal and that copying a ripped module will
almost always break the license agreement for the software
you got it from. Check the appropriate license if you are
in doubt.
The limitation of ripping is this: unless you have an
Action Replay cartridge, you can't actually stop the game
while its running and rip out data without disturbing
anything. Nevertheless, I have found this ripper software
to be very effective.

So there's your quick guide to modules. Read on to find out
how to use the programs in this package.



INSTALLATION


I do not recommend installing any of these programs onto
another floppy disk (with the exception of a method
explained later on for temporary use only).
To install the programs ModAlloc, ModRip, or ModWipe to
another disk, you must simply drag their Workbench icon to
the other disk.
ModPlay and ModPlay13, however, need a library file to
accompany them. To install this:

· Boot from your hard disk.
· Open a Shell/CLI.
· Enter 'List LIBS:'. A list of libraries already installed
  will appear. If the name 'reqtools.library' appears then
  you do not need to proceed, and you should enter 'EndCLI'
  to close the Shell/CLI. Otherwise, continue...
· Insert the disk this text is on.
· Change the current directory to the directory this text is
  in - you will have to type something like
  'CD DF0:ModUtils'.
· Enter 'Copy reqtools.library LIBS:'.
· Enter 'EndCLI' to close the Shell/CLI.

You can then drag the ModPlay or ModPlay13 icon to wherever
you want it on your hard disk, and it should run from there.



MODPLAY


ModPlay is a simple module player based on the Protracker
playroutine. The advantages it has over other module
players are these:

· It's very small.
· It can be made resident in memory for Shell use.
· It can stop music automatically instead of looping.
· It uses ReqTools (thanks to Nico François).
· It uses reliable CIA timing so the speed is correct
  whatever screenmode you are using.
· You can stop or change the music being played simply by
  running ModPlay again.

There are two versions of ModPlay supplied: the one called
simply ModPlay is for machines with OS 2.0 or above; the
one called ModPlay13 is for those with OS 1.3 (or lower).
Except where noted, the following information applies to
both versions.

One of the reasons I had for writing this was for use in
disk magazines (I was hoping to produce one myself but
that will have to wait). Although it can be run from
Workbench, ModPlay is designed for control by Shell
commands and especially by scripts.

Note that you MUST have reqtools.library version 38 or
better in your LIBS: directory to run it. Version 38 is on
Fred Fish disk 794; I have a more recent revision than the
one on that disk but I don't what disk it came from.

Before I go on to explain usage, I should mention that
ModPlay is very picky about the size of the modules it will
read.
For the technical bods: When it loads a module it will
first read the header to check for the Soundtracker ID
('M.K.'). Then it will add up the sample sizes and compare
them with the size of the rest of the module. If the length
of the song data isn't a multiple of 1024 (the size of one
block) it will complain. Now by my calculations the size of
a module should be 1084 + blocks*1024 + sample_size, and so
anything which fits this pattern will load in OK. However I
have come across a few modules which don't fit this formula
and which consequently are rejected by ModPlay as a safety
measure.
Please tell me if one program consistently saves modules
which won't load in because I could well have my facts
wrong - my address is at the end of this document. I have
got all my specifications simply by using hex editors on
modules and by reading the Protracker playroutine source
code (which I spent hours updating and turning into a
readable piece of code which will link properly!).


Shell usage:

To start playing a module, or to change the music already
playing, type

    ModPlay <module_name>
or  ModPlay <module_name> LOOP

where <module_name> represents the name of the module, and
LOOP is an optional switch which disables the anti-looping
feature of ModPlay.

To stop the music prematurely, or to stop a looping piece
of music, type

    ModPlay STOP

To use a file requester to start/stop music, just type

    ModPlay

then pick a module or click Cancel to stop. The requester
will keep coming back when each piece of music finishes,
until you click Cancel.
If you are using the 2.0 version of ModPlay you can specify
multiple modules on the command line or in the file request-
er (using Shift-select).
In the 2.0 version you can also stop a single module by
pressing Ctrl-C, or you can completely exit the program by
pressing Ctrl-D. If ModPlay is running in the background you
can use the Break command to do this (see your Commodore
manual for information about this).

NOTE: If you use ModPlay in a script for a disk magazine or
      similar, you will need to run ModPlay in 'background'
      with the Run command. If you want to put something
      like
	  ModPlay intro.mod
      in a startup-sequence, e.g.
	  Echo "Welcome to XYZ disk magazine issue #5!"
	  ModPlay intro.mod
	  LoadWB
	  EndCLI >NIL:
      you will actually need to use the command
	  Run >NIL: <NIL: ModPlay >NIL: <NIL: intro.mod
      otherwise the Shell window will just stay on the
      screen and do nothing until the music finishes.
      If ModPlay is asked to STOP and there isn't actually
      any music playing, it will return code 5 (WARN) in
      case you want your script to check for this.
      Obviously if something else goes wrong it will return
      code 20 (FAIL) which will terminate your script unless
      you use the Failat command (see your Commodore manual
      for details) to prevent this.


Workbench usage:

If you are using the OS 2.0 version, there are three poss-
ible ways to start ModPlay from the Workbench.

1. If your modules are saved with icons, you can set their
   default tool (using the Workbench 'Information' function)
   to something like 'SYS:utilities/ModPlay' (assuming that
   you have installed ModPlay in the 'utilities' drawer of
   your hard disk. Then, when you double-click them they
   will be played using ModPlay.
2. If your modules have icons, you can use extended
   selection to play them. What this means is, select the
   first one, then hold down Shift and select any others,
   then (keeping Shift held down) double-click ModPlay's
   icon.
3. Double-click on the ModPlay or ModPlay13 icon. A file
   requester will appear. Select the drawer your modules
   are stored in. Then select a module and click OK. In the
   2.0 version you can select as many modules as you want
   using Shift-selection.
   The requester will re-appear when the module(s) stop.
   You can then stop by clicking Cancel or select a
   module or modules again to go on playing.

Method 3 is the only one which works with the 1.3 version of
ModPlay.

You can stop a module which is already playing before it
ends by starting ModPlay from its icon and clicking Cancel.



MODRIP


ModRip is a simple module ripper. This means it is designed
to identify any Soundtracker or compatible modules in
memory, calculate their size, and save them to disk. It
should be completely system-legal as it only reads memory
within the bounds of the blocks listed in Exec's MemList.
If you are using Enforcer you might get thousands of 'hits'
although I don't know since I don't have Enforcer and I'm
not sure quite what it does. Please tell me if this occurs
so I can put a warning in any future documentation - my
address is at the bottom of this document.

It isn't 100% reliable as most games and demos bypass the
operating system and so are liable to have their data
corrupted (i.e. destroyed) in the period between exiting
the program and running ModRip. Also some games intercept
keyboard resets and clear their data in memory to prevent
ripping. Besides which, not all game music will be stored
in Soundtracker format. Note that I have also produced a
ripper for MED modules which may be on the same disk as
these utilities.

The effectiveness of ModRip can be improved using ModAlloc
or ModAlloc.BB	(see below).

Please note that the use of ripper programs of any kind may
break the copyrights of the producer of the original
material, and duplicating ripped modules will almost
certainly do so. Refer to your license agreement if in
doubt.


Shell usage:

To begin searching for modules, type

    ModRip

and wait. When a module is found, brief information about
it will be displayed in the window. If this is gibberish
then don't bother saving it - most modules contain some
meaningful text which you will be able to read. To save the
module, type in a filename - e.g. DF0:NiceRayTracedDemoTune
- and press Return. To skip it, just press Return.

When the search is finished, a Shell prompt will reappear.


Workbench usage:

Double-click the ModRip icon.
When a module is found, brief information about it will be
displayed in a window. If this is gibberish then don't
bother saving it! Most modules contain meaningful text
which you will be able to read. To save the module, type
in a filename - e.g. DF0:NiceRayTracedDemoTune - and press
Return. To skip it, just press Return.

When the search is finished, the window will disappear.



MODALLOC


This program installs a special 'KickTag' which is run
immediately after any reset. The KickTag code will find
any Tracker modules in memory and allocate the memory
they use so that they are protected from being written
over. This means that you can rip many modules which you
might otherwise not be able to.

To run it, simply double-click the ModAlloc icon or run
ModAlloc from the Shell. A message will appear telling
you to reboot when ready. This means that you can now
run whatever program/game/demo you want to rip music out
of, then reset the computer when the music you want is
playing.
Once ModAlloc has been run, every time you reset, the
screen will start to strobe slowly. At this point you
should press the LEFT mouse button to start searching
for modules or the RIGHT mouse button to bypass this and
reboot normally.
If you press the left button, the screen will immediately
turn red. If and when a module is found it will turn blue
until it finds the end of the module, when it will briefly
flash yellow. This may happen several times. Unfortunately
the routine seems to get stuck sometimes (I don't know why):
the process should take a maximum of 5 seconds for each
megabyte of memory switched on; if it takes much longer than
this, press the RIGHT mouse button to exit.
Once the procedure has finished or you press the right mouse
button to exit, the computer will boot up as normal.
You can then run ModRip to rip the modules as described
above.

Note that some programs may completely tear down the
operating system, which means the 'KickTag' code will no
longer be found and will not operate when you reset. In
this case you can use a slightly less effective method
of protection:

I have included a special bootblock which you can put on a
floppy disk along with the ModRip program which does the
same thing as the ModAlloc 'KickTag' code.
Format a standard disk (not a high-density one) then put
this disk in and double-click the InstallBBWB icon. You will
be asked to insert a disk to be installed. Insert the
formatted disk in the INTERNAL DRIVE and press Return.
From here on I will refer to your formatted disk as 'Empty'
which is what the Workbench will call it.

The ModAlloc bootblock works much the same as the ModAlloc
code. However, it is loaded rather differently. What you
must do now is to copy ModRip to Empty by dragging the
ModRip icon to Empty's icon. If you have only one disk drive
you will first need to insert Empty and open it's icon to
make sure that it stays on the screen. Once you have copied
ModRip, Empty is complete.

To use Empty, first turn off all unneeded drives, then reset
the computer and run the program/game/demo you want to rip
music out of. Then reset again and quickly insert Empty in
the internal drive (do NOT wait for the nice picture of a
disk). The ModAlloc bootblock will run just as the ModAlloc
'KickTag' code (described above) does.
When it has finished, you will be left with a single window
on the screen titled 'AmigaDOS'. Now type 'ModRip' and press
Return. ModRip will load and run as normal. You will have
plenty of space on Empty to save modules (as its name would
suggest!).



MODWIPE


This tiny utility just wipes out any modules in memory so
that they are invisible to the ModAlloc 'KickTag' code and
bootblock and so won't take up any valuable memory. It will
then reboot, freeing all memory and allowing you to restart
with all your memory available.

It will take a little while before it resets to check all
through memory - a maximum of 5 seconds for each megabyte of
memory switched on. During this time nothing will seem to
be happening - this is normal.

WARNING: Before running ModWipe you should ensure that any
data you are working on is saved to disk, and that all disk
access has stopped. Otherwise you could lose your work or
worse still corrupt a disk!

Shell Usage:

    ModWipe

Workbench usage:

    Double-click the ModWipe icon.



ACKNOWLEDGEMENTS


I owe the main player routine mainly to Lars 'Zap' Hamre
and Amiga Freelancers - and if you're out there somewhere,
please, please, can I have a well-commented up-to-date
routine because this one dates from 1991 and I had to spend
months hacking at it just so that I could understand it,
after which it needed a number of enhancements to handle
the modules I threw at it. Mind you, I'm not much good at
writing in assembly language anyway and custom hardware was
a complete mystery to me before I read this code.
Thanks also to Nico François for reqtools.library and its
excellent documentation, which is, like the library itself,
freeware.



WRITE TO ME!


Please write to me if you have any comments, suggestions,
bug reports or programming hints to make. I would especially
like to hear from anyone who can supply
   · some 'official' tracker specifications
or · a new playroutine (I am currently using a modified
     version of Protracker 1.1B VBlank)
or · any reports of Enforcer hits (well I don't exactly
     want to hear these but if there is a problem I ought
     to know)

My address (Snail mail only, sorry!) is:

		Ben Hutchings
		43 Harrison Close
		Reigate
		Surrey RH2 7HS
		ENGLAND