Installation and Requirements

Requirements

PHP >= 5.3
Enabled fopen wrappers and file_get/put_contents
Read/Write access to server (For caching)

How to install

Download latest version of MetaTune
Upload /lib and all it's contents to your web server.
Edit /lib/config.php to fit yout need.
Look at some of the examples or read the FeatureList for help using MetaTune.

Features

Some features includes:

Search for Track/Artist/Album
Lookup detailed/basic info about Track/Artist/Album
Exceptions for error handling.
Caching metadata.
XML Import/Export for quick save/load.
Generate Play Buttons from searches/lookups or objects.
NEW: Now uses namespaces to be more pluggable.

Look at the Wiki for usage and full support. The usage of the regular metatune class can be read below the new Play Button implementation.

New: Namespaces

Metatune now uses namespaces to be more pluggable and play better with other libraries. This means that you'll need PHP version 5.3 or later to be able to use the comming versions of MetaTune. The old version is still available in it's own branch (no-namespace), but will no longer be updated/maintained.

You use metatune as before, but you should update your autoload script and now use $metatune = MetaTune\MetaTune::getInstance() to get the metatune instance variable.

Play Button implementation

The Metatune wrapper now supports the new Spotify Play Button. The play buttons can be generated from the history of your searches/lookups, from an album or track object, a playlist URI or just an array of tracks. See the examples below the settings

Settings

Variable name	Description
playButtonHeight	Height of the player (int). To be large player, the height needs to be 80px more than the width. Default: 330.
playButtonWidth	Width of the player (int). Default: 250.
playButtonTheme	Player theme. Can be `white` or `black`. Default value: `black`.
playButtonView	Player view type. Can be `coverart` or `list`. Default: `list`.

See Spotify documentation for more description of the settings.

Play Button autogenerated from lookup

<?php
    // Get the metatune instance. 
    $spotify = MetaTune\MetaTune::getInstance();
    $spotify->autoAddTracksToPlayButton = true; // Will add all searches for tracks into a list.
    $spotify->playButtonHeight = 330; // For viewing the entire playlist
    $spotify->playButtonTheme = "white"; // Changing theme
    $spotify->playButtonView = "list"; // Changing view
    try
    {
        $tracks = array(
            $spotify->lookup("spotify:track:4kO7mrAPfqIrsKwUOK5BFx"),
            $spotify->lookup("spotify:track:0n49fCjNGsbtNOE6cuWk79"),
            $spotify->lookup("spotify:track:5kQ7CU798Sqm1BWNbYHFMa"),
            $spotify->lookup("spotify:track:57Xjny5yNzAcsxnusKmAfA")
        );

        echo $spotify->getPlayButtonAutoGenerated("My favorites");
    }
    catch (MetaTune\MetaTuneException $ex)
    {
        die("<pre>Error\n" . $ex . "</pre>");
    }
?>

Result

Play Button from album object.

<?php
    // Get the metatune instance. 
    $spotify = MetaTune\MetaTune::getInstance();
    try
    {
        // Need to be detailed, to have all tracks. (second argument true)
        $album = $spotify->lookupAlbum("spotify:album:6MBuQugGuX7VMBX0uiBnAQ", true);
        echo $spotify->getPlayButtonFromAlbum($album);
    }
    catch (MetaTune\MetaTuneException $ex)
    {
        die("<pre>Error\n" . $ex . "</pre>");
    }
?>

Result

More examples in the examples directory.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

SPOTIFY Disclaimer This product uses a SPOTIFY API but is not endorsed, certified or otherwise approved in any way by Spotify. Spotify is the registered trade mark of the Spotify Group.

Usage

You can pretty much do anything in the Spotify Metadata API with this library, and then some. Below you'll find all the features and some short example of how to use them.

In common for all the features, it requires a object of the MetaTune-class.

<?php
$spotify = MetaTune\MetaTune::getInstance();
?>

Search for Track/Artist/Album

You can search for everything in MetaTune. Not only tracks, but albums and artists aswell. In this example however, I will limit myself to just showing search for artists. The code would essentially be the same.

Method overview	Description
searchTrack()	Search for tracks. Will return an array of tracks
searchArtist()	Search for artists. Will return an array of artists
searchAlbum()	Search for albums. Will return an array of albums

<?php
// We have the MetaTune-object; $spotify

// First we take a search
$trackResults = $spotify->searchTrack ("Superfamily");

if(count($trackResults) > 0) {
    $out = count($trackResults) . " results \n<ul>";
    foreach($trackResults as $track) {
          // $track is now an object of the class Track. 
          $out . "\t<li>{$track}</li>\n";
    }
    echo $out . "</ul>";
} else {
    echo "No results";
}
?>

Spotify advanced search syntax

MetaTune supports all of Spotify's advanced search queries. See more information on Spotify Advanced Search Syntax.

Lookup detailed/basic info about Track/Artist/Album

Some times all you got is a Spotify URI, such as spotify:track:4CwcvWeCi2rFcLPIJCOwXw, and want to lookup detailed/basic information about a Track/Artist/Album.

Method overview	Description
lookupTrack()	Get all information about a track. Popularity, duration, artist, album, number and disc in album
lookupArtist()	Get basic information about an artist. This includes name and popularity
lookupArtistDetailed()	Get detailed information about an artist. This includes basic info + all the artist's albums
lookupAlbum()	Get basic info about an album. This includes release date, popularity, name.
lookupAlbumDetailed()	Get detailed information about an album. This includes basic info + all the album's tracks.
lookup()	Uses the Spotify URI to determine what to look up.

<?php
// We have the MetaTune-object; $spotify

// Get all information about a track!
$track = $spotify->lookup("spotify:track:4CwcvWeCi2rFcLPIJCOwXw");

// Print all results
echo "<pre>" . print_r($track, 1) . "</pre>";
?>

Exceptions

But what if the Spotify URI is in a wrong format or is not found? Then we have exceptions to tell us. Lets try to use exceptions in the example from lookup.

<?php
// We have the MetaTune-object; $spotify

try {
   // Get all information about a track!
   $track = $spotify->lookup("spotify:track:WRONG_URI");
   // all lookup-methods throws a MetaTuneException. We'll try to catch one. 

   // Print all results
   echo "<pre>" . print_r($track, 1) . "</pre>";
} catch (MetaTuneException $ex) {
   echo "Could not retrive information: " . $ex->getMessage();
}
?>

Caching

All access to the Spotify-servers will be cached as long as certain constants are set in the MetaTune class. Caching is activated per default.

The caching works by saving files locally on your server with this format: path/to/dir/<YOUR_PREFIX>_<MD5("THE_SEARCH_QUERY")>.xml

Search query is stripped of some non-alphanumerical signs and trimmed.

The Spotify servers only send information on requests as long as If-Modified-Since header field doesn't kick in. If a cache exists of a search the header field would be appended to the file request, and Spotify won't send you any data. All this happens automaticly as long as you have caching activated.

To activate/deactivate or change cache settings in any way, you can do this at the top of MetaTune

<?php
    const CACHE_DIR = 'lib/cache/'; // Cache directory (must be writable)
    const USE_CACHE = false; // Should caching be activated?
    const CACHE_PREFIX = "METATUNE_CACHE_"; // prefix for cache-files. 
?>

XML Import/Export

With XML import and/or export you can easily create XML structure of your searches. All ready to be saved to files and/or database (XML-types).

Here's an example of usage:

<?php
// ***Test for array of tracks***
$trackList = $spotify->searchTrack("Superfamily");
$tracksXML = $spotify->generateXML($trackList);
            
// This should now be the same as $trackList
$tracksImport = $spotify->parseXMLTracks($tracksXML);
// Demo print to check correct content
echo "<pre>" . print_r($tracksImport, 1) . "</pre>";
?>

In this case $tracksXML will contain something like:

<?xml version="1.0" encoding="UTF-8"?>
<tracks>
	<track href="spotify:track:3BbfQLpcj0BfjM5rq8Ioj9"><![CDATA[]]>
		<name><![CDATA[The Radio Has Expressed Concerns About What You Did Last Night]]></name>
		<artist href="spotify:artist:5ObUhLdIEbhEqVCYxzVQ9l"><![CDATA[]]>
			<name><![CDATA[Superfamily]]></name>
			<albums><![CDATA[]]></albums>
			<popularity><![CDATA[0]]></popularity>
		</artist>
		<album href="spotify:album:2PABf16wrJQau7JuDTqTzx"><![CDATA[]]>
			<name><![CDATA[The Radio Has Expressed Concerns About What You Did Last Night]]></name>
			<artist href="spotify:artist:5ObUhLdIEbhEqVCYxzVQ9l"><![CDATA[]]>
				<name><![CDATA[Superfamily]]></name>
				<albums><![CDATA[]]></albums>
				<popularity><![CDATA[0]]></popularity>
			</artist>
			<tracks><![CDATA[]]></tracks>
			<popularity><![CDATA[0]]></popularity>
			<released><![CDATA[2007]]></released>
		</album>
		<length><![CDATA[245.013]]></length>
		<popularity><![CDATA[0.56061]]></popularity>
		<track-number><![CDATA[1]]></track-number>
		<disc-number><![CDATA[0]]></disc-number>
	</track>
	
	[. . .]

</tracks>

And $tracksImport will contain your original data:

Array
(
    [0] => Track Object
        (
            [uri:Track:private] => spotify:track:3BbfQLpcj0BfjM5rq8Ioj9
            [title:Track:private] => The Radio Has Expressed Concerns About What You Did Last Night
            [artist:Track:private] => Artist Object
                (
                    [uri:Artist:private] => spotify:artist:5ObUhLdIEbhEqVCYxzVQ9l
                    [name:Artist:private] => Superfamily
                    [popularity:Artist:private] => 0
                    [albums:Artist:private] => Array
                        (
                        )

                    [spotifyBase] => http://open.spotify.com/
                )

            [album:Track:private] => Album Object
                (
                    [uri:Album:private] => spotify:album:2PABf16wrJQau7JuDTqTzx
                    [name:Album:private] => The Radio Has Expressed Concerns About What You Did Last Night
                    [release:Album:private] => 2007
                    [popularity:Album:private] => 0
                    [artist:Album:private] => Artist Object
                        (
                            [uri:Artist:private] => spotify:artist:5ObUhLdIEbhEqVCYxzVQ9l
                            [name:Artist:private] => Superfamily
                            [popularity:Artist:private] => 0
                            [albums:Artist:private] => Array
                                (
                                )

                            [spotifyBase] => http://open.spotify.com/
                        )

                    [tracks:Album:private] => Array
                        (
                        )

                    [spotifyBase] => http://open.spotify.com/
                )

            [length:Track:private] => 245.013
            [popularity:Track:private] => 0.56061
            [trackNr:Track:private] => 1
            [discNr:Track:private] => 0
            [spotifyBase] => http://open.spotify.com/
        )
	
	[. . . ]

)

See more examples of XML import/export in xmltest.php

mikaelbr/metatune

Installation and Requirements

Requirements

How to install

Features

New: Namespaces

Play Button implementation

Settings

Play Button autogenerated from lookup

Result

Play Button from album object.

Result

Usage

Search for Track/Artist/Album

Spotify advanced search syntax

Lookup detailed/basic info about Track/Artist/Album

Exceptions

Caching

XML Import/Export