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 .. 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 Tells Ufomod to cache 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 | --cfgpath 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 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 Disables the 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 | --refresh This command is no longer available since we do not support the colour interface to Linux users anymore. d. Library 'libmikmod' switches : -v | --driver 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 | --commit 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 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]