/usr/share/gtkpod/doc/gtkpod.xml is in gtkpod-data 2.1.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 | <?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book id="gtkpod">
<bookinfo>
<title>The gtkpod Manual</title>
<abstract role="description">
This is the user manual for gtkpod, a GTK+ iPod manager.
</abstract>
<subtitle>This is the user manual for gtkpod, a GTK+ iPod manager.</subtitle>
<copyright>
<year>2007</year>
<holder>gtkpod wiki contributors</holder>
</copyright>
<legalnotice>
<title>Legal Notices</title>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License (GFDL), Version 1.2 or any later version published
by the Free Software Foundation with no Invariant Sections,
no Front-Cover Texts, and no Back-Cover Texts. You can find
a copy of the GFDL at this <ulink type="help"
url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
distributed with this manual.
</para>
</legalnotice>
</bookinfo>
<chapter id="getting-started">
<title>Getting started</title>
<sect1 id="hooking-up-the-ipod">
<title>Hooking up the iPod</title>
<sect2>
<title>Introduction</title>
<para>The iPod has largely been an USB device yet there are older models of iPods that used IEEE1394/ / firewire for their connection interface. Historically, it took something of an effort for linux to recognise the iPod model correctly. However, this situation has greatly improved in recent times where it is now possible to simply plug the iPod into a USB port and have your distro recognise it straight off.</para>
<para>gtkpod first and foremost relies on the successful mounting of a recognised iPod. Thus, if the iPod cannot be mounted then gtkpod is NOT going to do it for you! Thus, before firing up gtkpod make sure you can see the filesystem of your iPod at its desginated mount point, eg. /media/ipod.</para>
</sect2>
<sect2>
<title>Using udev</title><para>For linux distros installed with hal and udev, plugging an ipod in and mounting it becomes a trivial exercise. A device node will normally be created under /dev, eg. /dev/sdc.</para><para>Using udev rules it is possible to "play" and refine this device node to reflect personal requirements. For example, including these udev rules will allow 2 ipods to be loaded at the same time without interfering with one another:</para><programlisting>
<![CDATA[#80GB IPOD
SUBSYSTEMS=="usb", ATTRS{serial}=="000A2700XXXXXXXX", KERNEL=="sd?2", \
NAME="80gbipod", MODE="0664", OPTIONS="last_rule"
#4GB IPOD NANO
SUBSYSTEMS=="usb", ATTRS{serial}=="000A2700YYYYYYYY", KERNEL=="sd?2", \
NAME="4gbnano", MODE="0664", OPTIONS="last_rule"]]>
</programlisting>
<para>By including the test against the serial number it is possible to uniquely identify an individual iPod and load it appropriately.</para>
</sect2>
<sect2>
<title>Mounting</title>
<para>
The result of this is that the ipod will be located on a device node and this can be mounted manually using the command (performed as root):
</para>
<programlisting>mount /dev/sdc2 /media/ipod</programlisting>
<para>This assumes an iPod is loaded onto the device /dev/sdc and that it is a 2 partition model. It seems that post-2006, iPods have become 1-partition items.</para>
<para>However, it should be noted that moden window managers such as gnome and kde take on the responsibility of managing connected devices. Thus, the result of connecting an iPod will be an icon on the desktop which will either be mounted automatically or can be mounted by the user with a click of the mouse on a popup menu.</para>
</sect2>
<sect2>
<title>Environment variables</title>
<para>
The following environment variables can be set if needed:
<itemizedlist>
<listitem>
IPOD_MOUNTPOINT: Defines the mountpoint of the iPod. This overwrites the value stored in the preferences, but is overwritten by the command line argument "-m" or "--mountpoint".
</listitem>
<listitem>
GTKPOD_DF_COMMAND: Only used on systems without statvfs(). Defines the "df" command to be used for probing the free space on the iPod including command line arguments. Default is "df -k -P". On some systems it may be necessary to remove the "-P" option. The mount point is added to this command line automatically. You can switch off calls to df by setting this environment variable to an empty string.
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
<sect1 id="setting-ipod-properties">
<title>Setting iPod properties</title>
<sect2 id='preferences-file'>
<title id='preferences-file-title'>Preferences File</title>
<para>On startup gtkpod will read the preferences from ~/.gtkpod/prefs (or /etc/gtkpod/prefs if the former doesn't exist). The file is created if preferences are changed using the Preference window.
</para>
</sect2>
<sect2 id='changing-preferences'>
<title id='changing-preferences-title'>Changing Preferences</title>
<para>Preferences can be changed by opending the Preference window. This is displayed by clicking on Edit > Edit Preferences or hitting Ctrl+P.
</para>
</sect2>
<sect2 id='duplicate-detection'>
<title id='duplicate-detection-title'>Duplicate Detection</title>
<para>You can instruct gtkpod (in the prefs window) to use file-size-dependent SHA1 checksums to prevent the same file from being copied to your iPod twice.
</para>
<para>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.
</para>
</sect2>
<sect2 id='extended-information-file'>
<title>Extended Information File</title>
<para>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
<itemizedlist>
<listitem>
<para>SHA1 hash
</para>
</listitem>
<listitem>
<para>filename in the locale's encoding
</para>
</listitem>
<listitem>
<para>filename in UTF8 encoding
</para>
</listitem>
<listitem>
<para>hostname where the file was added (not used for anything yet)
</para>
</listitem>
<listitem>
<para>filename of an associated converted file (for example an .mp3 for a .flac file)
</para>
</listitem>
<listitem>
<para>if the file is present in the local database a reference to there
</para>
</listitem>
<listitem>
<para>in order for playcounts to work on the local database as well
</para>
</listitem>
<listitem>
<para>last modification time
</para>
</listitem>
<listitem>
<para>the charset used for the file when adding it
</para>
</listitem>
</itemizedlist>
</para>
<para>
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.
</para>
<para>Using an extended information file will considerably speed up the import of an existing iTunes database when using duplicate detection,
since the SHA1 checksums do not have to be re-calculated.
</para>
<para>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.
</para>
</sect2>
<sect2 id='encoding-of-id-three-tags-op-charsets-cp'>
<title id='encoding-of-id-three-tags-op-charsets-cp-title'>Encoding of ID3 tags (charsets)</title>
<para>If you use correctly written unicode ID3V2 tags you don't have to worry about the charset setting. Otherwise you must specify the charset 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.
</para>
<para>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.
</para>
<para>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 recognized 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.
</para>
<para>gtkpod will recognize ID3V2 tags encoded in unicode automatically and ignore your charset setting when necessary.
</para>
</sect2>
<sect2 id='extracting-tag-information-from-the-filename'>
<title id='extracting-tag-information-from-the-filename-title'>Extracting tag information from the filename</title>
<para>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 filenames are constructed.
</para>
<para>For filenames like
<filename>code</filename>
music/new/latin1/alan_jackson - drive/01 drive_for_daddy_gene.mp3
<filename>code</filename>
you could use
<filename>code</filename>
%a - %A/%T %*.mp3
<filename>code</filename>
to extract artist, album, track number and title.
</para>
<para>The following character sequences are supported:
<itemizedlist>
<listitem>
<para>%t: title
</para>
</listitem>
<listitem>
<para>%a: artist
</para>
</listitem>
<listitem>
<para>%A: album
</para>
</listitem>
<listitem>
<para>%c: composer
</para>
</listitem>
<listitem>
<para>%t: title
</para>
</listitem>
<listitem>
<para>%g: genre
</para>
</listitem>
<listitem>
<para>%T: track number
</para>
</listitem>
<listitem>
<para>%C: CD number
</para>
</listitem>
<listitem>
<para>%*: placeholder, ignore data
</para>
</listitem>
<listitem>
<para>%%: the character '%'
</para>
</listitem>
</itemizedlist>
</para>
<para>
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.
</para>
</sect2>
<sect2 id='startup-and-shutdown-scripts'>
<title id='startup-and-shutdown-scripts-title'>Startup and Shutdown Scripts</title>
<para>During startup and after reading the preferences file, gtkpod will try to execute
<programlisting>~/.gtkpod/gtkpod.in or /etc/gtkpod/gtkpod.in</programlisting>
Just before exiting the program, gtkpod will try to execute
<programlisting>~/.gtkpod/gtkpod.out or /etc/gtkpod/gtkpod.out</programlisting>
Thus, extra arguments can be entered into these scripts and gtkpod will run them. An example of this could be uploading data to last.fm.
</para>
</sect2>
</sect1>
<sect1 id="troubleshooting-faq">
<title>Troubleshooting FAQ</title>
<sect2 id='contents:'>
<title id='contents:-title'>Contents:</title>
<itemizedlist>
<listitem>
<para>My iPhone or iTouch doesnt have a USB connection. How can I mount it on my linux box?
</para>
</listitem>
<listitem>
<para>My iPod is an iPhone, iTouch, Classic or nano3g. My tunes show up in gtkpod but I see nothing on the iPod when I eject?
</para>
</listitem>
<listitem>
<para>Installed libmp4v2 or libgpod from source to /usr/local/lib, but gtkpod is unable to locate libmp4.so.0 or libgpod.so.0
</para>
</listitem>
<listitem>
<para>Files copied to gtkpod but they don't appear in the database (0.80, Tony Williams)
</para>
</listitem>
<listitem>
<para>Filenames on the iPod appear in DOS 8.3 format and syncing to the iPod is not working as expected.
</para>
</listitem>
<listitem>
<para>./autogen.sh does not work
</para>
</listitem>
<listitem>
<para>The following error message is displayed when accessing the device (Markus Gaugusch, Justin Thiessen):
</para>
<programlisting><![CDATA[** ieee1394: sbp2: aborting sbp2 command
** Test Unit Ready 00 00 00 00 00]]>
</programlisting>
</listitem>
<listitem>
<para>The following error message is displayed when accessing the device (Ingo Reimann)
</para>
<programlisting><![CDATA[** usb-storage: Attempting to get CSW...
** usb-storage: usb_stor_bulk_transfer_buf: xfer 13 bytes
** usb-storage: Status code -75; transferred 0/13
]]>
</programlisting>
</listitem>
<listitem>
<para>When connecting an iPod via USB to a 2.6 kernel machine the iPod will be recognized but not work correctly. In /var/log/messages you'll see the a bunch of "Buffer I/O error on device sd?" when connecting the iPod (Jonas Bergler, Kevin Venkiteswaran)
</para>
</listitem>
<listitem>
<para>SHUFFLE won't play music after reformatting (Mark Davis)
</para>
</listitem>
<listitem>
<para>Calendar entries mixed up
</para>
</listitem>
<listitem>
<para>m4a files created by faac cannot be added by gtkpod (gentoo)
</para>
</listitem>
<listitem>
<para>gtkpod crashes when reading the iTunesDB (Fedora)
</para>
</listitem>
<listitem>
<para>Problems connecting the iPod to Solaris/SPARC
</para>
</listitem>
</itemizedlist>
<para>My iPhone or iTouch doesnt have a USB connection. How can I mount it on my linux box?
</para>
<para>Solution:
</para>
<para>The iPhone or iTouch, at present has to be mounted using sshfs.
</para>
<para>My iPod is an iPhone, iTouch, Classic or Nano3g. My tunes show up in gtkpod but I see nothing on the iPod when I eject?
</para>
<para>Solution:
</para>
<para>This is to do with requiring your iPod model number in a sysinfo file located on the iPod. Please see here for details.
</para>
<para>Installed libmp4v2 or libgpod from source to /usr/local/lib, but gtkpod is unable to locate libmp4.so.0 or libgpod.so.0?
</para>
<para>Solution:
</para>
<para>If you install to /usr/local/lib please don't forget to add the path to LD_LIBRARY_PATH:
</para>
<programlisting><![CDATA[LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
export LD_LIBRARY_PATH]]>
</programlisting>
<para>You can add those lines to your ~/.bashrc or add it globally to
/etc/profile.
</para>
<para>Files copied to gtkpod but they don't appear in the database (0.80, Tony Williams)?
</para>
<para>I'm having a problem that I wonder if you've seen. I've setup gtkpod. launch it and add files. I can hear the ipod harddrive spin up. If I go onto the ipod directly I can see the space being used and can even see the new files on the ipod. However the ipod interface doesn't show the new files and gtkpod keeps telling me that there are orphaned files.
</para>
<para>Solution:
</para>
<para>I finally figured out the problem. In my fstab I had the filesystem set to 'auto' and it was mounting as msdos instead of vfat. I specified vfat in fstab and voila! I'm a happy happy man.
</para>
<para>Filenames on the iPod appear in DOS 8.3 format and syncing to the iPod is not working as expected?
</para>
<para>Solution:
You need to specify "vfat" as file system type. How to do that depends on which way you use to mount the iPod -- see the README file for more details.
</para>
<para>./autogen.sh does not work?
</para>
<para>Solution:
</para>
<para>A ubuntu user has reported that he had to set
</para>
<programlisting>ACLOCAL_FLAGS=" -I /usr/share/aclocal/"
</programlisting>
<para>in order to get ./autogen.sh to work.
</para>
<para>The following error message is displayed when accessing the device:
</para>
<programlisting><![CDATA[ieee1394: sbp2: aborting sbp2 command
Test Unit Ready 00 00 00 00 00 ]]>
</programlisting>
<para>Solution:
</para>
<para>(Markus Gaugusch):
It is possible that hotplug and the "sg" support are not working well together. Try disabling "sg" support in the kernel configuration or
unload the "sg" module if you are using modules.
</para>
<para>(Justin Thiessen):
Forcing the sbp2 module to serialized I/O seems (so far) to have solved the problem.
</para>
<para>Ref.:
<itemizedlist>
<listitem>
http://www.netzwerk-aktiv.com/pub/doc/newsletters/linux1394-user/html/1676.html
</listitem>
<listitem>
http://www.ubuntuforums.org/printthread.php?t=6678
</listitem>
<listitem>
http://66.102.7.104/search?q=cache:Xh_gu43y6w8J:themikecam.com/newmikecam/blog/index.php/geek/2005/+ipod+serialize_io&hl=en
</listitem>
</itemizedlist>
</para>
<para>Looks like the driver is going to be set to default to serialized I/O in kernel 2.6.14, anyways.
</para>
<para>http://linuxtoday.com/developer/2005093001026NWKNDV
</para>
<para>The following error message is displayed when accessing the device
</para>
<programlisting>
<![CDATA[usb-storage: Attempting to get CSW...
usb-storage: usb_stor_bulk_transfer_buf: xfer 13 bytes
usb-storage: Status code -75; transferred 0/13 ]]>
</programlisting>
<para>Solution (by Ingo Reimann):
</para>
<para>I tried to use an iPod Mini with my nforce2-Board, kernel 2.6.14/2.6.15 debian sid and got messages like [above] in dmesg. /dev/sda appeared, but fdisk -l did not show anything
</para>
<para>The solution, that i found in a discussion on http://kerneltrap.org/node/3844 was to unload ehci_hcd.
</para>
<para>When connecting an iPod via USB to a 2.6 kernel machine the iPod wil be recognized but not work correctly. In /var/log/messages you'll see the a bunch of "Buffer I/O error on device sd?" when connecting the iPod (Jonas Bergler, Kevin Venkiteswaran)
</para>
<para>Solution (by "jeffmock"):
</para>
<para>Disable CONFIG_EFI_PARTITION (File Systems -> Partition Types -> Advanced Partition Selection -> EFI GUID Partition support) in your kernel configuration, recompile.
Details can be found at http://www.linuxquestions.org/questions/showthread.php?postid=1197015#post1197015
</para>
<para>Excerpt:
</para>
<para>"This problem could potentially happen with both 2.4 and 2.6 kernels."
</para>
<para>A longer story follows and perhaps someone can come up with a more sensible solution for the long run.
</para>
<para>The iPod looks like a removable disk drive to the host computer. When it is attached to the computer, the mini iPod reports a capacity of 7999488 512-byte sectors (or about 4GB). This turns out to be wrong for whatever reason. The mini iPod only really has 7999376 sectors and it exaggerates by 112 sectors. The other quality of the iPod is that if the computer attempts to read a sector greater than the actual capacity but less than the reported capacity, the iPod will dutifully report an I/O error, but it won't respond to any future requests until you unplug/plug the iPod."
</para>
<para>I followed the kernel recompile instructions for distro, disabled only the CONFIG_EFI_PARTITION option, and things ran perfectly for me afterwards. As indicated above, hopefully a better long-term solution will emerge soon."
</para>
<para>(Jorg Schuler: it seems a patch was introduced in kernel version 2.6.10: "<phil@ipom.com> [PATCH] USB Storage: Add unusual_devs entry for iPod This patch adds an unusual_devs.h entry for the Apple iPod as it reports one too many sectors. The patch was submitted by Avi Kivity <avi@argo.co.il> and re-diffed by me.")
</para>
<para>SHUFFLE won't play music after reformatting
</para>
<para>Solution (by Mark Davis):
</para>
<para>The SHUFFLE seems to care about the volume name which has to be "IPOD". Try to format as (replace /dev/sda1 with the appropriate device file for your SHUFFLE!):
</para>
<programlisting>mkdosfs -F32 -n IPOD /dev/sda1
</programlisting>
<para>Calendar entries mixed up?
</para>
<para>Solution:
</para>
<para>The iPod does not appear to like times specified in UTC (indicated by a trailing 'Z'). KOrganizer seems to do this. If you know how to work around it let me know.
</para>
<para>m4a files created by faac cannot be added by gtkpod (gentoo)?
</para>
<para>Solution:
</para>
<para>There appear to be some versions of faac that do not create 'good' m4a files. The problem could be solved under gentoo by using version 1.24.
In order to make error tracking easier, more detailled error messages are displayed when tracks could not be added for any reason starting with version 0.91-CVS of gtkpod.
</para>
<para>gtkpod crashes when reading the iTunesDB (Fedora)
</para>
<para>Solution:
</para>
<para>It appears that crashes were observed with kernel version 2.6.11-1.35_FC3. An upgrade to 2.6.12-1.1376_FC3 got rid of the problem. This was with gtkpod-0.94.0 and Athlon64 3000+.
</para>
<para>After updating the firmware of a 1st-gen iPod nano**, crashes are also observed with Fedora Core 5, kernel 2.6.20-1.2320.fc5, gtkpod 0.99.4 (which worked with the previous firmware). Downloading, building, and installing gtkpod 0.99.10 and libgpod 0.6.0 solved the problem.
</para>
<para>Problems connecting the iPod to Solaris/SPARC
</para>
<para>Solution:
</para>
<para>Current (as of 2006/03/30) versions of the Solaris pcfs SPARC driver have a bug where the correct filesystem/partition layout may not be
recognized, and this is true for iPods. This prevents the iPod partition from being mounted on Solaris SPARC. In order to work
around this, one must prevent pcfs from detecting the first FAT32 filesystem, forcing it to move on to the second one. This can be done
by changing the filesystem identifier like so:
</para>
<programlisting>
<![CDATA[# dd if=/dev/rdsk/c3t0d0s2 of=/tmp/ipod.orig count=1
# cp /tmp/ipod.orig /tmp/ipod.modified <edit /tmp/ipod.modified and change the first occurance of "FAT32" (at offset 0x52 for me) to something else like "CAT32">
# dd if=/tmp/ipod.modified of=/dev/rdsk/c3t0d0s2 count=1]]>
</programlisting>
</sect2>
</sect1>
<sect1 id="the-sysinfo-file">
<title>The sysinfo file</title>
<para>Starting with the 2007 generation of iPods, libgpod needs an additional configuration step to correctly modify the iPod content. libgpod
needs to know the so-called iPod "firewire id", otherwise the iPod won't recognize what libgpod wrote to it and will behave as if it's empty.
</para>
<sect2 id='the-iphone-and-itouch'>
<title id='the-iphone-and-itouch-title'>The iPhone and iTouch</title>
<sect3 id='global-assumptions-and-scope-of-this-tutorial'>
<title id='global-assumptions-and-scope-of-this-tutorial-title'>Global Assumptions and Scope of this Tutorial</title>
<para>touch_ip -- denotes the IP address that is assigned to your iPod Touch
(e.g. 192.168.0.27).
</para>
<para>touch_media -- denotes the mount point to your iPod Touch (i.e. the
directory the iPod is mounted on).
</para>
<para>To make effective use of the following you have to jailbreak your iPod Touch first (in order to access it via SSH). This document won't go into detail on this topic. One possibility to do this using a computer that runs Microsoft Windows (XP) can be found at:
</para>
<para>http://iphone.cricblogs.com/one-click-ipod-touch-jailbreak-for-windows-by-msbasher/
</para>
</sect3>
<sect3 id='compiling-libgpod-and-gtkpod-op-subversion-versions-cp'>
<title id='compiling-libgpod-and-gtkpod-op-subversion-versions-cp-title'>Compiling libgpod & gtkpod (subversion versions)</title>
<para>
Install and compile libgpod and gtkpod from subversion. See <filename>Compiling and Installing|here</filename> for details.
</para>
<para>Configure libgpod. The '--prefix' option will make sure that is not installed globally but locally within your home directory (note: replace '~' by the absolute path to your home directory):
</para>
<programlisting>~/libgpod$ ./autogen.sh --prefix=~/local
</programlisting>
<para>Otherwise make sure all dependencies are met ('gtk-doc' is a candidate likely to be missing, proper version of automake is another).
</para>
<para>Repeat this process for gtkpod ('PKG_CONFIG_PATH' make sure it builds on the freshly compiled version of libgpod; again, replace '~' by absolute path to your home directory):
</para>
<programlisting>~/gtkpod$ PKG_CONFIG_PATH=~/local/lib/pkgconfig ./autogen.sh --prefix=~/local
</programlisting>
<programlisting>~/gtkpod$ make && make install
</programlisting>
<para>Assuming that everything went well you should be able to start gtkpod:
</para>
<programlisting>~$ LD_LIBRARY_PATH=~/local/lib ~/local/bin/gtkpod
</programlisting>
<para>You won't be able to fully use it at this point so close it for now.
</para>
</sect3>
<sect3 id='determining-the-firewire-guid'>
<title id='determining-the-firewire-guid-title'>Determining the Firewire GUID</title>
<para>Connect your iPod Touch via USB (to your Linux machine) and issue the command:
</para>
<programlisting>sudo lsusb -v | grep -i iSerial
</programlisting>
<para>This should print something similar to this:
</para>
<programlisting><![CDATA[iSerial 3 fd98145617c113dc15ab151601001ff12354b139
[ ... ] ]]>
</programlisting>
<para>The first 16 characters constitute the FirewireGUID, i.e. in this example the FwGUID is:
</para>
<programlisting>fd98 1456 17c1 13dc
</programlisting>
</sect3>
<sect3 id='making-libgpod-aware-of-the-firewire-guid'>
<title id='making-libgpod-aware-of-the-firewire-guid-title'>Making libgpod Aware of the Firewire GUID</title>
<para>Mount your iPod Touch via:
</para>
<programlisting>sudo sshfs root@touch_ip:Media touch_media/ -o allow_other
</programlisting>
<para>Go to the directory 'iTunes_Control' and create (if it does not already exist) a directory named 'Device':
</para>
<programlisting><![CDATA[~/touch_media/iTunesControl$ mkdir Device; cd Device
~/touch_media/iTunesControl/Device$ echo "FirewireGuid: 0xfd98145617c113dc" > SysInfo ]]>
</programlisting>
<para>Test if libgpod is able to retrieve the FWGUID by changing into the 'tests' subdirectory of libgpod's source directory and runnning:
</para>
<programlisting>./test-firewire-id touch_media/
</programlisting>
</sect3>
<sect3 id='gtkpod-revisited'>
<title id='gtkpod-revisited-title'>gtkpod Revisited</title>
<para>With your iPod Touch still mounted start up gtkpod once more:
</para>
<programlisting>~$ LD_LIBRARY_PATH=~/local/lib ~/local/bin/gtkpod
</programlisting>
<para>You should now be able to sync songs to your iPod Touch. After syncing is complete go into "Music" on your iPod Touch: The songs you have just synced won't show up at this point. To make them appear press and hold the "Home"-Button until the springboard is reloaded. Going to "Music" now will show your music.
</para>
<para>Don't forget to unmount it after you're completely done.
</para>
<para>Tutorial compiled by staciemonroe (tobias kreisel gmail com)
</para>
</sect3>
</sect2>
<sect2 id='the-classic-and-nano-three-g'>
<title id='the-classic-and-nano-three-g-title'>The Classic and Nano3g</title>
<para>There are two ways to set up the iPod to make libgpod able to find its firewire id.
</para>
<para>The 1st one is mostly automated. First, make sure you have libsgutils installed before running configure/autogen.sh. If you built libgpod without it, install it and run configure/make/make install. You should now have an ipod-read-sysinfo-extended tool available. Run it with the iPod device path (eg /dev/sda) and the iPod mount point (eg /media/ipod) as arguments. This may require root privileges. ipod-read-sysinfo-extended will read an XMLfile from the iPod and write it as /media/ipod/iPod_Control/Device/SysInfoExtended. See http://ipodlinux.org/Device_Information for more details about the method used.
</para>
<para>Having that file is enough for libgpod to figure out the iPod firewire id.
</para>
<para>The 2nd method requires more manual intervention. First, you need to get your firewire id manually. To do that, run "sudo lsusb -v | grep -i Serial" (without the "") with your iPod plugged in, this should print a 16 character long string like 00A1234567891231. For an iPod Touch, this number will be much longer than 16 characters, the firewire ID is constituted by the first 16 characters. Once you have that number, create/edit /media/ipod/iPod_Control/Device/SysInfo (if your iPod is mounted at /media/ipod). Add to that file the line below:
</para>
<programlisting>FirewireGuid: 0xffffffffffffffff
</programlisting>
<para>(replace ffffffffffffffff with the string you obtained at the previous step and don't forget the trailing 0x before the string)
</para>
<para>Save that file, and you should be all set. Be careful when using apps which lets you manually specify which iPod model you own, they may overwrite that file when you do that. So if after doing that libgpod still seems to write invalid content to the iPod, double-check the content of that SysInfo file to make sure the FirewireGuid line you added isn't gone. If that happens, read it to the end of the file, and make sure libgpod rewrite the iPod content.
</para>
<para>Once that is done, if you compiled libgpod from source, you can test that libgpod can find the firewire ID on your iPod by running
</para>
<programlisting>libgpod/tests/test-firewire-id /ipod/mount/point
</programlisting>
</sect2>
</sect1>
<sect1 id="ipod-file-recovery">
<title>iPod file recovery</title>
<sect2 id='checking-ipod-and-#-three-nine-s-files'>
<title id='checking-ipod-and-#-three-nine-s-files-title'>Checking iPod's Files</title>
<para>For whatever reason -- it may happen that tracks are present in your iTunesDB that are no longer present on the iPod (dangling tracks), or
that tracks are on the iPod but not in the iTunesDB (orphaned tracks). The function "Checking iPod's Files" under the "File" menu will identify both types and take the following actions:
</para>
<sect3 id='orphaned-tracks'>
<title id='orphaned-tracks-title'>Orphaned tracks</title>
<para>A new playlist "[Orphaned]" will be created with all orphaned tracks in it. The only exception are orphaned tracks that would become duplicates (if duplicate detection is activated). Those are marked for deletion with the next sync.
</para>
</sect3>
<sect3 id='dangling-tracks'>
<title id='dangling-tracks-title'>Dangling tracks</title>
<para>These tracks will be marked for deletion with the next sync unless the original PC file is still available. In that case you can have them restored with the next sync.
</para>
</sect3>
</sect2>
<sect2 id='restoring-yourthe-ipod-after-file-system-error-eq-eq-after-a-file-system-error'>
<title id='restoring-yourthe-ipod-after-file-system-error-eq-eq-after-a-file-system-error-title'>After a File System Error</title>
<para>If iPod's file system gets corrupted and you need to reformat your iPod, there is a way to restore the contents semi-automatically if you have been using the "write extended information file" (iTunesDB.ext) options:
<itemizedlist>
<listitem>
<para>If the directory structure on the iPod doesn't exist yet, load the iPod in gtkpod and have it created for you. Then unload the iPod again.
</para>
</listitem>
<listitem>
<para>Copy your backup files in .gtkpod/ (usually iTunesDB and iTunesDB.ext) to your iPod (usually <mountpoint>/iPod_Control/iTunes/
</para>
</listitem>
<listitem>
<para>On the iPod the files must be named iTunesDB and iTunesDB.ext.
</para>
</listitem>
<listitem>
<para>Load the iPod in gtkpod.
</para>
</listitem>
<listitem>
<para>Select the iPod repository and start "Check iPod's files" from the File menu.
</para>
</listitem>
<listitem>
<para>Unload the iPod (or save changes).
</para>
</listitem>
</itemizedlist>
</para>
<para>
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.
</para>
</sect2>
</sect1>
</chapter>
<chapter id="ipod-and-content">
<title>iPod and content</title>
<sect1 id="layout-of-gtkpod">
<title>Layout of gtkpod</title>
<para>
<figure>
<title>Typical layout of gtkpod</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/gtkpod.png"/>
</imageobject>
</mediaobject>
</figure>
</para>
<sect2 id='what-is-a-repository-question'>
<title id='what-is-a-repository-question-title'>What is a Repository?</title>
<para>The left hand pane in gtkpod displays all the repositories that have been created. A repository is (like it implies) a collection of all music tracks, videos and photographs imported into it. They are associated together by a binary XML database file that is the same format as the one that sits on an iPod.
</para>
<para>By default, gtkpod creates a Local repository and a Podcast Repository. These sit on the computer with gtkpod (they can be found under the ~/.gtkpod directory). By having a local repository, it is possible to import tracks into gtkpod without needing to copy them straight to an iPod. This means that if the cover art, for example, needs to be changed then tracks can be managed without even having the iPod plugged in.
</para>
<para>Of course, gtkpod is pointless without accessing an iPod. In the same pane as the local repository, new iPod repositories can be created. These repositories related to iPods by model and mount point. Normally, one repository is sufficient but as you can see below, it is possible to set up multiple iPod repositories on the same computer.
</para>
</sect2>
<sect2 id='repository-pane'>
<title id='repository-pane-title'>Repository Pane</title>
<itemizedlist>
<listitem>
<para>Below each repository, available playlists are listed along with a podcast playlist.
</para>
</listitem>
<listitem>
<para>Under iPods that support photographs, a special dynamic node is created that, when clicked, invokes the photo management tool. This allows straight addition of photos to the iPod as well as management of photo albums on the iPod. **Note:** this photo node cannot be deleted!! There is no point trying as it is created by gtkpod for the sole purpose of displaying the photo management tool.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='menus-and-toolbar'>
<title id='menus-and-toolbar-title'>Menus and Toolbar</title>
<itemizedlist>
<listitem>
<para>Menus across the top provide alternative access to the most frequently used functions.
</para>
</listitem>
<listitem>
<para>Toolbar provides the following actions:
<itemizedlist>
<listitem>
<para>Load iPod(s) -> used for manually mounting any iPods already set up in gtkpod
</para>
</listitem>
<listitem>
<para>Save Changes -> vital button! The Save All function that save any changes made to loaded iPods or the local database.
</para>
</listitem>
<listitem>
<para>Files -> Add individual music files to the selected repository.
</para>
</listitem>
<listitem>
<para>Dirs -> Add any music files located in the selected directories to the selected repository.
</para>
</listitem>
<listitem>
<para>Playlist -> Add a playlist file to the selected repository.
</para>
</listitem>
<listitem>
<para>New PL -> Create a new playlist on the selected repository.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='filter-tabs'>
<title id='filter-tabs-title'>Filter Tabs</title>
<itemizedlist>
<listitem>
<para>The two notebooks above the track display are called "Filter Tabs".
</para>
</listitem>
<listitem>
<para>They allow you to filter which tracks are displayed.
</para>
</listitem>
<listitem>
<para>If you edit an entry in the filter 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.
</para>
</listitem>
<listitem>
<para>So in the image above, choosing "Alice Cooper" on the first filter tab and "Trash" on the second filter tab will only display the tracks from that most excellent of albums (no dissenting opinions required! ;-) ).
</para>
</listitem>
<listitem>
<para>Obviously, these filters can be altered to suit. Selecting ALL on a sort tab effectively removes the filter and displays all tracks.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='track-window'>
<title id='track-window-title'>Track Window</title>
<itemizedlist>
<listitem>
<para>Displays all tracks residing in the selected repository and conforming to the selected filters.
</para>
</listitem>
<listitem>
<para>The columns can be sorted and are interchangeable.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='cover-art-display'>
<title id='cover-art-display-title'>Cover Art Display</title>
<itemizedlist>
<listitem>
<para>Displays the cover art of all albums stored in the repository.
</para>
</listitem>
<listitem>
<para>If no cover art exists for an album then the default "?" image is displayed.
</para>
</listitem>
<listitem>
<para>
See <link linkend="cover-art">the Cover Art section</link> for more information.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="adding-files-and-folders">
<title>Adding files and folders</title>
<sect2 id='getting-tracks-into-gtkpod'>
<title id='getting-tracks-into-gtkpod-title'>Getting Tracks into gtkpod</title>
<itemizedlist>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>You can add directories recursively using "Add Dirs". A directory selection dialogue will appear.
</para>
</listitem>
<listitem>
<para>You can add existing playlists using "Add Playlists"
</para>
</listitem>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>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).
</para>
</listitem>
<listitem>
<para>You can specify which tags to display in the preferences window.
</para>
</listitem>
<listitem>
<para>You can specify (in the prefs window) if the ID3 tags of the corresponding mp3 file(s) should also be updated.
<figure>
<title>The Add Folders dialog</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/add-folders.png"/>
</imageobject>
</mediaobject>
</figure>
</para>
</listitem>
<listitem>
<para>Can add music and video files invidually using Add Files.
</para>
</listitem>
<listitem>
<para>Can add directories of music and video file using Add Directories.
</para>
</listitem>
<listitem>
<para>
The files are imported into the selected <link linkend="what-is-a-repository-question">repository.</link> If the selected repository is an iPod then the files will be copied directly onto it.
</para>
</listitem>
<listitem>
<para>
See <link linkend="supported-file-types">Supported File Types</link> for types of files that can be imported.
</para>
<para>Note: gtkpod is an iPod management tool. Tracks, videos and photographs already need to be on the computer filesystem before they can be imported. If adding a CD is the requirement then it needs to be ripped first. Have a look at:
<itemizedlist>
<listitem>
<para>
<ulink url='http://nostatic.org/grip/'>
<citetitle>grip</citetitle>
</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url='http://live.gnome.org/SoundJuicer'>
<citetitle>Sound Juicer</citetitle>
</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url='http://docs.kde.org/stable/en/kdemultimedia/kaudiocreator/index.html'>
<citetitle>kaudiocreator</citetitle>
</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='dragging-and-dropping'>
<title id='dragging-and-dropping-title'>Dragging and Dropping</title>
<itemizedlist>
<listitem>
<para>Once imported tracks can be dragged around gtkpod, including inbetween repositories, playlists, filter tabs and the track display pane.
</para>
</listitem>
<listitem>
<para>
A drop <emphasis role="italic">onto</emphasis> an existing playlist will add the tracks to that playlist.
</para>
</listitem>
<listitem>
<para>
A drop <emphasis role="italic">between</emphasis> two existing playlists or behind the last playlist will create a new playlist to which the tracks are added.
</para>
</listitem>
<listitem>
<para>The default action for the drop is either move or copy as appears appropriate (e.g. playlists are moved within a database ('local' or 'iPod/Shuffle'), but copied when dragged across different databases). The applicable action is displayed within the drag icon and can be changed by pressing the control key during the drop.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="view-and-edit-track-details">
<title>View and edit track details</title>
<sect2 id='edit-track-details'>
<title id='edit-track-details-title'>Edit Track Details</title>
<para>The Edit Track Details window can be displayed from a couple places.</para>
<itemizedlist>
<listitem>
<para>Select a track from the Track window, right-click and select "Edit Track Details" from the popup.
</para>
</listitem>
<listitem>
<para>Make a selection in any of the categories, eg. Album, Genre, and right-clicking "Edit Track Details will display the window and allow all tracks in that category to be edited.
</para>
</listitem>
<listitem>
<para>Right-clicking "Edit Track Details" from the popup menu on the CoverArt Display displays the window , allowing all tracks belonging to the album to be edited.
</para>
<para>
<figure>
<title>The Edit Track Details dialog</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/edit-track-details.png"/>
</imageobject>
</mediaobject>
</figure>
</para>
</listitem>
<listitem>
<para>The window allows multiple tracks to be edited at the same time. By selecting the "Change all Tracks Simulaneously" check box **BEFORE** making any edits, all the selected tracks can be updated with the new information.
</para>
</listitem>
<listitem>
<para>The coverart can be dragged n dropped on from a web browser in the same way as the Cover Art Display. However, dropping a new cover onto this window will update the cover art of the tracks and not the album! This is an important distinction as it is possible to have different cover art for tracks in the same album! (why anyone would but its possible)!
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='refresh-op-update-cp-track-info-from-file'>
<title id='refresh-op-update-cp-track-info-from-file-title'>Refresh (Update) Track Info From File</title>
<para>
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 <link linkend="extended-information-file">here</link>) is needed.
</para>
<para>"Update" will also re-read the replay-gain tags from disk, if available, and set the soundcheck field. If no replay-gain tag is available, the soundcheck field will be erased. You can also select entries in the filter tab or entire playlists for refresh.
</para>
</sect2>
<sect2 id='synchronize-with-directories'>
<title id='synchronize-with-directories-title'>Synchronize with Directories</title>
<para>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.
</para>
<para>"Synchronize with Dir(s)" 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.
</para>
<para>It will then add all non-existing tracks in those directories and update all existing tracks. The tracks are also added to the currently selected playlist, if they aren't already a member.
</para>
<para>Tracks that have been removed from the directory will only be removed from the iTunesDB if this option is checked in the option dialogue.
</para>
<para>For best results you should also activate duplicate detection. This avoids unnecessary copying of unchanged tracks.
</para>
</sect2>
<sect2 id='volume-normalization'>
<title id='volume-normalization-title'>Volume Normalization</title>
<para>There are two fields in the iTunes Database (iTunesDB) that allow for the adjustment of the volume of an individual track:</para>
<itemizedlist>
<listitem>
<para>the volume field (a signed integer)</para>
</listitem>
<listitem>
<para>the soundcheck field (in dB).
</para>
</listitem>
</itemizedlist>
<para>
The volume is always active, whereas the soundcheck field is only active when you select 'soundcheck' on the iPod. Further, the soundcheck field only affects the earphone output but not the line output of the iPod.
</para>
<para>
gtkpod will set the soundcheck according to the replay-gain tag set in your mp3 file. Newer versions of 'lame' automatically include the replay-gain tag when encoding. In that case the soundcheck field will be filled in when you first import a track.
</para>
<para>If no replay-gain tag is set, you can use the function 'Normalize Volume' to call mp3gain (mp3gain.sourceforge.net) to calculate the gain and write a replay-gain tag. Since this procedure is very time consuming, it is not done automatically during import. You need to install mp3gain in the default path or set the full path in the 'Tools' section of the preferences dialog. If the iPod is connected, the tag is written to the file stored on the iPod.
</para>
<para>At this time "album gain" functionality 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 one of the next versions.
</para>
<para>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.
</para>
<para>Once the replay-gain tag has been read, it is stored in the extended information file 'iTunesDB.ext'. When you call 'Normalize volume' again, the stored value will be used to re-populate the soundcheck field. Use 'Update Track' to re-read the tag from the file.
</para>
</sect2>
</sect1>
<sect1 id="cover-art">
<title>Cover art</title>
<para>Cover art is a visual element of your gtkpod music collection. It changes the black and white database of artists and title names back into something related to the physical CDs and DVDs that have been imported.
</para>
<sect2 id='clarity'>
<title id='clarity-title'>The Clarity Display Plugin</title>
<para>Should you have the capability of an opengl rendering graphics card and drivers then the clarity plugin provides a more stylish cover art display than the original coverart display plugin described here.
</para>
</sect2>
<sect2 id='coverart-display'>
<title id='coverart-display-title'>CoverArt Display</title>
<para>The display consists of 9 covers displayed at any one time. The entire album collection can be cycled through from one end to another. The main image is slighly larger and lacking in "shine" for viewing clarity.
</para>
<para>
<figure>
<title>Cover art display</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/coverart.png"/>
</imageobject>
</mediaobject>
</figure>
</para>
<itemizedlist>
<listitem>
<para>Use the scrollbar to quickly slide back and forth over the album collection.
</para>
</listitem>
<listitem>
<para>Use the scrollbar buttons to more precisely step through each album.
</para>
</listitem>
<listitem>
<para>Click on the main album cover image (one at the front and in the centre) once to display just the album's tracks in the right pane of gtkpod
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='coverart-popup-menu'>
<title id='coverart-popup-menu-title'>CoverArt Popup Menu</title>
<para>
<figure>
<title>Cover art popup menu</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/cover-popupmenu.png"/>
</imageobject>
</mediaobject>
</figure>
</para>
<itemizedlist>
<listitem>
<para>Right-click on the main album cover image to display the popup menu with 3 options:</para>
<itemizedlist>
<listitem>
<para>Select Cover From File
</para>
</listitem>
<listitem>
<para>View Full Size Artwork
</para>
</listitem>
<listitem>
<para>Edit Track Details
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<sect3 id='select-cover-from-file'>
<title id='select-cover-from-file-title'>Select Cover From File</title>
<para>
<figure>
<title>Select cover from file</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/cover-setfromfile.png"/>
</imageobject>
</mediaobject>
</figure>
</para>
<itemizedlist>
<listitem>
<para>Selecting this option displays a file chooser dialog. Select the preferred image file and click OK. The album cover changes to a scaled version of the new image, while all the tracks in the album have their artwork path modified to the path of the preferred image.
</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id='view-full-size-artwork'>
<title id='view-full-size-artwork-title'>View Full Size Artwork</title>
<para>
<figure>
<title>View full size artwork</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/cover-fullsize.png"/>
</imageobject>
</mediaobject>
</figure>
</para>
<itemizedlist>
<listitem>
<para>Selecting this options opens a dialog displaying the cover image. The image is either its true size of the biggest size it can be while still fitting on the desktop. Its true resolution is displayed underneath in the format width x height.
</para>
</listitem>
<listitem>
<para>The dialog is modal so must be closed before moving on. The OK button closes the dialog.
</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id='edit-track-details-coverart'>
<title>Edit Track Details</title>
<itemizedlist>
<listitem>
<para>This provides a shortcut to the "Edit Track Details" dialog for editing the ID3 tag information for all tracks belonging to the album displayed.
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="adding-cover-art-from-a-browser">
<title>Adding cover art from a browser</title>
<para>Unlike other applications, cover art in gtkpod is not hidden away in a "difficult to find" image cache. In fact, cover art files, for a local database, can be located anywhere on the filesystem.
</para>
<sect2 id='setting-image-on-track-import'>
<title id='setting-image-on-track-import-title'>Setting Image on Track Import</title>
<para>Locating the image file in the same directory as the tracks gives the additional benefit that gtkpod will analyse the image upon track import and set the image as the album's cover artwork. It is Important to ensure the image's filename corresponds to at least one of the image filename templates entered in the Preferences window.
</para>
</sect2>
<sect2 id='setting-image-on-existing-album'>
<title id='setting-image-on-existing-album-title'>Setting Image on Existing Album</title>
<para>
The use of the popup menu to select a cover art file from the filesystem has been documented <filename>Cover Art|here</filename>. It is also possible to download a cover art image file from the internet and drag n drop it into gtkpod.
</para>
<sect3 id='drag-and-#-three-nine-n-drop-using-firefox'>
<title id='drag-and-#-three-nine-n-drop-using-firefox-title'>Drag 'n Drop Using Firefox</title>
<orderedlist>
<listitem>
<para>Locate the preferred image and display it in firefox.
</para>
</listitem>
<listitem>
<para>Ensure the url of the image ends with ".jpg" or ".JPG" (other file extensions could be supported if demand warrants it).
</para>
</listitem>
<listitem>
<para>Drag the image from Firefox and drop it onto the Cover Art Display's centre/main cover image. The main cover image should be displaying the album which requires the new cover.
</para>
</listitem>
<listitem>
<para>If a cover already exists with the same filename then gtkpod will ask whether the existing image be overwritten or the new image be named something else.
</para>
</listitem>
<listitem>
<para>The image will be downloaded from the url location, saved in the album's directory on the filesystem and applied to each track belonging to that album.
</para>
</listitem>
</orderedlist>
</sect3>
<sect3 id='drag-and-#-three-nine-n-drop-using-konqueror'>
<title id='drag-and-#-three-nine-n-drop-using-konqueror-title'>Drag 'n Drop Using Konqueror</title>
<itemizedlist>
<listitem>
<para>A limitation of the dnd in Firefox is that only the url can be used to get at the image file. Thus, the page must be displaying just the image and gtkpod must redownload the image internally (using curl and the image url).
</para>
</listitem>
<listitem>
<para>Konqueror offers the additional functionality that the image file can be extracted directly from its cache. This has the benefits of avoiding the internal curl download and that the url is not restricted to those ending in ".jpg"
</para>
</listitem>
<listitem>
<para>
The importance of the latter benefit concerns websites that do not offer the direct download of cover art images.
<ulink url='http://www.allcdcovers.com'>
<citetitle>allcdcovers.com</citetitle>
</ulink>
is one such site, where its images are displayed in the browser but the image url cannot be used a second time to download the same image. Thus, allcdcovers.com cannot be used as a download dnd source in Firefox. However, in Konqueror, simply open a full image from allcdcovers then just drag 'n drop into gtkpod.
</para>
</listitem>
<listitem>
<para>Maybe Firefox will do this some day too..
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="copying-content-to-the-ipod">
<title>Copying content to the iPod</title>
<sect2 id='getting-tracks-onto-the-ipod'>
<title id='getting-tracks-onto-the-ipod-title'>Getting Tracks onto the iPod</title>
<itemizedlist>
<listitem>
<para>Tracks can be imported directly to an iPod by ensuring the latter is the selected repository before clicking Add Files or Add Directories.
</para>
</listitem>
<listitem>
<para>Normally though, tracks will already have been imported into the Local repository. To copy them onto the iPod simply select the tracks in the Track Window and drag them onto the iPod repository icon.
</para>
</listitem>
<listitem>
<para>To copy a whole album, selected the album in one of the sort tabs and drag that onto the iPod repository.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='playlists'>
<title id='playlists-title'>Playlists</title>
<itemizedlist>
<listitem>
<para>Use playlists to group together a set of tracks. Simply create a new playlist in the Local repository then drag n drop the tracks onto it.
</para>
</listitem>
<listitem>
<para>Tracks are not actually copied into a playlist so should a track be deleted then it will be deleted from all playlists.
</para>
</listitem>
<listitem>
<para>Drag n drop a playlist onto the iPod repository icon to copy it and all its tracks to the iPod. The playlist will be available in the Playlist section of the iPod's control system as well as all tracks being copied to the iPod.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='save-changes'>
<title id='save-changes-title'>Save Changes</title>
<itemizedlist>
<listitem>
<para>
At any change to a repository, eg. track addition, deletion, edit ..., a change has occurred that requires a database save. To highlight this, the name of the repository is changed to italics, ie. Local -> <emphasis role="italic">Local</emphasis>. This shows the repository requires saving.
</para>
</listitem>
<listitem>
<para>Should gtkpod be closed prior to any saving then a dialog is displayed informing that data changes will be lost if a save is not performed.
</para>
</listitem>
<listitem>
<para>Clicking the "Save Changes" button will save all changes made to all of the repositories. This is the point where tracks are actually copied to the iPod and the iPod database updated. Only after a save is performed will the tracks copied to the iPod, be playable on the iPod.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="playcounts-and-ratings">
<title>Playcounts and ratings</title>
<para>Whenever a track is played completely on the iPod (firmware version 1.3 or higher) a counter in the "Play Counts" file will be increased by one. The same file also contains the rating set with the 3rd generation (and later) iPods. This file appears to be deleted whenever the iPod resets itself, e.g. because the iPod is disconnected from the computer. Therefore, be careful! Charging the iPod seems to do no harm.
</para>
<para>When gtkpod is started, it will also read this file and incorporate the information into the iTunesDB that can be written back to the iPod. There have been several requests to also register playcounts when playing a track on the local machine. This is possible by calling gtkpod as
</para>
<programlisting>gtkpod -p <filename></programlisting>
<para>If gtkpod is already running, the playcount of that track there will be increased by one. If gtkpod is not already running, the playcount will be registered in ~/.gtkpod/offline_playcount. This file will be read the next time you import the iTunesDB from your iPod, and the playcounts will be updated accordingly.
</para>
<para>Please note that if you start several instances of gtkpod, only the first instance will register playcounts through "gtkpod -p".
</para>
<para>Now all that is required is to tell your favorite player to call gtkpod with the filename of the played track.
</para>
<para>For xmms this is possible as of July 18th, 2004 (CVS version). Versions before that (including 1.2.10) only allow you to have an external program called at the beginning of a track. Our patch allows to have an external program called also at the end of a track.
</para>
<para>In each case you will need to activate the "General Plugin" called "song_change" and configure it to call 'gtkpod -p "%f"'.
</para>
</sect1>
</chapter>
<chapter id="managing-playlists">
<title>Managing playlists</title>
<sect1 id="playlists-podcasts-and-photos">
<title>Playlists, podcasts and photos</title>
<sect2 id='playlists-ppp'>
<title>Playlists</title>
<para>Playlists reside under the iPod repository node in the left hand pane of gtkpod. Clicking on them will display the tracks associated with them, effectively filtering the other gtkpod panes. You can ...
</para>
<itemizedlist>
<listitem>
<para>create playlists with the <New Playlist> button on the toolbar or pressing "Ctrl-n" in the playlist listview.
</para>
</listitem>
<listitem>
<para>create playlists by adding an existing playlist file with <Add file> or <Add playlist>.
</para>
</listitem>
<listitem>
<para>add tracks to playlists by marking the tracks you want to add, and then dragging them onto the playlist.
</para>
</listitem>
<listitem>
<para>rename playlists.
</para>
</listitem>
<listitem>
<para>delete playlists by selecting the desired playlist and pressing "Ctrl-D", or by selecting "Delete Playlist" from the Edit menu.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='podcasts'>
<title id='podcasts-title'>Podcasts</title>
<para>
You have to download podcasts using a third party tool like
<ulink url='http://linc.homeunix.org:8080/scripts/bashpodder/'>
<citetitle>bashpodder</citetitle>
</ulink>
or
<ulink url='http://perli.net/projekte/gpodder/%29'>
<citetitle>gpodder</citetitle>
</ulink>
.
</para>
<para>Podcasts should be added directly into the 'Podcasts' playlist of the iPod repository, for example by selecting the Podcasts playlist before manually adding files/directories. Podcasts will then appear only in the Podcasts section on the iPod. If you add podcasts to the main playlist 'gtkpod/iPod' or any other iPod playlist first and then drag them over to the Podcasts playlist, the podcasts will appear in the Podcasts section on the iPod, as well as in the normal music section.
</para>
<para>The podcast 'repository' is a local repository (like 'Local') where you can keep all local podcasts. No mechanism exists to automatically synchronize the iPod repository with the Podcast repository at this time. You have to drag the podcasts over manually.
</para>
</sect2>
<sect2 id='photos'>
<title id='photos-title'>Photos</title>
<para>
If your ipod supports photos then a special dynamic playlist is created in the playlist tree. <emphasis role="bold">YOU CANNOT DELETE IT!</emphasis> Indeed when clicking on it all the usual track related ipod functions are disabled or removed.
</para>
<itemizedlist>
<listitem>
<para>The track window elements are replaced with the photo management pane. This displays the Photo Library and all the saved photos from the ipod and allows you to add new albums, add new images, remove albums, remove images and drag n drop image between albums.
</para>
</listitem>
<listitem>
<para>You cannot delete the Photo Library as this is the original photo database. All images are stored in it and thus clicking on it, all the images on the ipod are displayed in it. Subsequent albums display a subset of the Photo Library's images.
</para>
</listitem>
<listitem>
<para>Removing an image from an album will remove it from the album but it will still be stored on the ipod in the Photo Library.
</para>
</listitem>
<listitem>
<para>Removing an image from the Photo Library will delete it completely from the ipod.
</para>
</listitem>
<listitem>
<para>You can select a set of images from a selected album (inc. the Photo Library) and drag n drop them into another album.
</para>
</listitem>
<listitem>
<para>Any changes made in the photo management window will change the Photo playlist to italics indicating that a "Save Changes" should occur before exiting in order to preserve those changes.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>
<chapter id="advanced-features">
<title>Advanced features</title>
<sect1 id="exporting-files-from-the-ipod">
<title>Exporting files from the iPod</title>
<sect2 id='copying-from-the-ipod'>
<title id='copying-from-the-ipod-title'>Copying from the iPod</title>
<para>Unlike other iPod management applications, it is possible to copy tracks resident on the iPod back onto a PC, using gtkpod.
</para>
<itemizedlist>
<listitem>
<para>Mark the tracks you want to export and select "Export Tracks from Database" from the file menu (or use the context sensitive menu).
</para>
</listitem>
<listitem>
<para>A file selection dialog window appears and you can choose the directory you'd like the selected files to be written to.
</para>
</listitem>
<listitem>
<para>You can specify the output filename in the prefs dialog by specifying a template (e.g. "%A/%a - %t"). You can specify multiple templates for different file formats by separating them by a semicolon (e.g. "%A/%a - %t.mp3;%t.wav"). See the tooltip in the preferences window for a list of identifiers.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>
</book>
|