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

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


  - Using gtkpod
  - Features
     - Tracks
     - Sort Tabs
     - Playlists
     - Drag and Drop
     - Duplicate Detection
     - Preferences File
     - Startup and Shutdown scripts
     - Extended Information File
     - Refresh (Update) Track Info From File
     - Synchronize Directories
     - Volume Normalization
     - Offline Mode
     - Export of Tracks
     - Encoding of ID3 tags (charsets)
     - Extracting tag information from the filename
     - About filenames
     - Restoring your iPod after file system error
  - Connecting iPod to a Linux box:
  - Sick of loading the sbp2 modules by hand? (an example of how to
    use startup/shutdown scripts)

*----------------------------------*
|                                  |
|          Using gtkpod            |
|                                  |
*----------------------------------*


Follow steps 1-7 in the "Connecting your iPod to a Linux box"
(basically you need to get the iPod partition mounted to /mnt/ipod)


1) The faint-of-heart make a backup of their 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", "Add Directories" or DND to add files or
   directories.

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

6) Quit the program.

and continue with step 8-11 of the "Connecting your iPod to a Linux
box" section (basically describing how to unmount and disconnect your
iPod).


*----------------------------------*
|                                  |
|            Features              |
|                                  |
*----------------------------------*

Tracks
-----

- You can add individual tracks, entire directories recursively, or
  existing playlists using "Add Files". A file selection dialogue will
  appear. By default existing tracks (same full filename) will be skipped.
- 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 tracks by marking them and pressing the "Ctrl-d" . If
  you delete tracks from the master playlist (the topmost playlist,
  called "gtkpod" by default).  You can also delete tracks by selecting them,
  and using "Delete Track" in the Edit menu or from the context menu.
- You can update ID3 tags of selected tracks in gtkpod from the mp3
  file by pressing "Ctrl-u" or choose "Update track info from file" in
  the Edit menu or from the context 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 (or mark several tracks and edit the first).
- 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(s) should also be updated


Sort Tabs
---------

- The two notebooks above the track display are called "Sort Tabs"
- They allow you to filter which tracks to display
- If you edit an entry in the sort tab, the corresponding entry in all
  associated tracks will be updated as well. When writing the tags to
  disk as well, updating of a large number of tracks 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 tracks to playlists by marking the tracks 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 tracks from the track view _onto_ an existing playlist: the tracks
  will be added to that playlist.
- Drag tracks from the track view _between_ two existing playlists or
  behind the last playlist: a new playlist will be created and the
  tracks will be added to that playlist.
- Drag an entry of a sort tab _onto_ an existing playlist: all tracks
  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
  tracks matching the entry will be added to that playlist.
- Drag tracks, directories, or playlist files _onto_ an existing
  playlist: all tracks as well as the contents of playlist files will
  be added to that playlist.
- Drag tracks or directories _between_ two existing playlists or behind
  the last playlist: a new playlist will be created and all tracks 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 tracks will be added to
  that playlist.
- Drag tracks, directories, or playlist files into the track view (note:
  something must be displayed in the trackview before you can drop into
  it -- drop onto the correpsonding playlist otherwise.): the tracks
  will be inserted into the corresponding playlist at the position you
  dropped them.
- If holding the shift key when dropping tracks or a sort tab entry
  onto an existing or new playlist, the tracks will be moved instead
  of copied. Please keep in mind that tracks cannot be moved from or
  to the master playlist.


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.

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

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

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


Synchronize Directories
-----------------------

If you have added files to directories or changed files in directories
you have previously added tracks from, you can use the "Synchronize
Dirs" utility to update your iTunesDB.

"Synchronize Dirs" will use the selected tracks to make a list of
directories to update, so you should activate the "Write Extended
Information" option in the export section of the preferences
dialogue.

It will then add all non-existing tracks in those directories and
update (see "Refresh") all existing tracks. The tracks are also added to
the currently selected playlist, if they aren't already a member.

Tracks that have been removed from the directory will only be removed
from the iTunesDB if this option is checked in the option dialogue.

For best results you should also activate duplicate detection. This
avoids unnecessary copying of unchanged tracks.


Volume Normalization
--------------------

The iPod allows to individually increase or decrease the volume on a
track-to-track basis using a "volume tag".

gtkpod uses 'mp3gain' (mp3gain.sourceforge.net) to do the volume
normalization. You need to install mp3gain in the default path or set
the full path in the 'Tools' section of the preferences dialog.

For each song passed to mp3gain the volume adjustment needed to
achieve the "normal" volume level is determined and stored on the iPod
the next time the iTunesDB is written. Since this calculation takes
quite a long time, an option to write the gain information into the
mp3 file itself is also available.

At this time the "album gain" functionality of mp3gain is not
supported. "Album gain" means that the volume of all tracks of one
album is adjusted by the same gain, such that the relative volume
level remains the same. It is planned to realize this in the next
version.

Please note that the conversion between mp3gain's gain level and the
iPod's volume level is not well established yet. If you think the
results are strange, please play around with nm_gain_to_volume() in
normalize.c and tell me if you can improve it.

Also, please be aware that tracks are not normalized on a 'per
playlist' fashion. If a track is normalized, it's normalized in all
playlists it is a member of.


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 tracks, add playlists, modify playlists, delete
playlists, delete tracks) 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 tracks 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 Tracks
---------------

- mark the tracks 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)
-------------------------------
If you use correctly written unicode ID3V2 tags you don't have to
worry about the charset setting.

Otherwise you must 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
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 recognised 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 filanames 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, alabum, 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.


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

1) Make gtkpod think it still needs to copy the tracks 
  
$ perl -p -i -e 's/transferred=1/transferred=0/g' ~/.gtkpod/iTunesDB.ext

2) Import the iTunesDB in "Offline" mode

3) Switch to "Online" mode

4) Export iTunesDB

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.


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


*--------------------------------------------------*
|                                                  |
|  Connecting iPod to a Linux box using IEEE 1394  |
|  (kernel 2.4.20)                                 |
|  (connecting to 2.4.21 seems to work slightly    |
|   differently -- see below )                     |
|                                                  |
*--------------------------------------------------*

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.

Alternatively, I have received a report that Alan Cox's patches
(2.4.21-rc8-ac1, but 2.4.21-ac1 should work as well) include hfsplus
support. That should allow you to use hfs formatted iPods. But beware:
hfsplus support is still beta.

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 rw,user,noauto,noatime 0 0

NOTE: Some users have had problems with newer versions of mount(newer than
mount-2.11h) The following fstab entry might work better for you.

/dev/sda2	/mnt/ipod	vfat rw,user,noauto,noatime,shortname=winnt 0 0

NOTE: You can add ",umask=0" to the options to make the iPod
readable/writable for all users.

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.


*--------------------------------------------------*
|                                                  |
|  Connecting iPod to a Linux box (IEEE 1394)      |
|  (kernel 2.4.21)                                 |
|  (may also work with 2.4.20, but I didn't try)   |
|                                                  |
*--------------------------------------------------*

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.

Alternatively, I have received a report that Alan Cox's patches
(2.4.21-rc8-ac1, but 2.4.21-ac1 should work as well) include hfsplus
support. That should allow you to use hfs formatted iPods. But beware:
hfsplus support is still beta.

2) Get kernel source and configure
Needed configuration:

    * Code maturity level options - y
    * SCSI support - y
    * SCSI disk support - y
    * IEEE1394 (FireWire)/IEEE 1394 (FireWire) support (Experimental) - y
    * OHCI-1394 support - y
    * SBP-2 support - m (important to use module -- if someone finds
      out how to use hotplug with sbp2 compiled in, let me know)

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 rw,user,noauto,noatime,errors=remount 0 0

NOTE: Some users have had problems with newer versions of mount(newer than
mount-2.11h) The following fstab entry might work better for you.

/dev/sda2	/mnt/ipod	vfat rw,user,noauto,noatime,shortname=winnt 0 0

NOTE: replace "vfat" with "hfsplus" if you use a hfs-formatted iPod.

5) Install the hotplug utilities
   (http://linux-hotplug.sourceforge.net/, debian package: 'hotplug')

   (If you don't want to use the hotplug utilities, you must call the
   rescan-scsi-bus.sh (see below) by hand after loading the sbp2
   module. This is different from 2.4.20.)

5a) Add the ieee1394 hotplug support (described at
    http://www.linux1394.org/faq.html#hotplug):

   - copy ieee1394.agent to /etc/hotplug/ from
     http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/linux-hotplug/admin/etc/hotplug/
   - mkdir /etc/hotplug/ieee1394
   - create /etc/hotplug/ieee1394/sbp2:
       #!/bin/bash
       if [ "${ACTION}" = "add" ]; then
	 . /etc/hotplug/ieee1394/rescan-scsi-bus.sh
       else
	 . /etc/hotplug/ieee1394/rescan-scsi-bus.sh -r
       fi
   - copy rescan-scsi-bus.sh to /etc/hotplug/ieee1394 from
     http://www.garloff.de/kurt/linux/rescan-scsi-bus.sh

6) 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).

Jun 15 17:13:53 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023
Jun 15 17:13:55 hatarakibachi kernel: ieee1394: Node 01:1023 changed to 00:1023
Jun 15 17:13:57 hatarakibachi kernel: ieee1394: sbp2: Logged into SBP-2 device
Jun 15 17:13:57 hatarakibachi kernel: ieee1394: Device added: Node[00:1023]  GUID[000a2700020680b5]  [Apple Computer, Inc.]
Jun 15 17:13:57 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023
Jun 15 17:13:57 hatarakibachi kernel: scsi singledevice 0 0 0 0
Jun 15 17:13:57 hatarakibachi kernel:   Vendor: Apple     Model: iPod              Rev: 1.30
Jun 15 17:13:57 hatarakibachi kernel:   Type:   Direct-Access                      ANSI SCSI revision: 02
Jun 15 17:13:57 hatarakibachi kernel: Attached scsi removable disk sda at scsi0, channel 0, id 0, lun 0
Jun 15 17:13:57 hatarakibachi kernel: SCSI device sda: 39062520 512-byte hdwr sectors (20000 MB)
Jun 15 17:13:57 hatarakibachi kernel: sda: test WP failed, assume Write Enabled
Jun 15 17:13:58 hatarakibachi kernel:  sda: sda1 sda2
Jun 15 17:13:58 hatarakibachi kernel: scsi singledevice 0 0 1 0
...

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) Disconnect the iPod from your computer (ignore the "Do not
    disconnect" message -- as long as you wait for the 'unmount' to
    command to finish properly, everything should be fine).



*--------------------------------------------------*
|                                                  |
|  Connecting iPod to a Linux box (USB)            |
|                                                  |
*--------------------------------------------------*

I don't have much information about this so far (I don't own a third
generation iPod). Please help me to fill in the gaps.

Stephen Drye sent me the following note:

"I've figured out how to get a USB-connected iPod recognized...:

The trick to it is that you have to 

- plug the iPod in

- it'll fail to be recognized by the SCSI subsystem

- now, even though your ipod says not to, unplug the USB cord and
  immediately plug it back in.

- since the iPod's hdd was already spun up, the SCSI subsystem now
  recognizes it and mounts it as /dev/sda

- You can then mount /dev/sda2 to /mnt/ipod as normal."



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

(Remark: the hotplug facility of new kernels can also load and unload
the sbp2 module for you.)

/**********/
 * 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
started.
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 tracks 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. Further, decreasing the window size
  considerably speeds up the display.

  I also want to point out that updating the info window takes up a
  considerable amount of time. Update may become more intelligent in
  the future -- until then close the info window for more speed.

- When changing selections in the sort tabs while importing the
  iTunesDB, sometimes the interface freezes. I tried to track this
  problem down but only found out that gtk+ does not return control
  back to gtkpod. Selecting the "All" sort tabs seems to unfreeze the
  interace again.
