Mac::iTunes::Library::XML(3p)

NAME
Mac::iTunes::Library::XML - Perl extension for parsing an iTunes XML library

SYNOPSIS
  use Mac::iTunes::Library::XML;

  my $library = Mac::iTunes::Library::XML->parse( 'iTunes Music Library.xml' );
  print "This library has only " . $library->num() . "item.\n";

DESCRIPTION
A parser to read an iTunes XML library and create a Mac::iTunes::Library object.

  NOTES ON iTUNES XML FORMAT
Whereas someone who understands how to use XML would write this:

  <Playlists>
      <Playlist>
          <Name>Library</Name>
          <Playlist ID>7</Playlist ID>
          <Visible>false</Visible>
          <Playlist Items>
              <Track ID>14</Track ID>
              <Track ID>21</Track ID>
              <Track ID>28</Track ID>
          </Playlist Items>
      </Playlist>
  </Playlists>

Instead, we get this from iTunes:

  <key>Playlists</key>
  <array>
      <dict>
          <key>Name</key><string>Library</string>
          <key>Master</key><true/>
          <key>Playlist ID</key><integer>201</integer>
          <key>Playlist Persistent ID</key><string>707F6A2CE6E601F5</string>
          <key>Visible</key><false/>
          <key>All Items</key><true/>
          <key>Playlist Items</key>
          <array>
              <dict>
                  <key>Track ID</key><integer>173</integer>
              </dict>
              <dict>
                  <key>Track ID</key><integer>175</integer>
              </dict>
              <dict>
                  <key>Track ID</key><integer>177</integer>
              </dict>
          </array>
      </dict>
  </array>

The iTunes XML format doesn't make it clear where the parser is in the library, so to parser must keep track itself; this is done with the @stack array in XML.pm, which is used to set $depth in each of the callback methods.

Here are the elements that can be found at any depth. The depths are indexed with 0 being outside of any element (before the very first start_element call), 1 would be within a single element (<plist> being the outermost of an iTunes library file), 2 within the second element (<dict>), and so on. Note that because the iTunes XML library format is so awesome, the name of a key (contained within a <key> element, e.g. <key>Features</key>) occurs at the same level as it's value (e.g. <integer>5</integer>). Those XML elements (e.g. <key>, <integer) occur at some level n, but the data which we care about (e.g. 'Features', 5) are contained at level n+1.

•   Zeroth

       - <plist> element with version attribute

•   First

       - Outermost <dict> element

•   Second

       - <key> containing library metadata key name
       - <integer> containing library metadata
       - <string> containing library metadata
       - <true /> containing library metadata
       - <false /> containing library metadata

•   Third

       - Library metadata (major/minor version, application version, etc.)
       - Tracks and Playlists keys
       - <dict> containing library tracks
       - <array> containing playlists

•   Fourth

       - <key> with track ID
       - <dict> containing track data

•   Fifth

       - <key> containing track/playlist metdata key name
       - <integer> containing track/playlist metdata key name
       - <string> containing track/playlist metdata key name
       - <date> containing track/playlist metdata key name

•   Sixth

       - <dict> containing a single playlist track

•   Seventh

       - <key> containing the string "Track ID"
       - <integer> containing a track ID

EXPORT
None by default.

METHODS

  parse( $libraryFile )
Parses an iTunes XML library and returns a Mac::iTunes::Library object.

SEE ALSO
Mac::iTunes::Library::Item, Mac::iTunes::Library, Mac::iTunes::Library::Playlist

AUTHOR
Drew Stephens <drew@dinomite.net>, http://dinomite.net

CONTRIBUTORS

•   Mark Grimes <mgrimes@cpan.org>, <http://www.peculiarities.com>

•   Garrett Scott <garrett@gothik.org>, <http://www.gothik.org>

SOURCE REPOSITORY
http://mac-itunes.googlecode.com

SVN INFO
$Revision: 90 $

COPYRIGHT AND LICENSE
Copyright (C) 2007-2008 by Drew Stephens

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 372:
    Unknown directive: =over4

Around line 374:
    '=item' outside of any '=over'