iPod, iTunes, Mac, Macintosh, iBook are trademarks of Apple Computer,
Inc., registered in the U.S. and other countries.


Short instructions:
-------------------

Connecting iPod to a Linux box:
-------------------------------

1) You need a Windows iPod. See e.g.

http://www.blinkenlights.ch/cgi-bin/fm.pl?get=ipode

for information about how to convert your mac iPod to a windows iPod.

2) Get kernel source and configure
Needed configuration:

    * Code maturity level options - y
    * SCSI support - y
    * SCSI disk support - m
    * IEEE1394 (FireWire)/IEEE 1394 (FireWire) support (Experimental) - y
    * OHCI-1394 support - y
    * SBP-2 support - m

3) Create /mnt/ipod:

   mkdir /mnt/ipod

4) Add a line to /etc/fstab. You should edit uid to match your user
   id. Also, /dev/sda2 may not be appropriate, if you have other scsi
   devices.

/dev/sda2	/mnt/ipod	vfat	uid=1000,user,defaults,noatime,errors=remount 0 0

5) Connect your iPod to your computer and wait until you see something
   like the following on your system log (you can use the 'dmesg'
   command to check).

Nov 28 21:58:06 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023
Nov 28 21:58:09 hatarakibachi kernel: ieee1394: Node 01:1023 changed to 00:1023
Nov 28 21:58:12 hatarakibachi kernel: ieee1394: NodeMgr: hotplug policy returned -2
Nov 28 21:58:12 hatarakibachi kernel: ieee1394: Device added: Node[00:1023]  GUID[000a2700020680b5]  [Apple Computer, Inc.]
Nov 28 21:58:12 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023

6) Load the sbp2 module (most likely as root):

   modprobe sbp2

   You should see something like the following on your system log:

Nov 28 21:58:38 hatarakibachi kernel: ieee1394: sbp2: Logged into SBP-2 device
Nov 28 21:58:38 hatarakibachi kernel: scsi0 : IEEE-1394 SBP-2 protocol driver (host: ohci1394)
Nov 28 21:58:38 hatarakibachi kernel: $Rev$ James Goodwin <jamesg@filanet.com>
Nov 28 21:58:38 hatarakibachi kernel: SBP-2 module load options:
Nov 28 21:58:38 hatarakibachi kernel: - Max speed supported: S400
Nov 28 21:58:38 hatarakibachi kernel: - Max sectors per I/O supported: 255
Nov 28 21:58:38 hatarakibachi kernel: - Max outstanding commands supported: 8
Nov 28 21:58:38 hatarakibachi kernel: - Max outstanding commands per lun supported: 1
Nov 28 21:58:38 hatarakibachi kernel: - Serialized I/O (debug): no
Nov 28 21:58:38 hatarakibachi kernel: - Exclusive login: yes
Nov 28 21:58:38 hatarakibachi kernel:   Vendor: Apple     Model: iPod              Rev: 1.21
Nov 28 21:58:38 hatarakibachi kernel:   Type:   Direct-Access                      ANSI SCSI revision: 02
Nov 28 21:58:38 hatarakibachi kernel: Attached scsi removable disk sda at scsi0, channel 0, id 0, lun 0
Nov 28 21:58:38 hatarakibachi kernel: SCSI device sda: 39062520 512-byte hdwr sectors (20000 MB)
Nov 28 21:58:38 hatarakibachi kernel: sda: test WP failed, assume Write Enabled
Nov 28 21:58:39 hatarakibachi kernel:  sda: sda1 sda2

7) Mount the iPod hard drive

   mount /mnt/ipod

8) do whatever you need to do (e.g. start gtkpod, see below)

9) Unmount the iPod:

    umount /mnt/ipod

10) Unload the module sbp2 (as most likely as root):

    rmmod sbp2

11) Disconnect the iPod from your computer.



Using gtkpod
------------

Make sure you have followed steps 1-7 above. Then:


1) make a backup of your iTunesDB:

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

2) Start gtkpod

3) Use "Import" to import the contents of your old iTunesDB.

4) Use "Add Files" and "Add Directories" to add files or directories.

5) Use "Export" to write the added files to the iPod and create a new
    iTunesDB.

6) Quit the program.

and continue with step 8-11 above.



Features
--------

Songs
-----

- You can add individual songs, entire directories recursively, or
  existing playlists using "Add Files". A file selection dialogue will
  appear.
- 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 songs by marking them and pressing the "Ctrl-d" . If
  you delete songs from the master playlist (the topmost playlist,
  called "gtkpod" by default).  You can also delete songs by selecting them,
  and using "Delete Song" in the Edit menu.
- You can update ID3 tags of selected songs in gtkpod from the mp3
  file by pressing "Ctrl-u" or choose "Update song info from file" in
  the Edit 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.
- Cou can specify which tags to display in the preferences window
- Cou can specify (in the prefs window) if the ID3 tags of the
  corresponding mp3 file should also be updated


Sort Tabs
---------

- The two notebooks above the song display are called "Sort Tabs"
- They allow you to filter which songs to display
- If you edit an entry in the sort tab, the corresponding entry in all
  associated songs will be updated as well. When writing the tags to
  disk as well, updating of a large number of songs may take a while


Playlists
---------

- You can create playlists with "New Playlist" or pressing "Ctrl-n" in
  the playlist listview.
- You can also create playlists by adding an existing playlist file
  with "Add file" or "Add playlist".
- You can add songs to playlists by marking the songs you want to add,
  and then dragging them onto the playlist.
- You can rename playlists.
- You can delete playlists by selecting the desired playlist and pressing
  "Ctrl-D", or by selecting "Delete Playlist" from the Edit menu.


Duplicate Detection
-------------------

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

For the duplicate detection a list of MD5 checksums is kept in
memory. It is updated each time you add files or directories. It is
also updated each time you import your existing iTunes database.  The speed
hit taken for enabling this is very small, but will make startup a little
slower.

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 song 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 song it stores

  - MD5 hash
  - filename in the locale's encoding
  - filename in UTF8 encoding
  - hostname where the file was added (not used for anything yet)

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 MD5 checksums do not have to be re-calculated.

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

The extended information file is also used for the "Offline Mode"
described below.


Refresh Song 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
song. Simply select the song to be updated and press "Ctrl-u" or
choose "Update Song Info From File" from the Edit menu. Since gtkpod
needs to know the filename of the song, the "Extended Information
File" (see above) is needed.

You can also select entries in the sort tab or entire playlists for
refresh. 


Offline Mode
------------

It is possible to modify your iTunesDB "offline", i.e. without your
iPod connected to your computer. You can then synchronize the contents
of your iPod at any later time.

To to this, you must have a backup of your iTunes database and the
extended information file in the ~/.gtkpod/ directory (choose the
backup option in the prefs menu for automatic backups).

Before importing your iTunes database, you must select the "Offline"
option in the "Files" menu. (The import and export of your iTunes
database will then be done from or to ~/.gtkpod/.) Then import your
iTunes database.

You can modify (add songs, add playlists, modify playlists, delete
playlists, delete songs) as usual. When you export your iTunesDB, it
will be written to ~/.gtkpod/ along with an extended information file
(even if you have not chosen that option in the prefs menu), tagging
the songs not yet transferred.

Next time around you can import the database as described above,
switch off the offline mode, and export the iTunes database to your
iPod. The contents of your iPod hard drive are then brought up to
date.


Export of Songs
---------------

- mark the songs you want to export and select "Export Files to Disk"
  from the menu
- A file selection dialog window appears and you can choose the directory
  you'd like the selected files to be written to.


Encoding of ID3 tags (charsets)
-------------------------------
You can specify the carset 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 you
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.


About filenames (excerpt from the GTK2 release notes):
------------------------------------------------------
* The assumption of GLib and GTK+ by default is that filenames on the
  filesystem are encoded in UTF-8 rather than the encoding of the locale;
  The GTK+ developers consider that having filenames whose interpretation
  depends on the current locale is fundamentally a bad idea.

  If you have filenames encoded in the encoding of your locale, then
  you may want to set the G_BROKEN_FILENAMES environment variable:
  
   G_BROKEN_FILENAMES=1
   export G_BROKEN_FILENAMES

  Best integration of GTK+-2.0 with the environment is achieved by 
  using a UTF-8 locale.

------ end of excerpt

It is my feeling that many people use filenames encoded in the
encoding of the locale. The "Add directories" dialogue already takes
care of this and assumes the filenames to be in the same encoding as
you have specified for the ID3 tags (see above). You can therefore
forget about the excerpt above.

However, the "Add Files" and "Add Playlists" dialogue (at the moment)
uses the standard GTK+-2.0 file selection dialogue. Therefore I have
no access on the conversion functions used, and a warning is printed
when filenames are encountered that are encoded in a an encoding other
than the once of the current locale. ID3 tags are still read currectly
(according to the charset set in the preference dialogue).



Known bugs
----------

- Display of large number of songs is awfully slow (mainly because of
  the use of the standard GTK2 tree views) -> deactivate "Automatically
  select "All" in first sort tab" and/or deactivate "Automatically
  select master playlist". You could also "block the display" to speed
  up the display update.

