XMPlay 2.1 - Copyright (c) 1998-2001 Ian Luck. All rights reserved.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Files that you should have found in the XMPlay "package"
========================================================
XMPLAY.TXT    This file
XMPLAY.EXE    The executable
OGG.DLL       Ogg Vorbis 1.0rc2 module
VORBIS.DLL    Ogg Vorbis 1.0rc2 module
FILE_ID.DIZ   BBS description file


What's the point?
=================
XMPlay is a Win32 (Windows 95/98/NT/2k/etc...) music player, supporting
several audio formats.

Stream formats
--------------
* OGG - Ogg Vorbis
* MP3 - MPEG1/2/2.5 layer 3
* MP2 - MPEG layer 2
* MP1 - MPEG layer 1

These formats can not only be played from files located locally on a drive
or LAN, but also from FTP/HTTP/Shoutcast/Icecast servers on the internet,
optionally writing a copy to disk at the same time.

Module (MOD) formats
--------------------
* MO3 - Modules with MP3 or OGG encoded samples
* IT  - Impulse Tracker modules
* XM  - FastTracker2 modules
* S3M - StreamTracker3 modules
* MTM - MultiTracker modules
* MOD - Generic module formats
* UMX - Unreal/Tournament music package

XMPlay's got the best (most accurate to FT2) XM reproduction to be heard
from any player. 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... MIDI out is also supported
for XM files.

XMPlay also supports the MO3 format (modules with MP3 or OGG compressed
samples) that was introduced in BASS 0.7. If you wish to create MO3s,
then you should download BASS from the XMPlay website (URL below).

Winamp plugins
--------------
As well as the listed formats with built-in support, a whole bunch of other
formats can be played with XMPlay too, using Winamp input plugins.


Main features
=============
* Balls-on Accurate
- plays the way nature intended

* Interpolation & volume/pan ramping
- for output that's smoother than a baby's arse :)

* 5 Band Equalizer
- adjustable gain at five frequency bands

* Reverb & Surround Sound
- for a richer, fuller flavour

* Per-track settings
- save default output settings (eq/reverb/etc...) to be used each time a
  track is loaded

* Track list saving/loading
- reads M3U/PLS playlists, writes PLS playlists

* Track information
- displays file information, instrument/sample texts, and messages/tags

* WAV writer (with CODEC and normalization support)
- use XMPlay's output to write your own CD/MP3s

* Integration
- open files from Explorer, drag'n'drop files/directories/shortcuts/URLs,
  and monitor the clipboard for streamable URLs, drag tracks from XMPlay
  into other programs

* FTP & HTML scanning
- scan for streamable files in FTP directories and HTML webpages

* Winamp plugins
- adds support for a whole load more audio formats

* Archive file plugins
- play files from within archives (ZIP/RAR/ARJ/LHA/etc...)

* Visualisation plugins
- compatible with Sonique plugins

* Nice GUI! :)


The main window
===============
The title of the current track is displayed at the top, the buttons below
that from left to right are...

Track info - opens/closes a window to display information on the current
    track. See "The info window" below.

Previous track - play the previous track in the playlist, skipping over any
    that are set to "skip".

Play / Pause - toggles play/pause of the track. If no track is loaded, then
    the currently selected track in the playlist is loaded (or the 1st track
    if none is selected).

Stop - stops playback, and sets the position to the start.

Next track - play the next track in the playlist, skipping over any that
    are set to "skip".

Open file(s) - opens and plays file(s). Right-click to open a URL. If you open
    an FTP directory URL, XMPlay will automatically scan the directory for OGG
    and MPEG files.

The 2 sliders below these buttons control the volume and balance. Next is
the time display, which can be switched (by clicking on it) between the time
passed, the time remaining, or the order/frame/page position (depending on if
it's a MOD/MPEG/OGG format being played).

Below the time display is the position indicator. It can also be used to
change the playback position, except when streaming from the internet. When
streaming from the net, it will light-up to indicate how much of the file
has been downloaded so far (if the file is of a fixed length).

Below that, some basic information on the format and length the current track
is displayed. To the right of that is the looping switch, which can be set to
never loop, always loop, or only loop files that are apparently intended to be
looped. Note that some MOD files never actually reach an end.

When you drag'n'drop files into the main panel, they are opened as if the
"Open file(s)" button had been used - ie. playlist cleared and new tracks
added. As well as files, whole directory trees and shortcuts can also be
drag'n'dropped into XMPlay.

TIP: Double-click on any non-button area to toggle "mini on top" mode.


The "Output Options" panel
==========================
The response speed to all these options is dependant on the buffer size,
the delay will be the length of the buffer chosen in the device setup.

Left switches
-------------
Interpolation switch - MOD formats only
    Linear interpolation "draws" a straight line between the samples,
    spline interpolation "draws" a smooth curve between the samples and
    requires more CPU power.

Ramping switch (off/normal/sensitive) - MOD formats only
    Ramping makes volume and panning changes smoother so that sudden large
    volume/panning changes do not cause any "clicking" in the sound. It
    also fades-in (very quickly) new samples so that there is no click from
    them. Sensitive ramping only performs the fade-in when it's neccessary
    to prevent a click, so percussive sounds stay sharp.

Surround Sound switch (off/normal/mode 2) - MOD formats only
    "Mode 2" ignores panning, so is good for mono MODs.

Auto amplification reduction switch
    AAR causes the amplification level to be automatically reduced whenever
    clipping occurs. With fade-in enabled, it will fade-in new tracks until
    they clip, then it'll behave the same as normal. Dynamic mode continues
    to increase and decrease the amplification level throughout playback.

Bottom sliders
--------------
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.

To the right of the amplification slider, is the pan seperation slider. This
obviously can only affect things when playing in stereo. It also only affects
MOD formats.

NOTE: None of the options listed above apply to Winamp plugins.

Above center
------------
Graphic equalizer switch and sliders. The graphic equalizer sliders range
from +10dB (top) to -10dB (bottom). Use the mouse wheel to increase/reduce
the gains by 1dB. Presets are accessable by right-clicking the EQ switch.

Above right
-----------
Reverb switch and sliders. The "cutoff" slider affects how much high frequency
sounds are reverberated. The "level" slider affects how much the whole sound
reverberates. Use the mouse wheel to increase/reduce the levels by 5.

NOTE: Reverb is only applied when playing in stereo.

Top-left disk switch
--------------------
When ticked, this enables the automatic loading of "Output Options" settings
specific to the new track being loaded. The settings are stored based on the
track's filename, so a file can be moved around and the settings will still
take effect when it's loaded so long as the filename stays the same. If the
track does not have specific settings saved for it, then default settings are
used. Right-clicking brings up a menu of options...

Save track settings - saves the current settings as the default for the track
    that's currently loaded, overwriting any settings that were saved for it
    previously.

Load track settings - loads the saved settings for the current track.

Remove track settings - clears the current track's saved settings.

Remove all track settings - clears all saved settings for all tracks.

Save default settings - saves the current settings as the default for any track
    that does not have settings specifically saved for it.

Load default settings - loads the default settings.


The "Device Setup" panel
========================
You can change which device (if you have multiple devices) to use, and
what frequency/resolution/channels/buffer to use with the device. If the
chosen device is not available then a free device will automatically be
used instead, if there is one available.

You may also choose the "WAV Writer" device, to write the output to WAV
files rather than a soundcard. Or select "WAV Writer (codec)" to write
compessed WAVs. If the CODEC does not support the chosen format, XMPlay
will switch to the plain WAV writer.

The amplification slider controls the volume level of the WAV. Be careful
not to use a too high amplification level as this may result in samples
being clipped. You can avoid amplification problems by using the "WAV
Writer (normalized)" device.

NOTE: Only the WAV Writer devices (except CODEC) allows the 32-bit option,
      for any other device the output resolution will drop down to 16-bit.

Any new settings will take effect when playback is next started, or they
can be applied immediately by clicking "Apply". If the device does not
support the settings you chose, XMPlay will use the closest settings that
the device does support.

NOTE: MPEG/OGG files are always played at their correct sample rate. They
      are also always played in 16-bit, except when writing normalized WAVs.

NOTE: Only the device and buffer length settings apply with Winamp plugins,
      the other details should be set via the plugin "Config" option. When
      writing normalized WAVs, the resolution setting also applies then.


The "Integration" panel
=======================
You can set XMPlay to be the default player for the formats it supports. So
that whenever you "open" a file from within Windows Explorer, it is opened
by XMPlay. RED = MOD formats, GREEN = stream formats, BLUE = playlist formats.

MONITOR CLIPBOARD - monitor clipboard for streamable URLs
    XMPlay can monitor the clipboard for URLs of OGG and MPEG files, which
	it will automatically play or add to the playlist. When you see an OGG
    or MPEG file on a webpage, simply right-click and "Copy Shortcut" to
    have XMPlay stream it.

ADD TO LIST - queue the new tracks on the playlist
    If enabled, tracks opened from Windows Explorer or the clipboard are
    only added to the playlist, and are not played immediately.


The "Miscellaneous" panel
=========================
Norm/FT2/PT1 MOD - decides how MOD files should be played:
    FT2 MOD = FT2 plays MODs slightly differently from the convention,
      infact most trackers play MODs differently from eachother! Anyway,
      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! :)

TRIM - trim empty space from the end of MOD format files
    If there is any silent space at the end of a track, it will not be
    played. Instead XMPlay will jump to the next track, assuming there
    is more than one track in the list, and looping is not on.

RESTRICT DL RATE - restrict the download rate of internet files
    If enabled, the rate is restricted to the rate required to sustain
    playback. Otherwise, the file will be downloaded as quickly as the
    internet connection allows.


The "Plugins" panel
===================
The Winamp input plugins that are installed are listed here. By clicking
on a plugin you can view info about it, configure it, and set XMPlay as
the default player of any of the plugin's supported formats.

When changing a plugin's config while it's being used to play a track, you
will probably have to stop/restart the track for the config changes to take
effect.

NOTE: Only plugins that can feed the sample data to XMPlay (rather than
      use their own output device) are loaded, which is most of them.


The playlist panel
==================
Double-clicking on a track will make XMPlay play the track. Right-clicking
brings up further options to play the track, to write a copy to disk while
playing the track (URLs only), remove the track, and skip the track.

If an internet stream is of a fixed length (a file on an FTP/HTTP server),
the "write to disk" option can be selected while the track is already playing
(or has even finished playing), and XMPlay will write the portion that has
already been downloaded and continue to write the remainder that is being
downloaded. So you can preview the track before deciding if you want to keep
it, without having to start downloading it again.

Shoutcast streams that include the track titles, can be automatically split
into the seperate tracks when writing them to disk.

The currently playing track is highlighted with a yellow arrow. The currently
selected track is highlighted with a light-blue background. Tracks that are
set to be skipped have 3 light-grey lines through them. Dead tracks (those
that were unsuccessfully loaded) have a single red line through them.

Files can be added to the list by drag'n'dropping them from Windows Explorer.
Whole directory trees and shortcuts can also be drag'n'dropped into the list.
URLs can also be dragged from web-browsers. The new tracks are inserted into
the position that you "dropped" them.

Bottom buttons
--------------
Reorder list - shuffles the playlist order. Right-clicking brings up further
    options to sort by filename or title, and to reverse the order.

Save list - writes the playlist to a PLS file

Add to list - adds files/URLs to the playlist. Right-clicking allows you to
    choose if you want XMPlay to verify that files you add to the list are
    playable before they are put on the list (except URLs, which XMPlay does
    not verify). The contents of directories drag'n'dropped into the playlist
    are always verified before being added. If you add an FTP directory URL,
    XMPlay will scan the directory for MPEG and OGG files, and add them to
    the list. Enabling the "Scan HTML pages" makes XMPlay scan HTML webpages
    for links to MPEG and OGG files, which it then adds to the list.

Remove from list - removes the selected track from the list. Right-clicking
    gives further options to remove duplicates tracks, dead tracks, and all
    tracks.

Loop list - if ticked, XMPlay plays the first track in the list again after
    the last track.

Next to the buttons is the total playlist duration. If a "+" is shown, then
the total duration is not available, either because some tracks have not been
played yet or they have an unknown duration.

TIP: You can use the mouse-wheel to scroll the list, and drag tracks up/down
     the order. You can also drag tracks from XMPlay into other programs, by
     clicking the right button while holding the left button down.


The info window
===============
The info window displays information on the currently loaded track. There
are 4 modes...

General - displays info on the file's name, format, size, length, etc...

Message - displays any messages or tags contained in the file, including
    the current track name when streaming from Shoutcast servers.

Samples - displays instrument and sample texts (MOD formats only).

Vis - displays visualisation plugins.

The window can be resized by dragging the edges, or you can have XMPlay
automatically resize the window to fit the contents by ticking the box at
the top (2nd from left). The mouse wheel can be used to scroll up/down.

The 3rd button from the left toggles having the playlist panel duplicated
in the info window. With "auto resize" enabled, only the playlist display
width is resized - the number of tracks listed is left as it is.


Dragon droppings
================
Files, whole directory trees, shortcuts, and URLs can be drag'n'dropped into
XMPlay. If they are dropped into one of the playlist panels, then the tracks
are inserted into the playlist at the position they were dropped in. If they
are dropped outside the playlist panels, then the playlist is cleared, and
the dropped tracks are added and played.

The files and URLs of tracks can also be dragged out of the XMPlay playlist
panels, into other applications, by clicking the right button while keeping
the left button pressed.


Keyboard Shortcuts
==================
            O = Open/play file(s)
   P or Pause = Play/Pause
  left cursor = Rewind
 right cursor = Forward
      Page Up = Play previous track in playlist
    Page Down = Play next track in playlist
          End = Play random track in playlist
 (numpad) -,+ = Adjust volume
 (numpad) /,* = Adjust amplification

       Insert = Add file(s) to playlist
    up cursor = Select previous track (+shift = 5 tracks)
  down cursor = Select next track (+shift = 5 tracks)
 ctrl+up/down = Select current playing track
        Enter = Play selected track
       Delete = Remove selected track
     Spacebar = Toggle skipping for selected track

           F1 = Display "General" info window
           F2 = Display "Messages" info window
           F3 = Display "Samples" info window
           F4 = Display visualisation window
           F5 = Open playlist in info window
            M = Toggle "mini on top" mode


Plugins
=======
The plugins are available at the XMPlay website. To activate a plugin,
simply put it in the same directory as (or a sub-directory of) XMPLAY.EXE.

Sonique visualisation plugins can be used by simply copying them over to
the XMPlay directory, or a sub-directory of it.


Latest Version
==============
The latest version of XMPlay can always be found at the XMPlay website:

		http://www.un4seen.com/


Copyright, Disclaimer, and all that other jazz
==============================================
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, including, but not limited to,
burning your toast while being too engrossed in the XMPlay "experience".

All trademarks and other registered names contained in the XMPlay "package"
are the property of their respective owners.

OGG & VORBIS modules are Copyright (c) 2001, Xiphophorus


History
=======
These are the major (and not so major) changes at each version
stage. There are also many bug fixes made along the way too!

2.1 - 22/12/2001
----------------
* Winamp input plugin support
* Playlist panel duplicated in the info window
* HTML webpage scanning
* URL drag'n'dropping into XMPlay
* Drag'n'dropping files/URLs from XMPlay to other apps
* Write seperate tracks to disk (shoutcast streams)
* "Dynamic" auto-amp mode
* "Auto loop" mode applies to all formats now (not only MODs)
* 96khz MOD playback rate
* BPM/speed display for MOD formats
* Stereo sample support in MO3/IT/XM/S3M formats
* Current track displayed in taskbar
* Open file/URL dialogs combined
* Desktop chortcut option
* "Remove duplicate titles" option
* "Remove dead" also removes non-existant local files not marked as "dead"
* Random track shortcut

2.0 - 1/11/2001
---------------
* Too many things to remember! :)


The "thank you" section
=======================
BIG thanks to Josh "Cedri/Vesh" Elliot who did the original designs for
the XMPlay2 GUI.

Thanks also go to Isao Kasai, Mike Toomim, Maz, Yello '73, Neurotix,
Ralesk, Progg, Manwe, Frater Sinister, Kaparo, and especially It-Alien,
who between them have helped find a shitload of bugs for fixing.

And... thanks to all who have sent good suggestions and bug reports!
