Fading-Plugin for PM123 v0.6 Beta
=================================


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

This is a fading plugin for the mp3 player PM123. With this plugin, you
can achieve seamless playing. That is, if you start a new
song and the currently playing song is not finished yet, this plugin performs
a cross-fade: The currently playing song is faded out gently while at the same
time the new song is faded in.


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

You need the following components to run this plugin:

- OS/2 Warp 3 or higher
- DART installed
- A sound card :-)
- The mp3 player PM123 1.1 Beta 3 or higher


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

Place the file fade.dll into the PM123.EXE directory. Then perform
the following steps:

- start PM123
- Click on the PM123 window to open the "properties" dialog
- Choose the page "plugins"
- Press the "add" button in the "output plugin" section
- Choose "fade.dll" in the file dialog.
  Press Ok.
- Press the "Activate" button for fade.dll

And off you go!


4) Configuration
----------------

In the configuration dialog of the plugin you can chose the output device.
Deselect "shareable" if you don't want your music to be interrupted by other sounds
(btw this annoying ICQ sound :-)
You can also chose the number of sound buffers used by the plugin. More buffers
result in a longer fading time, but the plugin also uses more memory!
I think 40 buffers is a good choice, the minimum is 32 buffers, the maximum 100.
If your audio device isn't able to play 48kHz samples, you can select
"Play 48kHz as 44 kHz"... Doesn't sound very good, though :-)

Press OK to save your settings.


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

Fade.dll ist freeware.
The author of this program is not responsible for any damage, this program may cause.


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

You can download the newest version of fade.zip at
- Hobbes (http://hobbes.nmsu.edu/)
- My homepage (http://www.uni-karlsruhe.de/~uh45/) -> Goto "Andi's Programming Projects"

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


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

Version   Comments

0.5       - first public release

0.6       - Fixed bug in buffering logic: Sometimes fade.dll didn't fade.
          - Fixed bug: fade.dll didn't terminate a song correctly when there was
                       no more data to play.
          - Analyzer works now correctly
          - Implemented priority boost
          - Implemented display function for error messages, thus PM123 should
            not crash on error messages any more


8) Comments and known bugs
--------------------------

- This plugin only fades songs that have the same sampling and bit rate.
  I think this is no problem, because most mp3s are encoded at 44kHz, 16 bit.

- It plays only bit-rates at 8 and 16 bit. I haven't seen a mp3 file with an
  alternate bit rate, though...

- A "fast" computer could be necessary. This does not mean, that this plugin
  takes much processing power, it doesn't, indeed. But the decoder should be
  able to provide enough predecoded buffers, otherwise the plugin could
  get some timing trouble. To avoid this, I built in the priority boost algorithm
  also used in Samuel's original output plugin. Never tried it on a slow computer,
  though.

- Well, not really a bug, but the seek slider reacts a few seconds later than
  with the ordinary output plugin. This is because I can not perform "Trash buffers"
  in order to keep enough pre-decoded buffers in memory for the fading process.

- When an DART error occurs on sound device initialisation, PM123 crashes.
  Working on this...

- This is a beta, so don't expect this plugin to be stable :-)
  So if you encounter a bug, please report it to the email adresse below.
  A procedure to reproduce the bug would be a great help!


9) Get in contact
-----------------

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

the.defender@web.de


March 2001
Andreas Schoesser
