1iPod, iTunes, Mac, Macintosh, iBook are trademarks of Apple Computer, 2Inc., registered in the U.S. and other countries. 3 4 5 6Donations are welcome: please go to 7https://sourceforge.net/project/project_donations.php?group_id=67873 8for details. 9 10 11*----------------------------------* 12| | 13| Contents | 14| | 15*----------------------------------* 16 17 18 - Using gtkpod 19 - Features 20 - Tracks 21 - Filter Tabs 22 - Playlists 23 - Photos 24 - Drag and Drop 25 - Duplicate Detection 26 - Preferences File 27 - Startup and Shutdown scripts 28 - Load iPod and eject iPod scripts 29 - Extended Information File 30 - Refresh (Update) Track Info From File 31 - Synchronize Directories 32 - Volume Normalization 33 - Podcasts 34 - Export of Tracks (Copy from iPod) 35 - Encoding of ID3 tags (charsets) 36 - Extracting tag information from the filename 37 - Checking iPod's files 38 - Restoring your iPod after file system error 39 - Playcounts & Rating 40 - About filenames 41 - Icons for window managers 42 - Connecting iPod to a Linux box: 43 - Sick of loading the sbp2 modules by hand? (an example of how to 44 use startup/shutdown scripts) 45 46*----------------------------------* 47| | 48| Using gtkpod | 49| | 50*----------------------------------* 51 52 531) If your iPod is not mounted automatically when connecting it to 54 your computer follow steps 1-7 in the "Connecting your iPod to a 55 Linux box" (basically you need to get the iPod partition mounted to 56 /mnt/ipod). In most cases this should not be necessary any more 57 these days. 58 592) If you are using GNOME, starting with V1.0 of gtkpod your iPod will 60 be automatically loaded and displayed within gtkpod once you 61 connect it to your box. Otherwise: 62 63 - Use "Load iPods" to import the contents of your old iTunesDB (you 64 may have to specify the correct mountpoint: right-button click on 65 the "iPod" repository, select "Edit iPod's Properties" and change 66 the mountpoint). 67 683) Use "Add Files", "Add Directories" or DND to add files or 69 directories. 70 714) Use "Eject iPod" in the context menu or click on the icon to the 72 left of the iPod name to write the added files to the iPod and 73 create a new iTunesDB and unload the iPod from gtkpod. 74 755) Unmount your iPod. The easiest way is to use the windowmanager. If 76 this is not an option for you continue with step 8-11 of the 77 "Connecting your iPod to a Linux box" section (basically describing 78 how to unmount and disconnect your iPod). 79 80 You can automate the unmounting by adding creating a 81 ~/.gtkpod/gtkpod.eject file with the following line in it (without 82 the quotation marks): "eject $1" 83 84 85*----------------------------------* 86| | 87| Features | 88| | 89*----------------------------------* 90 91Tracks 92----- 93 94- You can add individual tracks, entire directories recursively, or 95 existing playlists using "Add Files". A file selection dialogue will 96 appear. By default existing tracks (same full filename) will be skipped. 97- You can add directories recursively using "Add Dirs". A directory 98 selection dialogue will appear. 99- You can add existing playlists using "Add Playlists" 100- You can delete tracks by marking them and pressing the "Ctrl-d" . If 101 you delete tracks from the master playlist (the topmost playlist, 102 called "gtkpod" by default). You can also delete tracks by selecting them, 103 and using "Delete Track" in the Edit menu or from the context menu. 104- You can update ID3 tags of selected tracks in gtkpod from the mp3 105 file by pressing "Ctrl-u" or choose "Update track info from file" in 106 the Edit menu or from the context menu. 107- You can rename ID3 tags by editing the fields in gtkpod. You can 108 change an entire group of ID3 tags by editing an entry in the sort 109 tab (or mark several tracks and edit the first). 110- You can specify which tags to display in the preferences window 111- You can specify (in the prefs window) if the ID3 tags of the 112 corresponding mp3 file(s) should also be updated 113 114 115Filter Tabs 116----------- 117 118- The two notebooks above the track display are called "Filter Tabs" 119- They allow you to filter which tracks to display 120- If you edit an entry in the filter tab, the corresponding entry in all 121 associated tracks will be updated as well. When writing the tags to 122 disk as well, updating of a large number of tracks may take a while 123 124 125Playlists 126--------- 127 128- You can create playlists with "New Playlist" or pressing "Ctrl-n" in 129 the playlist listview. 130- You can also create playlists by adding an existing playlist file 131 with "Add file" or "Add playlist". 132- You can add tracks to playlists by marking the tracks you want to add, 133 and then dragging them onto the playlist. 134- You can rename playlists. 135- You can delete playlists by selecting the desired playlist and pressing 136 "Ctrl-D", or by selecting "Delete Playlist" from the Edit menu. 137 138 139Photos 140------ 141 142If your ipod supports photos then a special dynamic playlist is created in 143the playlist tree. YOU CANNOT DELETE IT! Indeed when clicking on it all the 144usual track related ipod functions are disabled or removed. 145 146Instead, the track window elements are replaced with the photo management pane. 147This displays the Photo Library and all the saved photos from the ipod and 148allows you to add new albums, add new images, remove albums, remove images and 149drag n drop images between albums. 150 151You cannot delete the Photo Library as this is the original photo database. All 152images are stored in it and thus clicking on it, all the images on the ipod are 153displayed in it. Subsequent albums display a subset of the Photo Library's images. 154 155Removing an image from an album will remove it from the album but it will still 156be stored on the ipod in the Photo Library. 157 158Removing an image from the Photo Library will delete it completely from the ipod. 159 160You can select a set of images from a selected album (inc. the Photo Library) and 161drag n drop them into another album. 162 163Any changes made in the photo management window will change the Photo playlist to 164italics indicating that a "Save Changes" should occur before exiting in order to 165preserve those changes. 166 167 168Drag and Drop 169------------- 170 171Drag and Drop can be used in several ways: 172 1731) gtkpod internal 174 175- Playlists, entries of a filter tab, and tracks can be dragged. 176 177- A drop _onto_ an existing playlist will add the tracks to that 178 playlist 179 180- A drop _between_ two existing playlists or behind the last playlist 181 will create a new playlist to which the tracks are added. 182 183- The default action for the drop is either move or copy as appears 184 appropriate (e.g. playlists are moved within a database ('local' or 185 'iPod/Shuffle'), but copied when dragged across different 186 databases). The applicable action is displayed within the drag 187 icon and can be changed by pressing the control key during the drop. 188 1892) between external file browser and gtkpod 190 191- Tracks, directories or playlist files can be dropped onto the 192 playlist view or track view. Drops between two existing playlists 193 create a new playlist. 194 1953) between external web browser and gtkpod 196 197- jpg files can be displayed in a web browser (eg. firefox, konqueror) 198 and dragged onto the coverart display or the image in the Edit Details 199 window. This will download the jpg to the album's directory then apply 200 it to the album's tracks. In the case of Edit Details, the jpg will 201 only be applied to the selected tracks (or only the one track if the 202 "Change all tracks simultaneously" is deselected). 203 204Preferences File 205---------------- 206 207On startup gtkpod will read the preferences from ~/.gtkpod/prefs (or 208/etc/gtkpod/prefs if the former doesn't exist). 209 210 211Startup and Shutdown Scripts 212---------------------------- 213 214After reading the preferences file gtkpod will try to execute 215~/.gtkpod/gtkpod.in (or /etc/gtkpod/gtkpod.in if the former doesn't 216exist) during startup. 217 218Just before exiting the program, gtkpod will try to execute 219~/.gtkpod/gtkpod.out (or /etc/gtkpod/gtkpod.out if the former doesn't 220exist). 221 222Please see the section "Sick of loading the sbp2 modules by hand?" for 223an example of how to use this functionality. 224 225 226 227Load iPod and eject iPod scripts 228-------------------------------- 229 230Before loading the contents of an iPod, gtkpod will call 231~/.gtkpod/gtkpod.load with the iPod's mountpoint as the only 232command line argument. Put any commands here needed to access the 233iPod, for example if you need to mount the iPod manually. 234 235When ejecting an iPod, gtkpod will call ~/.gtkpod/gtkpod.eject 236with the iPod's mountpoint as the only command line argument. Put 237any commands here you want to execute after gtkpod has written the 238changes to the iPod. One major candidate will probably be 239 240sudo eject $1 241 242gtkpod will not attempt to do any magic of it's own to 243mount/unmount/eject the iPod. 244 245 246 247Duplicate Detection 248------------------- 249 250You can instruct gtkpod (in the prefs window) to use 251file-size-dependent SHA1 checksums to prevent the same file from 252being copied to your iPod twice. 253 254If a duplicate is detected, gtkpod will print out the filenames 255of the duplicate files. If the filename of the already existing file 256is not available (it is not stored in the iTunes database, see 257"Extended Information File" below), other available information of 258the track is printed. 259 260 261Extended Information File 262------------------------- 263 264Some (I believe) essential information is not stored in Apple's iTunes 265database. You can therefore instruct gtkpod to write an additional 266file (iTunesDB.ext) with extended information. For each track it stores 267 268 - SHA1 hash 269 - filename in the locale's encoding 270 - filename in UTF8 encoding 271 - hostname where the file was added (not used for anything yet) 272 - filename of an associated converted file (for example an .mp3 for 273 a .flac file) 274 - if the file is present in the local database a reference to there 275 in order for playcounts to work on the local database as well 276 - last modification time 277 - the charset used for the file when adding it 278 279Since the extended information file is only valid with the 280corresponding standard iTunes database, a checksum of the iTunes 281database is also stored in the extended information file. 282 283Using an extended information file will considerably speed up the 284import of an existing iTunes database when using duplicate detection, 285since the SHA1 checksums do not have to be re-calculated. 286 287Using an extended information file will also allow modification of ID3 288tags in the track files after the initial import, because the full 289filenames are still available. 290 291 292Refresh (Update) Track Info From File 293------------------------------------ 294 295If you have changed the ID3 tags of your original file, you can update 296the ID3 tags stored in gtkpod without removing and re-adding the 297track. Simply select the track to be updated and press "Ctrl-u" or 298choose "Update Track Info From File" from the Edit menu. Since gtkpod 299needs to know the filename of the track, the "Extended Information 300File" (see above) is needed. 301 302"Update" will also re-read the replay-gain tags from disk, if 303available, and set the soundcheck field. If no replay-gain tag is 304available, the soundcheck field will be erased. 305 306You can also select entries in the filter tab or entire playlists for 307refresh. 308 309 310Synchronize with Directories 311---------------------------- 312 313If you have added files to directories or changed files in directories 314you have previously added tracks from, you can use the "Synchronize 315Dirs" utility to update your iTunesDB. 316 317"Synchronize with Dir(s)" will use the selected tracks to make a list 318of directories to update, so you should activate the "Write Extended 319Information" option in the export section of the preferences dialogue. 320 321It will then add all non-existing tracks in those directories and 322update (see "Refresh") all existing tracks. The tracks are also added to 323the currently selected playlist, if they aren't already a member. 324 325Tracks that have been removed from the directory will only be removed 326from the iTunesDB if this option is checked in the options dialogue. 327 328For best results you should also activate duplicate detection. This 329avoids unnecessary copying of unchanged tracks. 330 331 332 333Volume Normalization 334-------------------- 335 336There are two fields in the iTunesDB that allow to adjust the volume 337of an individual track: the volume field (a signed integer) and the 338soundcheck field (in dB). The volume is always active, whereas the 339soundcheck field is only active when you select 'soundcheck' on the 340iPod. Further, the soundcheck field only affects the earphone output 341but not the line output of the iPod. 342 343gtkpod will set the soundcheck according to the replay-gain tag set in 344your mp3 file. Newer versions of 'lame' automatically include the 345replay-gain tag when encoding. In that case the soundcheck field will 346be filled in when you first import a track. 347 348If no replay-gain tag is set, you can use the function 'Normalize 349Volume' to call mp3gain (mp3gain.sourceforge.net) to calculate the 350gain and write a replay-gain tag. Since this procedure is very time 351consuming, it is not done automatically during import. You need to 352install mp3gain in the default path or set the full path in the 353'Tools' section of the preferences dialog. If the iPod is connected, 354the tag is written to the file stored on the iPod. 355 356At this time "album gain" functionality is not supported. "Album gain" 357means that the volume of all tracks of one album is adjusted by the 358same gain, such that the relative volume level remains the same. It is 359planned to realize this in one of the next versions. 360 361Also, please be aware that tracks are not normalized on a 'per 362playlist' fashion. If a track is normalized, it's normalized in all 363playlists it is a member of. 364 365Once the replay-gain tag has been read, it is stored in the extended 366information file 'iTunesDB.ext'. When you call 'Normalize volume' 367again, the stored value will be used to re-populate the soundcheck 368field. Use 'Update Track' to re-read the tag from the file. 369 370 371Podcasts 372-------- 373 374You have to download podcasts using a third party tool like bashpodder 375(http://linc.homeunix.org:8080/scripts/bashpodder/) or gpodder 376(http://perli.net/projekte/gpodder/) 377 378Podcasts should be added directly into the 'Podcasts' playlist of the 379iPod repository, for example by selecting the Podcasts playlist before 380manually adding files/directories. Podcasts will then appear only in 381the Podcasts section on the iPod. 382 383If you add podcasts to the main playlist 'gtkpod/iPod' or any other 384iPod playlist first and then drag them over to the Podcasts playlist, 385the podcasts will appear in the Podcasts section on the iPod, as well 386as in the normal music section. 387 388The podcast 'repository' is a local repository (like 'Local') where 389you can keep all local podcasts. No mechanism exists to automatically 390synchronize the iPod repository with the Podcast repository at this 391time. You have to drag the podcasts over manually. 392 393 394Export of Tracks (Copy from iPod) 395--------------------------------- 396 397- Mark the tracks you want to export and select "Export Tracks from 398 Database" from the file menu (or use the context sensitive menu). 399- A file selection dialog window appears and you can choose the directory 400 you'd like the selected files to be written to. 401- You can specify the output filename in the prefs dialog by 402 specifying a template (e.g. "%A/%a - %t"). You can specify multiple 403 templates for different file formats by separating them by a 404 semicolon (e.g. "%A/%a - %t.mp3;%t.wav"). See the tooltip in the 405 prefs dialog for a list of identifiers. 406 407 408Encoding of ID3 tags (charsets) 409------------------------------- 410If you use correctly written unicode ID3V2 tags you don't have to 411worry about the charset setting. 412 413Otherwise you must specify the charset to be used for representing ID3 414tags in the preferences menu. The default is "System Charset", which 415is the charset associated with the locale gtkpod is running under. If 416your tags are stored in a different encoding, you should set it 417appropriately. 418 419Please note that if necessary you can change the charset each time you 420add files or directories: the iTunesDB itself is using UTF16, so once 421tags are imported correctly, changing the charset has no influence. 422 423If you chose "Japanese (automatic detection)", gtkpod will try to 424determine if the string is in ISO-2022-JP, Shift_JIS, or EUC-JP 425(Hankaku Katakana (1-byte Katakana) may not be recognized correctly -- 426specify the correct encoding if you run into this problem). The actual 427encoding used for the ID tags will be stored and will be used when 428writing tags or doing updates/syncs. Check the "Use selected charset 429also when updating or syncing tracks" and "Use selected charset when 430writing tags" options if you want to specify a particular character 431set when writing or updating/syncing. The default charset is "EUC-JP" 432-- it will be used when the charset cannot be autodetected, as well as 433when writing tags if a specific charset could not be determined 434before. 435 436gtkpod will recognize ID3V2 tags encoded in unicode automatically and 437ignore your charset setting when necessary. 438 439 440Extracting tag information from the filename 441-------------------------------------------- 442Tags can also be extracted from the filename if you activate the 443option 'Use this template to parse filename for tag information' and 444supply a template that explains how the filenames are constructed. 445 446For filenames like 447 music/new/latin1/alan_jackson - drive/01 drive_for_daddy_gene.mp3 448you could use 449 %a - %A/%T %*.mp3 450 451to extract artist, album, track number and title. 452 453The following character sequences are supported: 454 455 %t: title 456 %a: artist 457 %A: album 458 %c: composer 459 %t: title 460 %g: genre 461 %T: track number 462 %C: CD number 463 %*: placeholder, ignore data 464 %%: the character '%' 465 466You cannot supply a template like "%a%t.mp3" because gtkpod would not 467know how to separate artist and title. "%a_%t.mp3" would be correct, 468if artist and title are separated by an underscore. 469 470You can also omit the trailing ".mp3" if you want the template to 471apply to all files instead of only to mp3 files. 472 473 474Checking iPod's Files 475--------------------- 476For whatever reason -- it may happen that tracks are present in your 477iTunesDB that are no longer present on the iPod (dangling tracks), or 478that tracks are on the iPod but not in the iTunesDB (orphaned 479tracks). 480 481The function "Checking iPod's Files" under the "File" menu will 482identify both types and take the following actions: 483 484Orphaned tracks: 485A new playlist "[Orphaned]" will be created with all orphaned tracks 486in it. The only exception are orphaned tracks that would become 487duplicates (if duplicate detection is activated). Those are marked for 488deletion with the next sync. 489 490Dangling tracks: 491These tracks will be marked for deletion with the next sync unless the 492original PC file is still available. In that case you can have them 493restored with the next sync. 494 495 496Restoring your iPod after file system error 497------------------------------------------- 498If iPod's file system gets corrupted and you need to reformat your 499iPod, there is a way to restore the contents semi-automatically if you 500have been using the "write extended information file" (iTunesDB.ext) 501options: 502 503 - If the directory structure on the iPod doesn't exist yet, 504 load the iPod in gtkpod and have it created for you. Then unload 505 the iPod again. 506 507 - copy your backup files in .gtkpod/ (usually iTunesDB and 508 iTunesDB.ext) to your iPod (usually 509 <mountpoint>/iPod_Control/iTunes/ 510 On the iPod the files must be named iTunesDB and iTunesDB.ext. 511 512 - load the iPod in gtkpod 513 514 - select the iPod repository and start "Check iPod's files" from the 515 File menu 516 517 - unload the iPod (or save changes) 518 519This should restore your iPod to what it was before, provided you 520didn't move or remove any of the original tracks on your harddrive, and 521the charset information was stored correctly. 522 523 524Playcounts & Rating 525------------------- 526 527Whenever you play a track completely on the iPod (firmware version 1.3 528or higher) a counter in the "Play Counts" file will be increased by 529one. The same file also contains the rating you can set with the 3rd 530generation iPods. 531 532This file appears to be deleted whenever the iPod resets itself -- 533e.g. because you disconnect it from the computer. Therefore, be 534careful... Charging the iPod seems to do no harm. 535 536When gtkpod is started, it will also read this file and incorporate 537the information into the iTunesDB that can be written back to the 538iPod. 539 540There have been several requests to also register playcounts when 541playing a track on the local machine. This is possible by calling 542gtkpod as "gtkpod -p <filename>". 543 544If gtkpod is already running, the playcount of that track there will 545be increased by one. If gtkpod is not already running, the playcount 546will be registered in ~/.gtkpod/offline_playcount. This file will be 547read the next time you import the iTunesDB from your iPod, and the 548playcounts will be updated accordingly. 549 550Please note that if you start several instances of gtkpod, only the 551first instance will register playcounts through "gtkpod -p". 552 553Now all you have to do is tell your favorite player to call gtkpod 554with the filename of the played track. 555 556For xmms this is possible as of July 18th, 2004 (CVS 557version). Versions before that (including 1.2.10) only allow you to 558have an external program called at the beginning of a track. Our patch 559allows to have an external program called also at the end of a track. 560 561In each case you will need to activate the "General Plugin" called 562"song_change" and configure it to call 'gtkpod -p "%f"'. 563 564 565About filenames (excerpt from the GTK2 release notes): 566------------------------------------------------------ 567* The assumption of GLib and GTK+ by default is that filenames on the 568 filesystem are encoded in UTF-8 rather than the encoding of the locale; 569 The GTK+ developers consider that having filenames whose interpretation 570 depends on the current locale is fundamentally a bad idea. 571 572 If you have filenames encoded in the encoding of your locale, then 573 you may want to set the G_BROKEN_FILENAMES environment variable: 574 575 G_BROKEN_FILENAMES=1 576 export G_BROKEN_FILENAMES 577 578 Best integration of GTK+-2.0 with the environment is achieved by 579 using a UTF-8 locale. 580 581------ end of excerpt 582 583It is my feeling that many people use filenames encoded in the 584encoding of the locale. The "Add directories" dialogue already takes 585care of this and assumes the filenames to be in the same encoding as 586you have specified for the ID3 tags (see above). You can therefore 587forget about the excerpt above. 588 589However, the "Add Files" and "Add Playlists" dialogue (at the moment) 590uses the standard GTK+-2.0 file selection dialogue. Therefore I have 591no access on the conversion functions used, and a warning is printed 592when filenames are encountered that are encoded in an encoding other 593than the one of the current locale. ID3 tags are still read correctly 594(according to the charset set in the preference dialogue). 595 596 597*--------------------------------------------------* 598| | 599| Environment variables | 600| | 601*--------------------------------------------------* 602 603The following environment variables can be set if needed: 604 605IPOD_MOUNTPOINT: Defines the mountpoint of the iPod. This overwrites 606the value stored in the prefs, but is overwritten by the command line 607argument "-m" or "--mountpoint". 608 609GTKPOD_DF_COMMAND: Only used on systems without statvfs(). Defines the 610"df" command to be used for probing the free space on the iPod 611including command line arguments. Default is "df -k -P". On some 612systems it may be necessary to remove the "-P" option. The mount point 613is added to this command line automatically. You can switch off calls 614to df by setting this environment variable to an empty string. 615 616 617 618*--------------------------------------------------* 619| | 620| Icons for window managers | 621| | 622*--------------------------------------------------* 623 624Should you require an icon for your window manager you can use those 625provided in $(datadir)/pixmaps (usually 626/usr/local/share/gtkpod/pixmaps or 627/usr/share/gtkpod/pixmaps). 628 629Currently the following files are available: 630 631 gtkpod-icon-32.png 632 gtkpod-icon-32x32.png 633 gtkpod-icon-32x32-2.png 634 gtkpod-icon-48.png 635 gtkpod-icon-48x48.png 636 gtkpod-icon-64x64.png 637 638 639*--------------------------------------------------* 640| | 641| Connecting iPod to a Linux box | 642| (kernel 2.6.6) | 643| (should also work with earlier 2.6 kernels) | 644| | 645*--------------------------------------------------* 646 647This describes how to set up the iPod together with the automounter in 648kernel V2.6.6 (some minor changes in the kernel configuration may be 649necessary for older V2.6 versions). 650 6511) It appears to be possible to use HFS-formatted (Apple) 652 iPods. However, this short guide assumes you have a Windows 653 (VFAT) iPod. For conversion from HFS to VFAT please see 654 655 http://www.blinkenlights.ch/gnupod/gnupod.html#SEC6 656 6572) I'm using the following kernel configuration options (I'm only 658 using FireWire -- so the USB options are just educated 659 guesses. Please let me know if it works). 660 661 I'm not using modules, simply because what's compiled in can't fail 662 loading. 663 664 * General Setup -> Support for hot-pluggable devices - y 665 * Device Drivers -> SCSI device support - y 666 * -> SCSI device support -> SCSI disk support - y 667 * -> SCSI device support -> SCSI generic support - y 668For FireWire: 669 * -> IEEE1394 (FireWire) support - y 670 * -> IEEE1394 (FireWire) support -> OHCI-1394 support - y 671 * -> IEEE1394 (FireWire) support -> SBP-2 support - y 672For USB: 673 * -> USB support -> Support for Host-side USB - y 674 * -> EHCI HCD support - y 675 * -> OHCI HCD support - y 676 * -> UHCI HCD support - y 677 * -> USB Mass Storage support - y 678For USB and FireWire: 679 * Filesystems -> DOS/FAT/NT Filesystems - y 680 * -> DOS/FAT/NT Filesystems -> VFAT fs support - y 681 * -> Kernel automounter version 4 support - y 682 * -> Native Language Support 683 * -> Codepage 437 (CONFIG_NLS_CODEPAGE_437) 684 * -> NLS ISO 8859-1 (CONFIG_NLS_ISO8859_1) 685 686 687 688(for iPods formatted with the HFS filesystem choose 689 * Filesystems -> Miscellaneous filesystems 690 -> Apple Extended HFS filesystem support) 691 692At least for the new 4Gs and iPod minis you should _disable_ 693(CONFIG_EFI_PARTITION, see Troubleshooting for more information): 694 * File Systems -> Partition Types -> Advanced Partition Selection 695 -> EFI GUID Partition support 696 6973) You need to install the following external packages: 698 699 hotplug and udev (http://linux-hotplug.sourceforge.net/) 700 autofs (ftp.kernel.org:/pub/linux/daemons/autofs) 701 702 Most likely packages are available for your distribution. 703 7044) Write rules for udev (/etc/udev/udev.rules, add at the beginning) 705 to recognize your iPod automatically (mind the spaces within 706 "iPod...", and be aware that some distributions require a double 707 equal after the BUS keyword (BUS=="scsi"...)): 708 709BUS="scsi", SYSFS{model}="iPod ", KERNEL="sd?2", NAME="%k", SYMLINK="ipod" 710 711 This will map /dev/sd?2 to /dev/ipod everytime you plug in your 712 iPod. That even works if you own more than one USB/Firewire device 713 that shows up as a harddisk, independent of the order in which you 714 connect the devices. 715 716 (You need to replace "sd?2" with "sd?1" (or maybe just "sd?") for 717 HFS formatted iPods.) 718 719 For more information on how to write udev rules please refer to 720 http://www.gamingclones.com/Howtos/udevrules.html. That document 721 gives an easy-to-understand introduction 722 7235) Set up autofs to automatically mount the iPod when you access it 724 and unmount it after 2 seconds of inactivity. In /etc/auto.master 725 add: 726 727/var/autofs/removable /etc/auto.removable --timeout=2,sync,nodev,nosuid,gid=autofs,umask=007 728 729 Adjust the gid,umask (and uid) values to whatever you need -- in this 730 example all users in the group "autofs" have read/write access, and 731 I have added all users that may access the iPod to the autofs group. 732 733 In /etc/auto.removable add 734 735ipod -fstype=vfat :/dev/ipod 736 737 (Obviously you need to change the filesystem type from 'vfat' to 738 'hfsplus' when you use an HFS formatted iPod.) 739 740 Then simply add a link from /mnt/ipod: 741 742 ln -s /var/autofs/removable/ipod /mnt/ipod 743 744 745Now your system is configured to mount the iPod every time you access 746/mnt/ipod and to unmount it again after two seconds of inactivity. You 747won't have to worry about doing mounting/unmouting yourself any more. 748 749 750 751*--------------------------------------------------* 752| | 753| Connecting iPod to a Linux box (IEEE 1394) | 754| (kernel 2.4.21) | 755| (may also work with 2.4.20, but I didn't try) | 756| (instructions for 2.4.20 can be found below) | 757| | 758*--------------------------------------------------* 759 7601) You need a Windows iPod. See e.g. 761 762http://www.blinkenlights.ch/gnupod/gnupod.html#SEC6 763 764for information about how to convert your mac iPod to a windows iPod. 765 766Alternatively, I have received a report that Alan Cox's patches 767(2.4.21-rc8-ac1, but 2.4.21-ac1 should work as well) include hfsplus 768support. That should allow you to use hfs formatted iPods. But beware: 769hfsplus support is still beta. 770 7712) Get kernel source and configure 772Needed configuration: 773 774 * Code maturity level options - y 775 * SCSI support - y 776 * SCSI disk support - y 777 * IEEE1394 (FireWire)/IEEE 1394 (FireWire) support (Experimental) - y 778 * OHCI-1394 support - y 779 * SBP-2 support - m (important to use module -- if someone finds 780 out how to use hotplug with sbp2 compiled in, let me know) 781 (With 2.6.1 compiling sbp2 in seems to work fine.) 782At least for the new 4Gs and iPod minis you should _disable_ 783(CONFIG_EFI_PARTITION, see Troubleshooting for more information): 784 * File Systems -> Partition Types -> Advanced Partition Selection 785 -> EFI GUID Partition support 786 * -> Native Language Support 787 * -> Codepage 437 (CONFIG_NLS_CODEPAGE_437) 788 * -> NLS ISO 8859-1 (CONFIG_NLS_ISO8859_1) 789 790 7913) Create /mnt/ipod: 792 793 mkdir /mnt/ipod 794 7954) Add a line to /etc/fstab. You should edit uid to match your user 796 id. Also, /dev/sda2 may not be appropriate, if you have other scsi 797 devices. 798 799/dev/sda2 /mnt/ipod vfat rw,user,noauto,noatime,errors=remount 0 0 800 801 (For HFS this line should read 802 803/dev/sda /mnt/ipod hfsplus rw,user,noauto,exec 0 0 804 805 please note that it's just '/dev/sda') 806 807 808NOTE: Some users have had problems with newer versions of mount (newer than 809mount-2.11h) The following fstab entry might work better for you. 810 811/dev/sda2 /mnt/ipod vfat rw,user,noauto,noatime,shortname=winnt 0 0 812 8135) Install the hotplug utilities 814 (http://linux-hotplug.sourceforge.net/, debian package: 'hotplug') 815 816 (If you don't want to use the hotplug utilities, you must call the 817 rescan-scsi-bus.sh (see below) by hand after loading the sbp2 818 module. This is different from 2.4.20.) 819 8205a) Add the ieee1394 hotplug support (described at 821 http://www.linux1394.org/faq.html#hotplug): 822 823 - copy ieee1394.agent to /etc/hotplug/ from 824 http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/linux-hotplug/admin/etc/hotplug/ 825 - mkdir /etc/hotplug/ieee1394 826 - create /etc/hotplug/ieee1394/sbp2: 827 #!/bin/bash 828 if [ "${ACTION}" = "add" ]; then 829 . /etc/hotplug/ieee1394/rescan-scsi-bus.sh 830 else 831 . /etc/hotplug/ieee1394/rescan-scsi-bus.sh -r 832 fi 833 - chmod +rx /etc/hotplug/ieee1394/sbp2 834 - copy rescan-scsi-bus.sh to /etc/hotplug/ieee1394 from 835 http://www.garloff.de/kurt/linux/rescan-scsi-bus.sh 836 - just to be sure: restart hotplug: 837 /etc/init.d/hotplug restart 838 8396) Connect your iPod to your computer and wait until you see something 840 like the following on your system log (you can use the 'dmesg' 841 command to check). 842 843Jun 15 17:13:53 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023 844Jun 15 17:13:55 hatarakibachi kernel: ieee1394: Node 01:1023 changed to 00:1023 845Jun 15 17:13:57 hatarakibachi kernel: ieee1394: sbp2: Logged into SBP-2 device 846Jun 15 17:13:57 hatarakibachi kernel: ieee1394: Device added: Node[00:1023] GUID[000a2700020680b5] [Apple Computer, Inc.] 847Jun 15 17:13:57 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023 848Jun 15 17:13:57 hatarakibachi kernel: scsi singledevice 0 0 0 0 849Jun 15 17:13:57 hatarakibachi kernel: Vendor: Apple Model: iPod Rev: 1.30 850Jun 15 17:13:57 hatarakibachi kernel: Type: Direct-Access ANSI SCSI revision: 02 851Jun 15 17:13:57 hatarakibachi kernel: Attached scsi removable disk sda at scsi0, channel 0, id 0, lun 0 852Jun 15 17:13:57 hatarakibachi kernel: SCSI device sda: 39062520 512-byte hdwr sectors (20000 MB) 853Jun 15 17:13:57 hatarakibachi kernel: sda: test WP failed, assume Write Enabled 854Jun 15 17:13:58 hatarakibachi kernel: sda: sda1 sda2 855Jun 15 17:13:58 hatarakibachi kernel: scsi singledevice 0 0 1 0 856... 857 8587) Mount the iPod hard drive 859 860 mount /mnt/ipod 861 8628) do whatever you need to do (e.g. start gtkpod, see below) 863 8649) Unmount the iPod: 865 866 umount /mnt/ipod 867 86810) Unload the module sbp2 (as most likely as root): 869 870 rmmod sbp2 871 87211) Disconnect the iPod from your computer (ignore the "Do not 873 disconnect" message -- as long as you wait for the 'unmount' to 874 command to finish properly, everything should be fine). 875 876 877 878*--------------------------------------------------* 879| | 880| Connecting iPod to a Linux box using IEEE 1394 | 881| (kernel 2.4.20) | 882| (connecting to 2.4.21 seems to work slightly | 883| differently -- see above) | 884| | 885*--------------------------------------------------* 886 8871) You need a Windows iPod. See e.g. 888 889http://www.blinkenlights.ch/gnupod/gnupod.html#SEC6 890 891for information about how to convert your mac iPod to a windows iPod. 892 893Alternatively, I have received a report that Alan Cox's patches 894(2.4.21-rc8-ac1, but 2.4.21-ac1 should work as well) include hfsplus 895support. That should allow you to use hfs formatted iPods. But beware: 896hfsplus support is still beta. 897 8982) Get kernel source and configure 899Needed configuration: 900 901 * Code maturity level options - y 902 * SCSI support - y 903 * SCSI disk support - m 904 * IEEE1394 (FireWire)/IEEE 1394 (FireWire) support (Experimental) - y 905 * OHCI-1394 support - y 906 * SBP-2 support - m 907At least for the new 4Gs and iPod minis you should _disable_ 908(CONFIG_EFI_PARTITION, see Troubleshooting for more information): 909 * File Systems -> Partition Types -> Advanced Partition Selection 910 * -> EFI GUID Partition support 911 * -> Native Language Support 912 * -> Codepage 437 (CONFIG_NLS_CODEPAGE_437) 913 * -> NLS ISO 8859-1 (CONFIG_NLS_ISO8859_1) 914 9153) Create /mnt/ipod: 916 917 mkdir /mnt/ipod 918 9194) Add a line to /etc/fstab. You should edit uid to match your user 920 id. Also, /dev/sda2 may not be appropriate, if you have other scsi 921 devices. 922 923/dev/sda2 /mnt/ipod vfat rw,user,noauto,noatime 0 0 924 925 (For HFS this line should read 926 927/dev/sda /mnt/ipod hfsplus rw,user,noauto,exec 0 0 928 929 please note that it's just '/dev/sda') 930 931 932NOTE: Some users have had problems with newer versions of mount (newer than 933mount-2.11h) The following fstab entry might work better for you. 934 935/dev/sda2 /mnt/ipod vfat rw,user,noauto,noatime,shortname=winnt 0 0 936 937NOTE: You can add ",umask=0" to the options to make the iPod 938readable/writable for all users. 939 9405) Connect your iPod to your computer and wait until you see something 941 like the following on your system log (you can use the 'dmesg' 942 command to check). 943 944Nov 28 21:58:06 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023 945Nov 28 21:58:09 hatarakibachi kernel: ieee1394: Node 01:1023 changed to 00:1023 946Nov 28 21:58:12 hatarakibachi kernel: ieee1394: NodeMgr: hotplug policy returned -2 947Nov 28 21:58:12 hatarakibachi kernel: ieee1394: Device added: Node[00:1023] GUID[000a2700020680b5] [Apple Computer, Inc.] 948Nov 28 21:58:12 hatarakibachi kernel: ieee1394: Node 00:1023 changed to 01:1023 949 9506) Load the sbp2 module (most likely as root): 951 952 modprobe sbp2 953 954 You should see something like the following on your system log: 955 956Nov 28 21:58:38 hatarakibachi kernel: ieee1394: sbp2: Logged into SBP-2 device 957Nov 28 21:58:38 hatarakibachi kernel: scsi0 : IEEE-1394 SBP-2 protocol driver (host: ohci1394) 958Nov 28 21:58:38 hatarakibachi kernel: $Rev$ James Goodwin <jamesg@filanet.com> 959Nov 28 21:58:38 hatarakibachi kernel: SBP-2 module load options: 960Nov 28 21:58:38 hatarakibachi kernel: - Max speed supported: S400 961Nov 28 21:58:38 hatarakibachi kernel: - Max sectors per I/O supported: 255 962Nov 28 21:58:38 hatarakibachi kernel: - Max outstanding commands supported: 8 963Nov 28 21:58:38 hatarakibachi kernel: - Max outstanding commands per lun supported: 1 964Nov 28 21:58:38 hatarakibachi kernel: - Serialized I/O (debug): no 965Nov 28 21:58:38 hatarakibachi kernel: - Exclusive login: yes 966Nov 28 21:58:38 hatarakibachi kernel: Vendor: Apple Model: iPod Rev: 1.21 967Nov 28 21:58:38 hatarakibachi kernel: Type: Direct-Access ANSI SCSI revision: 02 968Nov 28 21:58:38 hatarakibachi kernel: Attached scsi removable disk sda at scsi0, channel 0, id 0, lun 0 969Nov 28 21:58:38 hatarakibachi kernel: SCSI device sda: 39062520 512-byte hdwr sectors (20000 MB) 970Nov 28 21:58:38 hatarakibachi kernel: sda: test WP failed, assume Write Enabled 971Nov 28 21:58:39 hatarakibachi kernel: sda: sda1 sda2 972 9737) Mount the iPod hard drive 974 975 mount /mnt/ipod 976 9778) do whatever you need to do (e.g. start gtkpod, see below) 978 9799) Unmount the iPod: 980 981 umount /mnt/ipod 982 98310) Unload the module sbp2 (as most likely as root): 984 985 rmmod sbp2 986 98711) Disconnect the iPod from your computer. 988 989 990*--------------------------------------------------* 991| | 992| Connecting iPod to a Linux box (USB) | 993| | 994*--------------------------------------------------* 995 996I don't have much information about this so far (I don't own a third 997generation iPod). Please help me to fill in the gaps. 998 999Stephen Drye sent me the following note: 1000 1001"I've figured out how to get a USB-connected iPod recognized...: 1002 1003The trick to it is that you have to 1004 1005- plug the iPod in 1006 1007- it'll fail to be recognized by the SCSI subsystem 1008 1009- now, even though your ipod says not to, unplug the USB cord and 1010 immediately plug it back in. 1011 1012- since the iPod's hdd was already spun up, the SCSI subsystem now 1013 recognizes it and mounts it as /dev/sda 1014 1015- You can then mount /dev/sda2 to /mnt/ipod as normal." 1016 1017On the other hand: with my 4G iPod under 2.6.9 and 2.6.10 I never had 1018any problem whatsoever getting the iPod to work. With IEEE it was 1019awful (would work some times, would not some other time). 1020 1021 1022*----------------------------------* 1023| | 1024| Sick of loading the sbp2 | 1025| modules by hand? | 1026| | 1027| Corey Donohoe | 1028| <atmos at atmos dot org> | 1029| March 22nd 2003 | 1030| | 1031*----------------------------------* 1032 1033Sick of loading the sbp2 modules by hand every time you want to use your 1034ipod? Are you sick of mounting it too? Using sudo gtkpod can make manually 1035interacting with the ipod filesystem a thing of the past. Note that you 1036should have your ipod working with gtkpod before attempting this automated 1037method, see the README that came with gtkpod in order to get things up and 1038running. 1039 1040Here's a brief example of how I'm using gtkpod now in 8 easy steps. 1041 1042(Remark: the hotplug facility of new kernels can also load and unload 1043the sbp2 module for you.) 1044 1045/**********/ 1046 * Step 1 * 1047/**********/ 1048Using sudo allow users to load/remove the sbp2 module 1049Example /etc/sudoers 1050------------------------------- Begin Here --------------------------------- 1051 1052# Cmnd alias specification 1053Cmnd_Alias IPOD=/sbin/modprobe sbp2 sbp2_force_inquiry_hack=1, /sbin/rmmod sbp2 1054# User privilege specification 1055atmos ALL=(ALL) ALL 1056atmos ALL= NOPASSWD : IPOD 1057 1058------------------------------- End Here ----------------------------------- 1059I use the force inquiry hack cause I have an older iPod, if you normally can 1060get by with /sbin/modprobe sbp2 then ignore the inquiry hack stuff. Note 1061that explicitly specifying which module to probe/remove keeps the user from 1062being able to add/remove arbitrary modules. This allows us to keep gtkpod 1063as a user process, and execute commands the user wouldn't usually have 1064enough rights to. 1065 1066/**********/ 1067 * Step 2 * 1068/**********/ 1069Add a line similar to the below to your /etc/fstab, this will enable users 1070to mount the ipod with read/write capabilities. Example line assumes your 1071ipod mount point is /mnt/ipod and your ipod is detected as /dev/sda 1072 1073------------------------------- Begin Here --------------------------------- 1074/dev/sda2 /mnt/ipod vfat rw,user,noauto 0 0 1075------------------------------- End Here ----------------------------------- 1076 1077 1078/**********/ 1079 * Step 3 * 1080/**********/ 1081Then setup your /etc/gtkpod/gtkpod.in file to load the module when gtkpod is 1082started. 1083Example /etc/gtkpod/gtkpod.in 1084------------------------------- Begin Here --------------------------------- 1085 1086sudo /sbin/modprobe sbp2 sbp2_force_inquiry_hack=1 1087 1088------------------------------- End Here ----------------------------------- 1089 1090/**********/ 1091 * Step 4 * 1092/**********/ 1093 1094Then setup your /etc/gtkpod/gtkpod.out file to unload the module when gtkpod 1095is exited. 1096Example /etc/gtkpod/gtkpod.out 1097------------------------------- Begin Here --------------------------------- 1098 1099sudo /sbin/rmmod sbp2 1100 1101------------------------------- End Here ----------------------------------- 1102 1103/**********/ 1104 * Step 5 * 1105/**********/ 1106Then enable ipod automounting in the gtkpod prefs(in the misc tab). 1107 1108/**********/ 1109 * Step 6 * 1110/**********/ 1111You're now ready to use gtkpod in a much nicer fashion. Start by 1112plugging in your ipod. You should get a check mark with "OK to disconnect" 1113displayed on your ipod. 1114 1115/**********/ 1116 * Step 7 * 1117/**********/ 1118Start gtkpod, your ipod should be accessible (i.e. autoimport should work) 1119A "Do Not Disconnect" message is displayed on your ipod while gtkpod is 1120running. 1121 1122/**********/ 1123 * Step 8 * 1124/**********/ 1125After you exit gtkpod, the "OK to disconnect" message should be displayed 1126again. It's ok to unplug your ipod now. 1127 1128Good Luck. 1129 1130 1131 1132*----------------------------------* 1133| | 1134| Known bugs | 1135| | 1136*----------------------------------* 1137 1138 1139- Display of large number of tracks is awfully slow (mainly because of 1140 the use of the standard GTK2 tree views) -> deactivate "Automatically 1141 select "All" in first filter tab" and/or deactivate "Automatically 1142 select master playlist". You could also "block the display" to speed 1143 up the display update. Further, decreasing the window size 1144 considerably speeds up the display. 1145 1146 I also want to point out that updating the info window takes up a 1147 considerable amount of time. Update may become more intelligent in 1148 the future -- until then close the info window for more speed. 1149 1150- When changing selections in the filter tabs while importing the 1151 iTunesDB, sometimes the interface freezes. I tried to track this 1152 problem down but only found out that gtk+ does not return control 1153 back to gtkpod. Selecting the "All" filter tabs seems to unfreeze the 1154 interface again. 1155