MetalTux, version 1.1
=====================


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

MetalTux is a sound visualisation plugin for the OS/2 mp3 player PM123. It uses DIVE
(Direct Video Extensions - The fast OS/2 graphic system) to display the Linux
mascot Tux headbanging to the music you play.


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

You need the following components to run MetalTux:
- OS/2 Warp 3/4
- The mp3-player PM123
- DIVE installed
  (comes with Warp4, with Warp3 you have to install it, first)


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

Uncompress the file tux.zip into the PM123 subdirectory PM123_DIR\visplug
(!! IMPORTANT !!) where PM123_DIR is the directory where pm123.exe
is installed. There should be the following three files in the archive:

- tux.dll         the actual plugin
- metaltux.pcx    the Tux graphics
- readme.txt      the file you're reading

After that, you have to 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 "visual plugin" section
- Choose "..\visplug\tux.dll" in the file dialog.
  Press Ok.

That's it.

NOTE: Since PM123 1.1 Beta 2 seems to "forget" the plugins added by the
      configure dialog, here's a workaround for installing the plugin:
      Open the skin file you are using, for example "default.skn".
      Add the following line to the end of the file:

      10=visplug/tux.dll,0,0,0,0

      That should install the plugin, too, but it's not as comfortable as
      the dialog thing.
      I hope, this bug will be fixed by Samuel in the future...


4) How it works
---------------

MetalTux is a visualisation plugin, that is, it analyzes the audio data received from
the decoder. It separates the two channels left and right and performs
a Fast Fourier Transform (FFT) in order to compute the frequencies contained in the audio signal.
Now if there are high amplitudes in the bass range, MetalTux bangs with it's head (right, if
the right channel was loud or left if there were high amplitudes on the left channel). This makes
the penguing bang, if the the bassdrum is played. The feet are animated  after analyzing the treble
of left and right channel.
After that, MetalTux is blitted to the screen via DIVE.
Btw Metal Tux is not a port of the Linux version, it just "ripps" :) the idea and the bitmaps,
the coding was done by myself.


5) How to use
-------------

In order to configure MetalTux, you have to call the properties dialog again
and press the "configure" button for tux.dll

Here, you can configure the sensivity of Tux (that is how he reacts to the music) and the
Tux window position.

Use the sliders for "bass" and "treble" to adjust the sensivity. A high sensivity means that
the penguin reacts even on gentle tones where a low sensivity makes the penguin react only
on strong tones.

You can adjust the window position by hand: Use the spin buttons to do this. You can also
move the window by using the right mouse button. Pressing the left button on the Tux window
will bring up the PM123 window by the way.

"Disable Metal Tux" will keep the DLL loaded, but no Tux is displayed. Useful when you
temporarly need more CPU power.

"Float on top" will keep the Tux window on top of other windows.

Your configuration will be saved to disk if you press the "Ok" button.


6) License
----------

MetalTux ist freeware.
The author of this program is not responsible for any damage, this program may cause.
Thanks to Antti Takala for the idea and for the original Linux version of this plugin,
and to Larry Ewing for the cute Tux logo :-).
Thanks to Samuel Audet for his excellent mp3 player!
Thanks to the people at comp.os.os2.programmer.misc for answering every single question.
Thanks to Michael T. Duffy for his DIVE article at emd2.com and for some code snippets
I "borrowed" from him.


7) Download
-----------

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

Here you can find the original DiscoTux for Linux:
- http://wmdiscotux.stc.cx/

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


9) History
----------

1.0   - initial release

1.1   - Plugin now also works with PM123 1.1 beta 3
      - Fixed bug in the plugin's thread logic
      - The plugin window now snaps in at desktop edges
      

10) Known bugs
--------------

- Tux Plugin window still has a minimum size of 136x136 pixels. Seems to be a restriction of 
  PM frame windows! :-?
  Any idea how to fix this??


11) Get in contact
------------------

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

the.defender@web.de


September 2000
Andreas Schoesser
