README

   1
   2  Amarok - the audio player for KDE
   3 ===================================
   4
   5 There are many media players around these days, true. What's missing from most
   6 players is a user interface that doesn't get in the way of the user. How many
   7 buttons do you have to press for simply adding some new tracks to the playlist?
   8 Amarok tries to be a little different, providing a simple drag and drop
   9 interface that really makes playlist handling easy.
  10
  11
  12  FEATURES
  13 ==========
  14
  15     * Quick and simple drag and drop playlist creation
  16     * Music library (built-in SQLite, MySQL, or PostgreSQL)
  17     * Multiple backends supported (Phonon, xine, GStreamer, Helix, and NMM)
  18     * Plays all audio formats known to man
  19     * 10 band equalizer
  20     * Automatic cover art download using Amazon services
  21     * The unique and powerful stylable context browser
  22     * Automatic play-statistics generation (iRate style)
  23     * Full lyrics download
  24     * Learn about your music with integrated Wikipedia
  25     * Full last.fm support
  26     * Visualisations with libvisual
  27     * Crossfading and gapless playback
  28     * Fully configurable OSD for track changes
  29     * K3B (CD-burning) integration
  30     * Podcast support
  31     * Access to iPod, iRiver IFP, USB Mass Storage and many other devices
  32     * Powerful scripting interface
  33     * Complete DCOP Access
  34     * KDE integration
  35     * Preview and buy albums from the Magnatune.com music store
  36 --------------------------------------------------------------------------------
  37
  38
  39  DEPENDENCIES
  40 ==============
  41
  42 Required
  43     * KDE-Libs 4.0 + KDE-Base-runtime 4.0 (or newer)
  44       http://www.kde.org
  45
  46     * TagLib 1.4 (or newer)
  47       (metadata tagging library)
  48       http://freshmeat.net/projects/taglib
  49
  50     * Ruby 1.8
  51       (programming language, used for scoring, lyrics, last.fm streams)
  52       http://www.ruby-lang.org
  53
  54     * One of the multimedia frameworks listed below:
  55
  56 Recommended
  57     * xine-lib 1.0.2 (or newer)
  58       Note: xine-lib 1.1.1 is required for gapless playback.
  59       (multimedia framework)
  60       http://xinehq.de/
  61
  62 Optional
  63     * RealPlayer 10 or HelixPlayer 1.0
  64       (multimedia framework)
  65       http://www.real.com
  66       (Note: only HelixPlayer is exactly RealPlayer without MP3 support)
  67
  68     * KDE-Base 4.0 (or newer)
  69       (needed for Konqueror Sidebar)
  70       http://www.kde.org
  71
  72     * MySQL 4 or 5
  73       (faster database support)
  74       http://www.mysql.com
  75
  76     * PostgreSQL 7.4
  77       (faster database support)
  78       http://www.postgresql.org
  79
  80     * OpenGL accelerated X-Server
  81       (visualization rendering)
  82
  83     * Libvisual 0.4.0 + SDL 1.2
  84       (visualization framework)
  85       http://localhost.nl/~synap/libvisual/
  86       http://www.libsdl.org
  87
  88     * ProjectM 0.96 (or newer)
  89       (visualization plugins for Libvisual or XMMS)
  90       http://xmms-projectm.sourceforge.net/
  91
  92     * libtunepimp 0.3 (or newer)
  93       (automatic tagging support)
  94       http://www.musicbrainz.org/
  95
  96     * K3B 0.11 (or newer)
  97       (CD burning support)
  98       http://www.k3b.org
  99
 100     * libgpod 0.4.2 (or newer)
 101       (iPod support)
 102       http://www.gtkpod.org/libgpod.html
 103
 104     * libifp 1.0.0.2
 105       (iRiver iFP support)
 106       http://ifp-driver.sourceforge.net/libifp/
 107
 108     * libmp4v2 (mpeg4ip 1.5 is recommended, faad2 is less reliable)
 109       (MP4/AAC tag reading & writing)
 110       http://www.sf.net/projects/mpeg4ip
 111       http://www.audiocoding.com
 112
 113     * libnjb 2.2.4 (older versions may work)
 114       (NJB mediadevice (Creative Nomad/Zen family, Dell DJ devices)
 115       http://www.sf.net/projects/libnjb
 116
 117     * libmtp 0.1.1 (or newer)
 118       (MTP media device support AKA PlaysForSure)
 119       http://libmtp.sourceforge.net/
 120
 121     * libkarma 0.0.5 && OMFS 0.6.1
 122       (Rio Karma support via USB)
 123       http://freakysoft.de/html/libkarma/ && http://linux-karma.sf.net/
 124
 125 Please note, if compiling from source you must also install the devel versions
 126 of these packages.
 127 --------------------------------------------------------------------------------
 128
 129
 130  IMPORTANT INSTALL INSTRUCTIONS
 131 ================================
 132
 133 To compile from source, please refer to the INSTALL file.
 134
 135 Packages for popular distributions are available at http://amarok.kde.org
 136 --------------------------------------------------------------------------------
 137
 138
 139  INSTALLATION-FAQ
 140 ==================
 141
 142 Q: I have the required version of GStreamer installed but configure doesn't
 143    find it!
 144 Q: I have pkg-config problems.
 145 A: Here's an extract from the PKG-CONFIG man page:
 146
 147      pkg-config retrieves information about packages from  special metadata
 148      files. These files are named after the package, with the extension
 149      .pc. By default, pkg-config looks in the directory prefix/lib/pkgconfig
 150      for these  files;  it will  also  look in the colon-separated list of
 151      directories specified by the PKG_CONFIG_PATH environment variable.
 152
 153    So, do export PKG_CONFIG_PATH="/path/to/gstreamer-0.x.y.pc" and reconfigure.
 154
 155 Q: Can I improve Amarok's startup time?
 156 A: Prelinking Amarok has spectacular results; however if you have binary openGL
 157    drivers (eg Nvidia drivers), you will need to compile Amarok --without-opengl
 158    in order to get the amarokapp binary to prelink (the amarok binary is not
 159    important here).
 160 --------------------------------------------------------------------------------
 161
 162
 163  OTHER-FAQS
 164 ============
 165
 166 For answers to problems like "Amarok won't play any MP3s!" and "My MP3s skip
 167 and stutter!" please visit:
 168
 169    http://amarok.kde.org/
 170 --------------------------------------------------------------------------------
 171
 172
 173  INFORMATION FOR PACKAGERS
 174 ===========================
 175
 176 For Amarok packages we suggest you build:
 177
 178                 % ./configure --disable-debug
 179
 180 It is possible to build Amarok to use MySQL as the database backend. Using
 181 MySQL makes the Amarok collection faster.
 182
 183 We suggest compiling Os, there is no particular part of Amarok that would
 184 benefit from optimisation, so the smallest binary is probably the best route.
 185
 186 In order to limit the dependencies the Amarok package demands we suggest
 187 splitting Amarok into the following packages:
 188
 189    1. Amarok + one backend
 190    2. xine-engine
 191    3. Helix-engine
 192    4. amarok_libvisual
 193    5. ipod media device
 194    6. ifp media device
 195    7. njb media device
 196    8. mtp media device
 197    9. rio karma media device
 198
 199 Amarok is modular and will be fully functional as long as one of 2 or 3 is
 200 also installed. Hence we suggest Amarok + one backend. Feel free to include the
 201 helix, MAS and NMM engines if you can satisfy their dependencies.
 202
 203 Amarok ships with two binaries: amarok and amarokapp. The amarok binary is a
 204 wrapper designed to speed up command line argument passing. amarokapp is the
 205 real Amarok.
 206
 207 If you make packages for Amarok please let us know and we'll link to you on the
 208 homepage (as long as you don't object).
 209 --------------------------------------------------------------------------------
 210
 211
 212  CONTRIBUTING
 213 ==============
 214
 215 If you wish to contribute to Amarok, you should build it from SVN and subscribe
 216 to the amarok AT kde.org mailing list. The IRC channel is  also  a  place  where
 217 it's  nice  to  be, since you can talk to other developers much easier, and
 218 get instant notification of commits to the SVN. For instant email notification
 219 of commits, visit http://commitfilter.kde.org/.
 220 --------------------------------------------------------------------------------
 221
 222
 223 WWW : http://amarok.kde.org
 224 MAIL: amarok@kde.org
 225 IRC : irc.freenode.net - #amarok, #amarok.de, #amarok.es