/*****************************************************\
*      MOD Plugin - (c) 1997 by Olivier Lapicque      *
*                                                     *
*               - Distribute freely -                 *
*                                                     *
*         contact: c1lapicq@watson.ibm.com            *
*                                                     *
*    (Special thanks to MisterX for the graphics)     *
\*****************************************************/


- 1. Requirements
- 2. Installation
- 3. How do I use the MOD Plugin in my HTML files ?
- 4. Can I use the MOD plugin to play my modules on my
     local hard drive ?
- 5. What's new ?
- 6. Using NPMOD32.DLL in your programs.
- 7. Troubleshooting

-------------------------------------------------------
1. Requirements
-------------------------------------------------------

- DX2-66 or higher
- Windows 95 or NT 4.0.
- A soundcard with 32-bit drivers
- Netscape Navigator 3.0, or Microsoft Internet Explorer 3.0
- Make sure the setup program points to the correct path of your
  browser, especially if you had or have multiple browsers versions
  installed (they always leave some crap in the registry).

NOTE:
  44.1KHz sound quality is not recommended for computers
  slower than a 486DX4-100.

MOD-Plugin is a freeware and may be freely distributed.
As it is a freeware, I am not responsible for any
problems that could be caused by the usage of this plugin.

MOD-Plugin is a *light* version of ModPlug Player. In order to
limit the CPU usage, the number of simultaneous channels is
limited to 20 (It can go up to 80 in ModPlug Player).
Also, there is no volume ramping, or any click removal.
There is also no MultiPoint oversampling option.

To save a song, or configure the sound quality, right-click
on the controls, and a menu will be displayed.

Setup Options:
--------------

- Mixing Rate, Stereo, 16-Bit: quality of the sound

- Bass Expansion: The name speaks for itself.
  (It doesn't take a lot of extra CPU).

- Disable oversampling: you should not use this option,
  unless you have a slow CPU. You can try to listen to
  the music with and without oversampling to see the
  difference.

- Save packed songs: pack the samples when saving songs,
  using the Sae As command (Can reduce up to 50% the size of the
  song).

---------------------------------------------------------
2. Installation
---------------------------------------------------------

- Execute modsetup.exe and follows the instruction.
  You must select the path where your browser is installed.

- Launch your browser (If it was already launched, you'll
  need to quit and restart it).

- Check for updates at "http://www.castlex.com/modplug".


---------------------------------------------------------
3. How do I use the MOD Plugin in my HTML files ?
---------------------------------------------------------

The syntax to put a song in your page is the following:

<EMBED SRC="whatever.mod" width="145" height="48" ...>

NOTE:
  On a Web server, the command should also include the mime-type:

<EMBED type="audio/x-mod" src="whatever.mod" ...

The mime-type used by the MOD Plugin are the following:
audio/x-mod
audio/mod
audio/s3m
audio/xm
audio/x-zipped-mod (1.71+)
audio/x-zipped-it (1.81+)
audio/it (1.81+)

But you can always put any mime type for different file types:
audio/mod works with a s3m file, and vice-versa.
You should use "audio/x-mod" for all modules.
(You can also play NST, WOW and 669 files: just rename them into .MOD)

PLEASE DO NOT USE "audio/x-xm" and "audio/x-s3m"!!! I will remove
them if I need more MIME types. (audio/x-xm is not supported since
version 1.65 - use audio/xm or audio/x-mod instead)


That's it!


NOTE: Don't forget to use the packing option of the plugin:
  you'll need to use the "Save packed songs" options in the
  setup dialog, and save the song. This can make the file
  twice smaller. When the user will download the file from
  your page, it will be unpacked. It can make a big difference
  when downloading a file larger than 200K.


The other options you may want to add are the following:
- volume="x": set the volume of the song to x.
  (Default="100", range="1" to "100")

- loop="true": Loop the song. (Default:"false")

- autostart="true": Start playing the song when loaded.
  (Default="false"). (Also "autoplay" on versions 1.31+)

- autonext="true": Jump to next mod when finished playing.
  (Default="false") This is useful only if you have more
  than one song in your page. (You should use loop="true"
  instead to make the same song loop)

- controls="none"/"stereo":
  * "none": don't display anything - use with care
   because there is no way the user will be able to stop the
   mod (besides exiting the page). (same as "hidden="true")
  * "stereo"(1.65+): the horizontal spectrum analyzer will
   be split for right/left, on each side of the plugin.
   In this case the number of bands will be (width - 184) / 16.
  NOTE (1.75+): The option controls="smallconsole" has been
  removed, it's now automatic if height < 20.

- hidden="true": same as controls="none".

- title="song_title": Displays the text "song_title" when
  the song is not yet loaded. (Default: displays "Loading...")

- shuffle="true" (1.57+): goes along with autonext="true".
  when a song finishes playing, the next song will be randomly
  chosen. The shuffle option is a global flag and should appear
  on the first EMBED section in the page. This flags sets
  the autonext="true" flag automatically.

- bgcolor="black"(default),"gray" (1.60+): Select a background color
  for the plugin.
  v1.75+: you can specify a color like bgcolor="#RRGGBB".

- spcolor="red"(default),"green","blue" (1.61+): Select the color of
  the spectrum analyzer.
  v1.75+: you can specify a color like spcolor="#RRGGBB".

- vucolor="color1", vucolorhi="color2" (1.75+): you can now change
  the color of the VU-meter. The default for vucolor is green, and
  is red for vucolorhi.

- spcolorhi: defines the top-color of the spectrum analyzer (1.75+).
  The default color is red. The middle color will be the mix between
  spcolor and spcolorhi.

- autoload="false" (1.77+): if autoload is "false", the file will not
  start loading unless the user tries to play the mod. The default is
  autoload="true".

NOTE: (v1.43+)
--------------
- If you want to enable the VU-Meter, the width parameter
  should be set to "168". The VU-Meter cannot be used with
  the controls="smallconsole" option.
- If the plugin is hidden (with controls="none" or hidden commands),
  autostart will be set to "true".

Spectrum Analyzer (1.60+)
-------------------------
- You can enable the spectrum analyzer by setting a height
  of 96 (bottom spectrum) or a width of 336 (right spectrum).
- v1.61+: You can have from 3 to 80 bands in your right spectrum
  analyzer: set the width parameter to 176+(numbands*8).
  The frequency range is between 86Hz (left) and 11KHz (right).
- v1.65+: With the stereo spectrum, the number of bands on each
  side will be (width - 184) / 16.
 

--------------------------------------------------------
4. Can I use the MOD plugin to play my modules on my
   local hard drive ?
--------------------------------------------------------

Well, of course.
Create a modlist.htm file in your modules directory,
with a line for each module (Try not to put more than
10 mods on the same page, because they will all be 
loaded in memory)

The file should look like that:

<HTML>
<HEAD>
<TITLE>Ultra-trance-tekkno-rave mod page</TITLE>
</HEAD>
<BODY>

<P><A HREF="prevpage.htm">Previous Page</A></P>

<P><EMBED TYPE="audio/x-mod" SRC="mod01.mod" width="145" height="48" autostart="true" autonext="true"></P>
<P><EMBED TYPE="audio/x-zipped-mod" SRC="mod02.mdz" width="168" height="48" autonext="true"></P>
<P><EMBED TYPE="audio/x-mod" SRC="mod03.s3m" width="145" height="48" autonext="true"></P>

<P><A HREF="nextpage.htm">Next Page</A></P>

</BODY>
</HTML>

* end of file *

After that, you can open this file in Netscape in
File - Open File in Browser.

And voila !



--------------------------------------------------------
5. What's new ?
--------------------------------------------------------

------------- MOD Plugin version 1.8 -------------------
1.88:
- Updated to modplug sound library v1.30

1.87:
- Removed the Save as WAV option
  (you should use ModPlug Player for better quality)
- Upgraded to modplug sound library v1.28

1.86:
- Reduced size of the DLL.
- Upgraded to modplug sound library v1.26

1.85:
- Fixed Bug with position slider
- Upgraded to modplug sound library v1.25

1.84:
- Upgraded sound library to ModPlug Player 1.24
- Added ModPlug_CreateEx DLL export, for an easier interface with VB.

1.83:
- Upgraded sound library to ModPlug Player 1.21
- Fixed bug when saving IT modules (could corrupt end
  of patterns).
- Added support for zipped FAR modules (audio/x-zipped-mod)
- Autodetect Netscape Communicator path.

1.82:
- Upgraded sound library to ModPlug Player 1.19
- Added support for WAV files, and zipped WAV files,
  but they have to be renamed in .MDZ.
- Removed audio/mtm and audio/med mime types: use audio/x-mod instead.

1.81:
- Upgraded sound library to ModPlug Player 1.17
- Added GetPos, GetMaxPos and SetPos Java functions.

1.80:
- Faster mixing.
- Improved IT support.
- More DLL exported functions.

------------- MOD Plugin version 1.7 -------------------
1.78:
- Improved IT support.
- Fixed a crash bug with Surround.
- Improved player (A little bit faster).
- Upgraded Sound Library to ModPlug Player 1.15.

1.77:
- Added the "Enable Java" option in the setup, since it can cause some
  browsers to be unstable.
- Added IsReady() java function: returns TRUE if the mod finished loading.
- Fixed bug with loop="false", autostart="false" and shuffle="false" command.
- Added the autoload="false" option.

1.76:
- Fixed CRASH with Internet Explorer (That's it!)
- Fixed Java bug.

1.75:
- Mod-Plugin is now Java-Enabled !!! (With Netscape 3.0+)
  Available functions are Play(), Stop(), IsPlaying() and GetVersion().
- Added spcolorhi, vucolor and vucolorhi embed tags.
- Removed controls="smallconsole" (Automatic with height < 20).
- Fixed a bug in the XM loader.

1.74:
- Removed Reverb.
- Added Bass Expansion option.
- Improved player (Same as ModPlug Player 1.11).

1.73:
- Improved modsetup.exe (no more archive).
- Removed modlinks.htm - you can get it in the "deluxe version".

1.72:
- Improved ZIP support.
- Updated sound library to match ModPlug Player 1.07.

1.71:
- Improved setup.exe
- Changed audio/mdz to "audio/x-zipped-mod".
- Updated sound library to match ModPlug Player 1.03.

------------- MOD Plugin version 1.6 -------------------
1.69:
- Fixed tone-portamento bug in MOD files.
- Fixed vibrato depth bug.
- Misc. small bugs fixed.
- Pitch/Pan separation is no more lost when saving IT files.

1.68:
- Added support for instrument auto-vibrato in XM/IT.
- Fixed bug in Volume/Pan envelope interpolation.

1.67:
- Fixed panning envelope bug.
- Fixed tone-portamento bug.
- Fixed Global Volume (0) bug.
- Added Zipped-Module support (*.mdz): In order to play zipped mods,
  you can zip them with any zip archiver (like PKZIP) and rename them
  into .MDZ. To get the maximum compression level, you should first use
  the Save Packed Songs option, and then zip the packed song.
  example, to make mymod.s3m as small as possible:
     - Check Save Packed Songs
     - Use "Save As" and save the song as mymod1.s3m
     - use PKZIP mymod.mdz mymod1.s3m
- Removed MIME-Type audio/669. You should now rename any 669 modules
  into another supported extension.

1.66:
- Fixed registry problem (associations lost).
- Fixed panning slide bug.
- Added MOD surround support (8A4)
- Improved IT save function.
- Improved MOD loader.

1.65:
- audio/x-xm MIME-type has been removed (I needed room for .669)
- Fixed another HUGE bug (crash) with some mods (in all formats)
- Added Channel Volume Slide and Global Volume Slide effects.
- Added Save As support for IT modules.
- Added beta 669 support.
- Added controls="stereo" option for the spectrum analyzer.

1.64:
- Added most of the Impulse Tracker effects.
- The Save As MOD is now more powerful when converting from S3M/XM.
- Better MED support.
- Fixed a HUGE bug if 'force amiga limits' flags was set in S3M.

1.63:
- Added volume and pan envelopes support in XM modules.
- The packing option now converts 16-bit samples to 8-bits.
- The Set Filter amiga command can disable the oversampling.

1.62:
- Envelope information in XM modules is no more lost.
- Added pre-alpha support for IT modules (sample mode only).
- Fixed possible crash in replay routine.
- Portamento Slides were too fast in MODs.
- Note Delay was broken since 1.60.

1.61:
- Added "spcolor" option.
- Spectrum Analyzer is more accurate.

1.60:
- Added support for conversion to MOD/S3M/XM from any format.
- Added MTM modules support (import).
- Added Global Volume effects.
- Fixed VU-Meter bug when Surround was used.
- Added 20-bands Spectrum Analyzer
- Added Panning Slide effect in XM modules.
- Added Reverb option.
- Reduced total size of sound buffer from 1.6s to 1s.

------------- MOD Plugin version 1.5 -------------------
1.57:
- The replay routine runs now in a separate thread.
- Improved the Pre-Amplification option by clipping the sound.
- Added "shuffle" option.

1.56:
- MAJOR BUG FIX: Save As was corrupting MOD files with version 1.55
- Decreased size of sound buffer but increased number of buffers
- Fixed bug in S3M when sample loop end was bigger than sample length.
- "Loading..." is displayed when loading a module.

1.55:
- Fixed WAV file format bug.
- Fixed font display bug when displaying the song title.
- Updated MODLINKS.HTM

1.54:
- Added FastVolSlide & AmigaLimits flags in S3M modules.
- Fixed Speed 0 bug in MOD/XM.
- Fixed XM instrument panning bug.
- Fixed finetune bug in MODs.
- Fixed vibrato bug
- Too high frequencies are not played anymore (>200KHz).
- Added support for linear frequencies in XM modules.
- Added Save As Wave option (.wav export)

1.53:
- Instruments are now saved unsigned in s3m MODULES.
- Unused channels are now removed in S3M modules..
- Pattern Break bug fixed in XM modules.
- Song slider bug fixed.

1.52:
- Added OctaMed MMD2/MMD3 support.
- Song slider bug fixed.
- Minor bugs fixed.

1.51:
- Added basic support for OctaMed MMD0/MMD1 Modules (*.med)
- Added audio/x-xm and audio/x-s3m MIME-type (They were removed
  in 1.50 - but I saw some sites using them)

1.50:
- Added support for 16-bit samples (S3M,XM)
- Fixed VolSlide(0) in MODs
- Optimized play function

------------- MOD Plugin version 1.4x -------------------

- Now set the correct tempo when changing the position
- Improved XM support (fixed tempo<->speed) bug.
- Added Pro-Logic Surround and Pre-Amplicication options.
- Added XM key off/fadeout support.
- Added E8x effect in MOD/XM.
- Added 32KHz and 48KHz sound quality.
- Added X1/X2 effects in XM files.
- Added default "Loading..." while downloading a file.
- Fixed possible crash with Note Delay effect.
- Fixed Offset 0 effect bug
- Fixed retrig bug
- Fixed FineTune bug
- Fixed arpeggio bug
- Fixed volume slide bug in S3m.
- Fixed setup bug for MSIE when the plugins directory
  didn't exist.
- Recognises "looping" same as "loop" (for compatibility
  with the DSM Mac plugin).
- Fixed bug when "properties" was used before the module
  was loaded. (Properties screen was staying blank)
- Fixed VU-Meter bug in 8-bit format (always in the red)
- Fixed a problem that caused clicks in some loops
- Fixed S3M bug in Fine & Extra Fine Portamento Up/Down
- Fixed Note Delay problem with non-zero volume column byte
- Added MODLINKS.HTM to the package.
- Added VU-Meter.
- Added Glissando Control.
- Remember the last song position.
- Added multisample instrument support in XM files.
- Changed SETUP.EXE to support Internet Explorer.

------------- MOD Plugin version 1.3x ------------------

- Fixed bugs with Note Delay, Tremor and Retrigger.
- Added Save As for XM files (multisample instruments
  are not supported yet)
- Improved S3M Load/Save function
- Support for patterns with more than 64 rows in XM files.
- Minor other adjustments
- Added support for 16-bit samples
- Added effects on XM files.
- Added "hidden" option (same as "controls="none").
- Added Note Delay effect in MODs (EDx).
- Increased size of sound buffer.
- MAJOR bug fix in s3m modules.
- Added basic XM support (no effects and no Save As...).
- Fixed Netscape crash when changing page before load completed
- Added channel pan position effect.
- Added support with up to 32 channels for s3m modules.
- Added autoplay same than autostart.
- Added 4-bit ADPCM support for modules: this can make the module
  twice smaller! But WARNING: your other players/trackers will
  probably not support ADPCM, and will not be able to load the
  samples -> By default, the plugin will unpack the songs when
  saving. If you want to pack them, check the "Save packed songs"
  checkbox in the Setup dialog, and use the Save As command.
  If the "Save packed song" option is not checked, the song will
  be save unpacked, even if it was packed before. It can then be
  loaded by any tracker/player.

  This is very useful for the internet since it will be twice faster
  to download the module. (Think about it if you want to put a module
  on your home page)

  ATTENTION DEVELOPPERS: (If you want to support the packed format)
  When saving the song, the plugin will pack the samples only if
  it doesn't affect the quality. In MOD files, the sample data starts
  by "ADPCM". In S3M the regular compression byte is used with a value
  of 0x04. 4-bit ADPCM is coding the delta values between a sample and
  the next in 4-bits (starting value is zero). The delta values are
  stored as a 16-byte table at the start of the sample data:
  [16-bytes delta values][(length+1)/2 bytes of 4-bit indexes...]
  In XM files, the bit 6 of the sample type is set to 1, and the reserved
  byte is set to 0xAD. In IT files, the sample flags byte is set to 0xFF.


------------- MOD Plugin version 1.2x ------------------

- Added Retrig effect on MOD files (E9x command)
- Added Pattern Delay effect on MOD files (EEx command)
- Added Pattern Loop effect
- Added 'title' option.
- Added S3M support
- Added channels, instruments and patterns in the 
  properties box.
- Fixed some clicks problems in modules with an odd
  number of channels.
- Added README.TXT (this file).


------------- MOD Plugin version 1.1 -------------------

- Fixed problems with some NT sound drivers.
- Fixed "Netscape will launch the application..." 
  message when you had a mod player already installed.
- Added support for mods with more than 16 channels.


------------- MOD Plugin version 1.0 -------------------

First release of the plugin.

- Support up to 16 channels mods.
- Sound interpolation for each track remove metallic
  quality of the sound. (Like what the GUS does in 
  hardware) (256x oversampling)

-------------------------------------------------------
6. Using NPMOD32.DLL in your programs
-------------------------------------------------------

If you can access the public functions available in a
DLL, it's very easy: here is the C prototype of those
functions:
- LPVOID WINAPI ModPlug_Create(UINT argc, LPSTR argn[], LPSTR argv[])
  This function creates a plugin: argc is the number of 
  parameters on the HTML command line, argn is an array of 
  pointers to the parameters names, and argv is an array of
  pointers to the parameters values.
  This function returns NULL if it failed, or else, it's
  a pointer that you should keep for all the other functions.
- BOOL WINAPI ModPlug_Destroy(LPVOID plugin)
  This function destroys a plugin created by ModPlug_Create.
- BOOL WINAPI ModPlug_SetWindow(LPVOID plugin, HWND hwnd)
  This function should be called right after ModPlug_Create,
  with the window handle of the window where the plugin will
  draw itself. You are responsible for creating this child window.
- BOOL WINAPI ModPlug_Load(LPVOID plugin, LPCSTR lpszFileName)
  This function loads a module.
- BOOL WINAPI ModPlug_Play(LPVOID plugin)
  This function starts playing the module loaded.
- BOOL WINAPI ModPlug_Stop(LPVOID plugin)
  This function stops playing.
- DWORD WINAPI ModPlug_GetVersion()
  This function returns the current version of the plugin:
  ie: for version 1.75, it will return 0x175.
-------------------- v1.80+ additions -------------------------
- BOOL WINAPI ModPlug_IsReady(LPVOID plugin)
  Returns TRUE is a song is correctly loaded.
- BOOL WINAPI ModPlug_IsPlaying(LPVOID plugin)
  Returns TRUE is the plugin is currently playing a song.
- DWORD WINAPI ModPlug_GetMaxPosition(LPVOID plugin)
  Returns the maximum position of the song.
- DWORD WINAPI ModPlug_GetCurrentPosition(LPVOID plugin)
  Returns the current playing position. (Between 0 and ModPlug_GetMaxPosition)
- BOOL WINAPI ModPlug_SetCurrentPosition(LPVOID plugin, DWORD nPos)
  Sets the current playing position.
-------------------- v1.84+ additions -------------------------
- LPVOID WINAPI ModPlug_CreateEx(LPCSTR lpszParams)
  This function is identical to ModPlug_Create, but you can simply
  use a string, instead of an array of strings. Each keyword must
  be separated by a '|' character (It works also with carriage return).
  For example, the command <loop="true" vucolor="#ff00ff"> should
  be sent as "loop|true|vucolor|#ff00ff|".

-------------------------------------------------------
7. Troubleshooting
-------------------------------------------------------


- I don't like the MOD Plugin, it's crap and I hate it.

  Ta mere elle chausse du 2.


- I have a Mac, how can I get MOD Plugin for Mac ?

  A plugin is already available for Mac (PowerPC only).
  Check at: "http://www.spilk.org/dsm". (DSM Plugin)
  This plugin doesn't support compression.

- I'm running OS/2, how can I get MOD Plugin for OS/2 ?

  An OS/2 plugin is available at the following address:
  "http://www.polsci.wvu.edu/Henry/Madbrain/npdsmi.html"
  (DSMI/2 doesn't support compression yet)

- The plugin takes too much CPU

  Well, unlike most players, mod-plugin supports 16-bit
  samples (They are not converted to 8-bit). There is also
  an oversampling performed for each track in the song.
  The internal volume is calculated on 32-bit, which makes
  it hard to use a lookup table for multiply instructions.
  To decrease the CPU usage, you can try not going above
  32KHz, play in mono, disable the surround/bass effects, and
  if it's still too slow, use the 'disable oversampling' option.

- My browser is crashing when accessing a site with the plugin
  This shouldn't happen, but it seems that JavaScript causes
  a lot of browsers to be unstable. You can try to re-install
  the plugin and unchecking the "Enable Java" checkbox.

- Internet Explorer is opening the plugin each time I want
  to download a ZIP file:
  This is because of sites that used a ZIP extension with
  a ModPlugin MIME type: try to contact the webmaster of the
  site to ask them to change the extsnion into .MDZ.
  A fix is to use REGEDIT.EXE from use windows directory,
  and remove the following key:
  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Plugins\Extension\.zip
  and remove any reference to Mod Plugin in the MIME\"application/x-zip-compressed".

- For all other questions about the MOD Plugin, e-mail me
  at "olivierl@jps.net", and don't forget to tell me
  which version of the plugin you're using.