# Questions and Answers

## What is &amarok;?

What is &amarok;?

&amarok; is a music player for Unix systems (eg. Linux). More information can be found in a summary of its features and the screenshot gallery.

## Installation

Can I use &amarok; without KDE?

&amarok; only requires KDElibs, none of the other KDE stuff. So you have to have KDElibs installed properly (including all the binaries that come with it, as &amarok; needs some of these to find plugins and for the script plugins). We have written an entry for how to compile a minimal KDElibs, which you may find useful.

For some features to work correctly, such as the on-screen display, require your window manager to support the relevant freedesktop.org standards. So GNOME will work well, but fluxbox will have some trouble. We are committed to supporting &amarok; on all platforms. We use KDElibs and Qt because they provide an excellent development environment.

## Troubleshooting

&amarok; crashes during the Collection scan, always at the same point. What's happenning?

It's likely that one file in your Collection triggers a bug in the TagLib library, and makes &amarok; crash. You can identify this file by looking at ~/.kde/share/apps/amarok/collection_scan.log. You should report this crash to the TagLib bug database on bugs.kde.org and attach the broken file. Afterward you can remove the file from your Collection and repeat the scanning.

&amarok; crashes when I play a certain track, everytime, what's wrong?

This usually means TagLib is crashing while reading that track's tags. Report the bug against TagLib at bugs.kde.org.

&amarok; crashes often, what can I do?

Upgrade your ALSA libs and utils to the latest version, or use OSS, or OSS emulation.

If you use MySQL as the database backend, try the SQLite one, it is slightly more mature (the &amarok; code, not the db itself)

Try a different audio-engine.

Make sure that all the libraries that &amarok; uses were compiled with the same GCC version as &amarok; itself. The situation when &amarok; is compiled using GCC 3.4.x and linked against taglib which was compiled using GCC 3.3.x can lead to crashes during tag editing.

If you're using KDE with artsd, try disabling "auto suspend if idle after..." in the sound system settings or at least don't use a value of 1 second since that will interfere every time amarok switches songs.

Otherwise, forward us the backtraces when the email pops-up (you'll see). If you get a crash often you will get it fixed for sure if you forward a really good backtrace to us. See the next sections for assistance there.

How can I obtain a decent backtrace?

See the Debugging HowTo.

&amarok; is not using the tags I know are in my files!

If Konqueror or other apps are displaying different Title, Artist, Album or Genre information than &amarok; is picking up when it creates your collection, it may be reading the older ID3v1 format tags rather than the newer ID3v2 tags. This can be due to your Encodings setting: Go to Settings Configure &amarok;, and then find the Encodings section of the Settings panel. Uncheck all checkboxes to "Do not decode the following as latin1". Rescan your collection to pick up the ID3v2 tags.

&amarok; is not displaying my utf-8 id3v2 tags properly!

This is because most applications put utf8 data into id3v2 tags but do not specify the encoding as unicode. This perl script will fix that.

    #!/usr/bin/perl
    die "File $ARGV[0] doesn't exist" unless -f $ARGV[0];
    use MP3::Mplib;
    my $mp3 = MP3::Mplib->new($ARGV[0]);
    my $v2tag = $mp3->get_v2tag;
    print "Error writing tags of $ARGV[0]\n" unless $mp3->set_v2tag($v2tag,&UTF8);

This script requires the perl module MP3::Mplib which can be installed by issuing this command `perl -MCPAN -e 'install MP3::Mplib'`

Why do my statusbar icons always look active?

&amarok; statusbar icons(Random/Repeat/Append) look constantly Active on KDE 3.4.0. This is a known bug in KDE 3.4.0. The icon effects are sometimes forgotten. Simple fix kcontrol Appearance Icons Advanced, set disabled state to "Gray" and "Semi-transparent". Note that sometimes you must click on the icon 3 times before it has an effect after making this change.

Why does &amarok; complain about undefined symbols and then refuses to start?

if you get this error : "amarokapp: symbol lookup error: amarokapp: undefined symbol: _ZN11KSystemTray9setPixmapERK7QPixmap", then check that amarokapp uses the correct libqt (check with : ldd `which amarokapp` | grep qt).

To fix it, you might have to remove any conflicting libqt and/or edit /etc/ld.so.conf so it pick up the correct version first.

## General Usage

Where can I get support for &amarok;?

There are several options. Often times problems you have with the initial install of &amarok; are best answered by experts of your particular Unix or Linux distribution. You may seek help from fellow users and developers at the &amarok; forum and the IRC channel at irc.freenode.net channel #amarok.

Bugzilla is not a place to seek support. Please do enter a bug if you are serious about helping fix a bug in &amarok; itself.

When I start &amarok;, I see an empty playlist. How do I actually get tracks in there?

Simple. Use the File Browser on the left side to navigate to the desired directory. Then drag the files into the Playlist part on the right.

Where is the"Home" tab?

To avoid interface-clutter "Home" tab has been transformed into "Statistics" tool, available under Tools Statistics.

Is there a way to set up amount of information that "Context" borwser shows?

Yes, use the right mouse button menu anywhere on "Context" browser to modify it.

Why are the stars and numbers in the "Context" browser are out of sync?

The meaning of those symbols has changed in Amarok 1.4 "Fast Forward": stars represents the user-defined rating, while numbers shows calculated score.

Clicking on stars in "Context" browser does not work! How do I rate a song?

To rate a track you need a "Rating" column in playlist. Click with the &RMB; on playlist title, and choose Add Column Rating. Click anywhere inside "Rating" column to set up rating for a track. You can also use shortcuts [Win]+[1-5] to quickly rate a song, with Amarok running in the background.

How do I remove tracks from the Playlist?

Select the files you want to remove, and press Del key on your keyboard. Or right-click the selection and choose Remove Selected from pop up menu.

How can I load a playlist?

Just drag and drop the playlist file into the Playlist, like you would do with any other file. It's that simple!

How can I save the current playlist?

The Save playlist button is next to Add Media button in the Playlist Toolbar. Just click it!

There are no visualizations in the visualizations dialog.

You probably don't have xmms-config installed, reconfigure and build after installing the appropriate xmms-devel package. You also may want to install the latest version of libvisual, which has some ultra fancy visualizations.

Where's the equalizer?

The Equalizer Window can be found in the right mouse button menu. You can also find it in the Menubar by selecting Tools Equalizer.

## Playback

What media types does &amarok; support?

None. Yes, that's right! None! We have a backend independent approach, so the question you should be asking is "What media types does GStreamer/xine/aRts/NMM/MAS/KDEmm support?" So as you can guess we pretty much support absolutely every audio format you can think of. GStreamer can even decode text and PNG!

For more information, have a look at Audio Engine Comparison.

Why can't &amarok; play MP3s?

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

&amarok; won't play MP3's under SUSE Linux 9.3, what could I do?

Open the "YaST Online Update" and install the 'Multimedia Option Pack 1' patch. Voila, &amarok; plays MP3's.

With GStreamer-engine I'm getting 100% CPU usage while playing. How can I fix it?

When using GStreamer-engine with alsasink, &amarok; requires the device to provide a mixer. Mixing allows multiple applications to access the device at the same time, and output sound simultaneously. This can either be achieved by using a soundcard with hardware-mixing (e.g. SBLive), or by using the "dmix" plugin for alsa, which provides software-mixing. See Setting up Dmix for ALSA.

After installation you need to specify "dmix" as the sound device in the engine settings dialog.

I can't get any media to play in &amarok;, why not?

You need to test the sound frameworks at the commandline:

`artsplay foobar.mp3` `gst-launch filesrc location=/home/foo/bar.mp3 ! spider ! audioscale ! audioconvert ! alsasink` `xine-check`

The output from these commands should help you identify the problems you are having and how to fix them. Please note you may need to use a different sink to test GStreamer (eg. osssink).

Can &amarok; output directly to OSS/ALSA?

We already do! Don't forget that the media must be decoded first! You can't just pipe an MP3 to ALSA, all you will get is white-noise. GStreamer is the best choice for most people who want a low-overhead decoding solution, it reads the file, decodes it and pipes the PCM data to ALSA. Exactly like XMMS.

But! XMMS can output directly to ALSA!

But it decodes it first! GStreamer can output directly to ALSA too! So can xine!

The sound stutters, is there anything I can do to improve it?

You can either use the GStreamer engine (it's great!), or tweak aRts. Open Control Center Sound and Multimedia Sound System. Enable Run with highest possible priority, and increase the size of the Sound buffer: (warning, see the next FAQ!) You should also ensure that your artswrapper is suid:

`su` `chmod a+rsx /path/to/kde/bin/artswrapper` `killall -9 artsd`

With KDE 3.2.x there are issues with the KDEMultimedia codecs that can cause distorted playback, please see this bug report. Also, increasing the size of the sound buffer in your .asoundrc alsa configuration file can help a great deal.

The CPU usage is high, is there anything I can do to improve it?

Either don't use the aRts-engine, use the GStreamer or xine engines, or address the high CPU usage by installing KDEMultimedia in its entirety to get the faster aRts codecs (eg. libarts_mpeglib.so, etc.)

The &amarok; analyzers are really unresponsive!

You are probably using the aRts-engine, either use another engine (the xine-engine has been seriously tweaked to give perfect analyzer-sync), or reduce the size of your aRts buffer in kcontrol, sound system. The lower the buffer the more responsive the visuals. Yes this is a bug, please help us fix it!

I have GStreamer installed but when I try to change to the GStreamer engine &amarok; crashes, what gives?

After installing GStreamer you have register it's components, running `gst-register` (sometimes suffixed with a version, so gst-register-0.8) should take care of registering your GStreamer components.

I ran gst-register but I still have have GStreamer troubles, what can I do?

You can try the GStreamer FAQ. If all else fails you can try the knowledgeable people at the #gstreamer IRC channel.

&amarok; says that the GStreamer engine cannot play MP3 files, although I have compiled/installed the mad plugin!

Try this (make sure that &amarok; does not run): - Download, compile and install the ffmpeg package - Run gst-register (you may need to run it twice, as root and as your "normal" user) - Go to your GStreamer plugin directory (you can find it with gst-config / gstreamer-config) - Delete the ffmpeg files (or move them somewhere else) - Run gst-register again - Start &amarok;

## Development

How do I get a cvs/svn version of &amarok;?

How to obtain and build SVN &amarok;

I've found a bug / I've got a great idea for &amarok;!

Please report it at bugs.kde.org, if you have a list of suggestions/wishes it may be best to send them to our mailing list: amarok-devel@lists.sourceforge.net

Do you accept patches?

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 svn access. However, please let us know before you commit new features to svn! If you have a bug fix then just go ahead, this is open source after all :)

Why did you choose the name &amarok;?

&amarok; is an album by British composer Mike Oldfield. I happen to like it a lot, and I think the name's got a nice sound. Plus, of course, it contains the all important “K”.. :)

Is it &amarok;, AmaroK or Amarok?

It is &amarok;! Yes, we understand this is unconventional ;-)

## Tips and Tricks

How do I use &amarok; as an alarm clock?

Actually, thanks to the magic of DCOP you already can :) Simply set an alarm in your favorite calendar program and tell it to run the following command: `dcop amarok player play`

This command will tell &amarok; to start playing. Make sure that &amarok; is running before you go to bed, and you should wake up to the merry tune of whatever you pressed stop on before going to bed.

How do I get what &amarok; is playing right now, when I'm on another computer?

If you have a properly set up ssh environment, you can use that to get the information. The following command will return the Now Playing string. `ssh -i ~/.ssh/id_rsa yourip dcop --user yourusername amarok player nowPlaying`

Make sure that you replace yourip with your IP and yourusername with your username. Also note that this expects your identification to be found in the ~/.ssh/id_rsa file.

What kind of tricks can the Player Window do?

The &amarok; player analyzers can be detached from the Player Window. By pressing d on your keyboard the active analyzer will open in an independent, re-sizeable window.

What kind of tricks can the Playlist Window do?

Holding Control and clicking the right mouse button enqueues files in the order in which you clicked them. Pressing Enter after making a playlist search will play the first search item and will clear the search.

I see the Player Window and Playlist Window have neat tricks, what about the tray icon?

Hovering your mouse on the icon will display a nice popup with current track information. Clicking the middle mouse button on the icon play-pauses the current track. Scrolling the mouse wheel changes volume. Holding Shift while scrolling the mouse wheel seeks through the current track. Holding Control while scrolling the mouse wheel will skip through tracks in the playlist. Dragging and dropping items into the tray icon opens a pop up menu allowing you to choose from three options, Append to Playlist, Append and Play, and Queue after Current Track. Tray icon is also a song position indicator.

Where do I find the settings for &amarok;?

~/.kde/share/apps/amarok ~/.kde/share/config/amarokrc

How do I disable a browser section in &amarok;?

Clicking with the &RMB; on any browser title shows up a list of visible browsers. You can use this list to disable/re-enable any browsers available.

## General Questions

How Do I use an external MySQL database with &amarok;?

See MySQL HowTo.

My $HOME is located on NFS. After startup, &amarok; fails to build the Collection, printing many database errors to the console. What to do?

The internal SQLite database which &amarok; uses by default does not work on NFS. You must either link your ~/.kde/share/apps/amarok directory to a local drive, or use the MySQL support.

How can I rip/encode Audio-CDs with &amarok;?

Insert your CD, then click on "Play Audio CD" in the menu. The File-Browser will come up and show a tree with several folders. For normal ripping, go to the "wav" folder, select some tracks and drag them to the desired destination in a Konqueror window. For automatic encoding, drag files from the "mp3" or "ogg" folder instead.

CD-ripping requires the "AudioCD KIO-slave" to be installed. It is part of KDE-Multimedia.

How are track ratings determined?

&amarok; assigns a rating (a number 1-100) to a song based on how many times you've listened to it and whether you skip the song without it finishing. Every time the song finishes playing, the rating is changed. The code for changing the rating is in collectiondb.cpp. As of version 1.2.2, it was on line 1181, though you can find it by searching for "CollectionDB::addSongPercentage". When defining a score for a track which has never been played before, &amarok; uses the calculation score = ( ( 50 + percentage ) / 2 )

This sets the score equal to a number from 25-75, depending on how far through the song was allowed to play. For example, if the user stops or skips the song after only 25% of it has played, the score will be set to (50+25)/2, or 37.5. Scores are displayed as integers, however, so this number is rounded to the nearest integer before being displayed. The score is kept internally as a floating point number however, since after a song has been played several times, it may be impossible to alter the score by more than a point with a single play (see below). When defining a score for a track which has been played before, the calculation is a bit more complicated. In the source, it is score = ( ( values[2].toDouble() * values.first().toInt() ) + percentage ) / ( values.first().toInt() + 1 );

Substituting in the values from this line:

       QStringList values = query( QString(
               "SELECT playcounter, createdate, percentage FROM statistics "
               "WHERE url = '%1';" )
               .arg( escapeString( url ) ) );

We have score = ( ( statistics_percentage.toDouble() * PlayCounter.toInt() ) + percentage ) / ( PlayCounter.toInt() + 1 );

Basically, this adjusts the previous score (statistics_percentage) by a decreasing amount depending on how many times the track has been played. The more times the track has been played, the less of an impact each play has on the score.

How do I manually change a track's rating?

You may change the rating manually by right-clicking on the playlist columns titles (the ones that say title, artist, album etc) and select Score. You can then change the score like any other song attribute, by right clicking it and selecting "Edit Tag 'Score'" or pressing F2. You can also edit the score in the Tag dialog, available by right clicking on a track.

Why isn't &amarok; part of KDEmultimedia?

The developers don't want the man telling them when they can release. (Meaning, packages in KDE proper have a release schedule that doesn't fit with &amarok;'s fast-paced development).

How do I prevent the &amarok; icon from blinking in my system tray?

This is a new feature that has been added that some users might find distracting. Simply uncheck the "Flash icon tray when playing" option under General Options.

How can I show/remove the analyzer in the playlist window?

The playlist analyzer is part of the playlist toolbar. Select Settings Configure Toolbars Add/Remove Analyzer to the Current actions Press OK

How do I change the Context Browser theme?

Download a theme or make your own. Install it through Configure &amarok;... Appearance Context Browser Style, click Install New Style.

What legal issues caused "Blue Wolf" icon replacement?

The icon was way too similar to the Warp Graphics, Inc. logo (elfquest.com), so it had to be removed to avoid problems.

I don't have any visualizations. Where can I obtain these ?

Install the latest version of libvisual.

How can I add my favorite streams to &amarok;?

First of all, load the stream into the playlist. There are several ways to do this. You can simply click on a Stream-Playlist URL in Konqueror; &amarok; will then automatically open the stream. E.g. on shoutcast.com, click on the "Tune In" button. Or you can use the "Add Media" function to load a stream.Once the stream is loaded, you can save it by right-clicking on "Current Playlist" in the Playlist-Browser, then select "Save", and give it a meaningful name. The Stream will then be added to the Playlist-Browser view for later reference.

## Konqueror Sidebar

What is Konqueror Sidebar?

Konqueror sidebar allows you to monitor/control &amarok; while browsing with Konqueror. To see it, run Konqueror, press F9 to see sidebar, click on preferences (top one) button, in dropdown menu choose Add &amarok; Konqueror Sidebar.

## Audioscrobbler

What is Audioscrobbler?

Audioscrobbler is a free service that is sends information regarding which songs are played to an independent server. The service signup is free and only requires that you pick a user name and password that is not already in use. Audioscrobbler is currently utilized in &amarok;.

I do not want &amarok; to send information to Audioscrobbler!

Uncheck "Submit tracks I play" to prevent querying Audioscrobbler for suggested tracks.

How do I get to the Audioscrobbler &amarok; group?

The Audioscrobbler &amarok; group is located here: &amarok; Audioscrobbler Group

## General Engine/Playback Questions

Which sound engine should I use?

Please refer to the Audio Engine Comparison.

What version of ALSA should I use?

If you output to ALSA, you should use the newest available version of ALSA possible! Old versions of ALSA have caused plenty of crashes, and have caused plenty of wrongly attributed crash-reports.

I've installed GStreamer/xine/etc., but the relevant audio-engine won't show up. What gives?

&amarok; was probably compiled before you had xine and/or gstreamer installed, so the ./configure routine did not include them in the list of engines to be built. You will have to rebuild &amarok;.

But I did rebuild &amarok; after installing gstreamer and/or xine, but the engine still does not show up. What happened?

You most likely are using a distro that packages development libraries separately from the main library, so even though gstreamer is installed, &amarok; cannot link to it because gstreamer-devel is not installed. The same issue exists for xine, you must install xine-devel if your distro splits packages in this fashion. Don't forget to rebuild &amarok; after installing the devel packages.

## GStreamer engine

Why is there always a gap although I have crossfading enabled?

Make sure you don't have gst-ffmpeg installed. Instead, install the gst-mad plugin.

I'm getting this error: "GStreamer-CRITICAL **: Factory for `adder' has no type.". How to fix?

Your GStreamer was built with Prelinking, which is not compatible with GStreamer. You must rebuild it without this option. merlin-tc advises: In addition, don't use any ldflags when building GStreamer.

You receive an error "There is no element present to handle the file's mimetype audia/mp4" even though you have the correct gstreamer-faad plugin is installed.

To correctly play mp4 or m4a files with gstreamer, you must also have gstreamer-quicktime in addition to gstreamer-faad installed.

You receive an error "There is no element present to handle the stream's mimetype audio/mpeg"

You are trying to play an mp3 stream without the gstreamer-mad plugin installed. Install the gstreamer-mad plugin and run "gst-register" as root before restarting &amarok;.

I have a second soundcard and I'm using ALSA. How do I make Amarok use it instead of the default?

In Settings Configure Amarok Engine, check the 'Device' checkbox and fill in the device. Typical this is 'hw:0' for the default soundcard, and 'hw:1' for the second soundcard.

## xine engine

How can I change where the audio is output to?

If you are using ALSA, you can output to a specific device with xine. Set up an ~/.asoundrc (user only) or /etc/asound.conf (system wide) file that aliases your hardware devices, and then insert that alias in the "device used for stereo output:" box in the xine-engine configuration tab. Alternatively, you can directly enter the alsa device (hw:0,0 or hw:1,0 and so on). If you choose this latter (alternate) method, be aware that ALSA's corresponding plugfoo (e.g. plughw:0,0 or plughw:1,0 and so on) routing through alsa-lib is much preferred.

Here is a sample ~/.asoundrc for a machine that has an onboard Intel AC97 codec and a usb-audio device:

           pcm.intel8x0 {
              type plug
              slave.pcm "hw:0"
           }

           ctl.intel8x0 {
              type hw
              card 0
           }

           pcm.usb-audio {
              type plug
              slave.pcm "hw:1"
           }

           ctl.usb-audio {
              type hw
              card 1
           }

Now enter usb-audio in the xine-engine setup screen and output should go to the usb-audio device (with alsa-lib properly handling sample rate conversion, channels, and so on).

To use a dmixed virtual device, ensure that the "sound card can do mmap" checkbox is unchecked.

## aRts engine

Sorry, aRts-engine has no maintainer, but feel free to fix it yourself! You could be the new aRts-engine maintainer we need so desperately!