Media Device plugin for all Apple iPod models, iPhone and iTunes phones.

Supported Devices

When Apple releases new iPod models, they have been known to change things, such as firmware versions, which can cause problems when using the device with Amarok. Typically, any issues can be overcome given enough time to reverse engineer changes with how to communicate with the new iPod. The table below details which iPod models are supported and are known to work with Amarok.

Model and generation		Capacity	Status	Date Released	Requirements
iPod	1G	5, 10 GB	Working	23 October 2001
	2G	10, 20 GB	Working	17 July 2002
	3G	10, 15, 20, 30, 40 GB	Working	28 April 2003
	4G (iPod photo)	20, 30, 40, 60 GB	Working	July 2004
	5G	30, 60, 80 GB	Working	12 October 2005
iPod mini	1G	4 GB	Working	6 January 2004
iPod mini	2G	4, 6 GB	Working	22 February 2005
iPod nano	1G	1, 2, 4 GB	Working	7 September 2005
	2G	2, 4, 8 GB	Working	12 September 2006
	3G (with video)	4, 8 GB	Working	5 September 2007	Amarok 1.4.8, libgpod 0.6.0
	4G	8, 16 GB	Working	9 September 2008	Amarok 1.4.10, libgpod SVN r2153
iPod shuffle	1G	512 MB, 1 GB	Working	11 January 2005
iPod shuffle	2G	1 GB	Working	October 2006
iPod Classic	1G	80, 160 GB	Working	5 September 2007	Amarok 1.4.8, libgpod 0.6.0
iPod Classic	2G	120 GB	Working	9 September 2008
iPod Touch	1G	8, 16, 32 GB	Partially (firmware 1.x) No (firmware 2.x)	5 September 2007	Amarok 1.4.8, libgpod 0.6.0
iPod Touch	2G	8, 16, 32 GB	No	9 September 2008
iPhone	(2.5G)	4, 8, 16 GB	Partially (firmware 1.x) Partially (firmware 2.x)	29 June 2007	Amarok 1.4.8, libgpod 0.6.0
iPhone	3G	8, 16 GB	No	11 July 2008
Motorola iTunes phones	ROKR E1	512 MB	Unknown

Model Specific Notes

iPod nano 3G (fatty), iPod nano 4G, iPod Classic and iPod Touch (firmware 1.x only)

The song database is protected by a cryptographic hash. You need libgpod 0.6.0 (or newer) and the SysInfoExtended file as is detailed in Common Problems to compute it automatically.

iPod Touch and iPhone

Devices with Firmware 1.x

Jailbroken iPhones and iPod Touchs (models introduced in 2007 only) with firmware revisions not newer than 1.1.5 with ssh installed work if their /var/root/Media directory is mounted via fuse/sshfs and if they are added manually as a media device. Then you can copy music via Wi-Fi with libgpod 0.6.0 or newer.

There is a step by step howto on http://www.fredemmott.co.uk/blog_121.

Recently, another method to access the iPod/iPhone filesystem, which does not require the device to be jailbroken, emerged: the FUSE filesystem iFuse allows to transfer data via USB. While the filesystem level access works for all iPhone and iPod touch models and firmware versions, the problem of computing a correct hash value, which is accepted by firmware revisions 2.0 and newer, is not yet solved and makes it impossible to transfer music to these devices.

Devices with Firmware 2.x

Using Amarok to transfer music to iPhone 3G and iPod Touch 2G (models introduced in 2008) and all other models of iPod Touch and iPhone that have been upgraded to firmware 2.x requires the phone to be jailbroken, you must edit the file /System/Library/Lockdown/Checkpoint.xml on the phone, finding the key DBVersion and changing its value from a 4 to a 2[1]. Then follow the instructions as for firmware 1.x (sshfs or FUSE).

Compiling libgpod

Optional dependencies

Some features, e.g. artwork support, depend on all the following being present (including the respective -dev/-devel packages) at libgpod compile time:

gdkpixbuf: image reading
libgobject-2.0: interfacing with hal
hal/dbus: recognition of iPod model

Common Problems

Some users may experience specific problems when using their iPod depending on aspects such as installed library versions, having a 64-bit CPU etc. These issues are detailed below.

My iPod does not show any music

Starting from the iPod classic and Touch era, the iPods use a method to check the consistency of the database with an algorithm called SHA1. To either prevent 3rd party apps to manipulate your iPod or to have a reliable database, the iPod checks the data of the db and could not show the tracks you have synced. If you can add tracks with iTunes but not with gtkpod, this may be happening.

Upgrading to at least libgpod 0.6.0 may solve your problems. Otherwise, have a look at the Gtkpod wiki or follow these steps:

Mount your iPod.
Open a terminal and type in: "sudo lsusb -v | grep -i Serial" without the quotes. Then you will see a 16-character-long hash. Copy it to the clipboard.
Fire up a text editor, like Kate, Kwrite, vi, nano.
Type in: FirewireGuid: 0x...
... and paste that hash of step 2 (do not omit the 0x).
Save the file with the name SysInfo in the iPod_Control/Device folder under your iPod mount point.

For example, a /media/ipod/iPod_control/Device/SysInfo file can look like

ModelNumStr: xB029
FirewireGuid: 0x000A27001301221F

If you can't sync files yet, grab the latest libgpod from SVN or get libgpod 0.6.0 and compile it, install it and finally compile Amarok against it.

Lots of orphaned files, iPod will not play anything

The symptoms of this problem are

iPod will not play any of the newly added files,
when trying to repair iPod with Amarok, it will show an orphaned and a stale version of every newly added file.

The most likely reason for this is a version of libgpod that is incompatible with your Amarok binary. This happens mainly if your distributor compiled Amarok against libgpod 0.3.2 and later on upgrades libgpod to 0.4.0 without providing an updated Amarok binary, which is compiled against libgpod 0.4.0. The solution for this problem is to downgrade libgpod to 0.3.2.

Subfs/Submount

SUSE Linux 9.1 to 10.0 uses subfs/submount to automatically mount/unmount removable devices. As I didn't manage to get that work reliably with my iPod, I seriously suggest that you disable it, at least for your iPod.

Disabling subfs (tested on SUSE 10.0):

Create /usr/share/hal/fdi/policy/95userpolicy/noautomount.fdi with this content:

<?xml version="1.0" encoding="ISO-8859-1"?> 
<deviceinfo version="0.2">
 <device>
  <match key="storage.policy.should_mount" bool="true">
   <merge key="storage.policy.should_mount" type="bool">false</merge>
  </match>
 </device>
</deviceinfo>

However, if there is anybody out there having crafted pre-connect/post-disconnect commands that make it work without problems or having an ideas, please let us know!

There is a great wiki on Suse 10 and iPods that can be found here:

http://www.volker-lanz.de/en/toys/ipod_suse10/

Problems with iTunesLock

Something went wrong, data integrity is at stake. Make sure to

properly flush the data to the iPod: always use the 'Disconnect' button
not connect your device twice
unmount your iPod, but only after it was properly removed from amaroK: configure an appropriate 'post-disconnect command' (e.g. 'umount %d && eject %d')
don't unplug your iPod as long is it says 'Do not disconnect.': use eject to properly remove your iPod from your system
subfs will most likely lead to such problems (as it just unmounts file systems with open files behind your back): see above for how to disable it

Artwork not working

It is important that Amarok recognizes your iPod model:
- it is shown in the combo box at the top of the media device browser
- if not, you have to set it manually (choose 'Set iPod model' below iPod drop-down button)
Version 1.4.5 introduced support for setting the iPod model from within Amarok, however this did not work, making artwork and video transfer impossible. This is fixed starting with Amarok 1.4.6.
Make sure, all the optional prerequisites were available when you compiled libgpod! I.e.
- GdkPixbuf has to be available (including development package)
- libgpod has to be compiled with gtk support
- DBus and HAL libraries have to be installed
- libgobject-2.0 is required
With libgpod 0.4.0 and older, DBus/Hal has to be working for recognizing your iPod model!
Your iPod has to be recognized properly (e.g. problems with some HP iPods):
submit the contents of iPod_Control/Device/SysInfo together with a description of your iPod model to [email protected]
A bug within libgpod older than libpgod 0.6 makes artwork fail as soon as iPodControl/Artwork/ArtworkDB grows to more than 16 MB
Problems within libgpod make artwork fail on 64-bit systems, because of different alignment within structs (this is fixed in libgpod 0.4.0 and newer)
Recent iPod firmware versions (newer than mid 2006, and the firmware on 2nd gen iPod nanos, 5.5 gen iPods and the 2nd gen iPod shuffle) only create an empty iPod_Control/Device/SysInfo file. But this is used by libgpod for determining the kind of iPod you have. And libgpod has to know your iPod model for transferring artwork correctly. A work-around is to use a recent version of gtkpod for setting the iPod model manually (this sets the model version string in the SysInfo file).
As of Amarok 1.4.6, I needed no DBUS or HAL stuff running, I've just setup iPod model within Amarok, updated artwork and everything automagically worked (iPod Nano 2GB Silver). Your mileage may vary.

The Not-so-obvious Features

Transfer Audible audiobooks or m4v videos

Possibility 1:
- Use the filebrowser to locate your files
- Chose 'Add to media device transfer queue' or drag them to the media device tab
Possibility 2:
- Drag your files from konqueror onto the media browser

Working example for audio books

The following works for transfering aac files to a ipod classic 80g for the purposes of taking advantage of bookmarking for audio books originally in .wav format.

Versions:

amarok-xine-1.4.9.1-100.pm.1
Amarok 1.4.9.1
Ipod Classic 80GB
pacpl 4.0.2
opensuse 10.3

Steps

setup Amarok to use the xine engine.
convert the files to m4a. (I used pacpl to do this)
rename the files to m4b
drag/drop the files into a playlist in amarok
push the files to the ipod.

Once you rename the files with a m4b extension you will not be able to edit the tag information as far as I can tell.

References: ask.metafilter.com www.macosxhints.com

Remark: m4v support probably requires mp4/aac tag support via libmp4v2 (instead of the internal tag reading implementation).

Remark: ~~currently no m4v video support, as libgpod from cvs removed the calls to detect if the iPod is capable of playing videos.~~ m4v video support is back.

When It's Broke: Repairing Your iPod

If your iPod database has become corrupted (because you disconnected your device at an unfortunate point in time, because of an Amarok failure, ...), there is still some chance to preserve at least some of your songs.

In the case of corruption you might see the following:

Stale items: still recorded in your database, but not present on the iPod - it's probably best to remove them
Orphaned items: still in the iPodControl/Music folder on the iPod, but not in its database - with a right-click you can re-add them to your database (however podcasts are not recognized as such)
Invisible items: recorded in the iPod's database, but neither on the "master playlist" nor on the "podcast playlist" and thus not visible below the "Artists" category on your iPod

If Amarok is incapable of fixing your iPod, you could resort to gtkpod or else try the steps outlined in "How to reset iPod.

Using an iPod running Rockbox with Amarok

Since Amarok 1.4.6 it is possible to sync music with an iPod running Rockbox on it (Rockbox website). Although there is support for iPods using the original firmware of Apple, the usage of Rockbox couldn't be easier.

After connecting the iPod to your computer, open the Amarok interface. Next, open the configuration window which can be found in the "Settings" menu. Go to the section dedicated to the External Devices. Look for the entry that represents your iPod (usually it is labeled as "sdb2", but to make sure, look inside the details and see if the label corresponds to the name you have given your device).

Once you have found your iPod, set Amarok to treat is as a "Generic Audio Player" by selecting that entry in the "Plugin" list.

Next, click on the gears icon next to where you selected the plugin. A window will open which will tell Amarok how to treat it. If you want you can make Amarok automatically unmount the iPod itself instead of having to unmount it afterwards, add the unmounting command that your distibution uses, or leave it blank.

Here are some known and tested unmounting commands (change "xxxx" with the name of your iPod -example: "sdb2"-) :

 Ubuntu:  gnome-eject -ed /dev/xxxx

Rockbox supports many types of formats. To make Amarok transfer the supported files directly to the iPod without converting them, make sure that the following formats appear in the box: aac, flac, mp3, mpc, ogg, wav, wma. You can leave the other settings alone or change them if necessary.

Note: You might want to unmount and remount your iPod in order for Amarok to see it properly.

You are now set to transfer music to your Rockbox enabled iPod.

Note: Please consult the guide of Rockbox on how to work with the interface and make it show your music.

Adding podcasts to your Rockbox-enabled iPod

Before beginning to download podcasts it is recommended that you tell Amarok to download the podcasts in their own folder, somewhere you know like in your own music folder. To do this, create a folder wherever you want and name it "Podcasts".

Next, you have to tell Amarok about the new Podcast folder. To do this, go to the "Playlist" tab to the left of the main interface. Right-click on the "Podcast" entry and select "Configure Podcasts". Note: due to a bug you are not able to open the configuration menu for the podcasts unless you already have at least one Podcast channel added in Amarok. Until this is fixed, please add a podcast link before continuing. In the configuration menu that shows up, enter the new position where you created your own Podcast folder. You might also want to select the option to automatically add the newly downloaded podcasts to the transfer cue to your device.

After configuring Amarok to download the podcasts, it is now time to setup your iPod to receive them. Open your file browser and enter your iPod. Create a folder called "Podcasts" and exit. Now go back to to Amarok, and with your iPod connected go to the "Devices" tab on the left side of the main interface. Once there, select "Configure" on top of where the commands are to manage your device. Once there you will get the configuration window again you used at first to tell Amarok how to handle your iPod. This time go at the bottom where you can set the destination folder where Amarok will put your podcasts in your iPod. It should be set to " /Podcasts/ " or whatever the name or directory you have given it on your iPod.

There! You are all set to start downloading Podcasts and have them automatically cued up to your iPod!

Further Information

As Amarok's iPod plugin uses libgpod for interfacing with the device, much of the information pertaining to gtkpod and libgpod, will be relevant for Amarok as well. Also, the gtkpod wiki might be helpful.