Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 1bfedc80af
Fetching contributors…

Cannot retrieve contributors at this time

executable file 181 lines (170 sloc) 6.923 kb
<!--#set var="title" value="Playdar - Music Content Resolver" --><!--#include virtual="/inc/header.html" -->
<h2>Playdar HTTP API</h2>
<p>
Playdar is a service - it runs a small HTTP server locally on your desktop, and has a HTTP API
which returns JSON. All the important API calls also support JSONP, so you can call them from the web.
If you append <code>&amp;jsonp=mycallback</code> to any webservice call, the result will be JSONP, eg:
<code>mycallback({...json response...});</code>
</p>
<p>
The following examples are webservice calls made on my machine (called 'rjhome') and illustrate how you
use playdar to find a source for a track - in this case: 'Surfing with the Alien' by 'Joe Satriani'.
</p>
<p>
NB: I'm ignoring album names for now to keep things simple.
</p>
<div class="api">
<h3>Checking if Playdar is available</h3>
<h4>/api/?method=stat</h4>
<pre>
{
"name" : "playdar",
"version" : "0.1.0",
}
</pre>
</div>
<div class="api">
<h3>Initiating a search for one song</h3>
When you tell Playdar to start resolving a track, it gives you back a query id (qid).
You use ths qid to check the status of the query in subsequent calls.
<h4>/api/?method=resolve&artist=Joe%20Satriani&album=&track=Surfing%20with%20the%20Alien</h4>
<pre>
{
"qid" : "ccefa69c-0057-11de-a517-0018f32e506c"
}
</pre>
You can also specify a qid yourself by appending
<code>&amp;qid=XXX</code>. This can be useful for setting up Javascript
callbacks; the <a href="demos/haudio.html">hAudio demo</a> does this.
</div>
<div class="api">
<h3>Checking for results (first check)</h3>
<h4>/api/?method=get_results&qid=ccefa69c-0057-11de-a517-0018f32e506c</h4>
<pre>
{
"qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
"refresh_interval" : 1000,
"query" : {
"qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
"artist" : "Joe Satriani",
"album" : "",
"track" : "Surfing with the Alien",
"mode" : "normal",
"solved" : false
},
"results" : [
{
"sid" : "ccf63584-0057-11de-900d-0018f32e506c",
"artist" : "Joe Satriani",
"album" : "",
"track" : "Surfing with an alien",
"source" : "rjhome",
"size" : 12226688,
"mimetype" : "audio/mpeg",
"bitrate" : 213,
"duration" : 459,
"score" : 0.91
},
{
"sid" : "ccf636ec-0057-11de-910d-0018f32e506c",
"artist" : "Joe Satriani",
"album" : "",
"track" : "Surfing with the Alien (live)",
"source" : "rjhome",
"size" : 7905443,
"mimetype" : "audio/mpeg",
"bitrate" : 190,
"duration" : 331,
"score" : 0.84
}
]
}
</pre>
You can see two potential matches were found on my local machine, 'rjhome'.
The query object has a "solved" property set to false. This means Playdar hasn't found a perfect match.
The refresh_interval is the suggested number of milliseconds to wait before polling for results again.
</div>
<div class="api">
<h3>Checking for results (a second time)</h3>
After waiting a a second, you hit the same URL again. You'll receive the same results as before, possibly
with new results listed too.
<h4>/api/?method=get_results&qid=0b76e87c-0057-11de-b669-0018f32e506c</h4>
<pre>
{
"qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
"refresh_interval" : 1000,
"query" : {
"qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
"artist" : "Joe Satriani",
"album" : "",
"track" : "Surfing with the Alien",
"mode" : "normal",
"solved" : true
},
"results" : [
{
"sid" : "ccf63584-0057-11de-900d-0018f32e506c",
"artist" : "Joe Satriani",
"album" : "",
"track" : <strong>"Surfing with the Alien"</strong>,
"source" : "rjlaptop",
"size" : 10164410,
"mimetype" : "audio/mpeg",
"bitrate" : 196,
"duration" : 312,
"score" : 1.0
},
{
"sid" : "qwkk3584-0057-99de-900d-0018f32e506c",
"artist" : "Joe Satriani",
"album" : "",
"track" : <strong>"Surfing with an alien"</strong>,
"source" : "rjhome",
"size" : 12226688,
"mimetype" : "audio/mpeg",
"bitrate" : 213,
"duration" : 459,
"score" : 0.91
},
{
"sid" : "oob636ec-0157-00de-910d-0018f32e506c",
"artist" : "Joe Satriani",
"album" : "",
"track" : <strong>"Surfing with the Alien (live)"</strong>,
"source" : "rjhome",
"size" : 7905443,
"mimetype" : "audio/mpeg",
"bitrate" : 190,
"duration" : 331,
"score" : 0.84
}
]
}
</pre>
This time query.solved is true, because an exact match was found on the machine 'rjlaptop'.
Don't bother polling again, once a query is solved Playdar stops trying to find alternative sources.
</div>
<div style="border:1px solid grey; background-color:lightyellow; margin:10px; padding:5px;">
<h4>So what actually happened?</h4>
<p>
When the search was started, the Local Library resolver immediately found 2 matches
on my local machine (rjhome). The first check_results request lists those 2 matches.
</p>
<p>
Playdar recognized the query wasn't yet solved, because neither match was a perfect 1.0, so
the query was dispatched to other resolver plugins.
</p>
<p>
In this case, my laptop (rjlaptop) was on the same wifi network, and received a UDP broadcast message.
It found a match in its Local Library, and responded (it replied over UDP, actually by sending a JSON object).
By the time check_results was called a second time, results from the Laptop had arrived, and the query was deemed to be solved.
</p>
</div>
<div class="api">
<h3>Streaming the file you just found</h3>
To stream the result, you need the <code>sid</code> from the result object. You always receive the result by making an HTTP request to the Playdar service it came from. Playdar takes care of fetching and serving the file to you - it might be coming from your local disk, maybe over the network from your laptop, or something else entirely. Finding and accessing songs is all taken care of by induvidual resolver plugins. The important thing is you don't need to worry - it's just a local HTTP request using the <code>sid</code> from the result you want, which is almost always the result with the highest score.
<h4>/sid/ccf63584-0057-11de-900d-0018f32e506c</h4>
This will send the correct HTTP headers for mimetype and content-length, and appear like a traditional file download. These URLs can be passed directly to any media player and streamed, or to a flash swf provided it's flash compatible (ie, mp3).
</div>
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.