GUIPod User Manual

Howto Setup GUIPod

Step 0: Verify Paths Before Running Guipod

After installing Guipod, before running it please verify that the env variable KDEDIR is set to the right path and the scripts, and are present in the PATH. Also make sure that the perl modules XML::Parser and Unicode::String are installed properly. This can be done by running with no arguments. If you see the output: 0.4 (C) 2002 Adrian Ulrich (Modified for GUIPod by Chandan Kudige)
Part of the gnupod-tools collection
This tool updates your iTunesDB with the content of the gnuPodDB


Then the installation is proper.

Step 1: Mounting the iPod filesystem

iPod is basically a firewire harddisk with a firmware that can decode the mp3 files on the disk and play them. The firmware expects a special file (iTunesDB) which contain the song-information for each song on the disk. Only the songs with an entry in this file can be played by the iPod.

So the first step is to mount the iPod filesystem. Refer to the documentation in the gnupod website to do this. Once you are successful in mounting the iPod filesystem, using GUIPod is very easy. For this discussion let us assume that you mounted it under /mnt/ipod

Step 2: Configure the iPod mount path

When guipod is run for the first time it asks for the iPod mount-point. In this example we need to enter /mnt/ipod. In the next dialog click the 'Setup' button to prepare the iPod to be used with GUIPod.

Step 3: Import/Initialse the iPod filesystem

The setup dialog provides you two options:

1. Initialise: (For Freshly formatted iPods)

If you dont have any songs already on the iPod then you can choose the "Initialise" option in the 'Setup' dialog to create the required directory heirarchy and an empty database.

Note: If you already have some songs on the iPod and choose this option, the existing iTunes database will be erased. You WILL NOT be able to access these songs from your iPod.

2. Import: (For iPods with songs on them)

Select the option "Import" in the 'Setup' dialog to direct GUIPod to extract the existing iTunes database and create the corresponding XML file.

In either case, you will see a log window with a lot of (obscure ;) messages. If you have write permission to the iPod directory and the iPod filesystem is mounted properly you should be able to dismiss the log window and be ready to roll!

If guipod had trouble writing to the ipod directory you will see the setup windows popping up again and again. This is not a good sign. Verify that the iPod is mounted correctly and you have write permission to all the directories udner it.

Howto Use GUIPod

GUIPod has a very simple interface which support song management and playlist management in a heirarchical list. All the songs are displayed in the main tab, and each playlist is displayed in a separate tab. All song tab sorts the songs under artist title, where-as the playlists display all the songs in a flat heirarchy.

Each command is explained below. The usual sequence of operation is:

Adding new songs to iPod

New songs can be added by right clicking on the songlist (all the tabs) and selecting 'Add Songs' or using the 'Add Song' button. In the file-selection dialog select the MP3 files that you want to add and press 'Open'.

You can now enter the song information for these songs (artist name, album name, song title).

If any field is left empty, guipod tries to get that field from the ID3 header in the mp3 file (You can use the program mp3info to create the id3 header for any mp3 file). If the MP3 file does not have the ID3 tag information, the artist and album names default to 'Unknown' and the title defaults to the readable form of the file name.

Note that its best not to provide the title if you are adding more than one file since all the files will end up with the same title (as we dont support track numbers in this version).

Also note that this information can be changed later by using the 'Retag' command.

Deleting songs from iPod

Songs can be deleted from the iPod either from the main tab or the playlist tabs. The songs are deleted from the disk and cannot be recovered.

Retagging Songs

Songs can be retagged from any of the tabs by selecting the songs and clicking 'Retag' button or using the context menu. Retagging allows you to change the artist, album and title information once the songs are added. The most obvious use of this is to add new songs, and then retagging any songs that dont have a ID3 header by selecting the songs under artist 'Unknown'. You can also use retagging feature to maintain and organise a huge collection of songs in a meaningful order.

Note: Any fields that are left empty are unchanged in the song.

Repair Songs

This command makes the GUIPod re-read the mp3 file on the iPod disk and update the information. This is most useful if you replace a defective version of the a song with a new version. Repair option allows you to update the tag information, bitrate and playtime information from the new song and enter it into the index file.

Creating Playlists

The iPod allows you to organise songs under multiple playlists. You can use the 'New Playlist' command to create playlists. Each playlist is displayed under its own tab after the 'All Songs' tab.

The playlist tab displays all the songs without any heirarchy and you can sort them based on any of the tag fields. You can add/retag/repair songs from the playlist tab, and it affects the song in all the playlists as well as the mainlist.

Deleting Playlists

Playlists can be deleted from the main tab using the 'Delete Playlist' command. Once the selected playlist is deleted it *CANNOT* be recovered.

Note that the songs in the playlist still remain intact even though the playlist has been deleted.

Planned feature: Renaming playlists.

Adding Songs to Playlists

Songs can be added from the main tab, or from one of the other tabs into any of the playlists. Multiple entries can be added to the same playlist and the guipod doesnot check for this error. So add the entries with care.

Note that same song can be present in more than one playlist.

Planned feature: A speacial playlist called 'Sample List' that play just a small clip from each song in the playlist. Can be useful for sampling new songs.

Deleting Songs from Playlists

Songs can be deleted from the playlists by selecting the songs in that playlist tab and selecting the 'Remove song from playlist' option in the context menu. This operation DOES NOT delete the song from the iPod. This operation cannot be undone.


This is a very important command. After using any of the above operations, the iTunes database needs to be rebuilt. Hence this command should be executed. It can be done at the end of all the operations. The guipod prompts to run mktunes while quitting the application too.

NOTE: If you forget to run MKTUNES the changes made to the iPod will not be visible on the iPod. MKTUNES should be run *BEFORE* unmounting the iPod filesystem


In the event of changing the iPod (say, by using the gnupod commandline tools) outside of Guipod, you can make the guipod reload the changes by running this command.