amaroK README
-------------

INTRODUCTION
============

amaroK - the audio 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 audio formats, 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.1


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

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

    * TagLib 1.3
      (metadata tagging library)
      http://freshmeat.net/projects/taglib

recommended
    * GStreamer-0.8.1 + GStreamer-Plugins-0.8.1
      (multimedia framework)
      http://gstreamer.net

optional
    * aRts 1.2 + KDEMultimedia 3.2
      (multimedia framework)
      http://www.kde.org

    * MAS 0.6.3
      (multimedia framework)
      http://www.mediaapplicationserver.net

    * NMM 0.4.4
      (multimedia framework)
      http://www.networkmultimedia.org

    * xine 1.0.0
      (multimedia framework)
      http://xine.sourceforge.net

    * OpenGL accelerated X-Server
      (visualization rendering)

    * Libvisual 0.1.6 + SDL 1.2
      (visualization framework)
      http://libvisual.sf.net
      http://www.libsdl.org

    * libtunepimp 0.3
      (automatic tagging support)
      http://www.musicbrainz.org/

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

    * K3B 0.11
      (CD burning support)
      http://www.k3b.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`


Packages for popular distributions are available at http://amarok.kde.org


--------------------------------------------------------------------------------
INSTALLATION-FAQ
================

Q: I have the required version of GStreamer installed but configure doesn't
   find it!
Q: I have pkg-config problems.
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 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).


--------------------------------------------------------------------------------
OTHER-FAQS
==========

For answers to problems like "amaroK won't play any MP3s!" and "My MP3s skip
and stutter!" please visit:

   http://amarok.kde.org/component/option,com_staticxt/staticfile,faq.html


--------------------------------------------------------------------------------
INFORMATION FOR PACKAGERS
=========================

For amaroK packages we suggest you build:

                % ./configure --enable-final --disable-debug

There is a special option for packagers who wish to use the version of sqlite
that is distributed with their operating system:

                % ./configure --without-included-sqlite

However, the sqlite you ship MUST be threadsafe! Also amaroK will take longer
to start with this option since sqlite is not statically linked into the
amarok binary. The amaroK binary will be approximately 200kB smaller.

We suggest compiling Os, there is no particular part of amaroK that would
benefit from optimisation, so the smallest binary is probably the best route.

In order to limit the dependencies the amaroK package demands we suggest
splitting amaroK into the following packages:

   1. amaroK + GStreamer-engine
   2. aRts-engine
   3. xine-engine
   4. amarok_xmmswrapper + amarok_libvisual

amaroK is modular and wil be fully functional without 2, 3 and 4.

amaroK ships with two binaries: amarok and amarokapp. The amarok binary is a
wrapper designed to speed up command line argument passing. amarokapp is the
real amaroK.

If you make packages for amaroK please let us know and we'll link to you on the
homepage (as long as you don't object).


--------------------------------------------------------------------------------
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
MAIL: amarok-devel@lists.sourceforge.net
IRC : irc.freenode.net, #amarok
