# The &yammi; Handbook

## Introduction

With the success story of the mp3 format, more and more people are creating their personal digital music collection, consisting of a few hundred upto many thousand songs in popular formats such as mp3. While some people are happy to organize their songs from the command line, a lot of people realize they need some kind of organization tool to manage their collection. This tool should assist in finding songs and do something with them (eg. play, edit, categorize, backup or delete them). Yammi is targeted at exactly these needs, well suited to manage a song collection of 10.000 songs efficiently, and at the same has a very intuitive user interface, enabling even people with little computer experience to find songs and listen to them.

Yammi enables you to

- conveniently find songs - no matter whether you spelled them correctly - within a second (fast fuzzy search)

- organize your songs into playlists (called "categories")

- read and write id3 and ogg tags, easily keeping tags and filenames consistent

- keep statistics by logging when a song was played (when/how many times was a song played?)

- assist in burning a selection of songs to a single audio CD or your whole song collection to multiple data CDs (automatically distributing your songs over multiple media)

- act as a jukebox, loading song files which are not on your harddisk on demand from removable media (such as CDs or DVDs)

- prelisten to songs on headphone while normal playback (eg. to DJ your own party, needs a second sound card)

- invoke other programs or custom scripts such as k3b, cdlabelgen, ... to burn CDs, generate CD labels or execute other commands, using all information from Yammi's song database.

The feature that distinguishes this tool from others is an extremely powerful fuzzy (tolerant) search function, that is still as intuitive and easy as it can get: Type in anything that you are looking for (eg. artist, title, album, comment) and within a second Yammi will provide a list of "best matches", using a clever fuzzy search algorithm. Not knowing the exact spelling of titles or artists is no longer a problem, as Yammi will find them anyway - even if you are horribly misspelling them in the search. This fuzzy search works just as you would expect it, even with a couple of thousand songs in the database. Therefore you never ever have to dig through your directory structure to find a particular song.

Yammi organizes your songs into folders. On the one hand there are automatically generated and updated folders such as one folder per artist, album, year and genre. On the other hand, custom folders (comparable to playlists) can be created by the user. In the view of each folder, songs can be sorted after just every available information, eg. title, artist, length, most recently added songs, most recently played, bitrate...

Yammi does as an excellent job on a party. In connection with XMMS' crossfading plugin (volume normalization might be useful, too) and a second sound card (to prelisten to songs on a headphone) it almost replaces the DJ, and is still extremely easy to use even for people with little computer experience.

Yammi does also a good job in replacing your CD-player. In connection with a infrared receiver and LIRC its basic functions can be accessed with a remote control, even enabling you to turn off your computer via remote control (or let it play five more songs before shutting down, like the "sleep mode" of your stereo).

Although I tried my best, I can take no liability that Yammi is not causing any damage to your song collection, your speakers or your neighbour...

## Installation

### How to obtain Yammi

Give it a try at The Yammi Homepage.

### Requirements

#### Mandatory

- Trolltech's QT, version 3.2 or higher

- taglib, version 1.3 or higher

- libstdc++

#### Optional (but recommended)

- For XMMS support: XMMS, version 1.2.6 or later and glib (-lgtk -lgdk -lgmodule -lglib -ldl -lXi -lXext -lX11 -lm -lxmms)

- For Gstreamer support (experimental): gstreamer (version 0.6.x, versions 0.8.x will NOT work) and kgst bindings (version 0.6.1)

- For listening to songs on a second soundcard during playback on your primary soundcard you need a suited command line tool. By default these can be mpg123 (for mp3 files), ogg123 (for ogg files), mplayer (for flac files) or play (for wav files).

- If you want to use the grab and encode script which can be called from within yammi, you need cdparanoia and (not)lame or other ripping/encoding tools, for details have a look at the script "yammiGrabAndEncode" included in the distribution.

- Depending on your plugin configuration you might need other programs (such as k3b for the "Burn Audio/Data CD" plugins or cdlabelgen for the "Create CD Label" plugin). See the Yammi plugin page for details.

#### ...for compiling from source

If you want to compile Yammi from source, you need additionally to the above mentioned requirements the following packages installed:

##### Mandatory

- Xfree86-devel

- taglib-devel

- qt3-devel

##### Optional

- For XMMS support: xmms-devel

- For Gstreamer support: gstreamer-devel

### Compilation and installation

In order to compile and install Yammi on your system, type the following in the base directory of the Yammi distribution:

> ./configure --prefix=`kde-config --prefix`

> make

> make install

If compilation is successful, the executable "yammi" and some other files will be installed to the standard KDE directories.

Note: If you are upgrading from a previous yammi version (prior to 1.2-rc), you might have to delete an old yammi.desktop in your KDE installation, if yammi still appears in your menu structure under "Multimedia" -> "More Programs" (it should appear under "Multimedia" -> "Audio player" now).

### Problems

If you experience problems with compiling or installing, please consult the README file included in the distribution which explains various switches for the configure script that might be necessary on your system. If you still experience problems, please have a look at the "Bugs" page on the Yammi homepage for known problems or follow the procedure described on that page for submitting a bug report.

### Deinstallation

In the base directory of the yammi distribution, type

> make uninstall

### Starting the first time

After successful installation, you can start yammi via the KDE menu (it should be installed under "Multimedia" -> "Audio Player") or by typing "yammi" in a shell (Tip: if you encounter any problems or want to know what's going on: start yammi in a shell and have a look at the output that yammi creates on the console).

On first startup, yammi will create some files (usually, in ~/.kde/share/apps/yammi) to store your song database, preferences settings and logfiles. Before you start scanning your harddisk for songs, you should edit the preferences (Configure -> Settings...) and set the paths to the location of your song collection.

## Using &yammi;

This is how yammi looks like in action: Here's a screenshot of &yammi; Screenshot

### General Usage

The general usage of Yammi is intuitive:

- On the left, the "Quick Browser" provides a list of folders, each containing a list of songs or subfolders.

- On the right, all songs contained in the currently selected folder are shown.

- Normally you would use the Quick Browser to pick a selection of (or all) songs, then the songlist to pick one (or more) songs to play, edit, categorise, ...

- Alternatively, you can type something into the search field to search for a particular song, artist or album.

- The most important actions are available in the toolbar or context-menu (right-click on a song or a folder), the rest is available via the main menu.

### Scanning harddisk

The first step for using Yammi is to get your songs into Yammi's database by having your harddisk scanned. For this to work correctly, you should first check your configuration (Configuration->Settings) and make sure that the directory "base directory for scanning" is pointing to the base directory of your song collection. Also, give a path for "trash directory for deleted song files", as this directory is needed when you want to delete songs within Yammi (Yammi does not delete any files, but moves them to this directory and skips this directory when scanning for new songs). Now start your database update (Database->Update), which should insert all found songs into Yammi's database. After the update you are ready to use Yammi, for example search for songs, categorize them or enqueue them to your media player. For more information about scanning your harddisk, or for information about scanning CDs, see "Updating Database" in "Advanced Topics".

### Choosing a media player

Yammi supports different media player backends. Depending on your system, not all of them may be available, see the installation chapter for requirements.

#### ArtsPlayer

This player uses KDE's standard sound server arts. It does not provide any crossfading capabilities.

#### XMMS

This backend uses the X MultiMedia System for playback of songs. It synchronizes the playlist of Yammi with that of XMMS (in both directions, so you can also use the controls of the XMMS gui to skip tracks or seek). You can use all available plugins existing for XMMS, eg. the crossfading plugin.

#### Noatun

This backend uses two Noatun, instances for playing your songs. By using two instances, Yammi implements a crossfading of successive tracks (fading out the first Noatun instance while already fading in the second Noatun instance).

To make noatun correctly cooperate with Yammi, you might have to change your noatun configuration:

- disable "Allow only one instance of Noatun"

- disable at least "Tag Reader" and "Lucky Tag Reader" in "Other Plugins" (if you experience problems, try to disable all other Plugins

- choose "Split Playlist" as your playlist plugin

#### GStreamer

This player backend is still in an experimental state. It uses the gstreamer framework for playback. GStreamer itself uses different backends. It is recommended to use the "osssink" backend, because other backends might crash Yammi when seeking in songs (apparently a bug in the KDE gstreamer bindings, not in Yammi).

### Searching

Type in anything into the search field, Yammi immediately shows you the best matches, rated with a percentage (you can configure the threshold for the shown matches in the settings). That's basically it, simple but effective, just give it a try! Yammi looks into title, artist, album and comment for similarities. Yammi will automatically switch to the folder "Search Results" whenever you type in anything into the search field. Tip: For quickly searching for a song, use Ctrl-F or ESC to set the focus to the search field and clear it.

### Song information

In the songlist there is one row per song, containing various information about the song. The following columns are available, which ones will be shown can be configured in the view menu, and the order can be changed by dragging the columns to another position.

(* = corresponds to id3/ogg tag info, + = extracted from mp3/ogg layer info)

- artist*

- title*

- album*

- length+

- year*

- track*

- genre*

- addedTo

- bitrate+

- path

- filename

- comment*

- last played

Depending on the chosen folder, there may be additional columns, for example:

- Match (percentage of how similar the song is to the search term, only in folder "Search Results")

- Pos (position within the folder, only in folder "Playlist" and "Categories")

- Played on (when the song was player, only in folder "SongsPlayed" and "History")

- Reason (displaying the reason why there was a reason with this song, only in folder "Problematic Songs")

### Song coloring

The songs entries in the songlist are normally written in black, except:

- currently played song (red)

- song enqueued in playlist (blue)

- song already played in this session (green)

- song not available on local harddisk (grey) (=> probably needs to be loaded before playing)

- song available in swap dir (dark grey) (=> song is already loaded, will be only checked for folder "Playlist")

### Folder structure

The following folder structure is provided automatically:

#### Folder "All Music"

Contains all songs in Yammi's database.

#### Folder "Playlist"

Contains the queue of songs, that are still to play (and includes the currently played song). After a song was played, it is removed from the Playlist (all played songs are listed in the folder "Songs Played").

In this folder you can move songs around to change the order of the playlist. However, you are not allowed to drag a song to the top position, as this is the currently played song. Please note that you can only drag songs if the folder is ordered ascending after the first column ("Pos"), which is the default ordering when you click on this folder.

#### Folders Albums/Artists/Genre/Year

Contains a subfolder for every album (artist, genre, year) for which there are more than x songs in the database, with x=group threshold. The group threshold defaults to 5, but can be configured in the settings.

Please note that the default group threshold of 5 means that eg. if you add a single song from one artist there will be no folder for that artist created unless there are more than 5 songs of this artist.

#### Folder Categories

This folder contains "categories" (normally known as "playlists") of songs, that can be created and filled by the user. You can add a song to a category by right-clicking on it and choosing "Insert into..." and the desired category.

The songs in each category can be ordered by dragging the songs to the desired position. Please note that you can only drag songs if the folder is ordered ascending after the first column ("Pos"), which is the default ordering when you click on this folder.

#### Folder History

This folder contains the history of played songs, each song shown with the timestamp when it was played. For played songs to be logged, you need to activate "logging of played songs" in the preferences. This folder only contains the songs loaded from the history file at startup. Songs played in this session will be appended to the folder "Songs Played".

#### Folder Songs Played

Contains all songs that have been played in this session of Yammi, together with a timestamp. When Yammi terminates and logging of played songs is activated (see the settings dialog), these songs will be appended to the history file, and will appear in the folder "History" the next time Yammi is started.

#### Folder Media

Contains a subfolder for every media (eg. CD or DVD) that you prepared for burning with Yammi. Additionally contains a subfolder containing all those songs that are not contained on any media. This allows to easyily manage a backup of your song collection, quickly accessing those songs that are not yet contained on a (backup) media. When burning song files to a CD or DVD with the assistance of Yammi, the program adds information to its database about on which media (and under which path on that media) each song is available. This enables you to quickly find on which media you have song files, and it enables Yammi to request the required media to load songs into a swap directory (jukebox functionality).

#### Folder Problematic Songs

This Folder contains songs that were found problematic when performing a consistency check or database update (eg. songs contained twice). Note: This folder will not be saved to Yammi's database, therefore you should look at the identified problems immediately after performing a database update or consistency check.

#### Folder Search Results

This folder contains the results of the last search.

#### Folder Recent Additions

Yammi automatically groups into this folder the latest additions to your song database.

#### Folder Unclassified

This folder contains all songs that are not appearing in either

- a category

- the folder "Artists"

- the folder "Albums"

This folder can assist you in organizing your songs into categories.

#### Directory structure

Yammi does not require a specific directory structure of your song collection as Yammi keeps its own database of songs with all necessary information (artist, title, album, filename, ...). This song databse is saved as a simple xml file in the user's home directory (normally under ~/.kde/share/apps/yammi/songdb.xml).

However, you should not move your songfiles from outside Yammi, because Yammi will not find the files any more (although Yammi tries to detect files that have been moved on a database update). Therefore Yammi provides a function to move song files, which at the same time updates the information in Yammi's database.

Tip: It still helps a lot to have a fixed directory structure, like {artist}/{album}/{artist} - {title}.{suffix}, and Yammi actively supports this with its consistency check modes (which allow you to move your songs to the appropriate location and/or rename them automatically when you change tags).

### Song Actions

All song actions are available from the context menu (i.e. clicking on a song with the right mouse button). The most important ones are also available in the toolbar or via keyboard shortcuts.

#### Play...

- Enqueue - Enqueues a song to the end of Yammi's playlist.

- Enqueue as next - Enqueues a song as the next song to play in Yammi's playlist.

- Play immediately - First enqueues the song as the next to play, then causes a song change, so the song is immediately played.

- Dequeue - Dequeues a song from Yammi's playlist, ie. removes all occurrences of this song in Yammi's playlist (if applied on a song in the playlist, only removes that occurrence in the playlist).

#### Prelisten to...

(only available if a second sound device is configured in the preferences)

- start - Immediately starts playing the song via the second sound device, starting from the beginning.

- middle - Immediately starts playing the song via the second sound device, starting in the middle.

- end - Immediately starts playing the song via the second sound device, starting close to the end.

#### Info...

Opens a dialog showing information about the selected song(s), which also allows to edit the tags.

##### Correct filename / directory

If you have the consistency modes (keep filenames/directories consistent) activated, the checkbox "correct to" after the filename/directory will be checked, and you will see how Yammi will modify the filename or directory when you change the tag information of songs. A grey entry indicates that the filename or directory is consistent with the naming scheme you configured in the preferences, whereas a red entry indicates that it has to be corrected. If corresponding box is checked, these corrections will be made as soon as you exit the dialog with the "OK" button.

##### Multiple selected songs / mass editing

If more than one song is selected, the song info dialog is slightly different:

- Yammi shows the total size and length of the selection

- entries that are not exactly the same for all selected songs are shown as "!". When you change this entry, you can conveniently set that entry for all selected songs to the new value (ie. unifying that value for the whole selection). As long, as this is not changed, these entries are not touched

- entries that are exactly the same can be conveniently changed for all selected songs by changing the value shown

#### Insert into...

Allows to insert one or more songs into an existing category or remove them from a category. The icon in front of the category name indicates whether the song(s) will be added or removed from the category. A check mark means that the song(s) is already contained. Selecting a category with a check will remove the song(s) from it. A check mark in brackets means that some of the selected songs are contained in the category, and selecting the category will add all songs to it.

#### Search for similar...

This allows you to quickly search for songs from the same artist (or album or title) as the selected song. It simply takes the information you requested from the selected song and performs the usual fuzzy search with that information.

#### Advanced...

##### Delete

Deleting can be done in two ways:

1. Deleting the database entry in Yammi's database (does not touch the song file).

2. Deleting the song file, which is done by moving the song file to the trash directory. Yammi still keeps the database entry. Usually this makes sense if the song is present on at least one media, and therefore can be loaded to the harddisk before playing via Yammi's jukebox functionality (and therefore the dialog shows you on which media that song is registered).

##### Move file to...

Moves a file to another directory. The path information in Yammi's database will be updated with the new location of that file.

##### Check consistency...

Performs a consistency check on the selected song(s). See "Checking consistency" in "Advanced topics".

##### Burn to media...

assists in burning the selected songs to one or more media (distributing the selection of songs over multiple media according to the configured media capacity). See "Burning files" in "Advanced Topics".

### Settings

You can configure Yammi's settings via the menu: Settings -> Configure Yammi.

Only some options are explained here, the rest should be self-explanatory if you read the provided tool tips (stay over an item with the mouse for a while).

#### Consistency Mode Settings

These settings determine, whether Yammi modifies the meta info in your files or renames or moves them when you change any attributes (eg. the title or artist) in the song info dialog.

##### save tags immediately

When enabled, Yammi will immediately save all tags to the file (if possible) after altering any attributes in the song info dialog.

##### keep filenames consistent

When enabled, Yammi will by default correct your filenames (if necessary) to keep the filenames consistent with the configured filename pattern after altering relevant attributes in the song info dialog.

##### keep directories consistent

When enabled, Yammi will by default move your files (if necessary) to keep the directory consistent with the configured directory pattern after altering relevant attributes in the song info dialog.

##### Tip

If you don't want Yammi to touch your song files in any way, you should leave these three settings disabled!

However, for easy organizing your song files I found it extremely useful to have consistent filenames, directories and tags at any time.

See also "Checking consistency" in "Advanced topics".

#### Group Threshold

This value determines, how many items of one group must be present for a subfolder within the folder Artists/Albums/Genre/Year to be created. If you set this value to 1, every artist/album/genre/year will appear as a subfolder, a value of 10 only will create subfolders for artists/albums/genres/years which contain at least 10 entries.

### Key bindings

You can see and edit the key bindings for Yammi via the menu ("Settings" -> "Configure Shortcuts").

Note concerning crossfading:

If you use crossfading, it sometimes comes in handy to change to the next song without crossfading (e.g. to quickly listen to the next song). For these cases press the SHIFT key in combination with the requested action, which disables crossfading.

### Advanced topics

#### Autoplay

Too lazy to manually enqueue songs all the time?

Use Yammi's autoplay functionality to let Yammi automatically enqueue songs for you!

Choose a folder to enqueue songs from and choose "Autoplay" from the folder's context menu. Then set the autoplay mode from Yammi's "Autoplay" menu.

Currently, Yammi offers two modes:

"Random" randomly selects songs from the autoplay folder (Yammi does not select songs already enqueued in the playlist).

"Longest not played" chooses those songs, that haven't been played for the longest time. For this to work correctly, you need to enable the "logging of played songs" feature in the settings (If more than one song haven't been played at all, Yammi chooses randomly from those songs).

Tip: You can still manually enqueue songs without having to stop the autoplay mode. Yammi just fills up the playlist if there are less than 5 songs in it. The selected autoplay mode and folder are also saved for the next session.

#### Checking consistency

The menu offers the possibility to check your complete database for consistency. From the context menu, you can also apply this consistency check to only a selection of songs.

The consistency check is a tool meant to help you organizing your song collection. You can configure the aspects to be checked in a dialog, right now Yammi supports the following checks:

- check for existence of files: are the song files existing and readable?

If files do not exist on the location given in Yammi's database, the entry can be updated with a blank filename and path (if the file is existing on a media) or deleted (if the file is not existing on any media).

- check tags: consistent with Yammi's database?

If tags are not consistent, they can be corrected in two ways (only possible for mp3 and ogg files):

1. the tags in the corresponding files can be set to the values in Yammi's database (Yammi database => file tags, default mode).

2. Yammi can re-read the tags from the files and update its database content with the new values (for example if you edited tags with another program outside Yammi).

Be careful using this function, as it might overwrite all the tags in your files!

- check filename: consistent with the configured filename pattern (such as "{artist} - {title}")?

If filenames are not consistent, they can be corrected according to the filename pattern.

Be careful using this function, as it might rename all your files!

- check directories: consistent with the configured directory pattern (such as "{artist}/{album}")?

If directories are not consistent, the song files can be moved automatically to the correct location according to the directory pattern.

Be careful using this function, as it might move all your files!

- no song contained twice in the database?

Songs are considered the same if they have the same artist, title and album. These three fields serve as the "primary key" for Yammi's database. As Yammi uses this primary key for identification (eg. for logging and categories), you should never have more than one song with the same primary key. On addings songs to your database, Yammi will add a "(2)" to the song title if the added song's primary key is already existing.

Yammi also detects two song entries pointing to the same file, and one of them will be deleted.

Before writing tags, renaming or moving files, Yammi asks you for confirmation before performing that operation. You can confirm for a single song or for all songs.

After checking consistency, the folder ProblematicSongs contains all the problematic songs that were found. A column "reason" explains why a song was found to be problematic. This allows to resolve any inconsistencies. Note that this folder will not be saved for the next session, so please resolve any inconsistencies immediately after checking consistency.

#### Burning files

For most users, there are two reasons to burn files on CDs:

1. To burn an audio CD from a selection of songs, to play it on a normal CD player

2. To make an backup of some files on harddisk to CD (possibly to remove the files locally and use the removable media management of Yammi).

##### Burning an audio CD from a selection of songs

I highly recommend the fantastic burning program K3b (http://www.k3b.org) to burn an audio CD.

If you have k3b installed, you can simply select the songs you want to burn, and use the "Burn with K3b(audio)" plugin of Yammi. It will start k3b, open a new audio project and add all selected songs to it.

In that way, burning the favorite songs of a friend to an audio CD is easy as pie:

1. Create a new category

2. Let your friend put all favourite songs into that category

3. Mark all songs of the category and select "Burn with K3b(audio)" from the plugin menu

4. Start the burning process from within K3b.

5. Deliver the CD ;-)

##### Burning files to CDs as backup

For assistance in burning files to a CD, do the following:

1. Select the songs you want to burn

2. In the context menu of the songlist choose "Advanced"->"Burn to Media".

3. You will be asked for a name and a start index for that collection of songs.

4. Now Yammi will create subfolders in the "Media" folder, taking care that none of these subfolders exceeds the maximum media size configured in the preferences.

For burning the song files to CD, you can now simply invoke the "Burn with K3b(data)" plugin from the context menu (assuming you have installed k3b) for each created subfolder.

Yammi also remembers on which media a song is contained. This allows to delete song files from harddisk to save space, and let Yammi request the corresponding media the next time the song is in the playlist, so that the song can be loaded from the media on demand.

#### Playlist management of yammi

Yammi takes over the playlist management of the media player and has its own folder named "Playlist" where you can move songs up and down, remove them from the playlist, or directly retrieve information about them. You should not directly modify the playlist of the media player any longer, as Yammi might overwrite your song ordering or songs added from within the media player. Yammi also disables the random play setting of XMMS, as this would confuse Yammi's playlist management.

When Yammi is closed, it saves the current playlist and position within the song and restores this setting the next time you start it.

#### Updating song database

The "Database" menu offers the possibility to update your database in two ways: By scanning your harddisk (or selecting single files to add to the database) or by scanning a removable media (eg. a CD). After choosing the corresponding entry in the "Database" menu a dialog will show up which allows to set the directory to scan and the file pattern for scanning.

Yammi starts in the chosen directory and recursively scans your harddisk for new songs. It scans all files matching the given pattern and checks, whether the song is already contained in Yammi's database. For all new songs found, Yammi tries to get the song information such as artist, title, album... by looking at the id3(v1.x or v2.x) or ogg tags. If tags are not present, Yammi tries to extract the information from the filename, using the configured guessing scheme. If the filename contains an artist or title that is longer than 30 characters, and the tags contain only the first 30 characters (as this is the limit for id3v1.1), Yammi tries to take the full name from the filename (Yammi's database has basically no restriction for the length of the entries).

Updating your song database does not touch your song files. Exception: If a new song is already existing at another location, either the new or old version will be moved to your configured trash directory.

#### Scanning removable media

This is quite similar to scanning your harddisk. The difference is that the songs added to Yammi's database will not contain a path and filename, but instead will contain the scanned media's name in their "contained on" media list. This means that you can't directly play these songs, but have to enqueue them, and load them from this media into the swap directory before playing. You can load songs from a media into the swap directory by using the button in the toolbar. If a song is already existing in the database, Yammi will just add the media to its media list (if not contained already), so scanning a media twice should not create any inconsistencies.

#### Selecting single files to add to your database

Sometimes you don't want to scan your harddisk, but just add one or two files to your database. Select the menu entry "Import Selected File(s)".

#### Grabbing and encoding new songs

Especially on a party it might come in handy to directly grab and encode some songs from an audio CD. Yammi offers a basic support for that, but for grabbing a large number of songs I recommend using one of the many tools out there. For grabbing and encoding a single song, choose "Grab and Encode CD Track" from the "Database" menu. You will be asked for track number, artist and title. Then Yammi executes in the background the script "yammiGrabAndEncode" (which is included in the distribution and normally installed in /usr/local/bin/), which grabs the track from CD using paranoia, and then encodes it using (not)lame. (You might want to customize the script to fit your needs, eg. setting the bitrate for lame, which is defaulting to 256kb/s. Just have a look at the script, it's easy...). When the script has finished, a new song file exists in the directory given in the preferences under "base directory for scanning". Yammi then automatically adds this song to its database and informs you with a dialog box.

#### Child-safe mode (currently disabled)

This mode is thought for parties to protect your precious song collection from users deleting files or changing tags by accident. The following operations are not permitted, if this mode is switched on:

- the complete "Advanced" submenu in the context menu is disabled

- delete files

- clear the complete playlist

- update song database

- check consistency

Once enabled, you can only disable this feature with a password, which is: "protect". Alternatively, you could edit Yammi's preferences file by hand to disable this mode.

Okay, this is NOT SAFE IN ANY WAY, it's just meant to protect users who have very little knowledge of computers to do any harm to your song collection by accident.

For better safety, I recommend creating a new user "dj" on your computer with limited access rights, and start Yammi as that user. You can then use the command line option to specify the location of the .yammi directory and make that directory (and the directory with all your songs) read-only for the user "dj".

#### Sleep mode

Want to listen to a few more songs while falling asleep? But how do you turn off the computer then?

Enable Yammi's sleep mode by pressing the button in the toolbar, and specify the number of songs Yammi should play before initiating a shutdown on your computer.

Yammi will shut down in the following two cases:

- the number of songs to play (visible and editable in the toolbar) has reached 0

- the media player stops playback because the playlist is empty

A dialog box appears giving you the possibility to cancel the shutdown.

Via the settings you can configure the shutdown command, which defaults to 'dcop ksmserver ksmserver "logout" 0 2 0' (this corresponds to choosing "Logout" -> "Turn off computer" in KDE). Be careful with shutting down your computer in that way, as open documents might not be saved properly or running programs might not be terminated properly...

#### Removable Media Management

Yammi has support to function as a "Jukebox". That is, you don't need all your songfiles on your local harddisk, but can load them on demand from removable media (such as CDs) into a swap directory. Yammi still keeps all songs in its database to enable you to search and enqueue conveniently. However, before enqueuing the songs to the media player, Yammi will check for availability and enqueue only those songs that are on the harddisk.

To use this jukebox functionality, you should first create a swap directory on your harddisk and set the path and the size limit in the preferences. (I recommend to create a special swap directory and not to use "/tmp/" as your swap dir.)

To remove song files from your harddisk to gain disk space, but keep the song entries in Yammi's database, choose "Delete..." (from the context menu, "Advanced..."), and enable the checkbox "delete file" (and leave the "delete database entry" checkbox disabled). Take care only to remove song files that have a media location stored in their database entry (you can check this when you select "Info..." in the song context menu), or otherwise the deleted song will not be accessible anymore.

To scan a removable media and add all the contained songs to the database, use "Scan removable media" from the file menu.

For the removable media management, Yammi has an extra toolbar consisting of a media list and a "Load" button. In the media list, Yammi collects all the media that are needed to load the songs in Yammi's current playlist, the most urgent ones listed first. (For songs that are available on more than one media, Yammi lists all possible media in this list.) From this media list, you simply select the media that you inserted into your computer (eg. into your CD-Rom), and click "Load". Yammi will then load all songs that it needs in its current playlist from this media into the swap directory (given in the preferences). After loading, Yammi will update its playlist (and the playlist of XMMS) and update the list of needed media to reflect the changes.

For the swap directory, you can give a size limit (also in the preferences). If the size that all the swapped song files use in this directory increases beyond the given limit, then Yammi will remove song files from that directory, using a least-recently-used (LRU) strategy.

#### External Scripts / Plugins

Yammi offers support to call external programs with parameters like song titles or filenames. This can be extremely useful for calling a program for burning songs to CD or for creating a CD label.

These plugins can be configured in Yammi's preferences, and are available via the context menu in the songlist. There are two types of plugins, the first one ("single mode") is invoked for each song, the second one ("group mode") generates a list of items and invokes a program on this list.

Yammi has a set of standard plugins already configured. For other plugin examples, have a look at Yammi's website.

#### Customizing the playlist view

Yammi uses a template to display the playlist in the upper left corner of its window. This template can easily be customized, just have a look at it in the configuration dialog. The placeholders like {artist} and scope definitions like {scope:1} should be almost self-explanatory...

### Tips and tricks...

Avoid having two songs with the same artist, title and album! Yammi will get really confused...

Yammi communicates with Xmms session 0. If you have problems with the communication, you might need to disable "Allow multiple instances" in Xmms (Preferences->Options).

### FAQ

#### Why does Yammi delete all played songs from the XMMS playlist?

It just does so. If you want to listen to a series of songs again, you can select the songs in the "History" folder (where the songs are normally ordered after the time when they were played).

## Credits and License

Program copyright 2005 Oliver Noelle oli.noelle_AT_web.de

Thanks go to...

- ...Bob Lockie for spending days on completely rewriting my configure files

- ...Tom Roth for substantial feedback on the whole project, and detailed bug reports

- ...Philip Scott for contributing the reading of ogg tags

- ...Scott Wheeler for bug reports and ideas for future versions of Yammi

- ...Daniel Pichler, for preparing my sources for being internationalized and providing a german translation

- ...Stefan Gmeiner for sending a patch, cleaning up my messy sources...

- ...Sandra Taufer for providing beautiful new icons for yammi!

- ...Luis De la Parra for providing a big patch pushing yammi towards a proper kde app and cleaning up lots of things!

- ...and many more that I forgot to mention here...

Documentation copyright 2005 Oliver Noelle

&underFDL; &underGPL;
&documentation.index;