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.

cpanm Mac::iTunes::Library

perl -MCPAN -e shell
install Mac::iTunes::Library