IPod and content

What is a Repository?
The left hand pane in gtkpod displays all the repositories that have been created. A repository is (like it implies) a collection of all music tracks, videos and photographs imported into it. They are associated together by a binary XML database file that is the same format as the one that sits on an iPod.

By default, gtkpod creates a Local repository and a Podcast Repository. These sit on the computer with gtkpod (they can be found under the ~/.gtkpod directory). By having a local repository, it is possible to import tracks into gtkpod without needing to copy them straight to an iPod. This means that if the cover art, for example, needs to be changed then tracks can be managed without even having the iPod plugged in.

Of course, gtkpod is pointless without accessing an iPod. In the same pane as the local repository, new iPod repositories can be created. These repositories related to iPods by model and mount point. Normally, one repository is sufficient but as you can see below, it is possible to set up multiple iPod repositories on the same computer.

Repository Pane

 * Below each repository, available playlists are listed along with a podcast playlist.


 * Under iPods that support photographs, a special dynamic node is created that, when clicked, invokes the photo management tool. This allows straight addition of photos to the iPod as well as management of photo albums on the iPod. **Note:** this photo node cannot be deleted!! There is no point trying as it is created by gtkpod for the sole purpose of displaying the photo management tool.

Menus and Toolbar

 * Menus across the top provide alternative access to the most frequently used functions.


 * Toolbar provides the following actions:
 * Load iPod(s) -> used for manually mounting any iPods already set up in gtkpod


 * Save Changes -> vital button! The Save All function that save any changes made to loaded iPods or the local database.


 * Files -> Add individual music files to the selected repository.


 * Dirs -> Add any music files located in the selected directories to the selected repository.


 * Playlist -> Add a playlist file to the selected repository.


 * New PL -> Create a new playlist on the selected repository.

Filter Tabs

 * The two notebooks above the track display are called "Filter Tabs".


 * They allow you to filter which tracks are displayed.


 * If you edit an entry in the filter tab, the corresponding entry in all associated tracks will be updated as well. When writing the tags to disk as well, updating of a large number of tracks may take a while.


 * So in the image above, choosing "Alice Cooper" on the first filter tab and "Trash" on the second filter tab will only display the tracks from that most excellent of albums (no dissenting opinions required! ;-) ).


 * Obviously, these filters can be altered to suit. Selecting ALL on a sort tab effectively removes the filter and displays all tracks.

Track Window

 * Displays all tracks residing in the selected repository and conforming to the selected filters.


 * The columns can be sorted and are interchangeable.

Cover Art Display

 * Displays the cover art of all albums stored in the repository.


 * If no cover art exists for an album then the default "?" image is displayed.

See the Cover Art section for more information.

Getting Tracks into gtkpod

 * You can add individual tracks, entire directories recursively, or existing playlists using "Add Files". A file selection dialogue will appear. By default existing tracks (same full filename) will be skipped.


 * You can add directories recursively using "Add Dirs". A directory selection dialogue will appear.


 * You can add existing playlists using "Add Playlists"


 * You can delete tracks by marking them and pressing the "Ctrl-d" . If you delete tracks from the master playlist (the topmost playlist, called "gtkpod" by default). You can also delete tracks by selecting them, and using "Delete Track" in the Edit menu or from the context menu.


 * You can update ID3 tags of selected tracks in gtkpod from the mp3 file by pressing "Ctrl-u" or choose "Update track info from file" in the Edit menu or from the context menu.


 * You can rename ID3 tags by editing the fields in gtkpod. You can change an entire group of ID3 tags by editing an entry in the sort tab (or mark several tracks and edit the first).


 * You can specify which tags to display in the preferences window.


 * You can specify (in the prefs window) if the ID3 tags of the corresponding mp3 file(s) should also be updated.


 * Can add music and video files invidually using Add Files.


 * Can add directories of music and video file using Add Directories.

The files are imported into the selected repository. If the selected repository is an iPod then the files will be copied directly onto it.

See Supported File Types for types of files that can be imported.

Note: gtkpod is an iPod management tool. Tracks, videos and photographs already need to be on the computer filesystem before they can be imported. If adding a CD is the requirement then it needs to be ripped first. Have a look at:
 * 
 * Juicer
 * 

Dragging and Dropping

 * Once imported tracks can be dragged around gtkpod, including inbetween repositories, playlists, filter tabs and the track display pane.

A drop onto an existing playlist will add the tracks to that playlist.

A drop between two existing playlists or behind the last playlist will create a new playlist to which the tracks are added.


 * The default action for the drop is either move or copy as appears appropriate (e.g. playlists are moved within a database ('local' or 'iPod/Shuffle'), but copied when dragged across different databases). The applicable action is displayed within the drag icon and can be changed by pressing the control key during the drop.

Edit Track Details
The Edit Track Details window can be displayed from a couple places.
 * Select a track from the Track window, right-click and select "Edit Track Details" from the popup.


 * Make a selection in any of the categories, eg. Album, Genre, and right-clicking "Edit Track Details will display the window and allow all tracks in that category to be edited.


 * Right-clicking "Edit Track Details" from the popup menu on the CoverArt Display displays the window, allowing all tracks belonging to the album to be edited.


 * The window allows multiple tracks to be edited at the same time. By selecting the "Change all Tracks Simulaneously" check box **BEFORE** making any edits, all the selected tracks can be updated with the new information.


 * The coverart can be dragged n dropped on from a web browser in the same way as the Cover Art Display. However, dropping a new cover onto this window will update the cover art of the tracks and not the album! This is an important distinction as it is possible to have different cover art for tracks in the same album! (why anyone would but its possible)!

Refresh (Update) Track Info From File
If you have changed the ID3 tags of your original file, you can update the ID3 tags stored in gtkpod without removing and re-adding the track. Simply select the track to be updated and press "Ctrl-u" or choose "Update Track Info From File" from the Edit menu. Since gtkpod needs to know the filename of the track, the "Extended Information File" (see here) is needed.

"Update" will also re-read the replay-gain tags from disk, if available, and set the soundcheck field. If no replay-gain tag is available, the soundcheck field will be erased. You can also select entries in the filter tab or entire playlists for refresh.

Synchronize with Directories
If you have added files to directories or changed files in directories you have previously added tracks from, you can use the "Synchronize Dirs" utility to update your iTunesDB.

"Synchronize with Dir(s)" will use the selected tracks to make a list of directories to update, so you should activate the "Write Extended Information" option in the export section of the Preferences dialogue.

It will then add all non-existing tracks in those directories and update all existing tracks. The tracks are also added to the currently selected playlist, if they aren't already a member.

Tracks that have been removed from the directory will only be removed from the iTunesDB if this option is checked in the option dialogue.

For best results you should also activate duplicate detection. This avoids unnecessary copying of unchanged tracks.

Volume Normalization
There are two fields in the iTunes Database (iTunesDB) that allow for the adjustment of the volume of an individual track:
 * the volume field (a signed integer)
 * the soundcheck field (in dB).

The volume is always active, whereas the soundcheck field is only active when you select 'soundcheck' on the iPod. Further, the soundcheck field only affects the earphone output but not the line output of the iPod.

gtkpod will set the soundcheck according to the replay-gain tag set in your mp3 file. Newer versions of 'lame' automatically include the replay-gain tag when encoding. In that case the soundcheck field will be filled in when you first import a track.

If no replay-gain tag is set, you can use the function 'Normalize Volume' to call mp3gain (mp3gain.sourceforge.net) to calculate the gain and write a replay-gain tag. Since this procedure is very time consuming, it is not done automatically during import. You need to install mp3gain in the default path or set the full path in the 'Tools' section of the preferences dialog. If the iPod is connected, the tag is written to the file stored on the iPod.

At this time "album gain" functionality is not supported. "Album gain" means that the volume of all tracks of one album is adjusted by the same gain, such that the relative volume level remains the same. It is planned to realize this in one of the next versions.

Also, please be aware that tracks are not normalized on a 'per playlist' fashion. If a track is normalized, it's normalized in all playlists it is a member of.

Once the replay-gain tag has been read, it is stored in the extended information file 'iTunesDB.ext'. When you call 'Normalize volume' again, the stored value will be used to re-populate the soundcheck field. Use 'Update Track' to re-read the tag from the file.

Cover art
Cover art is a visual element of your gtkpod music collection. It changes the black and white database of artists and title names back into something related to the physical CDs and DVDs that have been imported.

CoverArt Display
The display consists of 9 covers displayed at any one time. The entire album collection can be cycled through from one end to another. The main image is slighly larger and lacking in "shine" for viewing clarity.


 * Use the scrollbar to quickly slide back and forth over the album collection.


 * Use the scrollbar buttons to more precisely step through each album.


 * Click on the main album cover image (one at the front and in the centre) once to display just the album's tracks in the right pane of gtkpod

CoverArt Popup Menu

 * Right-click on the main album cover image to display the popup menu with 3 options:
 * Select Cover From File


 * View Full Size Artwork


 * Edit Track Details


 * Selecting this option displays a file chooser dialog. Select the preferred image file and click OK. The album cover changes to a scaled version of the new image, while all the tracks in the album have their artwork path modified to the path of the preferred image.


 * Selecting this options opens a dialog displaying the cover image. The image is either its true size of the biggest size it can be while still fitting on the desktop. Its true resolution is displayed underneath in the format width x height.


 * The dialog is modal so must be closed before moving on. The OK button closes the dialog.


 * This provides a shortcut to the "Edit Track Details" dialog for editing the ID3 tag information for all tracks belonging to the album displayed.

Adding cover art from a browser
Unlike other applications, cover art in gtkpod is not hidden away in a "difficult to find" image cache. In fact, cover art files, for a local database, can be located anywhere on the filesystem.

Setting Image on Track Import
Locating the image file in the same directory as the tracks gives the additional benefit that gtkpod will analyse the image upon track import and set the image as the album's cover artwork. It is Important to ensure the image's filename corresponds to at least one of the image filename templates entered in the Preferences window.

Setting Image on Existing Album
The use of the popup menu to select a cover art file from the filesystem has been documented. It is also possible to download a cover art image file from the internet and drag n drop it into gtkpod.


 * Locate the preferred image and display it in firefox.


 * Ensure the url of the image ends with ".jpg" or ".JPG" (other file extensions could be supported if demand warrants it).


 * Drag the image from Firefox and drop it onto the Cover Art Display's centre/main cover image. The main cover image should be displaying the album which requires the new cover.


 * If a cover already exists with the same filename then gtkpod will ask whether the existing image be overwritten or the new image be named something else.


 * The image will be downloaded from the url location, saved in the album's directory on the filesystem and applied to each track belonging to that album.


 * A limitation of the dnd in Firefox is that only the url can be used to get at the image file. Thus, the page must be displaying just the image and gtkpod must redownload the image internally (using curl and the image url).


 * Konqueror offers the additional functionality that the image file can be extracted directly from its cache. This has the benefits of avoiding the internal curl download and that the url is not restricted to those ending in ".jpg"

The importance of the latter benefit concerns websites that do not offer the direct download of cover art images.  is one such site, where its images are displayed in the browser but the image url cannot be used a second time to download the same image. Thus, allcdcovers.com cannot be used as a download dnd source in Firefox. However, in Konqueror, simply open a full image from allcdcovers then just drag 'n drop into gtkpod.


 * Maybe Firefox will do this some day too..

Getting Tracks onto the iPod

 * Tracks can be imported directly to an iPod by ensuring the latter is the selected repository before clicking Add Files or Add Directories.


 * Normally though, tracks will already have been imported into the Local repository. To copy them onto the iPod simply select the tracks in the Track Window and drag them onto the iPod repository icon.


 * To copy a whole album, selected the album in one of the sort tabs and drag that onto the iPod repository.

Playlists

 * Use playlists to group together a set of tracks. Simply create a new playlist in the Local repository then drag n drop the tracks onto it.


 * Tracks are not actually copied into a playlist so should a track be deleted then it will be deleted from all playlists.


 * Drag n drop a playlist onto the iPod repository icon to copy it and all its tracks to the iPod. The playlist will be available in the Playlist section of the iPod's control system as well as all tracks being copied to the iPod.

Save Changes
At any change to a repository, eg. track addition, deletion, edit ..., a change has occurred that requires a database save. To highlight this, the name of the repository is changed to italics, ie. Local -> Local. This shows the repository requires saving.


 * Should gtkpod be closed prior to any saving then a dialog is displayed informing that data changes will be lost if a save is not performed.


 * Clicking the "Save Changes" button will save all changes made to all of the repositories. This is the point where tracks are actually copied to the iPod and the iPod database updated. Only after a save is performed will the tracks copied to the iPod, be playable on the iPod.

Playcounts and ratings
Whenever a track is played completely on the iPod (firmware version 1.3 or higher) a counter in the "Play Counts" file will be increased by one. The same file also contains the rating set with the 3rd generation (and later) iPods. This file appears to be deleted whenever the iPod resets itself, e.g. because the iPod is disconnected from the computer. Therefore, be careful! Charging the iPod seems to do no harm.

When gtkpod is started, it will also read this file and incorporate the information into the iTunesDB that can be written back to the iPod. There have been several requests to also register playcounts when playing a track on the local machine. This is possible by calling gtkpod as

gtkpod -p If gtkpod is already running, the playcount of that track there will be increased by one. If gtkpod is not already running, the playcount will be registered in ~/.gtkpod/offline_playcount. This file will be read the next time you import the iTunesDB from your iPod, and the playcounts will be updated accordingly.

Please note that if you start several instances of gtkpod, only the first instance will register playcounts through "gtkpod -p".

Now all that is required is to tell your favorite player to call gtkpod with the filename of the played track.

For xmms this is possible as of July 18th, 2004 (CVS version). Versions before that (including 1.2.10) only allow you to have an external program called at the beginning of a track. Our patch allows to have an external program called also at the end of a track.

In each case you will need to activate the "General Plugin" called "song_change" and configure it to call 'gtkpod -p "%f"'.