AdPlug Winamp plugin v1.8.2 (in_adlib.dll)

Copyright  1999 - 2007 Simon Peter <dn.tlp@gmx.net>
Copyright  2002 Nikita V. Kalaganov <riven@ok.ru>
Copyright  2010 Wraithverge <liam82067@yahoo.com>

Website: http://adplug.sourceforge.net
Module Archive: http://chiptunes.back2roots.org

Description:
------------
AdPlug is a Winamp input-plugin.  Winamp is a fast, high-fidelity audio
player for Windows (get it at www.winamp.com).  AdPlug plays music that was
originally composed for the AdLib (OPL2) and Sound Blaster (Dual OPL2/OPL3)
audio boards directly from its original format via an emulator, or by using
real hardware.  No OPL chip is required for playback, though.

Installation:
-------------
You will need to extract the files from this archive to your Winamp plugin
directory (on most machines, this will be C:\Program Files\Winamp\Plugins).

If the plugin does not show up in Winamp's input-plugin dialog after you have
installed it, then perhaps your computer does not meet AdPlug's system
requirements.  The file named "MSVCRT.DLL" needs to be in your system path
(for examples C:\WINDOWS\SYSTEM or C:\Windows\System32) for in_adlib to work.
If for some odd reason you do not have it (Win95 OSR2 and greater installs a
copy of it by default), you can get it from the internet; just launch your
favorite search engine to find it.

Usage:
------
Click on the top-left button on the Winamp title-bar, and select "Play" -->
"File..." to browse for and open a supported file.  Double-click on the song-
name field to display some information about the currently playing song.  By
default, AdPlug is automatically configured for most supported file-types.

Configuration:
--------------
To configure AdPlug, click on the top-left button on the Winamp title-bar,
and then select "Options" --> "Preferences...".  Note that you can also press
[Ctrl]+[P] to go directly to the "Winamp Preferences" dialog panel.  On the
left field, under "Plug-ins", click on "Input".  In the "Input plug-ins"
field, locate "AdPlug" on the list of available plugins, and either click on
the "Configure" button, or, double-click on the line with the plugin's name.

Output Tab:
-----------
- Emulator 1 -
This output method uses a very accurate OPL emulator, which was originally
written by Tatsuyuki Satoh, but was later improved by Jarek Burczynski.

  - Harmonic Effect -
  This option fully utilizes a process that pitch-shifts OPL2 data very
  slightly on one channel in order to produce a psuedo-stereo Phaser-like
  effect from a mono source.  Two copies of "Emulator 1" are generated for it
  to accomplish this goal.  Note that a prerequisite for this option to work
  is that "Emulator 1" must be selected as the chosen emulator.  Also note
  that this option will force 16-Bits Stereo modes, and you will not be able
  to change either of those options unless this option and "Dueling Synths"
  are both disabled.

- Emulator 2 -
This output method uses a somewhat inaccurate OPL emulator, which was written
by Ken Silverman.

  - Dueling Synths -
  This option utilizes the OPL2 Synth Wrapper's ability to host two separate
  streams of OPL2 data simultaneously and output the combination as 16-Bits
  Stereo PCM data.  One copy each of Mr. Satoh's and Mr. Silverman's
  emulators are generated for it to accomplish this goal, with them being
  heard respectively on the left and right channels.  Please note that a
  prerequisite for this option to work is that "Emulator 2" must be selected
  as the chosen emulator.  Also note that this option will force 16-Bits
  Stereo modes, and you will not be able to change either of those options
  unless this option and "Harmonic Effect" are both disabled.

- OPL2 at Port # -
If you have an OPL2-compatible sound-card, then you can select this output
method to utilize its on-board hardware chip.  You may need to specify a
different OPL2 port as a parameter in order for it work, though (388 is the
default port).

  - No OPL2 Testing -
  If you have problems with the "OPL2 at Port #" setting, then you can enable
  this option to bypass the hardware checks.

- Disk Writer (RAW Format) -
This output method will produce .RAW files, which can also be played-back by
AdPlug.  A very useful fringe benefit of this option is that you can use it
to convert any supported file-type to .RAW, and then convert that to a .MID
file with DRO2MIDI.

Beneath this setting, you can specify the output path that all .RAW files
will be written to via a wide button (the root of C:\ is the default path).

Note that this option is not to be confused with the Nullsoft Disk Writer
output-plugin of Winamp, itself.  If you want to create .WAV, .OGG, or some
other form of compressed audio file, then first select one of the other
output-methods of in_adlib, and then use the Nullsoft Disk Writer plugin,
instead.

Playback Tab:
-------------
- Auto-detect Song End -
If you disable this option, then doing so will make songs play endlessly
(that is, if they have Loop Points), just like the old Mod Players do.  Note
that, obviously, you can forget about using play-lists when doing this.

- OPL2: Fast Seek -
This option is only needed when you have chosen hardware-OPL2 output.  If
seeking takes too long on your machine, then you can enable this option to
make it significantly faster.  The drawback with it is that the player will
not preserve the module commands that would normally have been played during
the time you have skipped, and the module may sound a bit wrong for a short
amount of time after the seek.

- Disk Writer: Standard Refresh Rate -
This option is only used along with .RAW Disk Writer output.  If this option
is enabled, then AdPlug will write the output to disk at the same speed as
you normally hear it, so it will take significantly longer to finish.  When
this option is disabled, it will write the output to disk just as fast as it
possibly can.

- Database: Use Database -
If this option is checked, then AdPlug will use a database file to get
special information for playing some problematic file-types.  An up-to-date
version of the database can be downloaded from AdPlug's website.

Just below this option, you can specify the path to a database file via the
wide button (the default path is the "... \Winamp\Plugins" directory).

- Thread Priority -
This option can be used to make AdPlug a more or lesser important task in
your system.  If you have several other CPU-intensive programs open at the
same time as Winamp, then you may need to increase this setting until
in_adlib begins to play songs smoothly again.  Note that the setting of
"Real-time" is definitely not recommended, as it may cause your system to
become unstable or unresponsive.

Formats Tab:
------------
On this tab, you can choose from all of the formats that AdPlug supports.
If you have got other plugins that can also handle some of these file-types
(for examples, .IMF and .MID), then you can deselect them here, and AdPlug
will not try to play those types of files (that is, until you select them
again, of course).  Remember to restart Winamp after you have made any
changes, since this is usually necessary for it to update completely.

- S3M File work-around for Nullsoft Module Decoder Plugin -
This option works in conjunction with Nullsoft's Module Decoder Plugin.  It
is enabled by default, and it fixes a problem with sample-based S3M files not
playing anymore when AdPlug is told to handle .S3M files.  While the option
is enabled, the .S3M format will be hidden on the list.  Therefore, when you
disable this option, .S3M will appear on the list the next time you start
Winamp, and then you can select or deselect it as a playable file-type.

Supported formats:
------------------
AdPlug implements unique audio players for each supported format in order to
achieve the best possible quality of sound reproduction.  All currently
supported file formats are listed below, along with some information about
possible playback issues.  Players marked as "preliminary" are not considered
to be final by the author(s), therefore, those may contain many compatibility
issues, however, they are being included for the purpose of testing them.

- A2M: AdLib Tracker 2 by subz3ro
  - File format versions 1, 4, 5 and 8 are supported.
  - Unimplemented commands (version 1-4): FF1 - FF9, FAx - FEx
  - Unimplemented commands (version 5-8): Gxy, Hxy, Kxy - &xy
  - In version 5-8 files, some parts of the flags byte are ignored.
  - Only SixPack compressed and uncompressed files are supported.
  - OPL3 support for versions 5 through 8 files.
- ADL: Westwood ADL File Format
- AMD: AMUSIC Adlib Tracker by Elyssis
- BAM: Bob's Adlib Music Format by Bob
- CFF: BoomTracker 4.0 by CUD
- CMF: Creative Music File Format by Creative Technology
  - Supports Rhythm mode.
  - Supports Note Velocities within songs of which contain them.
  - Improved support for CMF v1.0 files.
- D00: EdLib by Vibrants
  - Bugs: Hard restart SR sometimes sound wrong.
- DFM: Digital-FM by R.Verhaag
- DMO: Twin TrackPlayer by TwinTeam
- DRO: DOSBox Raw OPL v1.0 and v2.0
- DTM: DeFy Adlib Tracker by DeFy
- HSC: HSC Adlib Composer by Hannes Seifert, HSC-Tracker by Electronic Rats
- HSP: HSC Packed by Number Six / Aegis Corp.
- IMF: Apogee IMF File Format by Apogee
  - Supports Adam Nielsen's Tag format.
- JBM: JBM Adlib Music Format
- KSM: Ken Silverman's Adlib Music Format by Ken Silverman
  - Needs "insts.dat" to be in the same directory as the loaded file.
- LAA: LucasArts AdLib Audio File Format by LucasArts
  - Bugs: Some volumes are a bit "off".
- LDS: LOUDNESS Sound System
- M: Ultima 6 Music Format by Origin
- MAD: Mlat Adlib Tracker
- MID: MIDI Audio File Format
- MKJ: MKJamz by M \ K Productions (preliminary)
- MSC: AdLib MSCplay
- MTK: MPU-401 Trakker by SuBZeR0
- RAD: Reality ADlib Tracker by Reality
- RAW: RdosPlay RAW file format by RDOS
  - OPL3 support.
- RIX: Softstar RIX OPL Music Format
- ROL: AdLib Visual Composer by AdLib Inc.
  - Needs "standard.bnk" to be in the same directory as the loaded file.
- S3M: Scream Tracker 3 by Future Crew
  - Bugs: Extra Fine Slides (EEx, FEx) and Fine Vibrato (Uxy) are inaccurate.
- SA2: Surprise! Adlib Tracker 2 by Surprise! Productions
- SAT: Surprise! Adlib Tracker by Surprise! Productions
- SCI: Sierra's AdLib Audio File Format by Sierra On-Line Inc.
  - Needs '???patch.003' to be in the same directory as the loaded file,
    where "???" are the first 3 characters of the loaded file.
  - Bugs: Some instruments are incorrectly reproduced.
- SNG: SNGPlay by BUGSY of OBSESSION
- SNG: Faust Music Creator by FAUST
- SNG: Adlib Tracker 1.0 by TJ
  - Needs 'songname.ins' to be in the same directory as the loaded file,
    where "songname" is the song's file-name, but with the ".ins" extension.
- XAD: eXotic ADlib Format by Riven the Mage
- XMS: XMS-Tracker by MaDoKaN/E.S.G
- XSM: eXtra Simple Music by Davey W Taylor

Known Problems:
---------------
The hardware-OPL2 output method will not work with SoundBlaster AWE32/64
sound-cards on-the-fly.  The plugin will detect their OPL chip properly, but
there will be no sound output.  This is because of an issue with the Creative
FM driver.  To work-around the issue, just follow this sequence of steps:

 1) Move "FMSWITCH.BAT" to the root of your C:\ drive.
 2) Reboot your system into DOS mode.
 3) Run the batch-file to disable the SB16 virtual device driver.

Real-time song position display in AdPlug's file-info box is ahead of the
sound heard when an emulator is used.

Hardware-OPL2 output on Windows NT/2000/XP:
-------------------------------------------
AdPlug is capable of using a hardware-OPL2 chip also under Windows NT/2000/
XP!  In order to do it, AdPlug can use the PortTalk device driver.  This
driver can be downloaded from:

http://www.beyondlogic.org/porttalk/porttalk.htm

After downloading the driver, please read the enclosed PDF file for
installation instructions.  I strongly recommend that you do the manual
installation method, by using the REG file!
