Getting started

From gtkpod iPod Manager

Jump to: navigation, search


Hooking up the iPod


The iPod has largely been an USB device yet there are older models of iPods that used IEEE1394/ / firewire for their connection interface. Historically, it took something of an effort for linux to recognise the iPod model correctly. However, this situation has greatly improved in recent times where it is now possible to simply plug the iPod into a USB port and have your distro recognise it straight off. gtkpod first and foremost relies on the successful mounting of a recognised iPod. Thus, if the iPod cannot be mounted then gtkpod is NOT going to do it for you! Thus, before firing up gtkpod make sure you can see the filesystem of your iPod at its desginated mount point, eg. /mnt/ipod.

Using udev

For linux distros installed with hal and udev, plugging an ipod in and mounting it becomes a trivial exercise. A device node will normally be created under /dev, eg. /dev/sdc. Using udev rules it is possible to "play" and refine this device node to reflect personal requirements. For example, including these udev rules will allow 2 ipods to be loaded at the same time without interfering with one another:

SUBSYSTEMS=="usb", ATTRS{serial}=="000A2700XXXXXXXX", KERNEL=="sd?2", \
NAME="80gbipod", MODE="0664", OPTIONS="last_rule"

SUBSYSTEMS=="usb", ATTRS{serial}=="000A2700YYYYYYYY", KERNEL=="sd?2", \
NAME="4gbnano", MODE="0664", OPTIONS="last_rule"
By including the test against the serial number it is possible to uniquely identify an individual iPod and load it appropriately.


The result of this is that the ipod will be located on a device node and this can be mounted manually using the command (performed as root):

mount /dev/sdc2 /mnt/ipod
This assumes an iPod is loaded onto the device /dev/sdc and that it is a 2 partition model. It seems that post-2006, iPods have become 1-partition items.

However, it should be noted that moden window managers such as gnome and kde take on the responsibility of managing connected devices. Thus, the result of connecting an iPod will be an icon on the desktop which will either be mounted automatically or can be mounted by the user with a click of the mouse on a popup menu.

Environment variables

The following environment variables can be set if needed:

IPOD_MOUNTPOINT: Defines the mountpoint of the iPod. This overwrites the value stored in the preferences, but is overwritten by the command line argument "-m" or "--mountpoint".

GTKPOD_DF_COMMAND: Only used on systems without statvfs(). Defines the "df" command to be used for probing the free space on the iPod including command line arguments. Default is "df -k -P". On some systems it may be necessary to remove the "-P" option. The mount point is added to this command line automatically. You can switch off calls to df by setting this environment variable to an empty string.

Setting iPod properties

Preferences File

On startup gtkpod will read the preferences from ~/.gtkpod/prefs (or /etc/gtkpod/prefs if the former doesn't exist). The file is created if preferences are changed using the Preference window.

Changing Preferences

Preferences can be changed by opending the Preference window. This is displayed by clicking on Edit > Edit Preferences or hitting Ctrl+P.

Duplicate Detection

You can instruct gtkpod (in the prefs window) to use file-size-dependent SHA1 checksums to prevent the same file from being copied to your iPod twice.

If a duplicate is detected, gtkpod will print out the the filenames of the duplicate files. If the filename of the already existing file is not available (it is not stored in the iTunes database, see "Extended Information File" below), other available information of the track is printed.

Extended Information File

Some (I believe) essential information is not stored in Apple's iTunes database. You can therefore instruct gtkpod to write an additional file (iTunesDB.ext) with extended information. For each track it stores

  • SHA1 hash
  • filename in the locale's encoding
  • filename in UTF8 encoding
  • hostname where the file was added (not used for anything yet)
  • filename of an associated converted file (for example an .mp3 for a .flac file)
  • if the file is present in the local database a reference to there
  • in order for playcounts to work on the local database as well
  • last modification time
  • the charset used for the file when adding it

Since the extended information file is only valid with the corresponding standard iTunes database, a checksum of the iTunes database is also stored in the extended information file.

Using an extended information file will considerably speed up the import of an existing iTunes database when using duplicate detection, since the SHA1 checksums do not have to be re-calculated.

Using an extended information file will also allow modification of ID3 tags in the track files after the initial import, because the full filenames are still available.

Encoding of ID3 tags (charsets)

If you use correctly written unicode ID3V2 tags you don't have to worry about the charset setting. Otherwise you must specify the charset to be used for representing ID3 tags in the preferences menu. The default is "System Charset", which is the charset associated with the locale gtkpod is running under. If your tags are stored in a different encoding, you should set it appropriately.

Please note that if necessary you can change the charset each time you add files or directories: the iTunesDB itself is using UTF16, so once tags are imported correctly, changing the charset has no influence.

If you chose "Japanese (automatic detection)", gtkpod will try to determine if the string is in ISO-2022-JP, Shift_JIS, or EUC-JP (Hankaku Katakana (1-byte Katakana) may not be recognized correctly -- specify the correct encoding if you run into this problem). The actual encoding used for the ID tags will be stored and will be used when writing tags or doing updates/syncs. Check the "Use selected charset also when updating or syncing tracks" and "Use selected charset when writing tags" options if you want to specify a particular character set when writing or updating/syncing. The default charset is "EUC-JP" -- it will be used when the charset cannot be autodetected, as well as when writing tags if a specific charset could not be determined before.

gtkpod will recognize ID3V2 tags encoded in unicode automatically and ignore your charset setting when necessary.

Extracting tag information from the filename

Tags can also be extracted from the filename if you activate the option 'Use this template to parse filename for tag information' and supply a template that explains how the filenames are constructed.

For filenames like music/new/latin1/alan_jackson - drive/01 drive_for_daddy_gene.mp3 you could use %a - %A/%T %*.mp3 to extract artist, album, track number and title.

The following character sequences are supported:

  •  %t: title
  •  %a: artist
  •  %A: album
  •  %c: composer
  •  %t: title
  •  %g: genre
  •  %T: track number
  •  %C: CD number
  •  %*: placeholder, ignore data
  •  %%: the character '%'

You cannot supply a template like "%a%t.mp3" because gtkpod would not know how to separate artist and title. "%a_%t.mp3" would be correct, if artist and title are separated by an underscore. You can also omit the trailing ".mp3" if you want the template to apply to all files instead of only to mp3 files.

Startup and Shutdown Scripts

During startup and after reading the preferences file, gtkpod will try to execute

~/.gtkpod/ or /etc/gtkpod/

Just before exiting the program, gtkpod will try to execute

~/.gtkpod/gtkpod.out or /etc/gtkpod/gtkpod.out

Thus, extra arguments can be entered into these scripts and gtkpod will run them. An example of this could be uploading data to

Troubleshooting FAQ


  • My iPhone or iTouch doesnt have a USB connection. How can I mount it on my linux box?
  • My iPod is an iPhone, iTouch, Classic or nano3g. My tunes show up in gtkpod but I see nothing on the iPod when I eject?
  • Installed libmp4v2 or libgpod from source to /usr/local/lib, but gtkpod is unable to locate or
  • Files copied to gtkpod but they don't appear in the database (0.80, Tony Williams)
  • Filenames on the iPod appear in DOS 8.3 format and syncing to the iPod is not working as expected.
  • ./ does not work
  • The following error message is displayed when accessing the device (Markus Gaugusch, Justin Thiessen):
** ieee1394: sbp2: aborting sbp2 command
** Test Unit Ready 00 00 00 00 00
* The following error message is displayed when accessing the device (Ingo Reimann)
** usb-storage: Attempting to get CSW...
** usb-storage: usb_stor_bulk_transfer_buf: xfer 13 bytes
** usb-storage: Status code -75; transferred 0/13

* When connecting an iPod via USB to a 2.6 kernel machine the iPod will be recognized but not work correctly. In /var/log/messages you'll see the a bunch of "Buffer I/O error on device sd?" when connecting the iPod (Jonas Bergler, Kevin Venkiteswaran)
  • SHUFFLE won't play music after reformatting (Mark Davis)
  • Calendar entries mixed up
  • m4a files created by faac cannot be added by gtkpod (gentoo)
  • gtkpod crashes when reading the iTunesDB (Fedora)
  • Problems connecting the iPod to Solaris/SPARC

My iPhone or iTouch doesnt have a USB connection. How can I mount it on my linux box?


The iPhone or iTouch, at present has to be mounted using sshfs.

My iPod is an iPhone, iTouch, Classic or Nano3g. My tunes show up in gtkpod but I see nothing on the iPod when I eject?


This is to do with requiring your iPod model number in a sysinfo file located on the iPod. Please see here for details.

Installed libmp4v2 or libgpod from source to /usr/local/lib, but gtkpod is unable to locate or


If you install to /usr/local/lib please don't forget to add the path to LD_LIBRARY_PATH:

You can add those lines to your ~/.bashrc or add it globally to


Files copied to gtkpod but they don't appear in the database (0.80, Tony Williams)?

I'm having a problem that I wonder if you've seen. I've setup gtkpod. launch it and add files. I can hear the ipod harddrive spin up. If I go onto the ipod directly I can see the space being used and can even see the new files on the ipod. However the ipod interface doesn't show the new files and gtkpod keeps telling me that there are orphaned files.


I finally figured out the problem. In my fstab I had the filesystem set to 'auto' and it was mounting as msdos instead of vfat. I specified vfat in fstab and voila! I'm a happy happy man.

Filenames on the iPod appear in DOS 8.3 format and syncing to the iPod is not working as expected?

Solution: You need to specify "vfat" as file system type. How to do that depends on which way you use to mount the iPod -- see the README file for more details.

./ does not work?


A ubuntu user has reported that he had to set

ACLOCAL_FLAGS=" -I /usr/share/aclocal/"
in order to get ./ to work.

The following error message is displayed when accessing the device:

ieee1394: sbp2: aborting sbp2 command
Test Unit Ready 00 00 00 00 00 

(Markus Gaugusch): It is possible that hotplug and the "sg" support are not working well together. Try disabling "sg" support in the kernel configuration or unload the "sg" module if you are using modules.

(Justin Thiessen): Forcing the sbp2 module to serialized I/O seems (so far) to have solved the problem.


Looks like the driver is going to be set to default to serialized I/O in kernel 2.6.14, anyways.

The following error message is displayed when accessing the device

usb-storage: Attempting to get CSW...
usb-storage: usb_stor_bulk_transfer_buf: xfer 13 bytes 
usb-storage: Status code -75; transferred 0/13 
Solution (by Ingo Reimann):

I tried to use an iPod Mini with my nforce2-Board, kernel 2.6.14/2.6.15 debian sid and got messages like [above] in dmesg. /dev/sda appeared, but fdisk -l did not show anything

The solution, that i found in a discussion on was to unload ehci_hcd.

When connecting an iPod via USB to a 2.6 kernel machine the iPod wil be recognized but not work correctly. In /var/log/messages you'll see the a bunch of "Buffer I/O error on device sd?" when connecting the iPod (Jonas Bergler, Kevin Venkiteswaran)

Solution (by "jeffmock"):

Disable CONFIG_EFI_PARTITION (File Systems -> Partition Types -> Advanced Partition Selection -> EFI GUID Partition support) in your kernel configuration, recompile. Details can be found at


"This problem could potentially happen with both 2.4 and 2.6 kernels."

A longer story follows and perhaps someone can come up with a more sensible solution for the long run.

The iPod looks like a removable disk drive to the host computer. When it is attached to the computer, the mini iPod reports a capacity of 7999488 512-byte sectors (or about 4GB). This turns out to be wrong for whatever reason. The mini iPod only really has 7999376 sectors and it exaggerates by 112 sectors. The other quality of the iPod is that if the computer attempts to read a sector greater than the actual capacity but less than the reported capacity, the iPod will dutifully report an I/O error, but it won't respond to any future requests until you unplug/plug the iPod."

I followed the kernel recompile instructions for distro, disabled only the CONFIG_EFI_PARTITION option, and things ran perfectly for me afterwards. As indicated above, hopefully a better long-term solution will emerge soon."

(Jorg Schuler: it seems a patch was introduced in kernel version 2.6.10: "<> [PATCH] USB Storage: Add unusual_devs entry for iPod This patch adds an unusual_devs.h entry for the Apple iPod as it reports one too many sectors. The patch was submitted by Avi Kivity <> and re-diffed by me.")

SHUFFLE won't play music after reformatting

Solution (by Mark Davis):

The SHUFFLE seems to care about the volume name which has to be "IPOD". Try to format as (replace /dev/sda1 with the appropriate device file for your SHUFFLE!):

mkdosfs -F32 -n IPOD /dev/sda1
Calendar entries mixed up?


The iPod does not appear to like times specified in UTC (indicated by a trailing 'Z'). KOrganizer seems to do this. If you know how to work around it let me know.

m4a files created by faac cannot be added by gtkpod (gentoo)?


There appear to be some versions of faac that do not create 'good' m4a files. The problem could be solved under gentoo by using version 1.24. In order to make error tracking easier, more detailled error messages are displayed when tracks could not be added for any reason starting with version 0.91-CVS of gtkpod.

gtkpod crashes when reading the iTunesDB (Fedora)


It appears that crashes were observed with kernel version 2.6.11-1.35_FC3. An upgrade to 2.6.12-1.1376_FC3 got rid of the problem. This was with gtkpod-0.94.0 and Athlon64 3000+.

After updating the firmware of a 1st-gen iPod nano**, crashes are also observed with Fedora Core 5, kernel 2.6.20-1.2320.fc5, gtkpod 0.99.4 (which worked with the previous firmware). Downloading, building, and installing gtkpod 0.99.10 and libgpod 0.6.0 solved the problem.

Problems connecting the iPod to Solaris/SPARC


Current (as of 2006/03/30) versions of the Solaris pcfs SPARC driver have a bug where the correct filesystem/partition layout may not be recognized, and this is true for iPods. This prevents the iPod partition from being mounted on Solaris SPARC. In order to work around this, one must prevent pcfs from detecting the first FAT32 filesystem, forcing it to move on to the second one. This can be done by changing the filesystem identifier like so:

# dd if=/dev/rdsk/c3t0d0s2 of=/tmp/ipod.orig count=1
# cp /tmp/ipod.orig /tmp/ipod.modified <edit /tmp/ipod.modified and change the first occurance of "FAT32" (at offset 0x52 for me) to something else like "CAT32">
# dd if=/tmp/ipod.modified of=/dev/rdsk/c3t0d0s2 count=1

The sysinfo file

Starting with the 2007 generation of iPods, libgpod needs an additional configuration step to correctly modify the iPod content. libgpod needs to know the so-called iPod "firewire id", otherwise the iPod won't recognize what libgpod wrote to it and will behave as if it's empty.

The iPhone and iTouch

touch_ip -- denotes the IP address that is assigned to your iPod Touch (e.g.

touch_mnt -- denotes the mount point to your iPod Touch (i.e. the directory the iPod is mounted on).

To make effective use of the following you have to jailbreak your iPod Touch first (in order to access it via SSH). This document won't go into detail on this topic. One possibility to do this using a computer that runs Microsoft Windows (XP) can be found at:

Install and compile libgpod and gtkpod from subversion. See Compiling and Installing|here for details.

Configure libgpod. The '--prefix' option will make sure that is not installed globally but locally within your home directory (note: replace '~' by the absolute path to your home directory):

~/libgpod$ ./ --prefix=~/local
Otherwise make sure all dependencies are met ('gtk-doc' is a candidate likely to be missing, proper version of automake is another).

Repeat this process for gtkpod ('PKG_CONFIG_PATH' make sure it builds on the freshly compiled version of libgpod; again, replace '~' by absolute path to your home directory):

~/gtkpod$ PKG_CONFIG_PATH=~/local/lib/pkgconfig ./ --prefix=~/local
~/gtkpod$ make && make install
Assuming that everything went well you should be able to start gtkpod:
~$ LD_LIBRARY_PATH=~/local/lib ~/local/bin/gtkpod
You won't be able to fully use it at this point so close it for now.

Connect your iPod Touch via USB (to your Linux machine) and issue the command:

sudo lsusb -v | grep -i iSerial
This should print something similar to this:
iSerial 3 fd98145617c113dc15ab151601001ff12354b139
[ ... ] 
The first 16 characters constitute the FirewireGUID, i.e. in this example the FwGUID is:
fd98 1456 17c1 13dc
Mount your iPod Touch via:
sudo sshfs root@touch_ip:Media touch_mnt/ -o allow_other
Go to the directory 'iTunes_Control' and create (if it does not already exist) a directory named 'Device':
~/touch_mnt/iTunesControl$ mkdir Device; cd Device
~/touch_mnt/iTunesControl/Device$ echo "FirewireGuid: 0xfd98145617c113dc" > SysInfo 
Test if libgpod is able to retrieve the FWGUID by changing into the 'tests' subdirectory of libgpod's source directory and runnning:
./test-firewire-id touch_mnt/
With your iPod Touch still mounted start up gtkpod once more:
~$ LD_LIBRARY_PATH=~/local/lib ~/local/bin/gtkpod
You should now be able to sync songs to your iPod Touch. After syncing is complete go into "Music" on your iPod Touch: The songs you have just synced won't show up at this point. To make them appear press and hold the "Home"-Button until the springboard is reloaded. Going to "Music" now will show your music.

Don't forget to unmount it after you're completely done.

Tutorial compiled by staciemonroe (tobias kreisel gmail com)

The Classic and Nano3g

There are two ways to set up the iPod to make libgpod able to find its firewire id.

The 1st one is mostly automated. First, make sure you have libsgutils installed before running configure/ If you built libgpod without it, install it and run configure/make/make install. You should now have an ipod-read-sysinfo-extended tool available. Run it with the iPod device path (eg /dev/sda) and the iPod mount point (eg /mnt/ipod) as arguments. This may require root privileges. ipod-read-sysinfo-extended will read an XMLfile from the iPod and write it as /mnt/ipod/iPod_Control/Device/SysInfoExtended. See for more details about the method used.

Having that file is enough for libgpod to figure out the iPod firewire id.

The 2nd method requires more manual intervention. First, you need to get your firewire id manually. To do that, run "sudo lsusb -v | grep -i Serial" (without the "") with your iPod plugged in, this should print a 16 character long string like 00A1234567891231. For an iPod Touch, this number will be much longer than 16 characters, the firewire ID is constituted by the first 16 characters. Once you have that number, create/edit /mnt/ipod/iPod_Control/Device/SysInfo (if your iPod is mounted at /mnt/ipod). Add to that file the line below:

FirewireGuid: 0xffffffffffffffff
(replace ffffffffffffffff with the string you obtained at the previous step and don't forget the trailing 0x before the string)

Save that file, and you should be all set. Be careful when using apps which lets you manually specify which iPod model you own, they may overwrite that file when you do that. So if after doing that libgpod still seems to write invalid content to the iPod, double-check the content of that SysInfo file to make sure the FirewireGuid line you added isn't gone. If that happens, read it to the end of the file, and make sure libgpod rewrite the iPod content.

Once that is done, if you compiled libgpod from source, you can test that libgpod can find the firewire ID on your iPod by running

libgpod/tests/test-firewire-id /ipod/mount/point

iPod file recovery

Checking iPod's Files

For whatever reason -- it may happen that tracks are present in your iTunesDB that are no longer present on the iPod (dangling tracks), or that tracks are on the iPod but not in the iTunesDB (orphaned tracks). The function "Checking iPod's Files" under the "File" menu will identify both types and take the following actions:

A new playlist "[Orphaned]" will be created with all orphaned tracks in it. The only exception are orphaned tracks that would become duplicates (if duplicate detection is activated). Those are marked for deletion with the next sync.

These tracks will be marked for deletion with the next sync unless the original PC file is still available. In that case you can have them restored with the next sync.

After a File System Error

If iPod's file system gets corrupted and you need to reformat your iPod, there is a way to restore the contents semi-automatically if you have been using the "write extended information file" (iTunesDB.ext) options:

  • If the directory structure on the iPod doesn't exist yet, load the iPod in gtkpod and have it created for you. Then unload the iPod again.
  • Copy your backup files in .gtkpod/ (usually iTunesDB and iTunesDB.ext) to your iPod (usually <mountpoint>/iPod_Control/iTunes/
  • On the iPod the files must be named iTunesDB and iTunesDB.ext.
  • Load the iPod in gtkpod.
  • Select the iPod repository and start "Check iPod's files" from the File menu.
  • Unload the iPod (or save changes).

This should restore your iPod to what it was before, provided you didn't move or remove any of the original tracks on your harddrive, and the charset information was stored correctly.