amaroK README
=============

amaroK - a new media player for KDE

There are many media players around these days, true. What's missing from most
players is a user interface, that doesn't get in the way of the user. How many
buttons do you have to press for simply adding some new tracks to the
playlist? amaroK tries to be a little different, providing a simple drag and
drop interface, that really makes playlist handling easy.

    * fresh playlist concept, very fast to use, with drag and drop

    * plays all formats supported by aRts, including mp3, ogg, audio CDs,
      streams

    * audio effects, like reverb and compressor

    * compatible with the .m3u and .pls formats for playlists

    * nice GUI, integrates into the KDE look, but with a unique touch


This file was last updated with relevance to amaroK 1.0-beta1


--------------------------------------------------------------------------------
DEPENDENCIES
============

required
    * KDELIBS 3.2
      http://www.kde.org

    * TagLib 1.0
      http://freshmeat.net/projects/taglib

recommended
    * aRts 1.2 + KDEMULTIMEDIA 3.2
      http://www.kde.org

    * OpenGL accelerated X-Server

optional
    * GStreamer-0.8.1 + Gst-Plugins-0.8.1
      http://gstreamer.net

    * NMM 0.4.4
      http://www.networkmultimedia.org

    * XMMS 1.2 + XMMS visualization plugins
      http://xmms.org


Please note, if you obtain these dependencies via a packaging system, you must
also install the devel versions of these packages!


--------------------------------------------------------------------------------
IMPORTANT INSTALL INSTRUCTIONS
==============================

In order to compile and install amaroK on your system, type the following in the
base directory of the amaroK distribution:


                % ./configure --prefix=`kde-config --prefix`
                % make
                % make install


Using enable-final will usually give a much faster compile, but it may cause
compile failure. See the file INSTALL for more information.


                % ./configure --enable-final --prefix=`kde-config --prefix`


--------------------------------------------------------------------------------
MINI-FAQ
========

Q: Why can't amaroK play MP3s?
A: It can! Chances are you're using Fedora/RedHat linux, they don't ship with
   MP3 decoders by default (due to patenting issues). Solution:

       ALT-F2, gg:redhat mp3 kde, ENTER

Q: The sound stutters/CPU usage is high, can it be improved?
A: You can either use the GStreamer engine (it's great!), or tweak aRts. Open
   the Control Center, go to "Sound and Multimedia", then "Sound System". Enable
   "Run with highest possible priority", and increase the size of the sound
   buffer (warning, see the next FAQ!) You should also enusre that your
   artswrapper is suid:
   
       $ su
       $ chmod a+rsx /path/to/kde/bin/artswrapper
       
   Finally you will benefit from installing kdemultimedia in its entirety to get
   the faster aRts codecs (eg. libarts_mpeglib.so, etc.)

Q: The amaroK analyzers are really unresponsive!
A: You are probably using the aRts engine, either use the GST or NMM engines, or
   reduce the size of your aRts buffer in the Control Center, sound system. The
   lower the buffer the more responsive the visuals. Yes this is a bug! Please
   help us fix it!

Q: I have the required version of GStreamer installed but configure doesn't
   find it!
A: Here's an extract from the PKG-CONFIG man page:

     pkg-config retrieves information about packages from  special metadata
     files. These files are named after the package, with the extension
     .pc. By default, pkg-config looks in the directory prefix/lib/pkgconfig
     for these  files;  it will  also  look in the colon-separated list of 
     directories specified by the PKG_CONFIG_PATH environment variable.
     
   So, do export PKG_CONFIG_PATH="/path/to/gstreamer-0.x.y.pc" and reconfigure.
   
Q: Can amaroK output directly to OSS/ALSA?
A: Yes, but not yet. One reason we use aRts/GStreamer and NMM is for codecs.
   To output directly to ALSA, etc. someone needs to write an amaroK engine
   plugin that uses libmad and libvorbis to decode directly to alsa. And then
   call it amaroK_ALSA_engine. :-)

Q: There are no visualizations in the visualizations dialog.
A: You probably don't have xmms-config installed, reconfigure and build after
   installing the appropriate xmms-devel package.

Q: I've found a bug / I've got a great idea for amaroK!
A: Please report it at http://bugs.kde.org.

Q: Can I improve amaroK's startup time?
A: The aRts engine is the slowest to load, using an alternative will help.
   Prelinking amaroK has spectacular results; however if you have binary openGL
   drivers (eg Nvidia drivers), you will need to compile amaroK --without-opengl
   in order to get the amarokapp binary to prelink (the amarok binary is not
   important here).

Q: Do you accept patches!
A: Happily! Your best course of action is to let us know what you plan to do
   before you do any work so we can discuss it, but don't fret we haven't turned
   down a patch yet! Discussion is mostly to help you patch the correct bits of
   amaroK. Then either submit a patch to the mailing list, or commit if you have
   cvs access. However, please let us know before you commit new features to
   cvs! If you have a bug fix then just commit, this is open source afterall:)


--------------------------------------------------------------------------------

CONTRIBUTING
------------

If you wish to contribute to amaroK, you should build it from CVS and subscribe
to the amarok-devel mailing list. The IRC channel is  also  a  place  where
it's  nice  to  be, since you can talk to other developers much easier, and
get instant notification of commits to the CVS.

--------------------------------------------------------------------------------

WWW : http://amarok.kde.org
IRC : irc.freenode.net, #amarok
MAIL: amarok-devel@lists.sourceforge.net
WIKI: http://wiki.kdenews.org/tiki-index.php?page=amaroK

