XM-EXE 1.6 - Copyright (c) 1997-99 Ian Luck. All rights reserved.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Files that you should have found in the XM-EXE package
======================================================
XM-EXE.EXE    The executable
XM-EXE.TXT    This file
XM-EXE.DLL    Playback module
COLORS.EXE    XMPlay GUI colour grabber
CWSDPMI.EXE   DPMI server
FILE_ID.DIZ   BBS description file


What's the point?
=================
Ever wanted to send that cool XM to your villiage idiot of a friend? They
don't have an XM player? They don't know how to get one? They wouldn't know
what to do if they did have one? ... STOP! ... Don't jump, help has arrived!

OK, maybe not! But, that's what this bunch of bytes allows. Basically,
XM-EXE attaches a Win9x/NT playback program to the XM. It also compresses
the XM to generally produce a smaller EXE file even with the playback code.
Should you wish to do so, you can extract the original file(s) from the
created EXE file. XM-EXE also supports MOD/S3M/IT/MTM files.

It's also got the best (most accurate to FT2) XM reproduction to be heard
outside of FT2 itself. All features/effects (including several FT2 quirks)
are 100% supported. The IT reproduction is also practically balls-on, with
full support for all effects/NNA/DCA/filters etc...

The EXE files will even tell you if they've been infected by a virus!

For ease of use, XM-EXE is actually a DOS executable. So, to create an EXE
file from an XM file, you can simply run XM-EXE with the XM filename in
the command-line.

NOTE: For XM-EXE to work, you must be running under a DPMI server
      (Windows, OS/2 etc...) or CWSDPMI.EXE must be in the current
      directory or path. This is only necessary for XM-EXE.EXE, not
      the output EXE (which is a Win32 executable). Also, note that
      you may not be able to compress very large files in a Windows
      DOS box. If you get any "Out of memory" errors, try using
      XM-EXE in real DOS.


Main Features
=============
* Balls-on Accurate
- plays XMs the way nature intended.

* Sample Interpolation
- linear/spline interpolated sample mixing.

* Volume/Pan Ramping
- for output that's smoother than a baby's arse.

* 5 Band Equalizer
- adjustable gain at five frequency bands.

* Surround Sound
- Now with all new surround "mode 2".

* Compression
- usually produces a smaller EXE file than the original XM.

* DLL Version
- reduces the EXE size by allowing all EXEs to share the same playback code.

* Multi-XM
- put collections of XMs in one EXE, for convenience and space saving.

* Virus detection
- the created EXEs check themselves for virus infection

* Nice GUI! :)
- simple, good looking and unobtrusive playback display.


Command-Line Options (XM-EXE)
=============================
-d     DLL version
       Excludes the playback code from the EXE but requires XM-EXE.DLL,
       which contains the playback code, to be in the current directory or
       path when executing the EXE.
-m<file> Create a multi-XM EXE (file.EXE)
       All the XM files in the command-line are put into one EXE, instead
       of a seperate EXE for each of them.
-l     Create a text-file list of the tracks put in the EXE
       (multi-XM only)
-b<file> Use a "cover" bitmap (must be a BMP file)
       This will display any graphic/message of your choice when the EXE
       is loaded (and when the user double-clicks the caption). Useful if
       you intend to distribute the EXE. The BMP is compressed in the EXE.
-c<c1,...> Replace the default colours ... SEE BELOW FOR DETAILS
-i<file> Replace the default "XM" icon with an icon of your choice
-o<opt> Override default option
       Overrides an option default of the output EXE. You must have a
       seperate override for each default you wish to override. See the
       valid examples below.
@<file> Use options file
       Options files allow you to store the options you use commonly in a
       file that you can re-use without having to re-type all the options.
       Multiple option files may be used.

NOTE: You can use wildcards and multiple filenames in the command-line.
      Valid examples:
                        xm-exe *.xm @options
                        xm-exe -d a.xm b.xm -bblah
                        xm-exe a.xm b* c.xm -iblah
                        xm-exe -mblah *.xm -d
                        xm-exe a*.xm b.xm -mblah -l
                        xm-exe *.xm -os -ob5 -oqg5,0,-2,-4,0

TIP: If you are going to convert many XM files you should use the DLL
     option (-d) as this will save a lot of disk space because only one
     copy of the playback code will be needed (in XM-EXE.DLL), instead of
     the playback code being in every EXE. You should copy XM-EXE.DLL into
     the Windows system directory, so that it will always be in the path.


Replacing the default colours
=============================
There are 7 elements, which make up the GUI, that you can change the
colour of. The colour values are in hex - the lowest 8 bits make up the
red part, the next 8 bits are the green, and the next 8 bits are the blue.

Example:
        -cffffff,ff80,7fff,ffff,8080,40ad43,824f

These are the 7 elements you can change the colour of:
        Text (includes the button text/symbols) (def: d2ff00)
        Selected text (includes the button text/symbols) (def: ffff9f)
        Inactive window frame and caption (def: 0)
        Activated window frame and caption (def: 9200)
        Button frame (def: ffff)
        Selected button frame (def: a2ffff)
        Title text (def: bcff00)

TIP: The best way to find a good colour scheme is to try changing the
     colour scheme in XMPlay (the stand-alone version of XM-EXE), and
     then use the supplied colour grabber.


Command-Line Options (output EXE)
=================================
-a<n>  Set amplification level (range: 0-84)
-b<n>  The number of buffers (100ms each) used for playback (range: 3-31)
       The more buffers you use, the less likely it is that the playback
       will be interrupted while running other software. But, the more
       buffers, the slower the response to the buttons.
-c<n>  Use stored config : 0 = off, 1 = on
       This option allows the output/setup configuration to be stored
       and restored. The stored config is shared by all EXEs that have
       this option enabled.
-d<n>  Select the playback device - 0 is the first
-e     Extract the original XM file
       Multi-XM: select the track with the "-t" option.
-g     Big (double size) GUI
-i<n>  Interpolation switch : 0 = linear, 1 = spline
       Linear interpolation draws a straight line between the samples,
       spline interpolation draws a smooth curve between the samples.
       Spline interpolation is very CPU intensive, compared to linear
       interpolation. If you use spline interpolation with a less than
       powerful CPU the sound will probably crack up.
-l<n>  Looping switch (multi-XM only) : 0 = off, 1 = on, 2 = auto
-m<n>  MOD playback option : 0 = normal, 1 = FT2, 2 = PT1
-p<n>  Set pan seperation (range: 0-84)
-q     Switch the equalizer on ... SEE BELOW FOR DETAILS
-qg<g1,g2,g3,g4,g5>  Set the equalizer gains
       example: -qg7,2,-2,-4,0
       The gains can be floating-point numbers, eg. 1.57, -4.2 etc...
-r<n>  Ramping switch : 0 = off, 1 = normal, 2 = sensitive
-s<n>  Surround sound switch : 0 = off, 1 = normal, 2 = "mode 2"
-t<n>  Set initial track (multi-XM only) - 1 is the first
       Also sets the track for extraction.
-v<n>  Set initial volume (range: 0-45)

NOTE: The defaults are overriden by the stored config, and the stored
      config is overriden by the command-line options.

Defaults
--------
Initial track is 1
Initial volume is 32
Amplification level is 42
Pan seperation is 42
Looping is AUTO
Interpolation is LINEAR
Ramping is NORMAL
Playback device is 1 (the first)
10 buffers (1s) are used
Surround sound is OFF
The equalizer is OFF
The equalizer gains are 6, 1, -1, -2, 1
Use stored config is ON

TIP: If you want to play the XM with any of the defaults changed, the best
     way is to use the "-o" option when creating the EXE to override the
     defaults. Alternatively, you can create a shortcut for it and edit the
     shortcut command-line to whatever you want. You can then double-click
     on the shortcut when you want to play the XM with those settings.


The "SETUP" Window
==================
Device Options
--------------
You can change which device (if you have multiple devices) to use, and
what frequency/resolution/channels/buffer to use with the device.

After you've made changes to the device settings, close the "SETUP"
window to apply the changes. If the device does not support the settings
you chose, XM-EXE will use the closest settings that the device does
support. If you re-open the "SETUP" window, you will see which settings
are actually being used.

Miscellaneous
-------------
AUTO/LOOP= Looping switch (same as '-l' option)
           You can choose the AUTO LOOP option, to let XMPlay decide if
           each track is meant to be looped. Looping is always on for
           single XM EXEs, as there are no other tracks to move on to.
HI-LIT   = Rollover controls switch
TIME     = Time display switch
           Displays the position in time, rather than patterns/divisions.
HI-LIT   = Rollover controls switch
           Rollovers make the controls (buttons/sliders etc...) light up
           as the mouse moves over them.
BIG      = Big GUI (double size) switch
           For those who use hi-res, where the normal GUI size is too tiny.
           Close the "SETUP" window to apply the change.
NORM/FT2/PT1 MOD = This decides how MOD files should be played:
         FT2 MOD = FT2 plays MODs slightly differently from the convention.
           If you want to hear MOD files as FT2 plays them, then select this.
         PT1 MOD = This plays MODs as the original ProTracker did, so now you
           can relive those early Amiga days! :)
AAR/-R/F = Auto amplification reduction switch
           If enabled, the amp level will automatically be reduced whenever
           clipping occurs. You may then have to raise the amp level again
           when you play a new track (multi-XM), unless you select the AAR-R
           or AAR-F options. The AAR-R option will automatically reset the amp
           level to the centre before playing a new track. AAR-F will fade-in
           the new track until it clips, then it'll behave the same as AAR.


The "OUTPUT OPTIONS" Window
===========================
LI/SI = Linear/Spline Interpolation switch
R     = Ramping switch (off/normal/sensitive)
S     = Surround Sound switch (off/normal/mode 2)
Eq    = Equalizer switch

The graphic equalizer sliders range from +10dB (top) to -10dB (bottom).

The slider on the bottom-right is the pan seperation slider. This obviously
can only affect things when playing in stereo.

The slider on the bottom-left is the amplification slider, this is different
to the volume slider. The volume slider controls the level of the sound
card output, the amplification slider controls the level of the actual
mixing output. The higher the amplification, the greater the resolution of
the mixing output, but if it's too high clipping may occur resulting in
distortion of the sound.

TIP: To centre any of the sliders (EQ/amplification/pan seperation), hold
     either of the SHIFT keys while clicking on the slider.

NOTE: The response speed to these options is dependant on the buffer size,
      the delay will be the length of the buffer chosen in the SETUP.


The Equalizer
=============
If you don't have your sound card output going through an equalizer (or a
hi-fi with one) then you can use this option to provide one.

The equalizer's five centre frequencies are 70hz, 350hz, 1000hz, 3500hz
and 10000hz. By using the equalizer you can emphasise or weaken these
frequencies. For example, you can boost the bass by using a positive gain
at the low frequencies, or you can boost the treble by using a positive
gain at the high frequencies. The gains are meusured in dB, a gain of 10dB
doubles the level of the frequency, a gain of -10dB halves the level, a
gain of 0dB leaves the level as it is.


The Keyboard Shortcuts
======================
 P (or Pause) = Pause/Play
         Home = Restart
  left cursor = Rewind
 right cursor = Forward
      Page Up = previous song  (multi-XM only)
    Page Down = next song      (multi-XM only)
 (numpad) -,+ = Adjust volume
 (numpad) /,* = Adjust amplification
   Delete,End = Adjust pan seperation
            I = Interpolation switch
            R = Ramping switch
            S = Surround sound switch
            Q = Equalizer switch
            T = Time display switch
     shift+F9 = Display message in INFO 'N' STUFF window (IT/MTM only)


Latest Version
==============
The latest version of XM-EXE can always be found at the XM-EXE homepage :

        http://www.icl.ndirect.co.uk/music/


Copyright, Disclaimer etc...
============================
This program is free for non-commercial use, so if anyone tries to charge
you for it kick 'em where it hurts.

This software is provided as-is. The author makes absolutely no warranties
on it. You use it at your own risk. The author shall not be held responsible
for any damage that may result from its use. So don't come crying to me!

All trademarks and other registered names contained in the XM-EXE package
are the property of their respective owners.


History
=======
1.6 - 12/2/99
-------------
* S3M/IT/MTM support
* Play position slider
* Surround mode 2 - ignores pan pos, useful for mono MOD/S3Ms
* WAV writer removed - use XMPlay to write WAVs
* HI-LIT/TIME/FT2 MOD/PT1 MOD/AAR/AUTO LOOP options
* Virus detection
* Amplification & pan seperation sliders
* Help "bubbles" - right click on a control for a helpful bubble
* MMX accelerated mixing
* INFO 'N' STUFF window replaces INSTRUMENT LIST window
* Variable sized INFO 'N' STUFF/TRACK LIST/FILE SELECTOR windows
* Works with WinNT again! :)

1.5 - 14/8/98
-------------
* Cover BMP
* Customizeable GUI colour scheme
* "SETUP" options window
* Improved linear interpolation quality
* Heavily optimized spline interpolation
* Improved surround sound
* MOD support
* Sensitive ramping
* Output/setup settings stored

1.4 - 19/5/98
-------------
* "OUTPUT OPTIONS","TRACK LIST" windows
* Keyboard shortcuts
* Override default options

1.3 - 23/4/98
-------------
* Customizable icon
* "INSTRUMENT LIST" window
* Improved compression (better ratios and speed)
* Looping option
* Playback window switches and equalizer sliders
* WAV writer

1.2 - 20/10/97
--------------
* 5 band equalizer
* Amplification/mono/volume options
* DLL version
* Multi-XM
* Spline interpolated sample mixing
* Volume/pan ramping

1.1 - 15/9/97
-------------
* Interpolated volume/pan slides
* Original XM extraction

1.0 - 10/9/97
-------------
First Release


Credits
=======
The compression system used in XM-EXE is developed from the ZLIB library
by Jean-loup Gailly & Mark Adler.


Bug Reports, Suggestions, Coments, Problems etc...
==================================================
If you have any of the aforementioned you can email :

        xm-exe@icl.ndirect.co.uk

