Muse/2 V1.3 an Os/2 Digital Module Player
July 1996

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 us.

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 a
   Sound Blaster) MOD 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, but your system
   will seem slightly slower. This 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
      669 - Early multi channel module format, 8 channels and 9 commands.
      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  - Fast Tracker ][ Files, unique things such as envolopes and
            an instrument/sample model are used in this format.
            32 channels
      ULT - UltraTracker, 32 channels, multiple effects, and better sample
            definition
      FAR - Farandole Composer files
            32 channels
      WOW - Very uncommon 8 channel MOD derivitive
      IT  - Impulse Tracker, this file format can have up to 256 channels,
            and uses new note action (NNA) which is very much like MIDI.
            Many of these songs require 64 channels to play.
      IT2 - A more advanced version of the IT format.

   Currently Muse/2 only supports all of the above formats

   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

   If you don't have any, I recommend the following songs to get a good
   feel of what MODs 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/disks/1996/t/theland.zip (900k)
      The Land Series from Lord Blanka the Black

    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

    ftp://ftp.cdrom.com/demos/music/disks/1995/f/fm*
      Music by FM (Five Musicians) Excellent Quality S3Ms

    http://www.teleport.com/~smithtl/modpage/modpage.htm
      The MOD page, lots of great stuff!

  FTP sites people tell me about
    ftp://solo.lhg.hib.no/pub/mods/composers/Skeletor
    http://www.america.net/~friedmen/mod_file_links.html
    http://www.watson.org/mods

   Five Musicians
    ftp.fm.org

   New Site:
    ftp://s3m.dfwmm.net (207.16.54.2)
      -- Currently this site is being brought up, and as of this writing
         has just suffered a hard drive crash

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. This was during the summer of 1995, it played it's
   first module about May 1995.

 Installing

   Installing Muse/2 is simple, the only thing you need to keep is
   Muse2Txt.exe. Copy this file to a directory in the path and
   you'll be able to easially play modules.

   The REXX scripts included are not nescessary for the operation of the
   program, but are handy to have around. See the section on the detaching
   Muse.

   You can test your sound setup by running,
c:\Muse!2\Muse2Txt -V

   It will show:
 Muse/2 Text Mode Interface V1.3                                          Ethos
 Loading Components
 Version Information:
    Muse/2 Digital Mixer (museDACMixer) is Version 1.5
 File Formats:
    Composd Module (muse669Format) is Version 1.1
    Farandole Module (museFARFormat) is Version 1.1
    UltraTracker Module (museULTFormat) is Version 1.1
    Impulse Tracker Module (museITFormat) is Version 1.0
    Extended Module (museXMFormat) is Version 1.5
    Scream Tracker 2.x Module (museSTMFormat) is Version 1.0
    MultiTracker Module (museMTMFormat) is Version 1.1
    Amiga Module (museMODFormat) is Version 1.1
    WOW Module (museWOWFormat) is Version 1.0
    Scream Tracker 3 Module (museS3MFormat) is Version 1.5
  Output Methods:
    .WAV File Ouput (museFileWAV) is Version 1.0
    .AU File Ouput (museFileAU) is Version 1.0
    .RAW File Ouput (museFileRAW) is Version 1.0
    Gravis UltraSound (museGUSMixer) is Version 1.3 (Detected, Level=5)
    DART Wave Output (museDACDART) is Version 1.5 (Detected, Level=2)
    MMPM/2 Wave Output (museDACMMPM2) is Version 1.2 (Detected, Level=1)

   During the generation of this list muse will detect what sound
   hardware/software you have in your system. If you do not have a device
   installed then it will show (Not Detected). Higher levels indicate a
   better device, for instance MMPM is considered the worst and is given
   a level of 1.

 Playing Songs

   To play a single file type 'muse2txt asong.s3m'. Muse will autodetect
   your sound device and play the song.

   Wild cards are accepted, along with list files, for instance
      c:\> muse2txt *.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 include 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> muse2txt \s3m\*.s3m -r -s
   Will randomly pick a song and play it, exiting after the song is completed.

   Also the song list can be sorted with the -R option or written to the file
   Songs.lst with the -W option.

 ZIP File Support

   Because Modules are highly compressible muse will automatically retreive
   songs from a ZIP file. In order to make this possible you must have
   InfoZIP unzip version 5.12 or greater in your path. Muse will then
   recognize something called a zip path, for instance:
      c:\songs\songs.zip\asong.mod
   Is a zip path, asong.mod is located inside songs.zip. Muse allows a wide
   range of combinations,
      c:\songs\songs.zip       -- Plays all songs in songs.zip
      c:\songs\*.zip\*.mod     -- Plays all mods in all zips
      c:\songs                 -- Plays all songs in that directory, even if
                                  zipped.
      c:\songs\*.mod           -- Only plays mod files that are unzipped.
      c:\songs\songs.zip\ADir\A*.mod -- Plays all mod files starting with A
                                        in the directory ADir inside the zip
                                        Songs.zip.
   Zip paths can be given inside song list files or on the command line. Any
   number of zips can be specified. Note that it will take a bit longer to
   load the player as it must scan all zip files given to it for songs.

 RAR File Support

   Like ZIP support RAR support allows muse to directly load a song from a
   RAR archive. However because of the poor support unrar.exe provides
   for extract to stdout it is VERY slow. RAR support works identically
   to zip support.

 The Text UI

   Muse's current user interface is called the Text UI. It runs in a VIO
   window and has a number of features. First two different graphic sets
   may be used, the new snazzy UI created by Fred or the older classic
   UI found in the original Muse, -U2 will enable the classic UI.

   Depending on which UI is used the infomation displayed will vary slightly,
   but there are a set of common keys,
      [,]       - Change songs in the song list
      \         - Play a random song
      P,R       - Pause and resume play
      Esc       - Exit
      Up,Down   - Move the info display up or down
      PgUp,PgDn - Scroll the info display
      S         - Statistics Screen
      I         - Instruments Screen
      H         - Help
      L         - Control Song looping, displayed in the upper right corner is
                  a small icon the indicates the current state,
                    None         - Play normally
                    Right Arrow  - Do not allow the song to loop
                    Double Arrow - Loop the song forever
      1-9       - Jump to one of the first 9 songs in the list
      +,-       - Change volume
      F1,F2     - Change pitch
      F3,F4     - Change Speed
      F5,F6     - Change Pitch and Speed
      F7,F8     - Change Pitch, Speed and Volume
      =         - Rest Pitch Speed and Volume to 100%
!!!!  D         - Digital Mixer Control Panel, allows control of the
                  digital filter as well as DSC!! (Not availible with
                  GUS)

  The player can also be run detached, by starting it with the detach
  command,
c:\Muse!2> detach muse2txt asong.s3m
  When detached few resources are used. In order to control the player in this
  mode the command pipe interface must be used, which right now conisists of
  several REXX scripts included with the package,
   plynext.cmd   - Play the next song in the song list
   modtry.cmd    - Allow you to send whatever command you like, see the top of
                   the script for more information.
   modexit.cmd   - Exit the player
   plysong.cmd   - Search the songlist for the first substring match of the
                   given argument and play it
   removsng.cmd  - Removes the current song from the songlist and plays the
                   next song
   delsng.cmd    - Removes the current song from the songlist and plays the
                   next song. It then DELETES the song from disk. Does not
                   work with .ZIP files.
   wrtsglst.cmd  - Write the songlist to the passed file.
  A large variety of things are possible with this control system, it also
  works while the player is running. modtry.cmd contains a list of all
  the commands supported, if you have any questions/comments email us
  at gunthorg@cuug.ab.ca.

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!

   Large S3M samples are supported.

 MOD Format

   The MOD player supports the following MOD types
      - 15 sample modules
      - ProTracker modules (4 channels)
      - NewTracker modules (4 channels)
      - FastTracker modules (6,4 channels)
      - FastTracker II modules (max 32 channels)
      - Startrekker modules (4,8 channels)
      - Atari Octalyser modules (8 channels)
      - Unknown name OCTA format (8 channels, never actually seen one)
      - unmarked 31 sample 4 channel modules
   All standard protracker commands are supported.

   Files by the extention .nst and mod.* are also recognized as MODs.

 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!

 WOW Format

   Suports 8 channel WOW files, and all Protracker commands. WOW files are
   created by "Mod's Grave" (aka "Grave Composer") for the IBM.

 XM Format

   Supports Fast Tracker ][ XM files. All commands and functions are supported.
   Check out the instrument list with XM files!

 STM Format

   Scream Tracker 2 files, .STM. All commands are supported.

 669 Format

   Composd Files, all documented commands are supported.

 IT Format

   The Latest IT2 files are now supported!

 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 like surround sound -o"44k -s6"
   The lowest CPU usage is
      -o22k or if you don't like surround sound -o"22k -s"

   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 # should be used instead of a % symbol. Also
   see the 'd' screen in the UI, it allows realtime adjustment of the
   scaling factor

   Also, the use of the -o option is not needed as Muse will determine the
   highest Sampling Rate and Bit rate your sound card will support. It's
   only use now is to override some settings, a full list is not needed ie:
      -o-s
   will disable surround sound.

 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.

   The MMPM driver will automatically determine the highest Sampling Rate/Bit
   Rate your sound card can support.

 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.
     AMPMXMCD.DLL
     AUDIOSH.DLL
   These dlls must be used to replace the existing mmpm dlls, see the readme
   file in that directory for more information.

   Also, it is possible to obtain the DART dlls from the Ultimate Sound
   Page, http://wvnvaxa.wvnet.edu/~hrieke/us.html.

   DART is used to enhance the stablity and speed for background playing, 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. The -T command line option can be used to make DART
   function in Real Time, meaning all commands take effect at once. However
   changing songs produces some noise. I recomend using DART without the -T
   option as it also makes multi tasking less jerky.

   I think it's worth mentioning, It seems to be, that EVERY dirver shipped
   with OS/2 supports dart to some degree, some of the Creative drivers have
   small problems, but in general the drivers work fine with muse.

   -- NOTE Installing a fixpack tends to overwrite one of the two dart dlls,
   when this happens half of dart is present. Muse will give some odd error and
   exit. You should reinstall the proper dart dlls.

 Gravis UltraSound

   Support has been added for the GUS in native mode through the Manely
   drivers. Version 0.85 or later is required. The GUS driver also has an IMM
   meaning you can load songs which are larger than the amount of GUS ram you
   posses. This is especially usefull with large XM files.

   Note, sometimes the GUS can lose timing, if this happens press F3 then F4.
   This will reset the timing, this is fixed in driver versions greater than
   1.10.

 WAV File Output
 AU File Output
 RAW file Output
   Used the -OWAV, -OAU, -ORAW options muse can write a song to a file, -f
   specifies the file name. the -o option is fully supported to specify the
   output type, except in .au were the output is fixed at 8012Hz, 16 bit.

   RAW is a headerless file, just the raw digital data, and the .au is in the
   SUN/NEXT U-Law encoded style.

   -- Note, entire song lists can be recorded to a file, and looping songs
   will generate infintely large files. This funtion is best used with the
   -l option (prevent loop) and single songs.

   If -f is not specified but -OWAV is the song's name will be used as a
   basis for the output name, ie k_macro.s3m.wav.

Final Note
~~~~~ ~~~~
   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, nick is Culus.

   We actually have an official site, s3m.dfwmm.net, but it's suffered
   a hard drive crash, it will take some time to restore it.

   Big thanks to the IRC beta testers:
      Nightboob Wizdom  Agent   HB   Jaxom
      Hiro      Raethma Roberte Schu      Sacul
      Sophisto  Sane    Malakai Solarian
      TNSLB     darb    __NS__  Swordfish
   If I forgot you then please email me -- I can't keep all the nicks right
   anymore!

   Greets to!
      AFMOS        [Stang]     Lucien
      madbrain     dandaman    Philo
      Vip          MaxMars     Mandie
      Stiltner     Force Ten   Khyron
      Neophyte     Highlandr   Iron_man

     All the beta testers and Ethos members,
     Henry for his web pages,
     Julien for... Well, you know :P
     Sander van Leeuwen and The #os/2 channel!

   Big thanks to Sophisto for the WAV/AU code!

 Credits
 ~~~~~~~
   Digital Mixer - Jason Gunthorpe (Culus)
   Text UI - Jason Gunthorpe (Culus)
   Text UI Graphics - Fred Boyle (Wizdom)
   S3M Format - Jason Gunthorpe (Culus)
   MOD Format - Nicholas Vinen (HB)
   MTM Format - Nicholas Vinen (HB)
   STM Format - Nicholas Vinen (HB)
   XM Format - Nicholas Vinen (HB)
   WOW Format - Jason Gunthorpe (Culus)
   669 Format - Nicholas Vinen (HB)
   IT Format - Nicholas Vinen (HB)
   AU/RAW/WAV - Sophisto / Jason Gunthorpe (Culus)
   MMPM/DART/GUS - Jason Gunthorpe (Culus)

Future Directions
~~~~~~ ~~~~~~~~~~
  INI file
  Maybe adding the RT displays..

Ethos

Email -> gunthorg@cuug.ab.ca (Jason Gunthorpe/Culus of Ethos)
