Revert previous commit, was incorrect
[amarok.git] / README
blobb6d0b2892be93ada5ce2764c2f4c7d1920666bc5
2  Amarok - the audio player for KDE
3 ===================================
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.
12  FEATURES
13 ==========
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, and Helix)
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 --------------------------------------------------------------------------------
39  DEPENDENCIES
40 ==============
42 Required
43     * KDE-Libs 4.0 + KDE-Base-runtime 4.0 (or newer)
44       http://www.kde.org
46     * TagLib 1.4 (or newer)
47       (metadata tagging library)
48       http://freshmeat.net/projects/taglib
50     * Ruby 1.8
51       (programming language, used for scoring, lyrics, last.fm streams)
52       http://www.ruby-lang.org
54     * One of the multimedia frameworks listed below:
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/
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)
68     * KDE-Base 4.0 (or newer)
69       (needed for Konqueror Sidebar)
70       http://www.kde.org
72     * MySQL 4 or 5
73       (faster database support)
74       http://www.mysql.com
76     * PostgreSQL 7.4
77       (faster database support)
78       http://www.postgresql.org
80     * OpenGL accelerated X-Server
81       (visualization rendering)
83     * Libvisual 0.4.0 + SDL 1.2
84       (visualization framework)
85       http://localhost.nl/~synap/libvisual/
86       http://www.libsdl.org
88     * ProjectM 0.96 (or newer)
89       (visualization plugins for Libvisual or XMMS)
90       http://xmms-projectm.sourceforge.net/
92     * libtunepimp 0.3 (or newer)
93       (automatic tagging support)
94       http://www.musicbrainz.org/
96     * K3B 0.11 (or newer)
97       (CD burning support)
98       http://www.k3b.org
100     * libgpod 0.4.2 (or newer)
101       (iPod support)
102       http://www.gtkpod.org/libgpod.html
104     * libifp 1.0.0.2
105       (iRiver iFP support)
106       http://ifp-driver.sourceforge.net/libifp/
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
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
117     * libmtp 0.1.1 (or newer)
118       (MTP media device support AKA PlaysForSure)
119       http://libmtp.sourceforge.net/
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 --------------------------------------------------------------------------------
130  IMPORTANT INSTALL INSTRUCTIONS
131 ================================
133 To compile from source, please refer to the INSTALL file.
135 Packages for popular distributions are available at http://amarok.kde.org
136 --------------------------------------------------------------------------------
139  INSTALLATION-FAQ
140 ==================
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:
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.
153    So, do export PKG_CONFIG_PATH="/path/to/gstreamer-0.x.y.pc" and reconfigure.
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 --------------------------------------------------------------------------------
163  OTHER-FAQS
164 ============
166 For answers to problems like "Amarok won't play any MP3s!" and "My MP3s skip
167 and stutter!" please visit:
169    http://amarok.kde.org/
170 --------------------------------------------------------------------------------
173  INFORMATION FOR PACKAGERS
174 ===========================
176 For Amarok packages we suggest you build:
178                 % ./configure --disable-debug
180 It is possible to build Amarok to use MySQL as the database backend. Using
181 MySQL makes the Amarok collection faster.
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.
186 In order to limit the dependencies the Amarok package demands we suggest
187 splitting Amarok into the following packages:
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
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, engine if you can satisfy their dependencies.
203 If you make packages for Amarok please let us know and we'll link to you on the
204 homepage (as long as you don't object).
205 --------------------------------------------------------------------------------
208  CONTRIBUTING
209 ==============
211 If you wish to contribute to Amarok, you should build it from SVN and subscribe
212 to the amarok AT kde.org mailing list. The IRC channel is  also  a  place  where
213 it's  nice  to  be, since you can talk to other developers much easier, and
214 get instant notification of commits to the SVN. For instant email notification
215 of commits, visit http://commitfilter.kde.org/.
216 --------------------------------------------------------------------------------
219 WWW : http://amarok.kde.org
220 MAIL: amarok@kde.org
221 IRC : irc.freenode.net - #amarok, #amarok.de, #amarok.es