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


*----------------------------------*
|                                  |
|            Contents              |
|                                  |
*----------------------------------*


  - Connecting iPod to a Linux box:
  - Using gtkpod
  - Features
     - Songs
     - Sort Tabs
     - Playlists
     - Drag and Drop
     - Duplicate Detection
     - Preferences File
     - Startup and Shutdown scripts
     - Extended Information File
     - Refresh (Update) Song Info From File
     - Offline Mode
     - Export of Songs
     - Encoding of ID3 tags (charsets)
     - About filenames
  - Sick of loading the sbp2 modules by hand? (an example of how to
    use startup/shutdown scripts)
  - Known bugs

*----------------------------------*
|                                  |
|  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.


Drag and Drop
-------------

Drag and Drop can be used in several ways:

- Drag songs from the song view _onto_ an existing playlist: the songs
  will be added to that playlist.
- Drag songs from the song view _between_ two existing playlists or
  behind the last playlist: a new playlist will be created and the
  songs will be added to that playlist.
- Drag an entry of a sort tab _onto_ an existing playlist: all songs
  matching the entry will be added to that playlist.
- Drag an entry of a sort tab _between_ two existing playlists or
  behind the last playlist: a new playlist will be created and all
  songs matching the entry will be added to that playlist.
- Drag songs, directories, or playlist files _onto_ an existing
  playlist: all songs as well as the contents of playlist files will
  be added to that playlist.
- Drag songs or directories _between_ two existing playlists or behind
  the last playlist: a new playlist will be created and all songs will
  be added to that playlist.
- Drag playlist files _between_ two existing playlists or behind the
  last playlist: for each playlist file a new playlist named after the
  file will be created and the corresponding songs will be added to
  that playlist.
- Drag songs, directories, or playlist files into the song view (note:
  something must be displayed in the songview before you can drop into
  it -- drop onto the correpsonding playlist otherwise.): the songs
  will be inserted into the corresponding playlist at the position you
  dropped them.


Preferences File
----------------

On startup gtkpod will read the preferences from ~/.gtkpod/prefs (or
/etc/gtkpod/prefs if the former doesn't exist).


Startup and Shutdown Scripts
----------------------------

After reading the preferences file gtkpod will try to execute
~/.gtkpod/gtkpod.in (or /etc/gtkpod/gtkpod.in if the former doesn't
exist) during startup. This is done before attempting to mount the
iPod directory (optional) or read the iTunesDB (optional)).

When leaving the program gtkpod will try to execute
~/.gtkpod/gtkpod.out (or /etc/gtkpod/gtkpod.out if the former doesn't
exist). This is done after attempting to unmount the iPod directory
(optional).

Please see the section "Sick of loading the sbp2 modules by hand?" for
an example of how to use this functionality.


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 (Update) 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).



*----------------------------------*
|                                  |
|     Sick of loading the sbp2     |
|         modules by hand?         |
|                                  |
|         Corey Donohoe            |
|     <atmos at atmos dot org>     |
|         March 22nd 2003          |
|                                  |
*----------------------------------*

Sick of loading the sbp2 modules by hand every time you want to use your
ipod?  Are you sick of mounting it too?  Using sudo gtkpod can make manually
interacting with the ipod filesystem a thing of the past.  Note that you
should have your ipod working with gtkpod before attempting this automated
method, see the README that came with gtkpod in order to get things up and
running.

Here's a brief example of how I'm using gtkpod now in 8 easy steps.

/**********/
 * Step 1 *
/**********/
Using sudo allow users to load/remove the sbp2 module
Example /etc/sudoers
------------------------------- Begin Here ---------------------------------

# Cmnd alias specification
Cmnd_Alias IPOD=/sbin/modprobe sbp2 sbp2_force_inquiry_hack=1, /sbin/rmmod sbp2
# User privilege specification
atmos   ALL=(ALL) ALL
atmos   ALL= NOPASSWD : IPOD

------------------------------- End Here -----------------------------------
I use the force inquiry hack cause I have an older iPod, if you normally can
get by with /sbin/modprobe sbp2 then ignore the inquiry hack stuff.  Note
that explicitly specifying with module to probe/remove keeps the user from
being able to add/remove arbitrary modules.  This allows us to keep gtkpod
as a user process, and execute commands the user wouldn't usually have
enough rights to.

/**********/
 * Step 2 *
/**********/
Add a line similar to the below to your /etc/fstab, this will enable users
to mount the ipod with read/write capabilities.  Example line assumes your
ipod mount point is /mnt/ipod and your ipod is detected as /dev/sda

------------------------------- Begin Here ---------------------------------
/dev/sda2       /mnt/ipod       vfat    rw,user,noauto          0       0
------------------------------- End Here -----------------------------------


/**********/
 * Step 3 *
/**********/
Then setup your /etc/gtkpod/gtkpod.in file to load the module when gtkpod is
exited
Example /etc/gtkpod/gtkpod.in
------------------------------- Begin Here ---------------------------------

sudo /sbin/modprobe sbp2 sbp2_force_inquiry_hack=1

------------------------------- End Here -----------------------------------

/**********/
 * Step 4 *
/**********/

Then setup your /etc/gtkpod/gtkpod.out file to unload the module when gtkpod
is exited
Example /etc/gtkpod/gtkpod.out
------------------------------- Begin Here ---------------------------------

sudo /sbin/rmmod sbp2 

------------------------------- End Here -----------------------------------

/**********/
 * Step 5 *
/**********/
Then enable ipod automounting in the gtkpod prefs(in the misc tab).

/**********/
 * Step 6 *
/**********/
You're now ready to use gtkpod in a much nicer fashion.  Start by
plugging in your ipod.  You should get a check mark with "OK to disconnect"
displayed on your ipod.

/**********/
 * Step 7 *
/**********/
Start gtkpod, your ipod should be accessible(i.e. autoimport should work)
A "Do Not Disconnect" message is displayed on your ipod while gtkpod is
running.

/**********/
 * Step 8 *
/**********/
After you exit gtkpod, the "OK to disconnect" message should be displayed
again.  It's ok to unplug your ipod now.  

Good Luck. 



*----------------------------------*
|                                  |
|           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.
