Crossfading-Plugin v1.5 for PM123
=================================


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
- Right-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 choose the output device.
Deselect "shareable" if you don't want your music to be interrupted by other sounds
(e.g. this annoying ICQ sound :-)

You can also choose 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 :-)

If you check the box "Autofade songs in playlist" the plugin fades in the next song
in list shortly before the current song is being finished. I recommend to use
70-80 buffers in this mode. This is because many songs have up to 2 seconds silence
at the end. Thus with a short fading time you wouldn't be able to recognize the fade
effect.

By default, "trash buffers on seek" is turned on, that is if you move the seek slider, PM123
jumps immediately to the specified position. In previous versions, it took a while
until the seek slider reacted to your input. Again, it was a little bit tricky to do, so
I don't know if it works everywhere. If it doesn't work for you (that is if the fading itself
doesn't work anymore): turn it off.



Press OK to save your settings. The changes will take effect, when a new song is started.


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

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


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

You can download the newest version of fade.dll at
- Hobbes (http://hobbes.nmsu.edu/)
- My homepage (http://andreas.schoesser.org) -> 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 now works correctly
          - Implemented priority boost
          - Implemented display function for error messages, thus PM123 should
            not crash on error messages any more

0.7       - Fixed a crash caused by "division by 0"

0.8       - Implemented autofade function
          - Fixed bug: Now the user defined amount of buffers is used

1.0       - Fixed bug: Sometimes fade.dll played "scattered" sound after fading
          - Fixed bug: Single channel mp3s were not played correctly.
          - Fixed bug: Pause button stopped playing since v0.8
          - Fixed bug: Not every song was played to it's end when using autofade mode
          - Hope I fixed all possible crashes... But you never know :)

1.1       - Internal version

1.2       - You can now have several instances of PM123 open with fade.dll loaded
            (shouldn't crash any more).

1.3       - Sound output is now (hopefully) played through the correct soundcard
            if you have 2 soundcards installed. I wasn't able to test this...

1.31      - As it is always: New settings didn't take effect in v1.3.
            So here's the fix.

1.4       - Fixed bug: The last 4 buffers were not played with previous versions.

1.5       - I hope I fixed an annoying bug introduced with v1.4: While v1.31 didn't play the
            last 4 buffers of a song (could be recognized when playing very short mp3s), 
            v1.4 played too many buffers; that is in some cases it played 1 or 2 false
            buffers at the end of a song, resulting in an annoying short "click-sound".
            Should be gone now.
          - Implemented "trash buffers on seek". The seek slider should now react in an
            acceptable time.


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

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

- It only accepts sampling resolutions (bps) at 8 and 16 bit. I haven't seen a mp3 file with an
  alternate bps value, 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 same priority boost algorithm
  also used in Samuel's original output plugin. Never tried it on a slow computer,
  though.

- The autofade function is quite a hack because the plugin doesn't really know
  when the decoder has finished a song. So it uses some timing logic. Might not
  work for every song. If you hear short breaks in the middle of the song even
  when the system is idle try to disable this function.

- 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


June 2002
Andreas Schoesser
