[Bug-gnupod] Documentation

[Jacinta Richardson]

G'day folk,

Although the documentation in the current CVS version is much improved 
vs the release late last year, it strikes me that so much more could be 
written.

I'm not a huge fan of the info way of navigating data and I've never 
learned how to write info files, so I've been writing in POD.  My 
thought is that the POD could be included in the relevant files (where 
possible) as well as creating other .pod files as required to provide 
all the necessary documentation.  I've certainly typed "perldoc 
gnupod_addsong.pl" enough times without thinking about it.

As such I've written documentation for gnupod_search.pl and 
gnupod_addsong.pl as well as some documentation for GNUtunesDB.xml. 
This still needs all the installation advice, using firewire and Macs 
advice, and other similar parts.  However, I doubt I'll have a chance to 
do those soon, so I thought I'd make this part available.

It would be awesome if we could improve the documentation to show how to 
add videos and TV Shows, but I'm not 100% sure that gnupod_addsong could 
handle that yet.

Feel free to mercilessly edit what I've written and coerce it into an 
info format if you'd prefer.

        J

=head1 Name

gnupod_addsong.pl  - Adds files to the iPod

=head1 SYNOPSIS

        # Mount the iPod
        mount /mnt/ipod

        # Sync changes made by other tools (such as iTunes)
        # only necessary if you are using other tools in addition to these
        tunes2pod.pl -m /mnt/ipod

        # Add a song 
        gnupod_addsong.pl -m /mnt/ipod /tmp/foo.mp3

        # You can also use wild cards and add more than one song at a time
        gnupod_addsong.pl -m /mnt/ipod /mnt/mp3/seiken_densetsu2_ost/* 
/mnt/mp3/xenogears/ost?/*

        # Convert to mp3 on the fly
        gnupod_addsong.pl -m /mnt/ipod myfile.flac myfile.ogg --decode=mp3

        # Add songs with artwork
        gnupod_addsong.pl -m /mnt/ipod /mnt/mp3/amos/* --artwork=amos.jpg

        # Add songs into playlists
        gnupod_addsong.pl -m /mnt/ipod --playlist=Party --playlist=Driving 
/tmp/*.mp3

        # Add a podcast (not the same as a regular song)
        gnupod_addsong.pl -m /mnt/ipod -p "Podcast Title" --playlist-is-podcast 
podcast.mp3

        # Add more than one podcast
        gnupod_addsong.pl -m /mnt/ipod -p "Podcast Title" --playlist-is-podcast 
podcasts/*

        # Fetch podcasts online and add to iPod
        gnupod_addsong.pl -m /mnt/ipod -p "Heute Morgen" --playlist-is-podcast 
http://pod.drs.ch/heutemorgen_mpx.xml

        # Record the changes to the iTunes database (this is essential)
        mktunes.pl -m /mnt/ipod

        # Unmount and go
        umount /mnt/ipod

=head1 DESCRIPTION

C<gnupod_addsong.pl> copies songs onto the iPod and updates the GNUtunesDB.xml
database.  For these changes to be visible to the iPod, C<mktunes> must be run.

=head1 OPTIONS

=head2 Generic Program Information

=over 4

=item -h, --help

Lists out all the options.

=item --version

Output version information and exit.

=item -m, --mount=directory

iPod mount point, default is C<$IPOD_MOUNTPOINT>.

=back

=head2 Disaster recovery

=over 4

=item -r, --restore

Restore the iPod (create a new GNUtunesDB from scratch).  This will
rediscover all the songs on the iPod, but will lose playlists and
data not stored in the mp3 header information.

=back

=head2 Duplicate management

=over 4

=item -d, --duplicate

It isn't possible to add the same MP3 multiple times, gnupod_addsong.pl detects
duplicates (Duplicate = same filesize/time and ID3Tag name). You can disable
the duplicate-detection with the '--duplicate' switch.

=back

=head2 Playlists

=over 4

=item -p, --playlist=string

Add songs to this playlist, can be used multiple times.  Playlists can also be
added manually, as covered later.

=back

=head2 Podcasts

See also the later section on podcasts.

=over 4

=item --playlist-is-podcast

Set podcast flag for playlist(s) created using '--playlist'.

=item --podcast-artwork

Download and install artwork for podcasts from their channel.

=item --podcast-cache-dir=string

Set a directory in which podcast media files will be cached.

=item --podcast-files-limit=int

Limit the number of files that are downloaded.
0 = download all (default), -X = download X oldest items, X = download X newest 
items

=back

=head2 Decoding

MP3/WAV (RIFF) and M4A (Apple AAC) files can be added directly.  FLAC and
OGG files can be decoded and also added.  C<gnupod_addsong.pl> attempts to
'auto-detect' the encoding.

(Note: To use all features of --decode, you will have to install
Audio::FLAC::Header, Ogg::Vorbis::Header::PurePerl, lame, flac, oggenc and
faac)

=over 4

=item -x, --decode=pcm|mp3|aac|aacbm

Convert FLAC Files to WAVE/MP3 or AAC 'on-the-fly'. Use '-e' to specify a
quality/bitrate.

=item -x, --decode=video

Convert .avi Files into iPod video 'on-the-fly' (needs ffmpeg with AAC
support).

=item -x, --decode=alac

Convert FLAC Files into Apple Lossless 'on-the-fly' (needs ffmpeg with ALAC
support).

=item -e, --reencode=int

Re-encode MP3/AAC files with new quality 'on-the-fly' (0 = Good .. 9 = Bad)
You may be able to save some space if you do not need crystal-clear sound.

=back

=head2 Setting title/album information

By default, GNUpod uses the ID3 tags included in the mp3 header
information.  If this information is incorrect, incomplete or just not what
you want, use these options.  You can also change track information later with
L<gnupod_search.pl>.

=over 4

=item --disable-v1

Do not read ID3v1 Tags (MP3 Only).

=item --disable-v2

Do not read ID3v2 Tags (MP3 Only).

=item --disable-ape-tag

Do not read APE Tags (MP3 Only) --disable-v1 with --disable-v2 implies 
--disable-ape-tag

=item --replaygain-album

Use the ReplayGain album value instead of the ReplayGain track value
(default).

=item -t, --set-title=string

Set Title  (Override ID3 Tag).

=item -a, --set-artist=string

Set Artist (Override ID3 Tag).

=item -l, --set-album=string

Set Album  (Override ID3 Tag).

=item -g, --set-genre=string

Set Genre  (Override ID3 Tag).

=item --set-rating=int

Set Rating.  (20 = 1 star, 40 = 2 stars, ... 100 = 5 stars).

=item --set-playcount=int

Set Playcount (how many times the song has been played).

=item --set-songnum

Override 'Songnum/Tracknum' field.

=item -b, --set-bookmarkable

Set this song as bookmarkable.  This is usually most valuable for media
such as podcasts and e-books where you may wish to stop the media part-way
through and come back to the same place.

=item --set-shuffleskip

Exclude this file when in shuffle mode. Most useful for media such as
podcasts and e-books.

=item --set-compilation

Mark songs as being part of a compilation.

=item --min-vol-adj=int

Minimum volume adjustment allowed by ID3 RVA/RVAD tag.

=item --max-vol-adj=int

Maximum volume adjustment allowed by ID3 RVA/RVAD tag. The volume can be
adjusted manually in iTunes in the range -100% to +100%. The default for
these two options is 0, which effectively ignores the RVA/RVAD tag.

=item --artwork=FILE

Use FILE as album cover.

=back

=head1 PLAYLISTS

You can use the C<--playlist> option when adding songs to add a song into
the nominated playlist. 

        # Add songs into playlists
        gnupod_addsong.pl -m /mnt/ipod --playlist=Party --playlist=Driving 
/tmp/*.mp3

Playlists can be manually created after the songs have been added.  To do
this, you'll need to mount your iPod and open the file (relative to your
mount point) F<iPod_Control/.gnupod/GNUtunesDB.xml> in a text editor.  It
is recommended that you first save a copy of your working file just in case
something goes wrong.

B<IMPORTANT:> In order for your changes to take effect, you must remember to
run C<mktunes.pl> after changing the C<GNUtunesDB.xml> file, before
unmounting.

To create a playlist named 'sweet' which holds the songs with the ID
1 and 2, create something like this:

        <playlist name="sweet">
                <add id="1" />
                <add id="2" />
        </playlist>

=head2 Extended playlists

To make playlist easier, it's possible to add entire albums, and to add
songs based on different criteria than just song id.  For example:

        <playlist name="bogus">
                <add album="seiken densetsu" bitrate="256" />
        </playlist>

This would add every song from the album 'Seiken Densetsu' (C<add>
is case INsensitive) which has a bitrate of 256kbit/s.

=head2 Regular Expression playlists

Since GNUpod 0.26 it's also possible to use regular expressions.

        <playlist name="Regex Demo">
                <regex album="^A" />
                <iregex album="^b" />
        </playlist>

This will add all songs from all albums that start with "A" and all songs
from all albums which start with "B" or "b".  C<regex> is case sensitive,
C<iregex> is case insensitive.

It's also possible to sort a playlist:

        <playlist name="By Album" sort="album">
                <iregex artist="bach" />
        </playlist>

This adds all songs from Bach, sorted by album (a..z). You can use
every C< <file ..> > item (id, bitrate, title..) for C<sort>.  Add
C<reverse>  at the beginning, to reverse the sorting:

        <playlist name="By Title" sort="reverse title">
                <regex artist="U2" />
        </playlist>

=head2 Smart Playlists

You can also use Smart-Playlists with Firmware >= 2.x

        <smartplaylist checkrule="spl" liveupdate="1" name="Example SPL1" >
                <spl action="eq" field="playcount" string="0" />
                <spl action="IS" field="artist" string="Jon Doe" />
        </smartplaylist>

        <smartplaylist checkrule="spl" liveupdate="1" name="Example SPL2" >
                <spl action="gt" field="bitrate" string="311" />
        </smartplaylist>

C<Example SPL1> matches all songs from 'Jon Doe' with playcount==0 (eg.
All songs from Jon Doe that haven't been played yet).

C<Example SPL2> matches all songs with a Bitrate > 331.  (See also
README.smartplaylists).

For more examples have a look at `doc/gnutunesdb.example' included in the
GNUpod tar-ball.  Also check out http://blinkenlights.ch/gnupod/mkspl.html
for a 'JavaScript SPL-Creator'

=head1 PODCASTS

Do not add podcast files in the same way as you add regular songs.  In
order for your iPod to distinguish between Podcasts and songs, we need to
make sure the media type is set correctly.  To add a single podcast do the
following:

        gnupod_addsong.pl -m /mnt/ipod -p "Podcast Title" --playlist-is-podcast 
podcast.mp3

You can add multiple podcasts to the same title as well:

        gnupod_addsong.pl -m /mnt/ipod -p "Podcast Title" --playlist-is-podcast 
podcasts/*

Including C<playlist-is-podcast> ensures that all of the attributes are set
correctly (shuffleskip, bookmarkable, mediatype etc).

=head2 Downloading podcasts

gnupod_addsong.pl can also download podcasts and create such playlists
itself:

        gnupod_addsong.pl -m /mnt/ipod -p "Heute Morgen" --playlist-is-podcast 
http://pod.drs.ch/heutemorgen_mpx.xml

Running this command will create a Playlist called 'Heute Morgen' (-p) and
set podcast="1" (--playlist-is-podcast). gnupod_addsong.pl will then fetch
the podcast from http://pod.drs.ch/heutemorgen_mpx.xml, download all (new)
files and add them to the 'Heute Morgen' playlist!

=head2 Creating additional podcast playlists

If you want to create additional podcast playlists manually as above, you
need to set the podcast flag to '1':

        <playlist name="Test Podcast" podcast="1">
                <iregex artist="John Doe" />
        </playlist>

Such a playlist will show up as a Podcast after running C<mktunes.pl>.

=head1 ARTWORK

GNUpod can write cover artwork for video, nano and late 2007-nano
iPods. The internal image format is model specific, so you should give
GNUpod a hint about the image format it should use.

If you own a video (compatible) iPod, set:

     model = video

in your GNUpod configuration file (found at F<~/.gnupodrc> or
F<$IPOD_MOUNTPOINT/iPod_Control/.gnupod/gnupodrc>, see
F<doc/gnupodrc.example> for more details).  For the iPod nano you should
use:

     model = nano

Late 2007-nanos need this setting:

     model = nano_3g

Late 2008-nanos need this setting:

     model = nano_4g

To specify a cover while adding files you'd use the `--artwork'
switch. Example:

     gnupod_addsong.pl --artwork cover.jpg *.mp3

Use L<gnupod_search.pl> to change/add artwork for existing files.
Don't forget to run L<mktunes.pl> afterwards.

=head1 COEXISTENCE

GNUpod can coexist with iTunes and other programs for the iPod.

If you want to use an iPod with GNUpod and used something other than
GNUpod (maybe iTunes) to perform the last update (adding songs,
editing playlists.. doing something..), you'll have to use
C<tunes2pod.pl> to update the (outdated) GNUtunesDB.

        tunes2pod.pl -m /mnt/ipod

The iPod is now ready again for GNUpod.

You have to do this because GNUpod stores its information in the
GNUtunesDB, but other programs access the iTunesDB directly. After you
did something with eg. iTunes, the GNUtunesDB would be 'outdated' and
you would lose any changes you made with iTunes. Running C<tunes2pod.pl>
will write a new GNUtunesDB which reflects the content of the current
iTunesDB.

You should avoid the use of any extended playlists if you use
your iPod with other programs.  For example if you have the following in
your C<GNUtunesDB.xml> file:

        <files>
        <file id="1" title="hello" album="foo"..
        <file id="2" title="boing" album="foo"..
        </files>
        <playlist name="extended">
                <add album="foo" />
        </playlist>

C<tunes2pod.pl> will render this merely as:

        <files>
        <file id="1" title="hello" album="foo"..
        <file id="2" title="boing" album="foo"..
        </files>
        <playlist name="extended">
                <add id="1" />
                <add id="2" />
        </playlist>

The songs are still in the playlists, but the expressions you wrote
are lost.  This is because the extended playlists are only syntactic sugar
provided by the GNUpod tools and have no representation in the iTunes
database.

=head1 DISASTER RECOVERY

It is recommended that before editing your
F<iPod_Control/.gnupod/GNUtunesDB.xml> file yourself, that you make a
back-up of it.  Most of the gnupod tools also make a backup of it before
making any changes and store that backup in
F<iPod_Control/.gnupod/GNUtunesDB.xml.old>.

=head2 Not running mktunes.pl

If you unmount your iPod without running C<mktunes.pl> then you'll find
that none of the changes you made (including adding songs) will appear to
have taken effect.  You should be able to remount your iPod, run
C<mktunes.pl> and unmount to recover from this.

=head2 mktunes.pl failed

If C<mktunes.pl> fails (perhaps you hit ctrl-c because it was taking too
long) then the iTunes database may be left corrupted.  If you unmount at
this point, your iPod may appear to have no files at all.  

If you are using Ubuntu 9.04 or above, and you found C<mktunes.pl> was
taking too long, you can either tell GNUpod your iPod's serial number:

        mktunes.pl -m /mnt/ipod --fwguid YM846......

or upgrade your version of the GNUpod tools in order for C<mktunes.pl> to work 
again.  You
can do that with the following commands:

        sudo su -
        apt-get remove gnupod-tools
        apt-get -y install cvs
        apt-get -y install autoconf
        cvs -z3 -d:pserver:address@hidden:/sources/gnupod co gnupod
        cd gnupod
        autoconf
        ./configure
        make install

In any case, remount your iPod, run C<mktunes.pl> again and unmount.  That
should fix the problem.

iPod models from late 2007 and onwards (3rd and later generation Nano,
Classic, Touch) refuse to work unless the iTunesDB has been signed with a
sha1 hash.  This hash helps to detect corrupted databases, prevents sharing
an iTunesDB between multiple iPods and locks out non-apple software. GNUpod
is able to create the required hash value if it knows the iPods serial
number, this is a 16 chars long hex value such as: `000ba3100310abcf' and
should be auto-detected on GNU/Linux (via `/proc/bus/usb/devices') and
Solaris (via `prtconf -v').  If GNUpod somehow fails to find the correct
serial number of your iPod (as it can with recent versions of Ubuntu)
you'll have to specify the correct value using the `--fwguid' switch of
`mktunes.pl'.

=head2 After a crash (or a failure to unmount)

If your computer crashed while uploading/deleting songs, you may have
some 'zombie' files.  This can also occur if you forget to unmount your
iPod before you unplug it from the computer.

In this case, you can use C<gnupod_check.pl> to search 'lost' files.
gnupod_check.pl will tell you what you could do to fix it.

If gnupod_check.pl found many errors (or you lost your
F<GNUtunesDB.xml>), you can 'rebuild' an GNUtunesDB using:

     gnupod_addsong.pl --restore -m /mnt/ipod

This won't delete any songs on the iPod but will attempt to recreate the
F<GNUtunesDB.xml> file including the Songs which are on the iPod and their
mp3 header information.  Playlists, and any additional information you've
added may be lost.

If you have a recent copy of your F<GNUtunesDB.xml>, you may find it useful
to back-up the new, restored F<GNUtunesDB.xml> file and overwrite it with
yours.  Then run C<mktunes.pl>.  This might be sufficient to return your
iPod to the previous state (although if you've added or removed songs etc;
then it might not work).

=head1 BUGS

Email bug reports to C<< <address@hidden> >>, a mailing
list whose archives can be found at 
C<< <http://lists.gnu.org/archive/html/bug-gnupod/> >>.

=over 4

=item * 

Smartplaylist support is incomplete (No liveupdate)

=item *

GNUpod doesn't like Audible.com and DRM Files

=back

=head1 SEE ALSO

=over 4

=item *

L<gnupod_search.pod> - Search, edit, delete files on your iPod.

=item *

L<GNUtunesDB.pod> - More information on file format.

=item *

L<http://www.ipodlinux.org/wiki/ITunesDB> - More information on the ITunesDB
format.

=back

=head1 LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it
under the terms of the GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007.

=head1 VERSION CONTROL

To check out the current version try:

        cvs -z3 -d:pserver:address@hidden:/sources/gnupod co gnupod

The CVS repository is due to be closed very soon with version control
moving to git.  TODO

=head1 AUTHORS

Adrian Ulrich <pab at blinkenlights.ch>  - Main author of GNUpod

Eric C. Cooper <address@hidden> - Contributed to the 'old' GNUpod (< 0.9)

Heinrich Langos - Many patches

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE
SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING
BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE
WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

=head1 Name

gnupod_search.pl  - Search, list, edit, delete songs from your iPod

=head1 SYNOPSIS

        # Mount the iPod
        mount /mnt/ipod

        # Sync changes made by other tools (such as iTunes)
        # only necessary if you are using other tools in addition to these
        tunes2pod.pl -m /mnt/ipod

        # search for all songs by the artist called 'Schlummiguch'
        gnupod_search.pl -m /mnt/ipod --artist="Schlummiguch"

        # search for all songs in the album 'Seiken Densetsu'
        gnupod_search.pl -m /mnt/ipod --album="Seiken Densetsu"

        # search for all songs whose ids contain the number 4
        gnupod_search.pl -m /mnt/ipod --id=4

        # search for the songs with id 4 (it's a regular expression)
        gnupod_search.pl -m /mnt/ipod --id="^4$"

        # search for all the songs whose rating is 3 - 5 stars and whose
        # Artist contains "Amos"
        gnupod_search.pl -m /mnt/ipod --rating="60-100" --artist="Amos"

        # search for all the songs whose play count is less than 3
        gnupod_search.pl -m /mnt/ipod --playcount<3

        # Change artist and rating for all songs by Alfred Neumann
        # Sets artist to "John Doe" and rating to 5 stars (5 x 20 = 100)
        gnupod_search.pl --artist="Alfred Neumann" --rename="artist=John Doe" 
--rename="rating=100"

        # Set cover-artwork for all songs by "Amos" to be "amos.jpg"
        gnupod_search.pl --artist="Amos" --artwork="amos.jpg"

        # Boost the volume for all the songs on album by 50%
        gnupod_search --album="Seiken Densetsu" --rename="volume=50"

        # Cut the volume for all the songs on album by -10%
        gnupod_search --album="Seiken Densetsu" --rename="volume=-10"

        # Delete all songs by the artist called 'Schlumminguch'
        gnupod_search.pl -m /mnt/ipod --artist="Schlummiguch" --delete

        # Record the changes to the iTunes database (this is essential)
        mktunes.pl -m /mnt/ipod

        # Unmount and go
        umount /mnt/ipod

=head1 DESCRIPTION

C<gnupod_search.pl> searches the F<GNUtunesDB.xml> file for matches to its
arguments.  These search results can then be changed (via C<--rename>) or
deleted (via C<--delete>).  For these changes to be visible to the iPod,
C<mktunes> must be run.

=head1 OPTIONS

=head2 Generic Program Information

=over 4

=item -h, --help

Lists out all the options.

=item --version

Output version information and exit.

=item -m, --mount=directory

iPod mount point, default is C<$IPOD_MOUNTPOINT>.

=back

=head2 Search fields

By default, search arguments are treated as regular expressions.  The
exception to this are numerical comparisons (C<< --id<4 >> and 
C<< bitrate>255 >>) and numerical ranges (C< --rating=20-40 >).

The argument for title/artist/album/etc has to be UTF8 encoded, B<not> latin1!

=over 4

=item -t, --title=TITLE

search songs by Title.

=item -a, --artist=ARTIST

search songs by Artist.

=item -l, --album=ALBUM

search songs by Album.

=item -i, --id=ID

search songs by ID.

=item -g, --genre=GENRE

search songs by Genre.

=item -c, --playcount=COUNT

search songs by Playcount.

=item -s, --rating=COUNT

search songs by Rating (20 is one star, 40 two, etc.)

=item -R, --podcastrss=RSS

search songs by RSS.

=item -U, --podcastguid=GUID

search songs by podcast group id.

=item -b, --bitrate=BITRATE

search songs by Bitrate.

=item -o, --match-once

Search doesn't need to match multiple times, even though there is more than
one match criteria.  Essentially changes the search from using I<and> to
I<or>.  For example:

        gnupod_search.pl -m /mnt/ipod --rating="60-100" --artist="Amos"

matches all songs by "Amos" which have a rating of 3-5 stars.  Whereas

        gnupod_search.pl -m /mnt/ipod --rating="60-100" --artist="Amos" 
--match-once

matches all songs by "Amos" and all songs which have a rating of 3-5 stars.

=item --view=ialt

Modify how the search results are displayed.  default=ialt  Options are:

        t = title    a = artist   r = rating      p = iPod Path
        l = album    g = genre    c = playcount   i = id
        u = UnixPath n = Songnum  G = podcastguid R = podcastrss
        d = dbid

=back

=head2 Changing song information

After you have finished making changes, you must remember to call C<mktunes.pl>
to ensure those changes are written to the iTunes database and are visible to
your iPod.

=over 4

=item --rename=KEY=VAL

Change tags on found songs. Example: --rename="ARTIST=Foo Bar"

=item --artwork=FILE

Set FILE as Cover for found files.  

The internal image format is model specific, so you should give GNUpod a
hint about the image format it should use in your GNUpod configuration file
(found at F<~/.gnupodrc> or
F<$IPOD_MOUNTPOINT/iPod_Control/.gnupod/gnupodrc>).  For example C<model =
video> for video-capable iPods, C<model = nano> for first and second
generation nanos, C<model = nano_3g> for late 2007 nanos and 
C<model = nano_4g> for late 2008 nano models.

=back

=head2 Deleting songs

=over 4

=item --delete

REMOVE (!) matched songs.  This removes the songs immediately, but you'll
still have to call C<mktunes.pl> to make the appropriate changes to the
iTunes database.

=back

=head1 COEXISTENCE

GNUpod can coexist with iTunes and other programs for the iPod.

If you want to use an iPod with GNUpod and used something other than
GNUpod (maybe iTunes) to perform the last update (adding songs,
editing playlists.. doing something..), you'll have to use
C<tunes2pod.pl> to update the (outdated) GNUtunesDB.

        tunes2pod.pl -m /mnt/ipod

The iPod is now ready again for GNUpod.

You have to do this because GNUpod stores its information in the
GNUtunesDB, but other programs access the iTunesDB directly. After you
did something with eg. iTunes, the GNUtunesDB would be 'outdated' and
you would lose any changes you made with iTunes. Running C<tunes2pod.pl>
will write a new GNUtunesDB which reflects the content of the current
iTunesDB.

=head1 EDITING GNUtunesDB.xml DIRECTLY

It is possible to perform most of the changes you might perform with
C<gnupod_search.pl> directly into the
F<iPod_Control/.gnupod/GNUtunesDB.xml> file.  It is recommended that if you
intend to do this, that you take a backup of the file first.

B<IMPORTANT>: After making any changes to the F<GNUtunesDB.xml> (whether
directly) or vial C<gnupod_search.pl> you must call C<mktunes.pl> to ensure
those changes are also reflected in the iTunes database.

=head1 DISASTER RECOVERY

It is recommended that before editing your
F<iPod_Control/.gnupod/GNUtunesDB.xml> file yourself, that you make a
back-up of it.  Most of the gnupod tools also make a backup of it before
making any changes and store that backup in
F<iPod_Control/.gnupod/GNUtunesDB.xml.old>.

=head2 Not running mktunes.pl

If you unmount your iPod without running C<mktunes.pl> then you'll find
that none of the changes you made (including adding songs) will appear to
have taken effect.  You should be able to remount your iPod, run
C<mktunes.pl> and unmount to recover from this.

=head2 mktunes.pl failed

If C<mktunes.pl> fails (perhaps you hit ctrl-c because it was taking too
long) then the iTunes database may be left corrupted.  If you unmount at
this point, your iPod may appear to have no files at all.  

If you are using Ubuntu 9.04 or above, and you found C<mktunes.pl> was
taking too long, you can either tell GNUpod your iPod's serial number:

        mktunes.pl -m /mnt/ipod --fwguid YM846......

or upgrade your version of the GNUpod tools in order for C<mktunes.pl> to work 
again.  You
can do that with the following commands:

        sudo su -
        apt-get remove gnupod-tools
        apt-get -y install cvs
        apt-get -y install autoconf
        cvs -z3 -d:pserver:address@hidden:/sources/gnupod co gnupod
        cd gnupod
        autoconf
        ./configure
        make install

In any case, remount your iPod, run C<mktunes.pl> again and unmount.  That
should fix the problem.

iPod models from late 2007 and onwards (3rd and later generation Nano,
Classic, Touch) refuse to work unless the iTunesDB has been signed with a
sha1 hash.  This hash helps to detect corrupted databases, prevents sharing
an iTunesDB between multiple iPods and locks out non-apple software. GNUpod
is able to create the required hash value if it knows the iPods serial
number, this is a 16 chars long hex value such as: `000ba3100310abcf' and
should be auto-detected on GNU/Linux (via `/proc/bus/usb/devices') and
Solaris (via `prtconf -v').  If GNUpod somehow fails to find the correct
serial number of your iPod (as it can with recent versions of Ubuntu)
you'll have to specify the correct value using the `--fwguid' switch of
`mktunes.pl'.

=head2 After a crash (or a failure to unmount)

If your computer crashed while uploading/deleting songs, you may have
some 'zombie' files.  This can also occur if you forget to unmount your
iPod before you unplug it from the computer.

In this case, you can use C<gnupod_check.pl> to search 'lost' files.
gnupod_check.pl will tell you what you could do to fix it.

If gnupod_check.pl found many errors (or you lost your
F<GNUtunesDB.xml>), you can 'rebuild' an GNUtunesDB using:

     gnupod_addsong.pl --restore -m /mnt/ipod

This won't delete any songs on the iPod but will attempt to recreate the
F<GNUtunesDB.xml> file including the Songs which are on the iPod and their
mp3 header information.  Playlists, and any additional information you've
added may be lost.

If you have a recent copy of your F<GNUtunesDB.xml>, you may find it useful
to back-up the new, restored F<GNUtunesDB.xml> file and overwrite it with
yours.  Then run C<mktunes.pl>.  This might be sufficient to return your
iPod to the previous state (although if you've added or removed songs etc;
then it might not work).

=head1 BUGS

Email bug reports to C<< <address@hidden> >>, a mailing
list whose archives can be found at 
C<< <http://lists.gnu.org/archive/html/bug-gnupod/> >>.

=head1 SEE ALSO

=over 4

=item *

L<gnupod_addsong.pod> - Add songs, podcasts and books to your iPod.

=item *

L<GNUtunesDB.pod> - More information on file format.

=item *

L<http://www.ipodlinux.org/wiki/ITunesDB> - More information on the ITunesDB
format.

=back

=head1 LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it
under the terms of the GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007.

=head1 VERSION CONTROL

To check out the current version try:

        cvs -z3 -d:pserver:address@hidden:/sources/gnupod co gnupod

The CVS repository is due to be closed very soon with version control
moving to git.  TODO

=head1 AUTHORS

Adrian Ulrich <pab at blinkenlights.ch>  - Main author of GNUpod

Eric C. Cooper <address@hidden> - Contributed to the 'old' GNUpod (< 0.9)

Heinrich Langos - Many patches

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE
SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING
BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE
WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

=head1 NAME

GNUtunesDB.xml

=head1 DESCRIPTION

Detailed description of the F<GNUtunesDB.xml> file format.  

=head1 FILE STRUCTURE

This is an XML file, containing a single list of all the songs/media (files)
and a number of playlists.

        <?xml version='1.0' standalone='yes'?>
        <gnuPod>
         <files>
           ...
         </files>
         <playlist .... >
           ...
         </playlist>
         <playlist .... >
           ...
         </playlist>
        </gnuPod>

=head1 SAMPLE SONG

A sample entry for a song added with C<gnupod_addsong.pl> should look much
like the below.

        <file addtime="3320718442" album="Jagged Little Pill" artist="Alanis 
Morissette" 
        artworkcnt="0" artworksize="0" bitrate="128" bookmark="0" bpm="0" 
cdnum="0" 
        cds="0" changetime="0" compilation="" dbid_1="0100000000000000" 
        dbid_2="0100000000000000" episodenum="0" fdesc="MPEG 1 layer 3 file" 
        filesize="4554789" gaplessdata="0" genre="New Age" has_gapless="0" 
id="52" 
        lastplay="3326375095" lastskip="0" lyrics_flag="0" mediatype="1" 
movie_flag="0"
        nocrossfade="0" 
path=":iPod_Control:Music:f15:g0__All_I_Really_Want.mp3" 
        playcount="3" played_flag="1" postgap="0" pregap="0" rating="0" 
releasedate="0"
        samplecount="0000000000000000" seasonnum="0" skipcount="0" songnum="1"
        songs="0" soundcheck="0" srate="44100" starttime="0" stoptime="0"
        time="284674" title="All I Really Want" volume="0" year="0" />

These fields are determined by the fields used in the iTunes database.  Most of
what we know about them comes from L<http://ipodlinux.org/wiki/ITunesDB>,
although these are in a different order and may have different names.

=over 4

=item addtime

Timestamp of when the song was added to the iPod.  Number of seconds since
1/1/1904.

=item album

Name of album, either found from the MP3 header information or set by the
user.

=item artist

Name of the artist, either found from the MP3 header information or set by
the user.

=item artworkcnt

The number of album artwork items put into the tags of this song. Even if
you don't put any artwork items into the tags of the song, this value must
at least be 1 for the iPod to display any artwork stored in the ithmb
files. 

=item artworksize

The total size of artwork (in bytes) attached to this song (i.e. put into
the song as tags).

=item bitrate="128"

MP3 bitrate.  The lower the bitrate, the smaller the file size, but the
larger the chance of compression artifacts.

=item bookmark="0"

The point, in milliseconds, that the track will start playing back at.  Since
this file isn't bookmarkable this will always be zero.

=item bpm="0"

Beats per minute of the track.  If available, zero otherwise.

=item cdnum="0" 

CD number for multi-CD sets.

=item cds="0"

Total number of CDs for multi-CD sets.

=item changetime="0" 

??  TODO

=item compilation=""

Name of the compilation.

=item dbid_1="0100000000000000" 

Unique 64 bit value that identifies this song across the databases on the
iPod.

=item dbid_2="0100000000000000"

Unique 64 bit value that identifies this song across the databases on the
iPod.

=item episodenum="0"

The episode number of the track, for TV shows only - although not displayed on
the iPod, the episodes are sorted by episode number.

=item fdesc="MPEG 1 layer 3 file" 

Full description?  TODO

=item filesize="4554789" 

File size in bits.

=item gaplessdata="0" 

The size in bytes from first Synch Frame (which is usually the XING frame that
includes the LAME tag) until the 8th before the last frame. The gapless
playback does not work for MP3 files if this is set to zero

=item genre="New Age"

Song genre.  Either from MP3 header information or set by user.

=item has_gapless="0"

Whether or not the track has gapless data.

=item id="52" 

Insertion id (unique number).

=item lastplay="3326375095"

Timestamp for when song was last played.

=item lastskip="0"

Timestamp for when song was last skipped.

=item lyrics_flag="0"

Whether lyrics are stored in the MP3 header information.

=item mediatype="1"

The media type for this file.  In this case a regular mp3.

=item movie_flag="0"

Whether this file is a movie.

=item nocrossfade="0"

Whether the track uses cross-fade in iTunes.

=item path=":iPod_Control:Music:f15:g0__All_I_Really_Want.mp3" 

iPod local path to the song location.

=item playcount="3"

How many times the song has been played.

=item played_flag="1" 

Whether this song has been played.

=item postgap="0" 

Number of samples of silence at the end of the song (for gapless playback). 

=item pregap="0" 

Number of samples of silence before the songs starts (for gapless playback). 

=item rating="0"

User provided rating.  20 = 1 star, 40 = 2 stars, ... 100 = 5 stars.

=item releasedate="0"

Song release date, probably of time released to music store, timestamp.

=item samplecount="0000000000000000" 

Number of samples in the song (for gapless playback). 

=item seasonnum="0" 

The season number of the track, for TV shows only.

=item skipcount="0"

How many times this song has been skipped.

=item songnum="1"

Track number for song on its CD.  In this example this was the first song
on the CD.  This information is taken from the MP3 header information and
thus may be set as zero if that information is left empty.  In such as
case, the iPod will play the songs ordered alphabetically.

=item songs="0" 

Total number of songs on CD.

=item soundcheck="0" 

The SoundCheck value to apply to the song, when SoundCheck is switched on in 
the iPod settings.

=item srate="44100" 

The sample rate of the song expressed as an IEEE 32 bit floating point number.

=item starttime="0" 

time, in milliseconds, that the song will start playing at.

=item stoptime="0"

time, in milliseconds, that the song will stop playing at.

=item time="284674" 

??? TODO

=item title="All I Really Want" 

Song title.  Either from the MP3 header information or set by the user.

=item volume="0" 

Volume modification.  Zero means no change to the volume.  A positive value
boosts the song, a negative value decreases it.  Must be between -255 and +255.

=item year="0"

Year of track release if known, else 0.

=back

=head1 SAMPLE PODCAST

A sample entry for a podcast correctly added with C<gnupod_addsong.pl>
should look much like the below.

        <file addtime="3320746257" album="dancarlin.com" artist="Dan
        Carlin" artworkcnt="0" artworksize="0" bitrate="96" bookmark="0"
        bookmarkable="1" bpm="0" cdnum="0" cds="0" changetime="0"
        comment="englibertarian, Independent, Constitution, Freedom,
        Non-Partisan Rights, Dan Carlin, politics" compilation=""
        dbid_1="6205000000000000" dbid_2="7a05000000000000" episodenum="0"
        fdesc="MPEG 1 layer 3 file" filesize="48214100" gaplessdata="0"
        genre="Podcast" has_gapless="0" id="1429" lastplay="3321687707"
        lastskip="0" lyrics_flag="0" mediatype="4" movie_flag="0"
        nocrossfade="0"
        path=":iPod_Control:Music:f15:g0_sewithDanCarlin147.mp3"
        playcount="1" played_flag="1" podcast="1"
        podcastguid="GNUpodG3DE42" podcastrss="GNUpodR7652E" postgap="0"
        pregap="0" rating="0" releasedate="0"
        samplecount="0000000000000000" seasonnum="0" shuffleskip="1"
        skipcount="0" songnum="0" songs="0" soundcheck="0" srate="44100"
        starttime="0" stoptime="0" time="4017841" title="cswdcb47 A Little
        Less Evil" volume="0" year="2009" />

Most of the elements here are the same as the former, but there are some
differences.

=over 4

=item bookmarkable="1"

As a podcast, we want to be able to come back to where we were up to if we
exit for some reason.

=item comment="englibertarian, Independent, Constitution, ..." 

Free-style comment field used to describe podcast content

=item mediatype="4"

Regular mp3s have mediatype 1, podcasts are mediatype 4.

=item podcast="1"

This is a podcast.

=item podcastguid="GNUpodG3DE42"

A unique ID for the track. It appears it is made sure that this ID does not
correspond to any real track ID.

=item podcastrss="GNUpodR7652E" 

?? TODO

=item shuffleskip="1"

When the iPod is on shuffle mode, this file should be skipped (so you only
get music).

=back

=head2 Podcast playlists

        <playlist name="dancarlin.com" plid="24217" podcast="1" >
                <add id="1428" />
                <add id="1429" />
        </playlist>

Podcast playlists must include the flag C<podcast=1> so that they'll show
up in the podcast menu on the iPod.

=head1 MEDIA TYPES

These media types are those used by iTunes.

        0 - Audio/Video (include in music lists and video lists)
        1 - Audio
        2 - Video
        4 - Podcast
        6 - Video Podcast
        8 - Audiobook
        20 - Music Video
        40 - TV Show (shows up ONLY in TV Shows)
        60 - TV Show (shows up in the Music lists as well)

=head1 SEE ALSO

=over 4

=item *

L<http://ipodlinux.org/wiki/ITunesDB> - More information on the underlying file 
format.

=item *

L<gnupod_search.pod> - Commandline tool that correctly manipulates this file 
for you.

=back

=head1 LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it
under the terms of the GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007.

=head1 VERSION CONTROL

To check out the current version try:

        cvs -z3 -d:pserver:address@hidden:/sources/gnupod co gnupod

The CVS repository is due to be closed very soon with version control
moving to git.  TODO

=head1 AUTHORS

Adrian Ulrich <pab at blinkenlights.ch>  - Main author of GNUpod

Eric C. Cooper <address@hidden> - Contributed to the 'old' GNUpod (< 0.9)

Heinrich Langos - Many patches

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE
SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING
BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE
WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.