/ 
LWP-UserAgent-iTMS_Client-0.22
/ LWP::UserAgent::iTMS_Client

NAME

LWP::UserAgent::iTMS_Client - libwww-perl client for Apple iTunes music store

SYNOPSIS

use LWP::UserAgent::iTMS_Client;

# search the Store   
my $ua = LWP::UserAgent::iTMS_Client->new;

my $listings = $ua->search( song => 'apples' );
foreach my $song (@{$listings}) { print $song->{itemName} }

$listings = $ua->search(
  media => 'music, 
  artist => 'Vangelis', 
  song => 'long', 
  genre => 'Electronic'
);
foreach my $a (@{$results2}) { 
  foreach (sort keys %$a) { print "$_ => ", $a->{$_}, "\n" } 
}

# get my authorization keys under iTMS old versions
my $ua = new LWP::UserAgent::iTMS_Client(
    account_type => 'apple',
    user_id => 'name@email.org',
    password => 'password',
);
$ua->retrieve_keys_from_iTMS;

DESCRIPTION

This perl module implements a user agent which can interact with the Apple iTunes Music Store (iTMS). For example, this module could allow a perl program that would automatically get samples of new albums by a particular artist, or buy everything on a Top Ten list weekly.

LWP::UserAgent::iTMS_Client is a sub-class of LWP::UserAgent and implements the methods of UserAgent, but does so using Apple's officially undocumented protocols. Because these protocols change with revisions to iTunes, the modules may occasionally lag Apple's changes until this module, too, is updated.

METHODS

new
# set up new instance for anon search
my $ua = LWP::UserAgent::iTMS_Client->new;

# set up for login
my $ua = new LWP::UserAgent::iTMS_Client(
    account_type => 'apple',
    user_id => 'name@email.org',
    password => 'password',
    gu_id => 'CF1121F1.13F11411.11B1F151.1611F111.1DF11711.11811F19.1011F1A1',
);

Create a new LWP::UserAgent::iTMS_Client object.
Options are:

account_type
    Either 'apple' or 'aol', this determines where the authentication 
    password is to be checked--on an AOL user database or with Apple's 
    accounts.
    
user_id (required)
    User name, usually an email address.
    
ds_id 
    A user identifier used by iTMS for authentication. May be useful if
    accessing local key files.
    
gu_id 
    A user's machine identifier used by iTMS for authorization.
    
password (required)
    The user's own (user typed, in iTunes) password.
    
error_handler
    Default error handling is to croak(). This allows alternate behavior by
    passing the name of a routine which takes a single scalar argument, 
    the error message.

deauth_wait_secs
    This is a mandatory wait before deauthorizing a machine after
    a virtual machine is used to get user keys.
  
country 
    The country where the user's account is based. Determines purchase 
    currency, etc.

home_dir 
    The directory where the drms keys subdirectory is located. Generally it
    may be best to allow the module to locate this by default.
    
maybe_dot 
    Determines if the drms subdirectory is called '.drms' or 'drms', again,
    best left to the default.

path_sep
    Generally '/'. Path separator for the local OS.
    
download_dir
    The default location for downloaded music files,
request
$ua->request('http://phobos.apple.com/WebObjects/MZSearch.woa/wa/com.apple.jingle.search.DirectAction/search', 
  '?term=beautiful balloon');

Sends a request to the iTunes Music Store. The first argument is the URL, 
the second is the parameter string.Handles encryption and compression, 
then returns an HTTP::Response object, as an overloaded method of the base 
LWP::UserAgent. Generally not called directly unless you know what you 
are doing. 
 my $results = $ua->search( media => music, song => 'Day', composer => 'Lennon' );
 print "Results for song => Day, composer => Lennon:\n";
 foreach my $a (@{$results1}) { 
     foreach (sort keys %$a) { print "$_ => ", $a->{$_}, "\n" } 
 }

 my $results2 = $ua->search( media => music, artist => 'Vangelis', song => 'long ago' );
 print "\nResults for artist => Vangelis, song => long ago:\n";
 foreach my $a (@{$results2}) { 
     foreach (sort keys %$a) { print "$_ => ", $a->{$_}, "\n" } 
 }
 
 my $results2 = $ua->search( media => TV, show => 'Heroes' );
 print "\nResults for TV show Heroes:\n";
 foreach my $a (@{$results2}) { 
     foreach (sort keys %$a) { print "$_ => ", $a->{$_}, "\n" } 
 }
 

 The following types of searches should be supported: album, artist, 
 composer, song, genre, all. If used, 'all' should override other 
 specifications.
 
 In addtion, varios iTumes 7.0+ media types are suppored in searches, 
 though the default is usallly still to just search music. 
 These are supported via the key 
 
 media => media type,
 
 where media is one of [ all,  music, podcast, TV, movie, video ].
 
 The search terms generally vary by media type.  See the following structure for details:

 my %search_topics = (
     album       => 'albumTerm',         # music and videos
     artist      => 'artistTerm',        # music and videos
     composer    => 'composerTerm',      # music and videos
     song        => 'songTerm',          # music and videos
     genre       => 'genreIndex',        # music and videos
     author      => 'authorTerm',        # book and podcast
     media       => 'media',             # actually for media type specifications
     title       => 'titleTerm',         # book and podcast
     director    => 'directorTerm',      # movies
     producer    => 'producerTerm',      # movies
     movie       => 'movieTerm',         # movies only
     description => 'descriptionTerm',   # TV and podcast
     show        => 'showterm',          # TV only
 );
login
Log in to the iTMS, using parameters given in new().
retrieve_keys_from_iTMS
$ua->retrieve_keys_from_iTMS;

Get the keys from the Store. Attempts to be compatible with key locations 
used by default by the Videolan project's media player (FairKeys 
compatibility). This should generally be used with a gu_id known by the 
user, preferentially one given as a 
gu_id => 11111111.11111111.11111111.11111111.11111111.11111111
(6 8-digit hex numbers separated by periods) argument to new.
deauthorize_gu_id
$ua->deauthorize_gu_id($id);

Deauthorize the machine used to get the keys.
retrieve_keys_with_temp_id
  $ua->retrieve_keys_with_temp_id;
  $ua->retrieve_keys_with_temp_id(\&callback);

  Create a temporary machine ID (you need to have one of your 5 machine 
  usages for iTunes available), get the keys with this virtual machine's 
  authorization, then deauthorize. Note that since this may result in an 
  additional key being created, you should limit the number of times you 
  do this. If you generally only purchase music on one or two machines 
  that do not change ID's, and only play copied music on your other 
  (iPod?) machines, once downloading your keys may be enough. The program
  will display a progress bar betwwen key retrieval and deauthorization. The
  optional argument is to allow custom display of the wait period, which by
  default prints to stdout. The optional callback routine must accept a single 
  argument which may have the values 'begin', an integer between 0 and 100, 
  and 'end'.
purchase
  $ua->purchase($song_id); 

  Purchase and download a song, by item id number or 'itemId' as a search 
  result (use search to find the song and then get the itemId from the 
  search result data structure, or "dict" hash reference). Should call the 
  B<download_songs> method automatically after the purchase.
download_songs
$ua->download_songs;

Download any songs pending for the user, including those just purchased. In order 
to download songs purchased but not immediately downloaded, should be called 
after B<pending_downloads> is called.
pending_downloads
my $hashref = $ua->pending_downloads;

Get a hashref, keyed by downloadKey, of purchased, but not yet downloaded 
songs. This data is also stored in the object, so that B<download_songs>
may be called after this method call to download the songs found.
notify_downloads_done
$qt->notify_downloads_done;

Notify iTMS that downloads of purchased music during the login session 
have been successful. After such notification, songs may not be available
to be re-downloaded as entries with B<pending_downloads>.
preview
$ua->preview($song);

Download a preview for a song entry, if available. $song is a reference
to the hash of data for a song returned by the search method.

BUGS

This code is not yet compatible with logins under iTunes 6.0+, 
but support for more recent versions may be pending.

The searches under 'artist' may be crippled, due to a server issue.  It seems 
that the artist name is seldom presently part of song metadata. There is a 
numeric artistId entry, but I don't currently have an index of artists 
for lookup.

Overuse of the purchase routine (once the module is again working under version 7+ )
might allow you to spend more on music than you intended. This might be a bug, 
from the perspective of your budget. (Enjoy :).

SEE ALSO

LWP::UserAgent

LWP::UserAgent

AUTHOR

William Herrera ( wherrera@skylightview.com ).

SUPPORT

Questions, feature requests and bug reports should go to <wherrera@skylightview.com>.

COPYRIGHT

Copyright (c) 2003-2007 William Herrera. All rights reserved.  
This program is free software; you can redistribute it and/or modify 
it under the same terms as Perl itself.