XM-EXE v1.5 - Copyright (c) 1997-98 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
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 a XM player? They don't know how to get one? They wouldn't
know what to do if they did? ... 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 XM from the created
EXE file. XM-EXE also supports MODs aswell.

It's also got the best (most accurate to FT2) XM reproduction that I've
heard from any player. All features/effects are 100% supported.

For ease of use, XM-EXE is actually a DOS executable. So, to create an EXE
file from a 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, unlike other players.

* 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
- surround yourself in sound.

* WAV Writer
- use XM-EXE's output for writing your own CDs.

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

* 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).


Command-Line Options (output EXE)
=================================
-t<n>  Set initial track (multi-XM only) - 1 is the first
       Also sets the track for extraction and WAV writing.
-v<n>  Set initial volume (range: 0-45)
-a<n>  Set amplification level (range: 0-5)
-l<n>  Looping switch (multi-XM only) : 0 = off, 1 = on
-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+FPU the sound will probably crack up.
-r<n>  Ramping switch : 0 = off, 1 = normal, 2 = sensitive
-d<n>  Select the playback device - 0 is the first
-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.
-m     Force mono output
-s     Switch surround sound playback on, obviously only works in stereo.
-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...
-g     Big (double size) GUI
-e     Extract the original XM file
       Multi-XM: select the track with the "-t" option.
-w     Write WAV file (16-bit 44100hz)
       Multi-XM: select the track with the "-t" option.
-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.

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 3
Looping is ON
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 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 Drop-Down Output Options
============================
LI/SI = Linear/Spline Interpolation switch
R     = Ramping switch (off/on/sensitive)
S     = Surround Sound switch
Eq    = Equalizer switch

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

TIP: If you plan to use these controls frequently during playback, you may
     want to use a lower number of buffers to reduce the delay between
     making a change and actually hearing the change.


The Drop-Down Setup Options
===========================
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
-------------
LOOP     = Looping switch (same as '-l' option)
           Looping is always on for single XM EXEs, as there are no other
           tracks to move on to.
BIG GUI  = Big GUI (double size) switch (same as '-d' option)
           For those who use hi-res, where the normal GUI size is too tiny.
           Close the "SETUP" window to apply the change.


The Keyboard Shortcuts
======================
 P (or Pause) = pause/play
         Home = restart song
  left cursor = rewind
 right cursor = forward
      Page Up = previous song  (multi-XM only)
    Page Down = next song      (multi-XM only)
          +/- = adjust volume
            I = interpolation switch
            R = ramping switch
            S = surround sound switch
            Q = equalizer switch


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

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


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


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. But, if you can't live with the guilt
of using a quality piece of software like this without paying then by all
means send a few presidents heads (of the paper variety) my way, to ease
your conscience.

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.5 - 14/8/98
-------------
* Cover BMP
* Customizeable GUI colour scheme
* Drop-down setup options
* Improved linear interpolation quality
* Heavily optimized spline interpolation
* Improved surround sound
* MOD support
* Sensitive ramping
* Output/setup settings stored
* Several bug-fixes

1.4 - 19/5/98
-------------
* Drop-down output options
* Drop-down track list
* Keyboard shortcuts
* Override default options

1.3 - 23/4/98
-------------
* Customizable icon
* Drop-down instrument list
* 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


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

        xm-exe@icl.ndirect.co.uk

