# The &amarok; Handbook

This documentation was converted from the &kde; UserBase &amarok; page.
&FDLNotice;
2011-01-29
&kde; SC 4.6

&amarok; is a free, versatile and powerful music player for &Linux;. The latest 2.x release series, often referred to as Amarok 2, is cross-platform (can be used on many platforms, including &Linux;, MacOS and &Microsoft; &Windows;) and implements a completely reworked code base that will enable it to incorporate exciting new features as the release matures. The current stable release is version 2.3.

KDE
multimedia
player
audio
ogg
mp3
wav
music
sound

## Interface

&amarok; sports a three-pane interface by default.

### The left pane (Media Sources)

The Media Sources pane on the left is the place where you access your local collection as well as other services: Local Music on top, which is the primary interface to your local collection and connected media such as mp3 players and &CD;s. There is a section for all Internet Services that you have enabled. Here, you can browse listings of radio stations and podcasts; listen/subscribe to them, interact with your last.fm account, purchase music from online stores such as Magnatune and download independent artists' music from Jamendo and more. The Playlists section allows you to create and manage Dynamic Playlists, access your Saved Playlists as well as the Automatic Playlist Generator. The Files section displays an integrated file browser and the Podcasts section will let you access your podcast subscriptions.

### The central pane (Context View)

This is where all the information is displayed. The central pane contains 3 applets that dynamically change to display context information about the track that is currently playing. You can see the rating, score and play count of the Current Track applet or the last played tracks if nothing is playing, the Lyrics of the song and the Wikipedia page on the artist. More applets can be added, removed or rearranged using the Applet Bar at the bottom of the pane.

### The right pane (Playlist View)

&amarok; has the most configurable playlist of any music player in existence. It puts the power in your hands to shape the playlist any way you see fit. To start you off, there are three pre-configured playlist layouts that you can use as starting points to create the layout that fits your flow the best. You can generate playlist dynamically with various bias or use the Automatic Playlist Generator, shuffle, play at random or repeat, queue tracks and save the existing playlists for later use.

## Features

### Music Playback

&amarok; can support most popular formats for music files. The actual list of formats is dependent on the codecs and audio backend in use on your system. There's also support for traditional playlists — you can create, save and load all the playlists you want.

### Device Support

&amarok; offers support for a great variety of Media devices such as iPods, MTP and UMS devices.

The button Merge View at the top of the collection lets you merge collections. This means songs from your local collection, audio &CD;, mp3-player and so on will be shown in one unified collection. It is a toggle switch so you can easily revert to showing the separate sources.

### Configurable Context View

The Context view, the centerpiece attraction in &amarok;, can automatically fetch contextual information about the currently playing song (such as album art, lyrics or Wikipedia information) from the Internet and display them. This is one of the unique features of the &amarok; series.

### More Internet Services

&amarok; opens the gateway to a rich multimedia experience on the Internet.

- Sporting interfaces to services such as Ampache music servers and mp3tunes lockers, it allows you to listen to your music from anywhere in the world.

- You can sample and buy music from Magnatune.

- Using the Jamendo service, you can listen to and download music from independent artists who can be supported by your donations.

- With integrated last.fm functionality, you can scrobble your tracks, use last.fm features like statistics, charts and subscribers can listen to radio streams customized to your music taste — all from &amarok;.

And that is just the beginning — you can add even more Internet services using the Script Manager.

### Script Manager

Scripts are add-ons that allow you to extend &amarok;’s functionality in innovative ways. Using the Script Manager, you can manage these scripts in that it allows you to install/remove or enable/disable scripts you already have. You can also use the Get More Scripts feature to download new scripts submitted by other users.

### Cover Manager

You can browse through your music collection using the nifty Cover Manager that displays the album art, download covers from various sources or let &amarok; check automatically for covers in the Internet.

### Rating and scoring

You can show your love for the songs by rating them. &amarok; supports ½⋅✩ ratings, too. In addition, &amarok; can calculate a score (a sort of guessed rating) depending on metrics such as how often you listen to or skip a song.

### Pop-Up Dropper

This is an innovative interface that offers contextual options (such as the ones you see in a right-click menu) that you can drop a song into. Grab a track and see the Pop-Up Dropper appear in the context view pane!

### Configurable Playlist View

The currently loaded playlist is highly configurable and can show information about the songs in any form you like. If you are used to the Spreadsheet View found in &amarok; 1.x series and other music players, you can have that, too! The Playlist View also allows you to save or export the current playlist.

### Dynamic Playlists

&amarok; allows you to create weighted random playlists that adhere to various criteria exactly (Proportional bias) or approximately (Fuzzy bias). For example, you can create a playlist that will be randomly populated by songs that are rated more than 3 stars and are approximately from around the year 1967!

### Replay Gain Support

&amarok; supports replay gain tag information embedded in files and automatically adjusts the overall volume of the song to a common level.

Rediscover your music!

## Hints, Tips and FAQs

If you find that most of your music is recognized by &amarok;, but some folders are not properly picked up, open a console and type

`touch folder`

where folder is the path to the folder that has the problem. Then select Settings Configure &amarok; in &amarok; main window menu, and open Collection Rescan Collection page. Your folder should be visible again now.

## More Information

- &amarok; Homepage

- &amarok; Forum

Congratulations on installing &amarok;, the most advanced music discovery software available. &amarok; will help you explore your music, and enjoy it as never before. Also, you can tour different sources of music, radio stations and audio books online. In this guide, we'll show you how to let &amarok; find your collection, play it for you, and also how to use &amarok; to find things online. We'll assume that you know nothing about &amarok;, but do know how to use menus, a mouse, and your keyboard.

## Getting started

### Starting &amarok;

If you already know your way around your operating system, you probably also know how to start &amarok;, and you can continue. Else, continue reading.

#### From &plasma;

If you are running the &plasma; Workspace, you can start &amarok; by either:

- pressing on &kickoff; and then Multimedia&amarok;.

- running &krunner; (&Alt;F2 by default), enter `amarok` and then press &Enter;.

### First Time

The first time you use &amarok;, a First Start User Interface will come up asking you to specify where your music is located. If you have a music folder already configured in your system, &amarok; should detect it and ask you to use it:

If you select No in this dialog, you will be presented with another which allows you to select your music folder:

See Setting Up a Collection

Once you have selected the folder where your music is, &amarok; will scan the folder and sub-folders, creating the collection. Depending on the number of tracks and the speed of the location this can take some time.

### Closing &amarok;

If you want to close &amarok;:

- Type &Ctrl;Q when you are in the &amarok; window, or

- Select the Quit option in the &amarok; menu, or

- Right-click on the blue wolf icon in the System Tray at the bottom of your screen. You will be presented with the following:

If you close the &amarok; window by clicking Close on the window border, &amarok; will continue to run in the background and only show the blue wolf icon in the System Tray:

If you log out of your session or shut down your computer without quitting &amarok;, some of your settings will not be saved.

## The &amarok; window

The &amarok; window is the default user interface designed to let you rediscover your music. In addition, it is also designed to give you as much visual information about your music as possible. While many users will find the default layout suitable for their needs, the layout is fully customizable if you prefer another layout.

### Default layout of the &amarok; window

Upon installation, &amarok; will look like this:

The &amarok; window has four main components:

1. right under the top-level menus is the Toolbar that lies above three panes:

2. your Media Sources (music collection and other media) in the left pane,

3. the Context pane in the center, and

4. the Playlist in the right-hand pane.

### Using the &amarok; window to manage and play your music

Playing music using &amarok; usually takes two steps:

1. Create a playlist by selecting some of the tracks in your collection, which you will find listed in the Media Sources pane, and send your music to the Playlist pane.

2. Play the music in your playlist, using the Playlist pane and/or the Toolbar.

Additionally, you may wish to transfer some of your music to a mobile music player, such as an iPod. The next sections will help you with these tasks.

## The Music Collection

### The Media Sources pane

The Media Sources pane is the place where you browse and display your complete collection of music. This includes the tracks on your local hard disk, as well as those on any external devices or media connected to your computer, such as audio &CD;, USB devices, media players, network disks or Internet sources.

### Setting up a collection

Do you have music tracks in mp3, ogg or FLAC format on your computer? Begin by telling &amarok; where to find those files, so it can begin creating your collection. In the top-level menu: Settings Configure &amarok;.

A tree-view of your Home folder is shown above. Click the check box where your music is stored; usually ~/Music. Then choose Fully Rescan Entire Collection. This will take some time, so don't be alarmed if &amarok; seems slow for a while. Once the scan is complete, it's best to quit &amarok; using the top-level &amarok; menu, or &Ctrl;Q, and then restart it. Your newly-added music should show up under the Local Collection section.

### Adding Media Devices to the Collection

Underneath the search bar near the top of the Media Sources pane you see the different devices and/or content categories within the Content Browser. If you insert an Audio &CD; in the &CD; drive it will appear in the Media Sources pane, along with Media Players, thumb drives, and other USB devices. After an external device has been mounted, it should show automatically within the Media Sources pane. You do not need to go through any additional actions to see the external devices in your Media Sources pane, as long as they have been recognized by your computer.

Below is a screenshot showing three connected sources with music: Audio &CD;, mp3 player, and the Local Collection.

### Ripping a &CD; into the collection

If you don't have any music files on your computer, it's easy to rip them (copy the tracks from your &CD;s to your collection). Just pop in a &CD;, and right-click on the banner of the &CD; device in the Content Browser to play, or copy to your collection, which will rip and tag your tracks (see image below). If you copy music from an audio &CD; to your Local Collection, the message bar at the bottom of the &amarok; window will indicate that it is busy copying. The ripping may take several minutes. Once the rip is complete, the message in the message bar disappears and the music appears in the content browser of your Local Collection. If the ripped music does not appear in your Media Sources pane it's best to quit &amarok; from the &amarok; top-level menu, or &Ctrl;Q, and then restart it. Now you should see it in your collection. The screenshot below shows how you move tracks from your audio &CD;, iPod or other device to your collection, using the context (right-click) menu.

In the above context menu, you can also see the choice to Edit Track Details. Use this option if you have a track that needs a tag edited. This becomes important when you rip music to .WAV format, losing some of the tags. If quite a bit of your collection needs tagging, consider dedicated tagging software, such as

- Picard

- EasyTag

- Kid3

Correct tagging is important to help &amarok; show your tracks in the appropriate albums and proper sort order. Learn more about ripping and tagging.

### Accessing other media sources

You might have wondered why the Media Sources pane is not called the 'Collections pane'. &amarok; gives you access to much more music than just your collection -- Internet shops, audio books, podcasts, music files stored outside your collection, and previously stored playlists. The &amarok; breadcrumb navigation is the key to all of this. The starting icon for the breadcrumb navigation is the blue home folder icon at the extreme top left of the Media Sources pane. This icon expands and contracts as you browse through the Media Sources pane, allowing you to easily navigate your collection by clicking your desired folder in the breadcrumb bar.

If you click the &amarok; home folder you see the Media Sources pane on the left below, containing icons to available resources. If you click the Files icon (left image below, second item from the bottom), you will see something similar to the image on the right, below. Notice how the breadcrumb bar expands and how the content of the selected folder is shown in the Media Sources pane (right image below). Clicking the > symbols among the breadcrumbs allows you to view the folders available at that level of the folder structure. The &amarok; file browser gives you access to your entire file system, even outside your Local Collection.

Media Sources pane

Files icon clicked

The functions of the icons in the &amarok; Home folder (left above) are:

#### Icons in the Home Folder

Icon | Name | Action
| Local Music | Your &amarok; collection
| Internet | Internet shops such as Magnatune, Jamendo and Last.fm. First configure your Internet resources in:Settings Configure &amarok;
| Playlists | Saved playlists — see also Playlists. Also playlists on media devices.
| Files | Your file system
| Podcasts | Access to Podcasts via RSS feed

Clicking the Local Music icon above or on the Local Music folder in the Breadcrumbs bar returns you to your collection, showing you a list of all the available resources, artists, albums and tracks that you have previously defined as part of your collection. The Breadcrumbs bar indicates that you are viewing your Local Music.

### Streams and Podcasts

There are two ways to listen to streams. If you have a favorite station, get the stream &URL; and add it: Playlist Add Stream. You'll be able to find it again in Playlists, as a Saved Playlist. Otherwise, browse through the scripts available in our Script Manager (Tools Script Manager). There are some excellent collections available, which will show up in the Internet section of your Media pane.

Podcasts have their own section in the Media pane, above. If you have an RSS or Atom feed &URL;, click the green + and add it there. If you have an OPML file to import, that choice is available also. Use the context (right-click) menus to Add to playlist, Configure, Remove Subscription, Update Channel, or mark an episode as New. If you are interested in browsing through a large collection of podcasts, check out the Podcast Directory available through the Script Manager, referred to above.

### Using the Content Browser

The hard disk of your computer, audio &CD;s, external devices and the Internet are the basic resources for your collection. After your collection has been set up, it is likely that your collection will hold a large number of albums and tracks, much more than can be shown on a single window.

How to change the display of your collection, below:

#### Hiding or expanding information

The area of the Media Sources pane below the search bar is called the Content Browser. Three media sources are indicated in the image of a Content Browser below: &CD;, Local Collection and a Media Player:

Clicking the banner for a device (the blue bar for the Sansa above) shows or hides the content of that device. The direction of the green arrow on the right indicates whether the contents for that device is hidden or shown. The content on a particular device can, in turn, be hidden or shown using the same principle, clicking on the appropriate artist or album. A - symbol on the left of an artist or an album indicates that the contents has been expanded. A + symbol indicates more contents for that category is available / currently hidden. In the image above, the information for Mike Oldfield - The Songs of Distant Earth &CD; has been expanded, showing the individual tracks. On the other hand, the albums and tracks in the Local Collection are hidden. By clicking these + or - symbols you also can expand or hide information.

#### Changing the order of tracks and albums

The order in which tracks are sorted in the Content Browser can be customised by using the Sort Options button at the top of the Media Sources pane:

The sort order is indicated on the top left of the Media Sources pane, just below the Search text box. The default order is Artist / Year - Album. The display order of the Content Browser can be temporarily switched between the user-defined sort order (described above) and a Merged view in which which artists are listed alphabetically, no matter on which media the music is stored. To toggle the Merged view,click the Merge icon at the top right-hand of the Media Sources pane:

To search your collection, type your search term into the search bar at the top of the Local Music section. Not only can you search by artist, album or track name, but any part. You might create a nice playlist by searching for winter, for instance, or merely find a track when you only remember one word of the title. You can also search by rating, playcount, even filetype. See Search in Collection for more details.

#### Deleting items from the collection

Use this option with care; the tracks will be deleted from your hard drive, not sent to the Trash.

You can delete any item from your collection by right-clicking on it and choosing the bottom item Delete Tracks. A confirmation dialog will appear, preventing the accidental deletion of any tracks. More than one item can be selected with &Ctrl;click.

## Playlists

### The Playlist pane

Having created a collection of music, you will wish to listen to it. So, create a playlist containing the selection of tracks you want, in the Playlist pane. This is where you play your music, streams, or podcasts. You can sort your playlist by title, album, artist, genre and many others. For instance you can sort your tracks by year first, then by artist and so on.

The search box lets you search or filter your tracks. The two big gray arrows at the top of the Playlist pane lets you skip to the next or previous track containing the letters you have chosen. The wrench to the right lets you filter your tracks by artist, album, &etc; The layout of the Playlist pane can be changed through the top-level menu: Playlist Playlist Layouts.

### Adding music to a playlist

There are four ways to add music to the playlist in the Playlist pane.

1. Choose some of your music in the Content Browser, and drag it to the right. If you drag it over the Context pane you'll see the Pop-up Dropper, also known as PUD. The image above shows PUD in action. PUD provides three options: Add to Playlist, Replace Playlist, and More.... The option highlighted in a grey area (Add to Playlist in this image) is the active one. Dropping the album there adds it to the playlist in the Playlist pane. Choose one of the other options to do something else with your selection. Dragging it over More... brings up a new menu of choices in PUD.

2. Drag your selection all the way onto the Playlist pane on the right-hand side of the &amarok; screen.

3. Double-click the album/track you wish to transfer to the playlist.

4. Right-click the album or track. In your right-click menu, you'll find similar choices. The image below shows the context menu that appears after an item (Brother Ali - Real As Can Be in this case) has been right-clicked. Select Add to Playlist.

### Using the Toolbar

The Toolbar at the top of the &amarok; screen provides a simple interface to control the playing of music in the playlist. Click the round icon on the left to start your music playing, and click it again to pause. On the right is the volume and mute control: click on the center of the icon to mute. Use your mouse scroll wheel to control the volume, or drag/click your mouse on the outside ring of the volume icon. Once a track or stream begins to play, the artist/album name/track title slowly alternates in bold in the center. On the right is the next track, which you can click to start it playing immediately. Once a track has played it will be on the left, so you can click on the title to go back to it. The progress bar in the middle of the Toolbar indicates the time elapsed (left hand) and time remaining (right hand) for the track that is currently playing. If you'd rather see a more traditional toolbar, you can select Slim Toolbar from the View menu.

### Manipulating playlists

The most important manipulation you will probably perform on your playlist is to delete albums or tracks, to rearrange the displayed items for each track or to rearrange the display order of tracks.

#### Removing a track

You can remove any track or album from your playlist by:

1. Right-click on the item in the playlist and choose the option Remove from playlist.

2. Drag the item to be deleted over the Context pane to activate PUD. Several options will appear over the Context pane. Drag the item to the area marked Delete from playlist. See the image below that shows a track being dragged onto the Remove option in PUD.

3. Selecting the track or tracks and use your Delete key. Multiple tracks can be selected using &Shift; or &Ctrl;.

You can undo your delete by pressing &Ctrl;Z or by clicking the appropriate arrow in the Playlist Toolbar at the bottom of the Playlist pane (see below).

#### Using the Playlist tools at the bottom

At the bottom of the Playlist pane are seven icons:

##### Icons of the Playlist Pane

Icon | Action
| Clear playlist of all albums and tracks
| Save your playlist. If you do not rename it, defaults to the date as a name.
| Undo your last edit to playlist
| Redo your last undo to playlist
| Highlight the track currently playing. Useful for long playlists
| Set the play mode: repeat tracks, random order, prefer rarely played, &etc;
| Set the play mode: repeat tracks, random order, prefer rarely played, &etc;
| Edit the playlist queue; tracks played first before the playlist resumes.

These buttons provide convenient alternatives to several keyboard actions.

### Saving and retrieving your favourite playlists

The disk icon (shown in the table above), at the bottom of your Playlist pane, allows you to save the current &amarok; playlist. This enables you to recall a particular selection of music from your collection at any time. Playlists only contain pointers to the music you selected, not the music itself. So if your playlist is pointing to music on an external device, it must be connected and mounted, otherwise the music cannot be played. There are three places to store playlists:

1. outside &amarok; on your computer file system,

2. in your &amarok; playlist database

3. on an portable media device.

Clicking the disk icon at the bottom of the Playlist pane stores your playlist in the &amarok; playlist database. By default, your saved playlist has a name composed of the date and time when you saved it (see image below). By right-clicking the playlist name, you can rename it to something more suitable. Right-clicking on a playlist name also allows you to add it to your existing playlist in the Playlist pane, or to replace your existing playlist.

## The Context View

The power of &amarok; is in the Context pane (in the center of the default &amarok; window), where you can install various applets to help you enjoy and explore your music. Most of this additional information is obtained from the Internet, so a connection is important to get the most out of your Context pane. By default, three applets are preset: Current Track, Lyrics and Wikipedia.

### Default layout

The default Context pane searches for the lyrics of the song you are playing. If it finds the lyrics, it displays this in the bottom half of the Context pane, while the top banner of the Context pane displays the album cover and track information for the current music. Sometimes lyrics are not available, because they may not be stored in an appropriate resource on the Internet. In addition, the track information for the current track needs to be tagged correctly for lyrics to be found. If lyrics are not found, this can be due to various reasons, amongst them wrong informations in the Internet sources like incorrect numbering system of the tracks within the album, and the mis-representation of unusual text, such as when the title of a track should contain characters with a circumflex, cedille or accent (ê,ç,à), but does not.

### Customizing the Context pane

At the bottom of the Context pane are three buttons for the default applets. On the right of these buttons you see a wrench, clicking on it will show a red X allowing you to remove these applets. Click the green + to add more display options (see image below). Drag the labeled buttons to re-order the applets you have, and click the wrench again to fix your selections. This makes the Context pane extremely flexible, maximizing the possibility of a custom display that fits your preferences.

## How to deal with problems

### Some of the music is being rapidly skipped over

You may not have installed the necessary codecs. More about that here FAQ: What Media Types Does &amarok; Support. Please refer to your distribution.

### After my iPod has been mounted, it is not shown in the Content Browser

This should not happen. Check that the device has been properly mounted. Simply typing `mount` in a console will show you all mounted devices.

### &amarok; cannot see the predefined playlists on my portable music player

Wait for the next version of &amarok;.

### After I have updated my collection, the additions are not shown in the Content Browser

From the top-level menu Tools Update Collection. If they don't show up, quit &amarok; from the Amarok menu, or use &Ctrl;Q to quit. Once you restart &amarok;, your collection should show your updates.

### &amarok; cannot find the lyrics of the songs that I play

Possibilities:

1. The lyrics are not available in the sites checked on the Internet. You may wish to add more sites via the script menu (Tools Script Manager).

2. The track numbering system within an album in your collection is not correct.

3. The title of your song contains special characters with a cedille, accent, &etc; that do not show in your track title. Therefore the lyrics script applet cannot find a match for your title. Check your tags and track numbering system with a tagger such as Picard.

### My question isn't answered here

More complex issues are covered in the Manual, including Troubleshooting and Common Problems, and the Amarok FAQ.

## GLOSSARY

### Breadcrumbs

This is a way of navigating a hierarchical file structure; on &amarok; near the top of the Media Sources pane. Starting at the Home folder level, it shows how deep one has navigated into the file system. When you have gone to a particular place in the file system, you will see all folders at a higher level. In &amarok; the > links between folder levels allow you to find out what alternative folders are available at a particular level. The breadcrumbs are an efficient mechanism to navigate the whole file system on your computer.

### Collection

All the sound files that &amarok; has compiled in the database. Your collection may vary in size and composition of music tracks, depending which external devices (such as audio &CD;s or portable players with music) are connected and mounted on your computer.

### Content Browser

This is the central part of the Media Sources pane that allows you to list the music that you have in your collection. The Content browser allows you to select the sort order of your track lists as well as the detail in which you wish to see your music.

### Playlist

A selection of tracks from your collection that you wish to play. Some portable music players have predefined playlists that are likely to differ from your &amarok; playlists.

### Script

&amarok; plugin to extend functionality. Scripts are available from Tools Script Manager. Add more lyrics sources, more streaming stations, save covers to your album folders, burn &CD;s from playlists, &etc;

### Scrobble

To scrobble a track means that as you listen to it, the title of the track and artist are sent to a Web site such as Last.fm, where the information is added to your profile.

### Stream, streaming

Like 20th-century radio stations, Internet radio stations send out streams of content. One can find music, news, commentary and opinion. Many streams can be accessed through &amarok;, either through scripts such as Cool Streams, or individually added by menu (Playlist Add Stream).

### Tags

The information about each of the tracks you listen to, &eg; album name, track title, composer, artist, year, &etc; There is a standard called ID3 for including this information on audio &CD;s. You can edit the tags of individual tracks within &amarok; if the file permissions are correct.

## Credits and License

Documentation Copyright see the UserBase &amarok; page history

&underFDL;
&documentation.index;