Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
executable file 204 lines (182 sloc) 8.43 KB
<!--#set var="title" value="Playdar - Music Content Resolver" --><!--#include virtual="/inc/header.html" -->
<h2>Playdar Javascript Library</h2>
<p>
<a href="http://github.com/jwheare/playdar.js">Get the latest <code>playdar.js</code> from Github</a> - a Javascript library for using the Playdar HTTP API.
<br/>
<span style="color:red; font-weight:bold">Check <a href="http://www.playdarjs.org/" target="pjs">playdarjs.org</a> for up-to-date docs!</span> <br/>
</p>
<p>
Here's how you use it:
</p>
<pre><code>var auth_details = {
name: "Playdar Documentation",
website: "http://<!--#echo var="domain" -->/js.html"
};
var listeners = {
onStat: function (detected) {
if (detected) {
alert('Playdar detected');
} else {
alert('Playdar unavailabled');
}
},
onAuth: function () {
alert('Access to Playdar authorised');
},
onAuthClear: function () {
alert('User revoked authorisation');
}
};
Playdar.setup(auth_details);
Playdar.client.register_listeners(listeners);
Playdar.client.init();
</code></pre>
<p>
This will setup the Playdar library with authorisation credentials for your domain, and register a series of lifecycle event listeners.
</p>
<p>
The library is separated into modules: <code>client</code>, <code>player</code> and <code>status_bar</code>.
</p>
<p>
The <code>client.init()</code> method checks for a running Playdar service. The <code>onStat</code> event is then fired 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>onAuth</code> event is fired and you can start querying Playdar. If a user clicks the "Disconnect" link in the status bar, their authorisation will be revoked and the <code>onAuthClear</code> event is fired.
</p>
<h3 id="auth">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 a URL that points to a <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 id="resolving">Resolving content</h3>
<p>
Searching an available Playdar service for streamable music is a two step process.
</p>
<ol>
<li>Register a results handler.</li>
<li>Call the <code>Playdar.client.resolve()</code> method with artist, track (and optionally album) 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.client.register_results_handler(results_handler);
Playdar.client.resolve("Weezer", "Pinkerton", "Getchoo");
</code></pre>
<p>
Results handlers are called with 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>
<p>
Note: You can alternatively register a default results handler along with the other event listeners. Just include an <code>onResults</code> listener when you call <code>register_listeners</code>. This is sometimes more convenient when you don't need custom handlers for each query.
</p>
<h3 id="autodetection">Autodetection</h3>
<p>
If you have content marked up with the <a href="http://microformats.org/wiki/haudio">hAudio microformat</a>, you can use the <code>Playdar.client.autodetect()</code> method to resolve this content.
</p>
<p>
<code>autodetect</code> takes an optional callback function, that will get called for each track, passing an object containing the artist and track name and the matched element. If the function returns a qid, this will be passed on to the resolve call so you can hook results up to a custom handler.
</p>
<pre><code>var track_handler = function (track) {
// Track object looks like this
// {
// 'name': [track_name String],
// 'artist': [artist_name String],
// 'element': [element DOMElement]
// }
var qid = Playdar.Util.generate_uuid();
track.element.className = 'q' + qid;
return qid;
};
Playdar.client.autodetect(track_handler);
</code></pre>
<h3 id="queries">Query history</h3>
<p>
Each query id passed back from <code>Playdar.client.resolve()</code> calls is stored in <code>Playdar.client.resolve_qids</code> (with the last one in <code>Playdar.client.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.client.get_results(Playdar.client.last_qid);
// Refetch the first query
Playdar.client.get_results(Playdar.client.resolve_qids[0]);
</code></pre>
<h3 id="streaming">Streaming</h3>
<p>
Once you've got a good result, you can construct a streaming url by calling <code>Playdar.client.get_stream_url()</code> on the sid.
</p>
<pre><code>alert("Stream URL: " + Playdar.client.get_stream_url(result.sid));
</code></pre>
<p>
The Playdar library also has a built in wrapper for the <a href="http://www.schillmania.com/projects/soundmanager2/">SoundManager 2 audio library</a>, available through the <code>Playdar.player</code> module. Simply include the <code>soundmanager2.js</code> file, configure the global <code>soundManager</code> object it creates and pass it into the <code>Playdar.setup_player</code> function to initialise the <code>Playdar.player</code> module.
</p>
<pre><code>soundManager.url = '/path/to/soundmanager2_flash9.swf';
soundManager.flashVersion = 9;
soundManager.onload = function () {
Playdar.setup_player(soundManager);
Playdar.client.init();
};
</code></pre>
<p>
Since SoundManager works via a flash object that's loaded asynchronously, you need to wait for the soundManager.onload event before calling <code>Playdar.client.init()</code>, or else you may end up calling SoundManager functions before it's ready.
</p>
<p>
You now have a couple of methods available for registering and playing Playdar streams:
</p>
<pre><code>
// register_stream passes options onto SM createSound
Playdar.player.register_stream(result, {
onstop: function () {
// Scope of 'this' is a SM Sound object
alert('Stopped playing sound: ' + this.sID);
}
});
// Play a specific sound. Calls togglePause on the SM Sound object
Playdar.player.play_stream(sid);
// togglePause on the current sound
Playdar.player.toggle_nowplaying();
// Stop the current playing sound
Playdar.player.stop_current();
// Stops a specific sound if it's now playing
Playdar.player.stop_stream(sid);
// Whether any sound is playing at the moment
Playdar.player.is_now_playing();
</code></pre>
<h3 id="scrobbling">Scrobbling</h3>
<p>
Scrobbling works out of the box with the built in player. If you've implemented your own player, you can use the <code>Playdar.Scrobbler</code> module:
</p>
<pre><code>
var scrobbler = new Playdar.Scrobbler();
scrobbler.start(artist, track, album, duration, track_number, mbid);
scrobbler.pause();
scrobbler.resume();
scrobbler.stop();
</code></pre>
<p>
Calling these according to the will keep the Playdar daemon's audioscrobbler plugin up to date with your playback process and automatically handle the scrobbling protocol.
</p>
<h3 id="utility">Utility Functions</h3>
<p>
The Playdar library defines a few utility functions that are mainly used internally for framework tasks, but you may find them useful:
</p>
<ul>
<li>Playdar.Util.generate_uuid</li>
<li>Playdar.Util.toQueryPair</li>
<li>Playdar.Util.toQueryString</li>
<li>Playdar.Util.mmss (formats seconds as mm:ss)</li>
<li>Playdar.Util.loadjs</li>
<li>Playdar.Util.setcookie</li>
<li>Playdar.Util.getcookie</li>
<li>Playdar.Util.deletecookie</li>
<li>Playdar.Util.get_window_position</li>
<li>Playdar.Util.get_window_size</li>
<li>Playdar.Util.getTarget</li>
</ul>
</body>
</html>