OFFICIAL UFOMOD 2.3 MANUAL
==========================
[08/10/2001]

The previous documentation files ('ufomod-2.x.doc') are now out-of-date.
Please read this file instead, because it covers all important issues
on Ufomod.

Also read the FAQ file, which contains a few important questions about the
package.

Hope this file is as much contentive as possible. ;-)

SOFTWARE STATUS
---------------

This software is completely freeware. Currently there is no source included
although I was about to release it as GPL. But before, I should tidy up
the code a bit to make it readable by people :)

VERSION
-------

This is the fifth version released, dated on 8 October 2001. I can
remember many previous releases, but this is definitely the most perfect.
Here are the stable ones we've published :
2.3 FULL     (rel. 22 Sep 2001)
2.3 PREVIEW  (rel. 10 Sep 2001)
2.2 FULL     (rel. 7 Aug 2001)
2.2 PREVIEW  (rel. 10 Apr 2001)
2.1 TEST     (rel. March 2000)
2.0 TEST     (rel. 15 Feb 2000)
Here's an unstable one :
2.2 BETA     (rel. 31 Jul 2001)
Another version, not seen these days, which was
a first public release, is UMP 0.1.4 (rel. 1 Sept 1999), which is known to
behave unstable.

This version is 2.3 FULL (patch 2 -> p2). We decided to release the 2.3 once
again after making a couple of little, but important changes to the source.
A few important bugs have been fixed. Read further for more details.

REQUIREMENTS AND OTHER THINGS
-----------------------------

The minimum hardware required :

Processor:   80386SX
RAM:         2 MB
Video card:  MCGA/EGA

Well, I think that every modern computer should match these requirements.
A multimedia hardware recommendation follows :

* On the DOS/Linux side *
Processor:   Pentium 120 or equivalent
RAM:         8 MB
Video card:  VGA
Sound card:  SB16 or compatible

* On the Windows side *
Processor:   Pentium 166 or equivalent
RAM:         16 MB
Video card:  SVGA
Sound card:  SB16 or compatible

The minimum processing power you'll need to play 32-chn modules is
equivalent to a Pentium-66. Because most modern module formats (like IT) often
use more than 32-chn with various effects, a Pentium-120 is recommended for
maximum listening pleasure, tough.

ABOUT THE MEMORY
Ufomod is capable of handling compressed archives using external software.
Such external processes require additional operating memory for its own.
Thus, it is recommended to have a lot of free RAM to Ufomod.

CACHE RECOMMENDATION
Ufomod's creators strongly recommend the use of a disk-caching program if
you use compressed archives with Ufomod. The following utilities drastically
speed up the operations (up to 8 times faster) :
* SmartDrive(tm) from Microsoft
* Norton Disk Cache from Symantec

ABOUT THIS VERSION
This version is compiled using GNU compiler within the DJGPP project. The
executable (`EXE`) is intended to run under MS-DOS or compatible systems.

FEATURES
--------

1. The current version of Ufomod supports the following module formats :
   669 -> Composer 669 & UNIS 669 modules
   AMF -> Advanced Module Format from the DSMI library
   DSM -> Digital Sound Interface Kit format modules
   IT  -> Impulse Tracker modules
   XM  -> FastTracker II modules
   MOD -> AMIGA Protracker or compatible (TakeTracker,Startrekker,Oktalyzer)
          modules
   STM -> ScreamTracker 2 modules
   STX -> Scream Tracker STMIK modules
   S3M -> Scream Tracker 3 modules
   IMF -> Imago Orpheus modules
   GDM -> General DigiMusic modules
   MED -> AMIGA OctaMED modules (without synths)
   FAR -> Farandole Composer
   UNI -> Mikmod modules (also including APlayer format APUN)
   PTM -> PolyTracker 1.0 modules
   MTM -> MultiTracker 1.0 modules
   OKT -> AMIGA Oktalyzer modules
   ULT -> UltraTracker V1.x

2. The following compression formats are recognized :
   ACE v1.x (C)Marcel Lemke
   RAR 2.x (C)Eugene Roshal
   IMP 1.x (C)Technelysium Pty Ltd.
   LHA 2.x (C)Haruyasu Yoshizaki
   ARJ 2.x (C)ARJ Software Inc.
   ZIP by PKZIP 2.xx from PKWARE Inc.
   JAR 1.x  (C)ARJ Software

3. Ufomod (libmikmod) mixer features :
   * output in 8/16-bit, frequency range 5-48KHz in stereo
   * interpolated (antialiased) mixing
   * software reverbation with factor 1-15
   * alternate High-Quality mixer

4. The DOS version utilizes the following hardware :
   * Sound Blaster 1.x/2.x/Pro/Pro-II/16/AWE32/64GOLD/128/Live!
   * or 100% SB Pro/AC'97 compatible (Pro Audio Spectrum, Aztech etc.)

INSTALLATION
------------

Just run the executable `ufomod-2.3p2-bin-full.exe` to install . In case
you got a zipped file `ufomod-2.3p2-bin-full.zip` it is enough to unzip into
a new folder.

CONFIGURATION
-------------

Unlike other players like Cubic, Ufomod is a command line oriented player.
This is due to the nature of Ufomod, which really was a Linux application
at the absolute start of our work. Ufomod is very intuitive and widely
configurable. For a short list of available commands type :
> ufomod -?
or
> ufomod -h

Ufomod's basic operation structure is called the `playlist`. A playlist is
a chain of playable items, that we call `modules`. Without a playlist,
Ufomod doesn't do any further processing, signalizing it as an error
('No modules to play'). You specify, where to find modules to play :
> ufomod <module1> <module2> ..

Ufomod is also knowing of its internal commands typed onto the command line.
These so called `switches` allow to access all of Ufomod's features, where
Ufomod's interface allows to control only a few options (mainly mikmod
settings). Here's a list of all available commands grouped in sections :

a. Processing switches :

-d <directory>
   Tells Ufomod to cache directory <directory>. `Caching a directory` means
   browsing its contents in search of modules for every Ufomod start, but with
   no directory recursing. You can cache as many directories as you want.
   The cache information is stored in the configuration file.
   ex: ufomod -d /music/mods

--cleandircache
   Cleans the directory cache. The playlist stays unchanged.

--cleanplaylist
   Cleans the playlist. This doesn't alter the directory cache.

-p <path> | --cfgpath <path>
   The switch points Ufomod to a new configuration path. Ufomod will use
   the configuration file from that location if present, and store there
   updated configuration on exit.

--probeonly
   Performs all initializations, incl. configuration load, driver/library
   inits, but the directory caching and playlist loading, and exits.

--console[+-]
   Enables the native Ufomod console mode. The console mode was previously
   dedicated to Linux systems. Disabled by default.
   When in the console mode, the playback occurs automatically after
   starting Ufomod. Most of the keys also work while the playback goes on.

-a | --autoplayback
   This allows to skip the Playlist Editor pane coming up at start.

--resetconfig
   Performs a configuration reset, by defaulting all settings incl. libmikmod
   defaults, flushing the directory cache and the playlist. Carefully !

--listconfig
   Lists all current configuration settings.

--version
   Returns Ufomod version to the 'STDERR' device.

b. Archiver support switches :

--archivercheck
   By default, Ufomod doesn't care about the presence of a certain archiver
   in your system. It just tries to invoke it everytime it is needed, and
   when the call fails, it displays a message. Because archiver invoking can
   take up much time under DOS, we created this switch, which performs
   a presence check of all archivers required by Ufomod, and notifies, if one
   of the archiver is not present in your system. You may notice a great
   speed improvement when scanning many archives not supported in your system.
   All settings are stored in the configuration file.
--enable <archiver>
   Forces some archiver to be enabled. Ufomod will invoke it. The parameter
   is one of the following, currently supported archivers: ace, jar16, lha,
   unimp, pkunzip, unrar, arj. This setting is stored in the configuration.
--disable <archiver>
   Disables the archiver <archiver> support (see also previous one).
   TIP: Useful to ACE v1.1B under Win9x, which seems to hang the system.
   This setting is stored in the configuration.

c. Linux switches :

-H <value> | --refresh <value>
   This command is no longer available since we do not support the colour
   interface to Linux users anymore.

d. Library 'libmikmod' switches :

-v <index> | --driver <index>
   In libmikmod all sound drivers are assigned to a certain value. Driver
   1 is usually the SoundBlaster driver, 2 is the disk writer (see a complete
   list of all drivers available in the current version by --listdrivers)
   and so on. The command tells libmikmod which driver to use. By default,
   the value 0 is used, which means `driver autodetection`. If you don't like
   autodetection, please choose a concrete driver.

-I[+-] | --interpolation[+-]
   Interpolation is a sound mixer feature. Interpolation, also known as
   anti-aliasing, removes sound quantisation effect from the output signal,
   resulting in a smooth, noiseless sound. It is recommended, even if it loads
   your processor a bit more.
   INTERFACE COMMAND: When in the playback pane, use the `I` key to toggle
   interpolation.

-S[+-] | --stereo[+-] | --mono
   Enables or disables stereo mixing and output. This option can be controlled
   only by the command line.

-F[+-] | --fadeout[+-]
   The libmikmod supports a fade out at the end of module playback.

-X[+-] | --extspd[+-]
   This option is not needed to be disabled. It is intended to use with VERY
   old modules which weren't programmed for use with the BPM.

-m <command> | --commit <command>
   This is a low level sound driver commanding switch. You may send your
   command to the sound driver before initialization. See the driver section
   for a list of low level commands of each driver.
   This setting is not stored in the configuration file.

-q
   This command enables the optional high-quality mixer. It mixes the samples
   using 64-bit precision, uses a sample declicking technique and many more.
   Alas, it requires MUCH processing power (a Pentium-66 can cope with up to
   6 channels only!).
   This setting is stored, but ignored in the configuration file.

--listformats
   Lists all module formats supported by the current version of libmikmod.

--listdrivers
   Lists all sound drivers supported by the current version of libmikmod.

UFOMOD IN PRACTICE
------------------

Start Ufomod by executing the executable file. Suprisingly, Ufomod might quit
immediately after start. This is because the player cannot find any modules
in the current folder. Please start Ufomod from the command line prompt as
follows :

> ufomod c:\music\mod\*.mod e:\cdrom\all\*.xm d:\zipped\*

and so on. Everything on the command line, which is not prefixed by `-`
is treated like a module/archive name or mask. Ufomod will `grab` all files
matching those masks in their locations.

Ufomod has also got an another feature, which is called a directory cache.
The directory cache is supposed to scan selected directories for updated
files, for example.

> ufomod -d c:\module_p\ -d d:\music\pack\ -d e:\zipped\xm\

Ufomod will remember those directories and scan them everytime you restart it.
Use it with contents that change constantly.

You can clean the directory cache by specifying the `--cleandircache` on the
command line. The command `--cleanplaylist` also cleans up the current
playlist. A few more does the command `--resetconfig` : it defaults all
configuration settings (use if you have troubles with re-configuration).

Now that you programmed Ufomod to grab some modules, a red
`playlist editor` screen comes up. This is functionally similar to
the WinAmp`s playlist window. Keys that work in this pane :

SPACE - drop module (it falls to the bottom of the playlist and won't
be playable anymore . Note that SPACE works like a toggle - you may
bring a module back by pressing it again). Please don't misunderstand
this. This is a replacement of the `remove from the playlist` command.
You cannot remove anything from the playlist with the editor. To flush
it completely, use the `--cleanplaylist` command.
GREY UP & DOWN ARROWS - move up / down along the playlist
PAGE UP & PAGE DOWN - move by one screen up / down along the playlist
. , - push / pop a module (higher or lower) to change playlist order
ENTER - start to play the playlist sequence, another pane comes up
ESC - quit
BACKSLASH - a randomize mix of the modules

(Note that the playlist is always saved, so there`s no need to worry
about it. Playlist`s size is unlimited. )

After you press ENTER Ufomod will : 1) load the file into memory (takes
more time if the module is compressed); 2) start the playback.
Another colour pane comes up - this is the centre pane of Ufomod, where
you have full control over the playback. In the upper left corner some
important details as the module name, type and description appear. The
played channels are represented by coloured bars, every channel`s pan
is shown too (a bit higher). A module`s sample/instrument list often
contains interesting information about the module and the author itself
- it is also shown by Ufomod as a scrolled list in the lower left blue
window.

On the right side there are `spicy` details about the module playback.
Shortcuts are explained here :

SPM - the ticks / row value
BPM - the beat / minute value
Row - current row played
Pat - total rows in current pattern
Ord - current position in order sequence
Pos - total length of order sequence
Chn - total channels used for playback declared by the module
Vce - number of currently allocated channels (or real channels used by
      the playback - useful when playing modules that use NNA)
Time - current playing time
GlobalV - global volume setting - don`t confuse with module amplification
          setting
LPU - experimental, ignore it (may be used in future versions)

other text :
Mono / Stereo - the current mixer output
Interpolation - antialiasing enabled or disabled
HQ-Mix - high quality mixer enabled or disabled
Surround - surround tracker commands process or ignore

Useful keys :

O - surround toggle
I - interpolation toggle
[ ] - increase/decrease reverbation factor (watch the green indicator)
ESC - stop playing and go back to the playlist editor
INSERT - skip to next song
HOME - pause song playback
PAGE DOWN - skip pattern forward
DELETE - rewind pattern
END - view the playlist editor while playback goes on
1 2 3 4 5 6 7 8 9 0 - set mixer amplify to 10-100%
GREY + - - increase/decrease mixer amplification by 1%

When you press END, the playback will continue while you control your
playlist again. The currently played module is marked. If you want to
return to the playback pane, simply press ESC.

A few examples :

1. Turning on SBPro capable settings with interpolation and fadeout
at the end of song :
> ufomod -f 22050 -b 8 -I -F

2. Reverse stereo, set reverb factor to 10 and use the nosound driver :
> ufomod -v 2 -R -r 10

3. Enable the disk writer to write to file sound.wav in current folder :
> ufomod -v 3 -m file=.\sound.wav

4. Clean dir cache, and enable auto playback :
> ufomod --cleandircache -a

5. Since version 2.2 it is possible to use Ufomod as a commandline player.
The parallel using of directory cache feature is not recommended in this case.
> ufomod -p /mod/ufomod --cleanplaylist -a <module_file>
It loads the configuration from `/mod/ufomod` location, then cleans up the
playlist with `--cleanplaylist`, enables autoplay with `-a` and loads the
module file.

UFOMOD PROGRAMMING LIMITATIONS AND OTHER IMPORTANT ISSUES
---------------------------------------------------------

1. The maximum DOS command line length is 126 chars. You may experience
running out of space when adding too much commands onto the command
line. This is not the fault of Ufomod, but the DOS itself.
There is a workaround : you'll have to use other DJGPP command line tools,
which allow to communicate between DJGPP programs with no commandline
limitations (please read the DJGPP FAQ).

2. Ufomod's internal filename length limitation is 256. A filename/pathname
must not exceed this length.
Workaround: Needs some reprogramming, that can be done rather easy.
Please mail us if this is your case.

3. Ufomod handles Long Filenames under Win9x operating system. Therefore
there might occur errors when loading a playlist with LFNs under DOS. The
solution of this might be the disabling of Windows filename tiling in
the Windows registry (read the Win9x Tips&Tricks tutors for more info).

4. Ufomod is, due to the DJGPP environment, which's emulating the Unix, POSIX
compatible. What does in mean in the practice :
+ the use of forward slashes is allowed
+ filenames may contain POSIX-style masks : `[]` square brackets, for example
> ufomod ./[a-z]*.mod
(for more info on POSIX read the GNU docs)

Unfortunately, Ufomod does not allow:
- command grouping on the command line, for example `-SLX`
- case sensitivity on single score switches like `-q` (`-Q` is not `-q`)

5. Pipelining and STDOUT/STDERR redirecting doesn't work. A switch will appear
in the future versions of Ufomod allowing to redirecting the screen output to
devices.

ARCHIVER SUPPORT
----------------

This version includes basic archiver support. Since now Ufomod is "knowing"
about 7 popular packed formats : RAR, ARJ, ZIP, LHA, J(AR), IMP, ACE.
You will need those compression software, provided by their respective
distributors, usually published over the Internet, installed in your system.
Ufomod will use the following popular archivers developed for MS-DOS :

    - RAR : UNRAR.EXE (tested with RAR up to 2.80) (c)2001 Eugene Roshal
            + no problems with RAR
            + fast processing
    - LHA : LHA.EXE (tested with version 2.55) (c)1992 Haruyasu Yoshizaki
            + no problems with LHA
            + also working with ICE.EXE (rename to LHA.EXE)
    - JAR : JAR16.EXE (tested with version 1.02) (c)1997 ARJ Software
            + no problems with JAR
    - ARJ : ARJ.EXE (tested with version 2.75a) (c)2000 ARJ Software
            + no problems with latest ARJ
    - IMP : UNIMP.EXE (not tested now -> BUGGY?) (c)2000 Technelysium Pty Ltd.
            - see below.
    - ACE : ACE.EXE (tested with versions up to 1.2b) (c)1997 Marcel Lemke
            - terribly slow extraction due to its long initialization
            - version 1.1b contains a bug :
              It recreates the whole TEMP directory structure in the current
              directory everytime you extract to the real TEMP. Since we're
              not going to include any "patches", you're left alone with
              this problem
            - WARNING: ACE often reboots the machine when using with Ufomod
              under Windows !

              WE DO NOT RECOMMEND USING UFOMOD WITH ACE FOR DOS !
              ```````````````````````````````````````````````````

    - ZIP : PKUNZIP.EXE (tested with version 2.50) (c)1999 PKWARE Inc.
            + no problems with PKZIP
            + very fast processing

These executables must be present in your system, available through the
PATH environment variable. Ufomod calls the archiver everytime it lists
or extracts an archive.

Ufomod uses your TEMP environment setting to place its temporary processing
files. If it isn't set, it uses the root directory of the current drive
as the storage place. The temporary files are created only

FURTHER NOTES ON ARCHIVER SUPPORT :
-----------------------------------

1. Ufomod might require additional system memory to cope with the extraction.
An unsufficent memory operation may result in drastical processing slowdown.
Also note, that Ufomod is not able to "return" any detailed archiver message
to the user, so it it very difficult to find out, what's wrong at the time.
Please read the archiver docs for information about the system requirements
for optimal performance.

2. The actual IMP compressor cannot run along with Ufomod (it is a WATCOM
executable). You'll need a 16-bit free extractor of the IMP, that we call
UNIMP.EXE, to get full IMP support. UNIMP.EXE probably doesn't exist at
all, but if there is any DOS tool, that is able to extract IMPs without
using the DOS4GW extender, please rename it to UNIMP.EXE. It will work !

3. Ufomod is able to use the Win32 console versions of archivers. For example,
you may use the Win32 console port of the UNRAR.EXE as long as you operate
under Windows 9x. BTW, read also pt. 5 for LFN warning for Win9x users.

4. Nested archives (archive in an archive) are not supported by Ufomod.

5. LFN WARNING: We do not recommend using archives with long filenames.
Long filenames can be extracted properly ONLY under Windows 9x. Under DOS,
some of the extractors may refuse to extract or extract the files with
short filenames. Ufomod is not aware of when Win9x is active, so it may
try to extract long filenames, which results in an error. This is especially
painful with PKUNZIP, which won't extract files with unordinary names.

6. Multivolume archives are neither supported nor projected to be used with
Ufomod. WARNING! The use of such files may result in unexpected program
behaviour depending on the archiver type. Ufomod doesn't know about the
recognition of such archives !

Problems that left to be fixed :

7. There is a problem in the current loading system with filenames using
multiple dots under Windows. Extracting & loading such modules (like
`fade.grey.xm`) will cause in file open errors.

8. Ufomod properly extracts modules from archives with subdirectory
information. It consequently has to recreate the directory structure of the
module, storing it in the temporary directory. Ufomod does remove the
temporary module file, but it doesn't remove the empty directories.

ENGINE, DRIVERS AND MORE (DOS/Windows)
--------------------------------------

Ufomod 2.3p2 has been compiled with libmikmod version 3.1.10 modified beta 1.
For details about the GPL project itself read the supplied Doc/*.mikmod files.
Libmikmod 3.1.10 supports a wide range of various module formats and a few
software sound driver. A few more will hopefully be supported in the future.

WHY LIBMIKMOD ?
1. Libmikmod is a very accurate module player. The 3.1.10 version included in
Ufomod has a several bugfixes and improvements.
2. It supports the widest range of module formats.
3. Its source is available for FREE to everyone within the General Public
License.

THE SOUND DRIVERS
Ufomod is equipped with different audio software drivers. The current
version includes drivers :
- Sound Blaster or compatible (1.x/2.x/Pro/16) Driver v1.2.1 BETA (index 1)
- Disk Writer (index 2)
- Nosound Driver (index 3)

1. SOUNDBLASTER
The SB driver has been tested with various sound cards (utilising PCI
or ISA bus) that were AC'97 compatible and is known to work. Note,
that on AC'97 compatible cards there will be no 16-bit / 44KHz
available, because the SB Pro can cope with 22KHz / 8-bit only.
General problems may occur when setting to 8-bit / mono outputs. Since
the Sound Blaster driver has been rewritten, it is possible to play correctly
in 44KHz only. Going down below 40KHz will cause a warning to appear, since
the beta driver still produces bad sound in this case.

WE DO NOT RECOMMEND 8-BIT SOUND, since it does not fit high fidelity
requirements these days. Don't complain about relatively worse sound output
while playing 8-bit cards.

AC'97 OR SOUNDBLASTER PRO COMPATIBLE ?!
Because the most cards on the market are AC'97 compatible, there shouldn't
be any problems with playing modules in 8-bit / 22KHz. You should know that
there's no difference between AC'97 and SB Pro in compatibility.
The following table shows the possible SB compatible configurations :

      card ->        |   AC'97/SBPro       |  SB16/64/128/Live!..
     ------------------------------------------------------------
      channels ->    |   mono / stereo     |     mono / stereo
     ------------------------------------------------------------
     8-bit 22KHz     |    yes(* / yes      |    yes(* / yes
     8-bit 44KHz     |    yes   / no       |    yes   / yes
     16-bit 44KHz    |    no    / no       |    yes   / yes

In short: The highest possible frequency in a SBPro card is 44KHz sampled
8-bitin mono. On a SB16 compatible sound card (very few on the market) or
latest SoundBlasters there are no configuration problems as far as we know.

*) Another 8-bit mono WARNING :
Although the 8-bit 22KHz mono and lower settings are possible, we can't
promise a problemless playback. Since the SB driver has been reprogrammed,
there is more support for 8-bit mono playback, but only at sample rates >=40KHz.
Lower rates cause synchronization problems resulting in skips/gaps/clicks
in the playback, depending on your hardware configuration. So, if you have to
use 8-bit mono, PLEASE SET THE SAMPLE RATE TO 40KHz OR HIGHER (ex. 44KHz).

Ufomod is a *VERY* configurable player. It takes care of the BLASTER
settings, too. So, if you have detection problems, please run your sound
configurator and set up to SoundBlaster Pro mode (T4).

The Sound Blaster driver can be configured at a very low level by the use of
the `-m` command. Supported driver command :
`-m dmasize=xxxxx` : set the size of the DMA buffer in range 1024-8192.
The value must be powers of two (1024, 2048, 4096, 8192).

2. DISK WRITER
The disk writer allows to save the signal output to a Microsoft RIFF format
compatible WAV file on the hard disk. To specify output path\file, please
use the low level command sequence :
`-m file=[path\filename]`

3. NOSOUND DRIVER
This driver is for testing only. It does not produce any sound, instead can be
used to check system and video compatibility etc, as well as performance
measuring.

WANT TO HELP IN DEVELOPING UFOMOD ?
-----------------------------------

What we need is the mikmod-3 for DOS, released a long time ago, maintained
by Jake Stine, the creator of the WinAMP module plugin.  Please mail, if
you have the sources .


SUPPLIED MODULE
---------------

There are no supplied modules within the pack. We decided not to attach any
file to keep the pack as small as possible. You can get mod files from
the Internet (check www.modarchive.com, for example).

UNINSTALL
---------

No uninstall available.

CONTACT
-------

Please mail ONLY when necessary (BTW, did you REALLY read the FAQ?) :
ufo303@poczta.onet.pl

[UfoLogic Systems]