Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
executable file 136 lines (123 sloc) 5.4 KB
<!--#set var="title" value="Playdar - Music Content Resolver" --><!--#include virtual="/inc/header.html" -->
<h2>Playdar Javascript Library</h2>
<p>
<code>playdar.js</code> is a Javascript library for interacting with the Playdar HTTP API.
</p>
<p>
Here's how you use it:
</p>
<pre><code>var auth_details = {
name: "Playdar Documentation",
website: "http://www.playdar.org/js.html"
};
var handlers = {
stat: function (detected) {
if (detected) {
alert('Playdar detected');
} else {
alert('Playdar unavailabled');
}
},
auth: function () {
alert('Access to Playdar authorised');
},
clear_auth: function () {
alert('User revoked authorisation');
}
};
var playdar = new Playdar(auth_details, handlers);
playdar.init();
</code></pre>
<p>
This will setup a <code>Playdar</code> instance with <code>stat</code>, <code>auth</code> and <code>clear_auth</code> handlers.
</p>
<p>
The <code>init()</code> method checks for a running Playdar service. The <code>stat</code> handler is then triggered and if Playdar is detected a status bar appears at the bottom of the window. A user is then able to allow a domain to make use of Playdar. After user authorisation, the <code>auth</code> handler is triggered and you can start querying Playdar. If a user clicks the "Disconnect" link in the status bar, their authorisation will be revoked.
</p>
<h3>Advanced authorisation</h3>
<p>
If you'd like to streamline the auth process, you can include a <code>receiverurl</code> in the <code>auth_details</code> object. This should be the URL to the <a href="/demos/playdarauth.html">playdarauth.html</a> file hosted on your domain that receives messages through the location hash and passes it back to a <code>window.opener</code>. An auth token will be sent to this URL after user authorisation so that Playdar can set an auth cookie on your domain.
</p>
<h3>Resolving content</h3>
<p>
Searching an available Playdar service for streamable music is a two step process.
</p>
<ol>
<li>Register a <code>results</code> callback handler.</li>
<li>Call the <code>resolve()</code> method with artist, album and track names.</li>
</ol>
<pre><code>var results_handler = function (response, final_answer) {
if (final_answer) {
if (response.results.length) {
alert('Found results: ' + response.results.length);
} else {
alert('No results');
}
}
};
playdar.register_results_handler(results_handler);
playdar.resolve("Weezer", "Pinkerton", "Getchoo");
</code></pre>
<p>
Note: You can alternatively register the results handler in the <code>new Playdar()</code> constructor, just include it in the <code>handlers</code> object as <code>results</code> along with <code>stat</code> and <code>auth</code>. All handlers passed into the constructor will be passed through <code>register_results_handler</code> internally.
</p>
<p>
The <code>results</code> handler takes two arguments:
</p>
<ul>
<li><code>response</code> <i>(JSON)</i> from the <code>get_results</code> API method.</li>
<li><code>final_answer</code> <i>(bool)</i> indicating whether polling has ended.</li>
</ul>
<p>
The <code>register_results_handler()</code> and <code>resolve()</code> methods also take an optional final argument, <code>qid</code> which lets you define your own query id, and define custom handlers for content resolution.
</p>
<h3>Query history</h3>
<p>
Each <code>resolve()</code> query id is stored in <code>playdar.resolve_qids</code> (with the last one in <code>playdar.last_qid</code> for convenience). So you can easily refetch results by calling <code>get_results()</code> yourself:
</p>
<pre><code>// Refetch the last query
playdar.get_results(playdar.last_qid);
// Refetch the first query
playdar.get_results(playdar.resolve_qids[0]);
</code></pre>
<h3>Streaming</h3>
<p>
Once you've got a good result, you can build a streaming url wth <code>get_stream_url()</code>.
</p>
<pre><code>var result = response.results[0];
alert("Stream URL: " + playdar.get_stream_url(result.sid));
</code></pre>
<p>
<code>playdar.js</code> also has a built in wrapper for the <a href="http://www.schillmania.com/projects/soundmanager2/">SoundManager 2 audio library</a>. Simply include the <code>soundmanager2.js</code> file, setup the global <code>soundManager</code> object it creates and register it with your playdar object:
</p>
<pre><code>soundManager.url = '/path/to/soundmanager2_flash9.swf';
soundManager.flashVersion = 9;
soundManager.onload = function () {
playdar.init();
};
playdar.soundmanager = soundManager;
</code></pre>
<p>
To avoid a race condition where soundmanager is ready but playdar isn't or vice versa, wait until SM has loaded before calling <code>init</code> on playdar.
</p>
<p>
You now have a couple of methods available for registering and playing Playdar streams:
</p>
<pre><code>// Register a set of result sids for streaming with SoundManager
// register_stream passes options onto SM createSound
for (var i = 0; i < results.length; i++) {
playdar.register_stream(results[i], {
onstop: function () {
// 'this' refers to the SM Sound object
alert('Stopped playing sound: ' + this.sID);
}
});
}
// Play a registered sid
// play_stream calls togglePause on the SM Sound object
function click_handler (sid) {
playdar.play_stream(sid);
}
</code></pre>
</body>
</html>