Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100755 181 lines (170 sloc) 6.923 kB
d4cdd74 @RJ initial checkin
authored
1 <!--#set var="title" value="Playdar - Music Content Resolver" --><!--#include virtual="/inc/header.html" -->
2 <h2>Playdar HTTP API</h2>
3 <p>
44afd03 misc site updates
RJ authored
4 Playdar is a service - it runs a small HTTP server locally on your desktop, and has a HTTP API
d4cdd74 @RJ initial checkin
authored
5 which returns JSON. All the important API calls also support JSONP, so you can call them from the web.
6 If you append <code>&amp;jsonp=mycallback</code> to any webservice call, the result will be JSONP, eg:
7 <code>mycallback({...json response...});</code>
8 </p>
9 <p>
10 The following examples are webservice calls made on my machine (called 'rjhome') and illustrate how you
11 use playdar to find a source for a track - in this case: 'Surfing with the Alien' by 'Joe Satriani'.
12 </p>
13 <p>
14 NB: I'm ignoring album names for now to keep things simple.
15 </p>
16
17
18 <div class="api">
19 <h3>Checking if Playdar is available</h3>
20 <h4>/api/?method=stat</h4>
21 <pre>
22 {
23 "name" : "playdar",
24 "version" : "0.1.0",
25 }
26 </pre>
27 </div>
28
29 <div class="api">
30 <h3>Initiating a search for one song</h3>
31 When you tell Playdar to start resolving a track, it gives you back a query id (qid).
32 You use ths qid to check the status of the query in subsequent calls.
33 <h4>/api/?method=resolve&artist=Joe%20Satriani&album=&track=Surfing%20with%20the%20Alien</h4>
34 <pre>
35 {
36 "qid" : "ccefa69c-0057-11de-a517-0018f32e506c"
37 }
38 </pre>
39 You can also specify a qid yourself by appending
40 <code>&amp;qid=XXX</code>. This can be useful for setting up Javascript
41 callbacks; the <a href="demos/haudio.html">hAudio demo</a> does this.
42 </div>
43
44 <div class="api">
45 <h3>Checking for results (first check)</h3>
46 <h4>/api/?method=get_results&qid=ccefa69c-0057-11de-a517-0018f32e506c</h4>
47 <pre>
48 {
49 "qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
50 "refresh_interval" : 1000,
51 "query" : {
52 "qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
53 "artist" : "Joe Satriani",
54 "album" : "",
55 "track" : "Surfing with the Alien",
56 "mode" : "normal",
57 "solved" : false
58 },
59 "results" : [
60 {
61 "sid" : "ccf63584-0057-11de-900d-0018f32e506c",
62 "artist" : "Joe Satriani",
63 "album" : "",
64 "track" : "Surfing with an alien",
65 "source" : "rjhome",
66 "size" : 12226688,
67 "mimetype" : "audio/mpeg",
68 "bitrate" : 213,
69 "duration" : 459,
70 "score" : 0.91
71 },
72 {
73 "sid" : "ccf636ec-0057-11de-910d-0018f32e506c",
74 "artist" : "Joe Satriani",
75 "album" : "",
76 "track" : "Surfing with the Alien (live)",
77 "source" : "rjhome",
78 "size" : 7905443,
79 "mimetype" : "audio/mpeg",
80 "bitrate" : 190,
81 "duration" : 331,
82 "score" : 0.84
83 }
84 ]
85 }
86 </pre>
87 You can see two potential matches were found on my local machine, 'rjhome'.
88 The query object has a "solved" property set to false. This means Playdar hasn't found a perfect match.
89 The refresh_interval is the suggested number of milliseconds to wait before polling for results again.
90 </div>
91
92 <div class="api">
93 <h3>Checking for results (a second time)</h3>
94 After waiting a a second, you hit the same URL again. You'll receive the same results as before, possibly
95 with new results listed too.
96 <h4>/api/?method=get_results&qid=0b76e87c-0057-11de-b669-0018f32e506c</h4>
97 <pre>
98 {
99 "qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
100 "refresh_interval" : 1000,
101 "query" : {
102 "qid" : "ccefa69c-0057-11de-a517-0018f32e506c",
103 "artist" : "Joe Satriani",
104 "album" : "",
105 "track" : "Surfing with the Alien",
106 "mode" : "normal",
107 "solved" : true
108 },
109 "results" : [
110 {
111 "sid" : "ccf63584-0057-11de-900d-0018f32e506c",
112 "artist" : "Joe Satriani",
113 "album" : "",
114 "track" : <strong>"Surfing with the Alien"</strong>,
115 "source" : "rjlaptop",
116 "size" : 10164410,
117 "mimetype" : "audio/mpeg",
118 "bitrate" : 196,
119 "duration" : 312,
120 "score" : 1.0
121 },
122 {
123 "sid" : "qwkk3584-0057-99de-900d-0018f32e506c",
124 "artist" : "Joe Satriani",
125 "album" : "",
126 "track" : <strong>"Surfing with an alien"</strong>,
127 "source" : "rjhome",
128 "size" : 12226688,
129 "mimetype" : "audio/mpeg",
130 "bitrate" : 213,
131 "duration" : 459,
132 "score" : 0.91
133 },
134 {
135 "sid" : "oob636ec-0157-00de-910d-0018f32e506c",
136 "artist" : "Joe Satriani",
137 "album" : "",
138 "track" : <strong>"Surfing with the Alien (live)"</strong>,
139 "source" : "rjhome",
140 "size" : 7905443,
141 "mimetype" : "audio/mpeg",
142 "bitrate" : 190,
143 "duration" : 331,
144 "score" : 0.84
145 }
146 ]
147 }
148 </pre>
149 This time query.solved is true, because an exact match was found on the machine 'rjlaptop'.
150 Don't bother polling again, once a query is solved Playdar stops trying to find alternative sources.
151 </div>
152
153 <div style="border:1px solid grey; background-color:lightyellow; margin:10px; padding:5px;">
154 <h4>So what actually happened?</h4>
155 <p>
156 When the search was started, the Local Library resolver immediately found 2 matches
157 on my local machine (rjhome). The first check_results request lists those 2 matches.
158 </p>
159 <p>
160 Playdar recognized the query wasn't yet solved, because neither match was a perfect 1.0, so
161 the query was dispatched to other resolver plugins.
162 </p>
163 <p>
164 In this case, my laptop (rjlaptop) was on the same wifi network, and received a UDP broadcast message.
165 It found a match in its Local Library, and responded (it replied over UDP, actually by sending a JSON object).
166 By the time check_results was called a second time, results from the Laptop had arrived, and the query was deemed to be solved.
167 </p>
168 </div>
169
170 <div class="api">
171 <h3>Streaming the file you just found</h3>
172 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.
173
174 <h4>/sid/ccf63584-0057-11de-900d-0018f32e506c</h4>
175
176 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).
177 </div>
178
179 </body>
180 </html>
Something went wrong with that request. Please try again.