
............................................ Slixter proudly presents .....
 
                         d e M O D i f i e r    v 1.0

............................................................................
                              because nostalgia is a terrible thing to waste
                             
What is this?
------------
deMODifier converts SoundSmith music files into ScreamTracker 3 modules.


Why?
---
SoundSmith was arguably the most popular music authoring tool for the
Apple IIgs.  Introduced in the IIgs's heyday (which was, accurately 
enough, just about one day), this software inspired the creation
of countless numbers of IIgs-specific tunes, several of which were 
actually worth listening to.  

Alas, as years passed and the Apple was overshadowed by newer computers,
people started to forget the meaning of the 's' in IIgs.  (The 'g' now
stood for "Gee, I wonder if I put my IIgs in the closet or the garage?")
The music which enraptured a generation of computer users was locked away
on dusty hard drives, hard drives which were never to see +5 volts again.

However, in the PC world, digital music lived on.  The MOD format, once
derided for its pitiful four-channel restriction, grew and expanded and
blossomed and flourished to the point where it eventually became powerful
enough to describe music of IIgs-caliber.  The most popular MOD variant
was (and is) .S3M, the ScreamTracker 3 format, which was developed by
Future Crew, who were sort of the PC equivalent of the FTA, more or less.

ScreamTracker 3 modules can be played with any modern MOD player worth 
its bits (including Winamp with the excellent Nullsoft Module Decoder
Plugin), and can be edited with a number of trackers (including Impulse
Tracker and (duh) ScreamTracker 3).

So, if you, say, hypothetically speaking, had some sort of way of
converting your old SoundSmith music into ScreamTracker modules, you could
then play and even edit them on your current computer.  Wouldn't that be
nifty?


Installation for Windows Users
------------------------------
deMODifier is a command-line utility.  That means that in order to use it,
you have to type in the name of the program at a command prompt.  That
means that the program should be in your PATH.  If you don't know what
that means, just copy "demodifier.exe" into your C:\WINDOWS folder and
everything will work out nicely.


Installation for UNIX Users
---------------------------
I have compiled and run deMODifier under Linux, Digital UNIX, and SunOS,
and it'll probably work under most other UNIX-ish operating systems.

1. Make a new directory and untar the archive into it.  The directory should
   now contain a bunch of .c and .h files, as well as this readme.txt.
2. Type "gcc -O2 -o demodifier *.c" without the quotes.  You can even throw
   in -Wall if you are the paranoid sort. 
3. Move the "demodifier" executable to wherever you want it, and delete the
   directory you created.


How to Use
----------
Type "demodifier" without any arguments to get the formal usage info:

   usage: demodifier [options] soundsmithfile [...]
   optional command line switches:
            -n SONGNAME       title the next song SONGNAME
            -o FILENAME.S3M   write the next song to FILENAME.S3M
            -v                verbose; talk while processing files
            -V                very verbose; talk a lot
   You can list multiple SoundSmith files to be converted at once.
   Wildcards are supported, even under Windows. 
   Make sure the necessary instrument file(s) are in the same directory
   as the SoundSmith file.

Basically, type "demodifier" followed by the pathname(s) of some SoundSmith
song(s), and it'll convert them to .S3M files.  As it says, make sure you
have the necessary instrument files.  This could either be a single
DOCRAM wavebank (usually the same name as the SoundSmith file, with a
".D" or ".W" suffix), or individual ASIF instrument files.

Interestingly, the resulting .S3M files are almost always smaller than
the sum of their parts, so unless your SoundSmith songs share a lot
of instruments, you can even save some disk space by converting them.

The -V option will list any patterns in the file that are not actually
used in the song, so you can later load it into your favorite tracker
and hear the music that you were NEVER MEANT TO HEAR.  If you are into
that sort of thing.


Usage Examples
--------------
demodifier BunnyTune
    produces the file "BunnyTune.s3m".

demodifier -v *.mtp
    converts all SoundSmith files with a .mtp suffix, and lists each one.

demodifier -o lambda1.s3m song1 -o lambda2.s3m song2 -o lambda3.s3m song3
    converts SoundSmith files "song1", "song2", and "song3" into
    "lambda1.s3m", "lambda2.s3m", and "lambda3.s3m" respectively.

demodifier -n "FTA - Modulae" modulae -n "FTA XMAS Demo - Gifts" gifts.mtp
    produces "modulae.s3m" and "gifts.s3m", which will display the proper
    song titles when played with a MOD player.

demodifier *
    exceptionally lazy way to convert all songs in a directory.  
    Non-SoundSmith files will be detected as such and skipped over with
    a harmless error message.


Accuracy
--------
SoundSmith effects other than volume and tempo are not implemented.  (This
includes pitchslide, arpeggiato, portamento, and other strange-sounding
words.)  However, most SoundSmith players did not implement these effects, 
and extremely few SoundSmith songs make use of them.

SoundSmith allowed blank instrument entries -- if the instrument number for
a note was set to zero, it would use whatever instrument was previously
played on that channel.  Most MOD players do not support this, so deMODifier
fills in blank instrument entries with what it thinks are the correct
instruments.  Unless your SoundSmith song is doing some really weird stuff
(REALLY weird stuff), this should almost always work correctly.  You can
disable blank instrument filling with the secret "-b" option, but most MOD
players will not play the resulting file correctly.

Everything else should work pretty well.  Every song I've tried converting
has sounded perfect, but then again I don't have an especially large
collection of SoundSmith songs lying around.  If your .S3M file sounds bad,
it could be your player.  I recommend Winamp.


Alternatives
------------
Ian Schmidt (http://home.cfl.rr.com/ischmidt) provides "MegaTracker Player",
which is a standalone SoundSmith player as well as Winamp plugin.  On my
computer, the player suffers from poor sound quality and the plugin causes
lockups, but you may wish to try it out for yourself.

Incidentally, back in the day, Ian created a IIgs program called "MODifier"
which translated MOD files into SoundSmith songs.  "deMODifier" essentially
does the reverse...  hence the name.


Guilt Trip
----------
deMODifier is freeware.  You may use and distribute it as you see fit.
You may also steal parts of my source code for use in your own nefarious
schemes.  (Proper credit is requested, notification would be nice as well.)

However, donations are welcomed, since it would be nice to eat once in a
while.  You can mail money (or anything else you would like to donate) to:

   Bret Victor
   1406 Navellier St.
   El Cerrito, CA  94530

Or, you can send a PayPal payment to bret@ugcs.caltech.edu and you
don't even have to get up from your computer.


About the Author
----------------
Bret Victor is 24 years old, which should have been plenty of time for
him to figure out what to do with his life.  The fact that he hasn't
worries his parents.  He has graduated from electrical engineering
departments at UC Berkeley and the California Institute of Technology,
so he supposedly knows a thing or two about something or another.  He
has a website:

    http://www.ugcs.caltech.edu/~bret

which attempts to bestow some significance on his mundane accomplishments.
Back in the day, he wrote thirty or so programs for the Apple IIgs, all of
which are available for download from his website.

His email address is:
 
    bret@ugcs.caltech.edu

He knows you aren't going to send him any e-mail, but man, he sure would
like it if you did.


............................................................................
 copyright (c) 2001  Bret Victor, and the picture he would paint...

