gtkpod 2.0.2 April 2015

[tempestuous]

gtkpod is an iPod/iPhone/iPad manager for Linux. Mainly this involves managing a music file collection between an Apple "i-device" and a Linux computer.

UPDATED April 06 2015, to include the latest underlying libraries - libplist, usbmuxd, and libimobiledevice,
but unfortunately device compatibility is limited by the libgpod library, for which new models were no longer updated from early 2011, and only minor bugfixes were added until development virtually ceased around August 2014.
So gtkpod device support goes up to:
- iPhone4 (but not 4S)
- iPod Touch 4th gen
- iPad 1st gen (both WiFi and 3G models)
- Nano 6th gen
- iPod Classic / Mini / Shuffle should be supported across their entire range of releases.

Such device compatibility is a significant achievement under Linux, because Apple has made the communication methods on their i-devices more complicated with each new device release, and also with each new iOS release, clearly aiming to lock out access to any other application apart from iTunes.

This new gtkpod package was compiled under Slacko 5.7.0, and it's also compatible with older Slacko versions back to 5.4.
For recent Ubuntu-based Puppy releases I have provided a separate library-compatibility dotpet; at this stage, Puppy Precise 5.7.x and Tahrpup 6.x are compatible. Refer to the download information at the bottom of this post.

Older Puppies are incompatible; this includes Slacko 5.3, Lucid (5.1/5.2 series) and Wary.

This gtkpod package permits the addition of an embedded audio player, using gstreamer as the back-end application. The gstreamer dotpet I have provided is a stripped-down "audio-only" package, which supports all the important audio formats:
- AAC (m4a)
- ALAC (Apple Lossless m4a)
- MP3
- WAV (uncompressed)
- FLAC
- Vorbis (ogg)
Beware; if you install and run gtkpod-2.0.2 before you install the gstreamer dotpet, gtkpod will automatically detect that embedded audio playback is not possible, and it will disable the "Media Player" plugin. If you then install gstreamer at a later stage, you must re-enable the Media Player plugin, in -
Edit > Preferences

gtkpod will import all of the audio formats listed above, but i-devices will only accept AAC/m4a and MP3, so gtkpod will do the necessary format conversion when copying to the i-device. I have configured gtkpod to do the conversion to AAC audio compression. The mp4v2 library is included for this purpose. Under Edit > Preferences > Settings, you can change the conversion format to MP3 if you wish.

WARNING 1: To avoid possible harm to the filesystem on your iPod, before disconnection you should always unmount the device.
WARNING 2: in case of total music database corruption on your device, you should probably have your original iTunes music library still available on a Mac or Windows machine.

The 2 main dotpets are:
http://www.smokey01.com/tempestuous/gtk ... IL2015.pet
http://www.smokey01.com/tempestuous/gst ... .10.35.pet
for Slacko 5.4 - 5.7 that's all you need.

For Puppy Precise 5.7.x and Tahrpup 6.x this additional dotpet is required -
http://www.smokey01.com/tempestuous/gtk ... e-libs.pet
After installing the dotpets, reboot, so that pupevent/udev is restarted and will detect your i-device when it's plugged in.

[tempestuous]

INSTRUCTIONS, preparation:

If your i-device is brand new, you should connect it to a Windows or Mac computer, and copy a few music tracks onto it using iTunes. Obviously this is easier if you have a "fresh" installation of iTunes, which doesn't already contain several thousand music tracks!
This process will initialise the i-device, which is necessary before gtkpod can communicate with it.
Be aware that for "conventional" iPod models, initialising with a Mac computer will make things more complicated when mounting the device later under Linux. So unless you specifically want to share your i-device between Mac and Linux computers, it's easier if you initialise under Windows.
This issue doesn't apply, however, to iPhone/iPad/Touch. There's no problem initialising these devices under Mac.

It's also possible to initialise your new i-device directly under Linux, but the process is a bit complicated. If you insist on doing it this way, instructions are here -
http://ihash.marcansoft.com/

Once initialised, connect your i-device to your Puppy computer with a USB cable. Check to see if Pupcamera automatically launches - this is potentially a problem because Pupcamera may claim the device, blocking access by gtkpod.
If Pupcamera does launch, close it, and unplug your i-device. Now we need to disable Pupcamera - use ROX to browse to /etc/udev/rules.d/
and delete (or just shift) the file "88-puppy-autodetect.rules". Then reboot.

Now you're ready for setup instructions specific to your model.

[tempestuous]

INSTRUCTIONS for "conventional" iPod models - Classic, Shuffle, Mini, Nano.

This does not include the iPod Touch, which must be treated the same way as the iPhone and iPad.

If you initialised your iPod with a Mac computer, its filesystem will be journaled HFS+. But Linux can only (safely and reliably) write to a NON-journaled HFS+ filesystem, so here's how to disable journaling:
Connect your iPod to a Mac computer, running Mac OSX 10.5 Leopard or later. Go to Utilities > Disk Utility, and select the iPod in the left column. Under the "Options" button there's an option to disable journaling.

Now connect your iPod to a Puppy computer, and you should see a drive-icon appear near the bottom of your desktop. With certain iPod models you may see up to THREE drive icons appear, which represent separate partitions within your iPod. The last partition usually contains the music files.
Let's first deal with iPods which have been initalised under Mac. Some manual commands are required to mount it -
first load these 2 kernel modules (this step can be automated later) -

Code: Select all

modprobe hfs
modprobe hfsplus

Now it's worth checking what partitions Puppy can see -

Code: Select all

fdisk -l

I think that the relevant partition will be /dev/sdb3 (??) so I will perform the mount commands assuming this to be the case -

Code: Select all

mkdir /mnt/sdb3
mount /dev/sdb3 -t hfsplus /mnt/sdb3

Your Mac-initialised iPod is now ready for the next step.

If your iPod was initialised under Windows, its filesystem will be FAT32, which is easy to deal with in Linux. Just click on the desktop icon, and the iPod will "mount" ready for access by gtkpod.
Don't be concerned if you can't see any files on the mounted iPod using ROX. gtkpod will handle all file management.

Next there's a configuration process necessary - you need to update the iPod's "SysInfoExtended" database file before gtkpod can talk to it, using the "ipod-read-sysinfo-extended" command. You may see some reference on the internet to manually modifying the SysInfoExtended file with your "FireWireGUID" value. This will work - but only with certain iPod models. It's safer to perform this step using the ipod-read-sysinfo-extended command.

For early iPod models, this is the command syntax -

Code: Select all

ipod-read-sysinfo-extended <device node> <mountpoint>

So if your iPod partition is sdb3, for example, then after mounting it, run this command -

Code: Select all

ipod-read-sysinfo-extended /dev/sdb3 /mnt/sdb3

For models after Sep 2009 - Nano 5g/6g, Classic 6g-revision2, Shuffle 3g/4g
the command syntax is different -

Code: Select all

ipod-read-sysinfo-extended <USB bus number> <device number> <mountpoint>

To first find out the USB bus number and device number (as seen by Puppy) run this command -

Code: Select all

lsusb

The relevant output will be something like this -

Code: Select all

Bus 002 Device 004: ID 05ac:1266 Apple, Inc. iPod Nano 6.Gen

So in this case the bus number is 002 and the device number is 004, and this is the command you would then use -

Code: Select all

ipod-read-sysinfo-extended 002 004 /mnt/sdb3

If you have a Nano 6gen, go to the "Special requirements" post.
For all others, skip the next 2 posts, and proceed to "gtkpod configuration"

[tempestuous]

INSTRUCTIONS for iPhone, iPad, and iPod Touch.

These devices are not seen as conventional drives, but instead use a unique USB communication protocol to establish a "virtual filesystem".

Connect your iPod/iPhone/iPad to Puppy via USB. Puppy should automatically launch the usbmuxd daemon.
To check, go to Menu > System > System Status and Config > Pprocess process manager
You should see "/usr/sbin/usbmuxd -u -U root -v -v" listed somewhere near the end of the list.
If so, that's good. If not, you will need to launch it manually each time, as such -

Code: Select all

/usr/sbin/usbmuxd --user root

Now open /var/log/messages in Geany, and at the end you should see that your device has been recognised, with text like this -

Code: Select all

usbmuxd[12707]: [4] Initializing USB
Found new device with v/p 05ac:1290 at 3-68
...
Connected to v1.0 device 1 on location 0x30044 with serial number be2975afb30b6db9025f95261b9e0a7041044661

If so, we can proceed. Take note of those last 40 characters; that's your UUID, and you will need it shortly.
Mount your device with ifuse -

Code: Select all

ifuse /mnt/ipod

Now create the necessary iTunes_Control/Device directory on your device -

Code: Select all

mkdir -p /mnt/ipod/iTunes_Control/Device

Next we create the necessary configuration file -

Code: Select all

ipod-read-sysinfo-extended YOUR_UUID /mnt/ipod

Obviously replace "YOUR_UUID" with the 40 character string we identified earlier.
This should create a file (on your i-device) in /mnt/ipod/iTunes_Control/Device called "SysInfoExtended". Open this file in Geany and check that it looks OK - it should be a largish file with XML entries.
Your device is now configured to work with gtkpod.
Now might be a good time to back up your iPod's database, into the gtkpod directory. Do this -

Code: Select all

cp /mnt/ipod/iPod_Control/iTunes/iTunesDB /root/.gtkpod/iTunesDB.bak

Before we can continue it's necessary to unmount the iPod -

Code: Select all

fusermount -u /mnt/ipod

and reboot Puppy.
There are some reports that it's also necessary to restart your iPod/iPhone. It wouldn't hurt.

We're now almost ready to run gtkpod ... but refer to the next post regarding special requirments ...

[tempestuous]

Special requirements for recent iPhone, Touch, and Nano models.

With the release of iOS 5 in late 2011, Apple introduced a new hash code to "verify" file transfers onto i-devices. Affected models are:
- iPhone4
- iPod Touch 4th gen
- Nano 6th gen

(If your iPhone/iPad/Touch/Nano is an earlier model, you can skip this section)

Until the gtkpod developers manage to reverse-engineer this hash code, the only way for gtkpod to handle the hash is via a special library called "libhashab". If you use gtkpod to copy music files onto a recent i-device without the libhashab library, the file transfers are "unverified", so while the gtkpod interface will appear to show the files as being copied successfully onto the device, these files will fail to show up on the device itself.
I don't want to offer downloads/dotpets of the 2 libhashab.so files on Puppy-associated websites, because I'm uncertain about Apple's attitude regarding these files. So for now get the libhashab.so files here -
https://github.com/denydias/libhashab
On the right side of that webpage click on the button labelled "Download ZIP" and you will be prompted to download a file called "libhashab-master.zip". Now unzip this file with -

Code: Select all

cd /path/to/where/I/downloaded/the/file
unzip libhashab-master.zip

this will yield 8 files within a sub-directory "libhashab-master"

For the Nano 6gen the correct file is "libhashab32.so". Move it to /usr/lib/libgpod
and rename it "libhashab.so"

For iPhone4 and Touch 4gen the correct file is "libhashab_original.so". Similarly, move it to /usr/lib/libgpod
and rename it "libhashab.so"


OK, all of this setup is quite involved, but it's a once-only process! Once rebooted and your i-device is connected, you now just need to run these two commands -

Code: Select all

ifuse /mnt/ipod
gtkpod

It's somewhat inconvenient to run these commands manually each time you connect, so I provided a script; /usr/bin/gtkpod-run
which can be linked to an icon on the desktop. A suitable icon is /usr/local/lib/X11/pixmaps/gtkpod48.png

[tempestuous]

INSTRUCTIONS for gtkpod configuration.

Finally! Your device is now connected to Puppy, you have mounted it, and you have just launched gtkpod for the first time.
First go to Edit > Configure Repositories
and press the "+ Add New ..." button. You need to create a new repository, with the following:
Repository type: iPod
Repository name: <choose a name for your iPod>
iPod mountpoint: "/mnt/ipod" for iPhone/iPad/Touch, or "/mnt/sdb.." for conventional iPods.
iTunesDB backup: /root/.gtkpod/iTunesDB.bak (for iPhone/iPad/Touch)
Model: select your EXACT model.

Now go ahead and add some music files.

When you exit gtkpod, iPhone/iPad/Touch devices are automatically unmounted, via a script; /root/.gtkpod/gtkpod.out For reference, this is the command which does the unmounting -

Code: Select all

fusermount -u /mnt/ipod

Obviously, don't disconnect the device until after you have closed the gtkpod application, or you have run the unmount command manually.

For conventional iPods, you need to manually unmount these by right-clicking their desktop icon, and selecting "Unmount".
If you disconnect your device before unmounting, you risk damage to the filesystem.

If all has gone well, your newly added music files should show up in the i-device, itself.

[tempestuous]

If anyone wants to employ volume normalization during the transfer of audio files from Puppy to iPod, you need the additional utilities:
mp3gain and aacgain
I have provided these as a single dotpet -
http://www.smokey01.com/tempestuous/mp3 ... in-1.9.pet
Once installed, you must then enable the normalization funtion. Go to: Edit > Preferences > Settings > Normalization...
and specify the location of the mp3gain and aacgain executables, as illustrated.

[tempestuous]

Tagging and Coverart

As I understand it, iPods will only display coverart that is embedded into the tags of your music files
ie. it's not possible just to copy over separate coverart files called "folder.jpg" or ".folder.png"

Apparently gtkpod has a function to modify tags, including coverart ... but its success is not assured, and you may find that your iPod fails to display the tags that you added. Tagging is probably best achieved with Puppy's dedicated tagging utility, Ptag, found under
Menu > Multimedia > Ptag audio file tag editor

Before you start, you first need to add two important components:
1) coverart tagging support for mp3 files -
id3pic-0.1.pet
http://murga-linux.com/puppy/viewtopic.php?t=70011

2) .m4a file support (Apple iTunes format) including coverart support -
atomicparsley-0.9.4-i486.pet
http://murga-linux.com/puppy/viewtopic.php?t=24941

Now when you launch Ptag and select your music file(s) the filetype will be automatically detected, and the 2 screenshots below show where to select the coverart file that you want to add.

[tempestuous]

Regarding MTP (Media Transfer Protocol) devices, as typically represented by various brands of Android smartphones, file transfer is achieved via the go-mtpfs utility, in combination with various GUIs. Refer here -
http://www.murga-linux.com/puppy/viewtopic.php?t=91442

[redandwhitestripes]

Hi Tempestuous,

I'm using a brand new 7th Gen Ipod Nano and Precise Puppy full install.

I initialised under windows, then installed the two pets in this thread.

I also followed the instructions (and extra download) for 6th gen Nanos as I guessed 7th gen would have the same issue.

The message I'm getting is:
No device found, is it connected?
If it is make sure that your user has permissions to access the raw usb device.
If you're still having issues try unplugging the device and reconnecting it.



I also tried installing usbmuxd which did nothing to help but did give me a bonus error message:
usbmuxd_get_device_list: error opening socket!



I've tried rebooting and mounting/unmounting. Just no joy.

Any ideas?
Thanks.

[tempestuous]

It sounds like you're trying to use usbmuxd, which is incorrect for a Nano.
A Nano is a "conventional" iPod model, and the relevant setup instructions are in my 3rd post above:

If your iPod was initialised under Windows, its filesystem will be FAT32, which is easy to deal with in Linux. Just click on the desktop icon, and the iPod will "mount" ready for access by gtkpod.
Don't be concerned if you can't see any files on the mounted iPod using ROX. gtkpod will handle all file management.

[redandwhitestripes]

Ah yes, I just tried that after I had no luck beforehand.

I've now removed usbmuxd. I still can't get ifuse to see my ipod (I get the same error message). I can run gtkpod and it can see my ipod and its music, but I can't add any tracks. When I click "load ipod", I get the message

"Errors created during repository import"

And then when I try to add a track:

"Failed to generate sqlite database: an error occurred during Locations.itdb.cbk generation"


Is this simply a case of 7th Gen Nanos not being supported yet?

Thanks for your time and support.

[tempestuous]

At the outset, I'm concerned that you're attempting to perform some of the steps from the 4th post, which is completely wrong for the Nano.
The gtkpod-2.0.2-May-2014.pet package already contains usbmuxd. There's no need to add usbmuxd, and there's also no need to remove usbmuxd. usbmuxd is only used with iPhone, iPad, and Touch, anyway.
Similarly, ifuse is only used with iPhone, iPad, and Touch.

I can run gtkpod and it can see my ipod and its music

OK, that's a good start. I think I know what the problem may be, but I need some information -

i) please confirm what your Nano's mountpoint is in Puppy - /mnt/sdb3 ??

ii) with your Nano connected to Puppy and mounted, use ROX to browse to /mnt/sdb3/iPod_Control/Device/
and check that there's a file called "HashInfo"
This will confirm that the Nano has been initialised.

iii) in the same directory, check that there's a file called "SysInfo"

iv) if so, open SysInfo in Geany, and check if it contains a line which starts with "FirewireGuid:"

[redandwhitestripes]

Thanks for the feedback.

My 'pod mounts at: /mnt/sdb1
In the directory /mnt/sdb3/iPod_Control/Device/ there is *no* file called 'hashinfo'.

To be sure, I went back to my windows computer, opened itunes and looked at my songs without any problems.

The SysInfo file is present but contains only this line:
ModelNumStr: xC526

Thanks again,
Greg

[tempestuous]

EDIT: deleted.

[tempestuous]

EDIT Nov 2014 - deleted.
Correct iPod configuration is now tested, and instructions updated in the 3rd post.

[redandwhitestripes]

Don't thank me, sir. The thanks is all in your direction

Interestingly, the mount point *was* /mnt/sdb3 until I installed your hotfix.then it changed to /sdb1. (Maybe it was just because I had rebooted (?))

There's no error message. The sysinfo file as exactly as before however there is a new file called extendedsysinfo. It gives me the following:

<key>FireWireGUID</key>
<string>000A2700249C347B</string>

gtkpod is still returning the same errors, however.

[tempestuous]

EDIT Nov 2014 - deleted.
Correct iPod configuration is now tested, and instructions updated in the 3rd post.

[redandwhitestripes]

Thanks again,

I apologise for getting the file name back to front. That was sloppy of me.

I have followed your instructions, the serial numbers match, but the outcome is the same. Could it simply be that gtkpod doesn't support the new nanos yet?

[tempestuous]

EDIT Nov 2014 - deleted.
Correct iPod configuration is now tested, and instructions updated in the 3rd post.