/ 
Mac-iPod-GNUpod-1.0
River stage one • 1 direct dependent • 1 total dependent
/ Mac::iPod::GNUpod

NAME

Mac::iPod::GNUpod - Add and remove songs from your iPod; read and write databases in iTunes and GNUpod format

ABSTRACT

A re-implementation of the GNUpod package for manipulating an iPod. This module provides methods for initializing your iPod, adding and removing songs, and reading and writing databases in the iTunes and GNUpod formats. This module is based on the GNUpod script package, written and distributed by Adrian Ulrich, (pab at blinkenlights.ch). URL: http://www.gnu.org/software/gnupod/.

SYNOPSIS

use Mac::iPod::GNUpod;

my $ipod = Mac::iPod::GNUpod->new(mountpoint => '/mnt/ipod';

# Read existing databases
$ipod->read_gnupod;
$ipod->read_itunes;

# Add songs
my $id = $ipod->add_song('/home/music/The Foo Brothers - All Barred Up.mp3');

# Get paths to songs
my $path = $ipod->get_path($id);

# Find the id numbers of existing songs
my @yuck = $ipod->search(artist => 'Yoko Ono');

# Remove songs
$ipod->rm_song(@yuck);

# Write databases
$ipod->write_gnupod;
$ipod->write_itunes;

DESCRIPTION

Mac::iPod::GNUpod is a module designed to let you read the database(s) on your iPod and add and remove songs from it using Perl. It is based on the GNUpod script package written by Adrian Ulrich, which is available at http://www.gnu.org/software/gnupod/. You do NOT need to install the GNUpod scripts in order to use Mac::iPod::GNUpod module. The GNUpod scripts use a plaintext XML database alongside the binary iTunes database used internally by the iPod. This package is capable of reading and writing both the GNUpod database format and the iTunes database format, and can peacefully coexist with both.

Currently this module ONLY works with Unix and Unix-like systems. This probably includes Linux, FreeBSD, MacOS 10.x, and Solaris. OS-independence will come, someday.

Note that the GNUpod database format, the original GNUpod package, and much of the code in this module is (c) Adrian Ulrich.

This module is object oriented. A brief description of the methods needed to perform various tasks follows:

Preparing a blank or corrupted iPod

Your iPod must be formatted and mounted for this module to see it. It can be formatted in FAT32 (Windows) or HFS+ (Mac) format, just so long as your kernel supports it.

If your iPod is fresh out of the box, probably nothing needs to be done, but if its file structure has been corrupted you should initialize it with the "init" method.

If your databases have been lost or corrupted, you may use the "restore" method to find and all of the songs on the iPod and rewrite fresh databases.

Reading and writing databases

You can read and write the iTunes DBs with the "read_itunes" and "write_itunes" methods respectively. Conversely, the GNUpod DBs are accessed with "read_gnupod" and "write_gnupod".

The advantage of the GNUpod DB is that it can be read and written many times faster than the iTunes DB can, so your scripts will run much faster than if you use only the iTunes format. The following scripts are functionally identical:

A:

my $ipod = Mac::iPod::GNUpod->new(mountpoint => '/mnt/ipod');

$ipod->read_itunes;

# Etc ...

$ipod->write_itunes;

B:

my $ipod = Mac::iPod::GNUpod->new(mountpoint => '/mnt/ipod');

$ipod->read_gnupod;

# Etc ...

$ipod->write_gnupod;
$ipod->write_itunes;

However, in benchmarks B runs about twice as fast as A, because the gain of speed reading the GNUpod DB outweighs the cost of the extra write step. (Of course, the significance of this depends on what you do in the middle.)

Adding and removing songs

Add songs with "add_song". Remove songs with "rm_song".

Finding existing songs

You can search for existing songs on your iPod with the "search" method. If you want a list of all songs, use "all_songs".

Working with playlists

There are currently no methods for manipulating playlists. However, the GNUpod DB format makes it easy to create playlists by editing the DB file by hand, and GNUpod playlists are fully supported by this module. Read more about making playlists with GNUpod at http://www.gnu.org/software/gnupod/.

METHODS

new

my $ipod = Mac::iPod::GNUpod->new(mountpoint => '/mnt/ipod');

You create a new iPod object with new(). You must supply key-value pairs as arguments. Most of the time you will only provide the mountpoint key, which indicates where the iPod is mounted. However, if your iPod structure is nonstandard or you wish to test without writing to the actual iPod, you may provide both the gnupod_db and itunes_db keys with values indicating the locations of those files.

mountpoint

my $mnt = $ipod->mountpoint;
$ipod->mountpoint('/mnt/ipod2');

You may use this method to get the current mountpoint for the iPod. If you provide an argument, it sets the mountpoint. When you use this method to set the mountpoint, it automatically sets the itunes_db and gnupod_db, potentially overwriting values you may have previously had there.

itunes_db

my $itunes = $ipod->itunes_db;
$ipod->itunes_db('/home/ipod/testdb');

Use this method to get/set the location of the iTunes DB, if it is different from the default location on the iPod. The default location is {mountpoint}/iPod_Control/iTunes/iTunesDB.

gnupod_db

my $gnupod = $ipod->gnupod_db;
$ipod->gnupod_db('/home/ipod/gnupod.xml');

Use this method to get/set the location of the GNUpod DB, if it is different from the default location. The default location is {mountpoint}/iPod_Control/.gnupod/GNUtunesDB.

allow_dup

$ipod->allow_dup(1);

Get/set the flag stating whether duplicate songs are allowed. If this is false, when you call add_song, this module will check for duplicates in the DB and refuse to add the song if a duplicate is found. If true, no duplicate checking is done. Default is FALSE.

move_files

$ipod->move_files(0);

Get/set the flag stating whether or not to actually (re)move files. If true, when you call add_song or rm_song, the files will actually be copied or deleted. If false, the songs will simply be added or removed from the database, but the file contents of your iPod will not be changed. Default is TRUE.

init

$ipod->init;

Initialize a blank or empty iPod. NOTE: this method only pays attentiont to mountpoint. The only arguments to this method are optional key-value pairs naming options. Currently the only option recognized is france, which causes a limit file to be created if true. (This method is equivalent to the gnupod_INIT.pl script, and the france option is equivalent to the --france command-line option.)

restore

$ipod->restore;

Restore an iPod with corrupted databases. This scans the files on the iPod and rebuilds the databases with the files it finds. (This is equivalent to the gnupod_addsong.pl script with the --restore option.

read_itunes

$ipod->read_itunes;

Read an iTunes database (found at itunes_db) into memory. Note that this will forget any iTunes or GNUpod DB previously read.

write_itunes

$ipod->write_itunes;

Write the contents of memory to the iTunes DB. You should do this at the end of any script if you want your newly added or deleted songs to be available!

read_gnupod

$ipod->read_gnupod;

Read the GNUpod database into memory. This also forgets any databases previously read.

write_gnupod

$ipod->write_gnupod;

Write the GNUpod database. If you want to use any GNUpod tools with the iPod, you should write this db at the end of any script.

add_song

$ipod->add_song('/home/music/The Cure - Fascination Street.mp3');

Add a song to the iPod. Takes one or more arguments, which are the filenames of songs to be added. Currently only MP3 and WAV files are supported, unfortunately, and trying to add a song of another type will bring up a warning. On success, this method returns the new id number(s) of the song, on failure returns undef.

rm_song

$ipod->rm_song(256);

Remove a song from the iPod. Takes one or more arguments, which are the id numbers of the songs to be removed. (You can find the id numbers of songs using the search method.) Returns the number of songs successfully removed.

get_song

$ipod->get_song(256);

Get information about a song. Takes one or more arguments, which are the id numbers of songs. Returns a hash reference (or a list of hash references) with the following keys:

  • id

  • artist

  • album

  • title

  • songnum

  • songs

  • cdnum

  • cds

  • composer

  • year

  • genre

  • fdesc

    A brief description of the file type

  • filesize

  • bitrate

  • time

    Playing time in milliseconds

  • srate

    The frequency in hertz

  • playcount

  • path

    The iPod-formatted path. To get a path in Unix format, use "get_path".

get_path

$path = $ipod->get_path(256);

Get a Unix-formatted path. Takes a list of ids as arguments, returns a list of paths to the songs with those ids. If mountpoint isn't set, returns undef.

BUG/FEATURE: If you try to get the path of a song that was added while move_files was false, you will probably get garbage.

$ipod->search(artist => 'Bob Dylan', title => 'watchtower', nocase => 1);

Search for songs on the iPod. The argument to this function is a hash of key => value pairs that give attributes that the returned songs will match. You may search on any of the keys that appear in the hashref returned from get_song (listed above). You may specify multiple keys, in which case the songs returned must match ALL of the values specified. By default, searches are regexes, which means that searching for artist => 'Cure' will return songs labeled 'Cure', 'The Cure', 'Cure, The', and 'Cured!' You may also use regex metacharacters in your values, like title => '[Tt]he'. A list of id numbers is returned, which can be used with get_song to get the complete information about a song.

You may also alter the behavior of the search by using special optional keys. These keys are:

  • exact

    Only return songs that match the given terms EXACTLY. This tests using eq instead of a regular expression, and so may be much faster.

  • nocase

    Perform a case-insensitive search. This is not mutually exclusive with exact; using both of them searches for things that are identical except with regard to case.

  • nometachar

    Ignore regular expression metacharacters in the values given.

The search results are returned to you sorted by Artist > Album > Cdnum > Songnum > Title.

all_songs

$ipod->all_songs;

Return a list of all of the song ids on the iPod.

NOTES

The GNUpod XML file is expected to be encoded in UTF-8. Other encodings will probably work as well (UTF-16 has been tried successfully), but Your Mileage May Vary.

Playlists that contain <add /> elements that don't have id attributes, <regex /> elements, or <iregex /> elements may produce songs in a different order than the order produced by the GNUpod script mktunes.pl. This is because mktunes.pl simply adds matching songs to the playlist in the order that it finds them, while this module sorts them by artist, album, cdnum, tracknum, and title. What the module does is better :).

TODO

Add methods for manipulating playlists.

Add support for more filetypes, particularly .aac files.

BUGS

Smartplaylist support is untested, so it's entirely possible that this module will munge your smartplaylists (though it tries not to).

Turning move_files on and off during the life of a script may have strange results.

AUTHOR

Original GNUpod scripts by Adrian Ulrich <pab at blinkenlights.ch>. Adaptation for CPAN and much code rewriting by JS Bangs <jaspax@cpan.org>.

VERSION

v. 1.0, Jan 09 2004.

LICENSE

The GNUpod scripts are released under the GNU Public License (GPL). This module adaptation is released under the same terms as Perl itself (a conjunction of the GPL and the Artistic License).

iTunes and iPod are trademarks of Apple. This module is neither written nor supported by Apple.