Crystality Plugin v0.92
Realtime plugin for remastering mp3 sound
Bandwidth Extender, Harmonic Booster and 3D Echo.

Copyright (C) 2001 Rafal Bosak <gyver@fanthom.irc.pl>


PURPOSE:

This software consists of XMMS plugin and stdin/stdout plugin. It was written
for realtime remastering of sound from mp3 files.
You will need a reasonably good stereo and a good ear to notice quality
improvement, otherwise this is not for you.
This plugin tries to patch mp3 format flaws, not a poor audio hardware!
Yes, you should be able to hear well enough (sorry) - for some of my friends
plugin is a cool thing, while the others does not hear nothing but echo and
stereo expander (well, you will hear every effect if you set it to the maximum,
but it will not sound nice).

This plugin does mainly four things (and some minor tricks):

1. Adds some sounds in very high frequency range. Most of the mp3s in The Net
   are flawed with a 16(15?) kHz cutoff. Even these ones compressed at high
   bitrates. This spectrum hole is audible and very unpleasant. This plugin
   helps a bit.
   Old mp3s made from the vinyl or the magnetic tape may also sound better with
   these "steroids". For old mp3s you'll probably need to set filter to 0.1.

2. Adds some even harmonic distortions (actually nonlinearity), that sounds
   nice. Valve amps introduce even harmonic distortions (although differnt way)
   Look at audiophile pages for more info (well, mp3 format is not an audiophile
   stuff at all, but... welcome to the real world...).

3. Adds simple, but nice 3D echo (concert hall or church like). Most of echo
   plugins sounds too hard and aggresively for me. This one does not.

4. Extends stereo.


USING:

There are currently two versions of plugin - XMMS plugin and stdin/stdout.
Stdin/out plugin is completly independent of XMMS plugin. It even stores its
configuration in a separate file (~/.crystalityrc). Stdin/out plugin is alpha
code, so some features are missed. You cannot reopen configuration dialog after
closing without restarting plugin, there are no "save config", "load config"
buttons. Configuration is loaded automatically on startup and saved on exit,
either on normal finish or ^C. You can disable GUI with -g option (useful
in scripts).
Because this plugin adds some sounds at high frequencies, you will probably
need to decrease treble level on your amplifier.
Plugin does not perform normalization, so you should slightly decrease signal
level in XMMS equalizer (NOT volume slider on the main panel).
Setting sliders to the maximum is generally a bad idea (well, except the
filter, where that setting is useful).


PERFORMANCE:

It eats about 15% of CPU on my AMD K6-2/400 and optimization is still
possible, this is not highly optimized code.


INSTALLATION:

Distribution contains binary version of XMMS plugin library and stdin/stdout
plugin executable (Linux i586, glibc 2.1.3).
You may copy plugin library file (libcrystality.so) into XMMS's Effect
directory and executable (crystality-stdio) to /usr/local/bin or any location
you prefer. For default locations simply type:

make install

and that's it.
You may also build crystality from the source.

make buildinstall

typed as root in the source directory should be all you have to do.
For more info and if in trouble - use the Source, Luke!
This plugin was my first small step in gtk programming, so don't expect
any wonders, GUI is actually a quick hack to hardcoded settings. I am not
a GUI programmer.


WARRANTY NOTICE:

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

