Normalizer plugin v0.2 beta for PM123
=====================================

1) Introduction
---------------

This is a plugin for the mp3 player PM123 for OS/2. With this plugin installed, you can
normalize the sound output of PM123. That is when playing mp3 files, the volume level of
different songs is kept approximately equal.
In order to do that, normal.dll reads the "normalizer id3 tag" of the currently playing file
generated by normalizer.exe.
Normalizer.exe is part of the normalizer package written for Linux by Chris Vaill. There's also
an OS/2 port on Hobbes! Normalizer.exe computes the average volume level of each mp3 file and
appends information the be read by the normalizer plugin. The advantage of normalizer.exe is, that
the mp3 data itself isn't touched, so the normalizing speed is quite fast.
So before the normalizer plugin can do anything with the mp3 files it is given, you first have
to execute normalizer.exe on your mp3 collection once. After that step, you won't have to fiddle
around with the volume slider any more if there's a loud or silent song to be played! :-)

The normalizer plugin is freeware.


2) System requirements
----------------------

- OS/2 Warp 3/4
- The mp3 player PM123 1.1 Beta 3 or higher
- The normalizer.exe from the normalizer package found on hobbes:
  http://hobbes.nmsu.edu/cgi-bin/h-search?key=normalize



3) Installation
---------------

Unpack the zip-archive in a directory, then do the following:

- The normalizer plugin comes with two .dll files:

  1) normal.dll    <- This does the actual work
  2) normhelp.dll  <- This is used only to pass some pointers to normal.dll

  Copy these two files into the ..\visplug directory of PM123

- Then open your currently used skinfile with a texteditor and append
  the following line

  4=visplug/normhelp.dll,0,0,0,0

  The trailing id (4) should be unique, so if there's another plugin using this
  id then alter it.

- Start PM123 and open the configuration dialog

- Chose the notebook page "plugins". In the section "visual plugins" you should
  now see a "normhelp.dll" entry. Go the the "filter plugin" section and press
  the "Add" button".

- Chose "normal.dll" in the file dialog, press Ok.

- Now you should be ready. You can select the new "normal.dll" entry and
  press "configure" to reveive information about the current adjustment.


4) Usage
--------

As mentioned above, you first have to download the normalizer-package and
execute normalize "normalize.exe" once on your mp3 files. To normalize a whole
directory, simply execute

"normalize.exe *.mp3"

This will normalize all mp3's to a standard volume. The normalizer plugin
will use the id3 tag generated by normalize.exe to recalculate the sample data
in order to keep the volume level at an equal level.

You HAVE to install both, normhelp.dll AND normal.dll. Otherwise you will
receive an error message or PM123 might even crash (don't know exactly why
THAT happens... we'll see!)


5) License
----------

normal.dll is freeware.
The author is not responsible for any damage this program may cause.
If you copy this package, always copy all files contained in the original archive!


6) Download
-----------

You can download the newest version of normal.dll at
- Hobbes (http://hobbes.nmsu.edu/)
- My homepage (http://andreas.schoesser.org) -> Goto "Andi's Programming Projects"

The normalizer.exe package is available here:
- Hobbes (http://hobbes.nmsu.edu/)
  Search for "normalize-0-7-1.zip" or a higher version or use the following link:
  http://hobbes.nmsu.edu/cgi-bin/h-search?key=normalize

Here you may download the mp3 player PM123:
- http://www.sektori.com/pm123


7) History
----------

Version     changes

0.1 beta    - Initial release

0.2 beta    - changed false installation instructions in this readme
            - fixed bug: PM123 crashed when loading a new skin file in case
              normhelp.dll is already loaded.


8) Comments & known bugs
------------------------

- The normalizer id3 tag is found by a simple pattern searching algorithm.
  Todo: Implement a decent id3 tag reading function.


9) Thanks!
----------

Thanx go to:

- Chris Vaill for the normalizer package and for some enlightenments I got by reading
  his code. I used some code fragments of his plugin for XMMS :-)
- Michael Such for porting normalizer.exe to OS/2
- All the freaks using OS/2


10) Get in contact
------------------

Questions, bug reports, comments or laudation :-) to:

the.defender@web.de


Feb 2002
Andreas Schoesser
