Muse/2 V1.1 a Os/2 Digital Module Player
November 1995

This program is freeware, meaning it can be freely distrbuted so long as
no files are removed and none of the included files are altered in any way.
If you are going to rip portions of this document then please credit me.

Modules
~~~~~~~
   A Module, in this sense, is a music file format that stores both digital
   instruments and note information. Unlike MIDI files which are soly note
   information and WAV files which are a single digital instrument. Modules
   use a technique known as Wave Table Synthesis or Digital Mixing for play
   back. A more advanced, but similar system is used in most of today's
   synthesisers.

   The result is a reproduction identical to what the origial author intended
   and unlike a digitial recording the size does not grow very large for
   long songs. A 30 minute song could easialy be a mear 300k. Almost all
   of the space in a module file is used by the instruments.

   Instruments in a module are fairly simple, an attack portion which is
   used to simulate the striking of the instrument the sustain portion which
   is used to simulate the way the instrument sounds if it is continuously
   played and in some formats the decay portion which simulates the relase
   sound. On a guitar each portion could sound similar to the following:
      Attack - the fingers striking the strings
      Sustain - The free vibration of the strings
      Decay - the hand hitting the strings to stop the vibration

   The note infomation is organized into channels, each channel can play
   1 note at a time, so the more channels the more notes you can have at
   once.

   Unlike MIDI files which are played in hardware (ie with the FM chip on your
   Sound Blaster) S3M files are played in software.  The DAC (digital to
   analog converter) on your sound board is used to play digital data which is
   synthesised by the program.  Some cards, like the Gravis UltraSound (GUS),
   have a specialized chip onboard which does this same process, but in
   hardware.  Since the CPU must be used to generate the data to be played,
   time is taken away from other programs in the system.  OS/2's multitasking
   allows you to do other things while the song is playing, your system
   will seem slightly slower, that is because data is being streamed to the
   sound card at 44k/s (for 22kHz 8bit playback) and several threads are
   running to manage this transfer.

   Since the synthesis method basically generates the equivilant of a WAV
   file, it has many characteristics of a WAV file, like Sampling Rate and
   bit rate. Sampling rate and bit rate combine to determine how good the
   resulting sound will be. CD's use a Sampling rate of 44KHz and a bit rate
   of 16 bits, this is considered sufficiant to reproduce a wide range of
   sound with good accuracy.

   There are many different formats for modules, a quick list:
      MOD - Original format, from the amiga which had a hardware chip to do
            the synthesis. Many different formats for mods exist, ranging
            from 4 to 32 channels
      STM - Early predecessor to S3Ms, 4 channels, but several enhancements
            on the MOD idea (Scream Tracker 2)
      MTM - A refinement on mods, 32 channels and 16 bit samples are added
      S3M - A format that doesn't look very much like a mod (internally) but
            works in much the same manner. Typicaly called Scream Tracker files.
            16 channels
      XM  - I don't know much about these but from the spec they look VERY
            good, things like volume envolopes and more commands are in this
            format.
      ULT - UltraTracker, 32 channels, multiple effects, and better sample
            definition

   Currently Muse/2 only supports S3M/MOD/MTM

   Some good FTP sites for S3M's are:
      kosmic.wit.com /kosmic/songs
      ftp.cdrom.com  /demos/music/songs/199?/S3M
                     /demos/music/songs/199?/MTM
                     /demos/music/songs/199?/MOD
                     /demos/music/disks
     -- Note, many other file formats are on those sites, make sure you
        get .s3m/.mod/.mtm files (often zipped)

   If you don't have any, I recommend the following songs to get a good
   feel of what S3Ms are.

    Light techno style of music, excellent samples and fairly long songs:
      ftp://kosmic.wit.com/kosmic/songs/95/k_macro.zip (241k)
      ftp://kosmic.wit.com/kosmic/songs/95/k_2deep.zip (183k)

    ftp://ftp.cdrom.com/demos/music/songs/1995/s3m/t/tlgrea.zip (303k)
      Folk type of music

    ftp://ftp.cdrom.com/demos/music/songs/1995/mtm/p/potrm.zip (348k)
      Techno style

    ftp://ftp.cdrom.com/demos/music/disks/1995/l/legacy.zip (1.4 Meg, Many songs)
      Music Disk from Neophyte widely varied.

    ftp://ftp.cdrom.com/demos/music/disks/1995/f/f10_pck5.zip (1.7 Meg, Many songs)
    ftp://ftp.cdrom.com/demos/music/disks/1995/f/f10_pck6.zip (1.9 Meg, Many songs)
      Music Disk from Force Ten, contains rock and jazz styles of music

Muse/2
~~~~~~
   Muse/2 is the first released OS/2 S3M player, it first appeared in the
   Ethos Peripheral Evolution Demo, and had been in beta for at least 2
   months before.

   Because it was originaly used in a Graphics/Sound demo, the goal in
   creating this player was to make is use the smallest amount of CPU
   power possible, and so far that goal has been achived! On my
   486dx50 memsize's CPU load monitor will register the CPU load as being
   18% to 30% (it varies as the song playes) for 22kHz 8Bit playback.

   -- Note to Pentium Users, Muse/2 has not been optimized for the Pentium
   (Compiler is being annoying) and will not run at the maximum possible
   speed. When I can get Pentium optimizations working a fix will be placed
   on hobbes, should be 1.5 to 2 times as fast.

 Installing

   Installing Muse/2 is simple, place all of the files in this archive into
   a directory. If you use it alot then point your LIBPATH and PATH to that
   directory. All of the DLL's must reside in the same location as the EXE.

   You can then test the installation by typing 'mus2tiny -V'
   Eg: (Version numbers may vary)

c:\Muse!2> muse2tiny -V
 Muse/2 Background User Interface V1.1                          Culus of Ethos
Loading Components.
Version Information:
   Muse/2 Digital Mixer (museDACMixer) is Version 1.2
  File Formats:
   Scream Tracker 3 Module (museS3MFormat) is Version 1.2
  Output Methods:
   MMPM/2 Wave Output (museDACMMPM2) is Version 1.0
   DART Wave Output (museDACDART) is Version 1.0
c:\Muse!2>

   There must be at least one Output Method and one File Format. Included with
   this package are the S3M File Format and the MMPM/2 output method.

 Playing Songs

   To play a single file type 'mus2tiny mysong.s3m', but replace mysong.s3m
   with the file you wish to play :>

   Wild cards are accepted, along with list files, for instance
      c:\> muse2tiny *.s3m @favsongs
   Will play all of the S3M's in the current directory and all the files
   listed in favsongs, also in the current directory. A list file should have
   exactly 1 song per line ie:
      Song1.s3m
      Song2.s3m
      Song3.s3m
   List files can included paths as well.

   The song list can be randomized by using the -r option. Also a random
   song from a directory of songs can be loaded and played, by using the
   -r -s pair, ie:
c:\Muse!2> mus2tiny \s3m\*.s3m -r -s
   Will randomly pick a song and play it, exiting after the song is completed.

 The UI

   The user interface is very simple, press 'H' for a description of all
   of the keys. ESC will exit the player

   The default display is the instruments screen which shows the names
   of all of the instruments in the song, often authors write messages in
   the instrument names. Up and Down on the cursor pad will scroll the list.

   [ and ] will change to the next/last song in the song list, while 1-9 will
   change to that song in the list, ie '1' is the first song, '2' is the
   second etc..

Notes about the Components
~~~~~ ~~~~~ ~~~ ~~~~~~~~~~
 S3M Format

   This S3M player supports all of the normal S3M commands.  It does support
   the DMP panning command, which includes surround sound mode!  If you don't
   have a surround sound setup you should disable surround sound mode, or
   surround channels may sound incorrect.

 MOD Format

   The MOD player supports the following MOD types
      - 15 sample modules
      - ProTracker modules (4 channels)
      - NewTracker modules (4 channels)
      - Oktalyzer modules (max 32 channels)
      - Startrekker modules (max 9 channels)
      - unmarked 32 sample 4 channel modules
   All standard protracker commands are supported.

 MTM Format

   The MTM player supports all of the documented MTM effects, as well as
   large samples and 16 bit samples, although I have yet to see a MTM
   that has 16 bit samples, if you have one please email it to me!

 Digital Mixer

   The Digital Mixer supports varying playback frequencies as well as surround
   sound and 16 bit output. The best sound quality can be achived with this
   command line option:
      -o"44k -6" or if you don't have surround sound -o"44k -s6"
   The lowest CPU usage is
      -o22k or if you don't have surround sound -o"22k -s"
   The default is 8 bit 22k with surround sound enabled.

   The output scaling can also be adjusted with by adding the scale % ie:
      -o"22k 300% -6"
   300% is the default. 100% will NEVER clip, but is very quiet. For .cmd
   files and 4OS2 users a # can be used instead of a % symbol.

   If you don't have a stereo sound card this mixer will not work.

 MMPM/2

   MMPM/2 based output does not support the pause command.  Since it does not
   use IBM's new DART system all of the UI commands will take a few moments to
   come into effect.  This is due to the non realtime nature of the MMPM/2
   system.  While you are waiting for a command to change the ouput you can
   still continue to use other commands. Ie hit ] many times to advance
   many songs, the line at the top will display the current song and when the
   song is finally loaded the rest of the information will be filled in and
   the audio will catch up.

 DART

   This is an implementation of IBM's new Direct Audio Real Time system.  To
   use it you muse have the new DART enabled multimedia DLLS.  Currently the
   only known source is the DevCons CD's.  The DLL's are located on disk 3, in
   the directory

     \toolkits\warptlkt\toolkit\beta\samples\entoolkt\audio\daudio\AMPMXMCD.DLL
     \toolkits\warptlkt\toolkit\beta\samples\entoolkt\audio\daudio\AUDIOSH.DLL
   These dlls must be used to replace the existing mmpm dlls, see the readme
   file in that directory for more information.

   DART is used to enhance the stablity and speed for background playing.
   It's realtime features ARE NOT currently used, as it degrades system
   responsiveness.  However less memory and cpu are used by the DART output
   method than the normal MMPM/2 method, and better skip control is also
   achieved.  Pause (P) and Resume (R) are implemented.

 Tiny UI

   Designed to use very little processor power while still displaying
   something usefull.  It doesn't have any neato real time tracking or scopes.

   It is possible to run it in detached mode, ie:
c:\Muse!2> detach mus2tiny mysong.s3m
   In which case you will be unable to control it.

Programming Info
~~~~~~~~~~~ ~~~~
   Muse/2 is unique in the ability to allow other programmers to extend it's
   basic functionality through the use of inheritance.  This is similar to the
   Work Place Shell.  However, since I have not yet had the time to produce
   suitable documentation I have not included the required header files.  If
   you are interested in using Muse/2 in some product then email me and I'll
   see what I can do.  For those who care, Muse/2 can function as a dynamic
   Nth channel mixer for sound effects, while still playing music files.  Now
   that DART support has been incorperated, true realtime has been achived,
   and a few people are making use of this powerfull feature.  (This is
   similar to the rumored Oasis RealTime Nth Channel mixer, except Muse/2 will
   allow a S3M to be played along with the SFX)

   It is also possible to add new file formats and output methods, ie GUS
   support, or MOD's. Again, email me if interested.

Ethos
~~~~~
   Ethos is a fairly young Os/2 demo group.  This player first appeared in our
   Peripheral Evolution Graphics/Sound demo (pe_ethos.zip).  Our member list
   changes alot, but at the moment it includes:

      Culus, Sane, Sophisto, Raethma, Wizdom, Daedalus and Zapper

   We are pondering doing another demo, but our graphics coder is gone, so
   it's not too likely :<

Final Note
~~~~~ ~~~~
   I'm not sure if I will continue to develope this program, if there is
   sufficient intrest I probably will.

   I have been thinking of releasing the IDL files, which would allow anyone
   to make use of the player, in any program.  But they are useless without
   some documentation which I don't really have the time to write.  However,
   if there is interest I could probably scrounge something together.  EMail
   me if you'd like to use it in something, or would like like to extend it
   with new file formats, better UI, whatever.  It can all be done, it's quite
   flexable.

   Comments, Critisims, Bugs etc welcome at gunthorg@cuug.ab.ca, please put
   Muse/2 somewere in the subject line. I suppose it's worth pointing out
   that if I don't get any email's, very little will happen. If you find
   a bug send it in, if it's really a bug you get on my beta list! :>
   I can also be found on IRC in the #Os/2 channel.

   Big thanks to the beta testers:
      Nightboob      Wizdom       Agent    HrBeing
      Hiro           Raethma      Roberte
      Sophisto       Sane         Malakai
      TNSLB          darb         __NS__

   Greets to!
      AFMOS        [Stang]
      madbrain     dandaman
      Vip          MaxMars
      Stiltner     Force Ten
      Neophyte     Highlandr

     All the beta testers and Ethos members,
     Sander van Leeuwen and The #os/2 channel!

Future Directions
~~~~~~ ~~~~~~~~~~
   XM
   GUS Support
   PM UI
   Auto-UnZIPing

Culus of Ethos
