Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
Playdar is a music content resolver, written in Erlang, MIT licensed.
It's modular and can be extended using resolver scripts in any language.
It has an HTTP API to answer the question "can i play this song?".
If yes, you get a localhost URL that will play the song, from whichever souce
playdar resolved it to (plugins do the resolving).

Read on for build instructions and an "Understanding Playdar" tutorial.
More information and binary installers / packages can be found at:

To build all the erlang code:

    $ make

To build the collection scanner (needs taglib, g++):

    $ make scanner


    $ ./playdarctl start-debug

In another terminal you can now do:

    $ ./playdarctl numfiles
    $ ./playdarctl scan "/path/to/music"
    $ ./playdarctl numfiles

Then check out http://localhost:60210/ and

Understanding Playdar

The core playdar daemon is a generic content-resolver engine.
It contains a simple http server (Mochiweb), a resolver infrastructure, external
module loader (plugins) and configuration management. 

Playdar core allows you to dispatch queries and check query status, but by 
itself it can't resolve content. This is all handled by plugins.

Clients talk to Playar using the HTTP API. JSON is used for everything.

Resolver Queries
All queries passed to Playdar are simply JSON objects of any shape or size. 
Playdar checks for a "qid" propery - a GUID for the query, in each object,
but nothing else - it's up to the plugins to decode the query objects.

If a plugin doesn't recognise a query it simply ignores it.

The following examples are similar in syntax to how Playdar is built, but may
not necessarily be exactly correct. They serve to illustrate the query

Music Query Example
The query object:
    "qid" : "XXX123",
    "artist" : "Big Bad Sun",
    "track"  : "Sweet Melissa"

This is a simple query for a specific song. In this case, the default plugins
that ship with Playdar know how to handle it - because we're using Playdar as
a music content resolver. The library plugin will search your disk and respond
with a result if you have a copy of the song being searched for:
A result object:
    "sid" : "YYY456",
    "qid" : "XXX123",
    "result" : {
        "url" : "/path/to/sweet_melissa.mp3",
        "bitrate" : 128,
        "duration" : 283,
        "artist" : "Big Bad Sun",
        "track" : "Sweet Melissa (live)",
        "score" : 0.89
In the the above example, the library plugin reports a result for the query 
with a score of 0.89 - it found a live version - but close enough.
The "sid" propery is a GUID for the result.

Resolvers can report multiple result objects for any query.

Non-music Example
Depending on the plugins loaded, Playdar could be used to resolve anything.
Here's a fictional example query for an academic essay:
    "qid"    : "XXX789",
    "author" : "Jonathan swift",
    "year"   : 1729,
    "title"  : "a modest propsal"
... and if you have a resolver plugin that could search for essays and academic
papers, it might respond like this:
    "sid"    : "YYY123",
    "qid"    : "XXX789",
    "result" : {
        "author" : "Jonathan Swift",
        "year"   : 1729,
        "title"  : "A Modest Proposal",
        "score"  : 1.00,
        "category"   : "humour",
        "url"    : ""

In this example, the resolver matched the query to an essay posted on the web
instead of the local filesystem. 

Custom Protocols
Playdar ships with support for reading content from http:// and file:// URLs.
That is to say support for those protocols is implemented by plugins that ship
by default.

A resolver could provide an url like this: "custom://abc123-modest-blah" and
register itself as a handler for custom:// urls. This allows resolver plugins
to fetch and stream content in any way they like. 
You could add support for ftp:// or a custom p2p:// protocol if you wanted.

How Clients Fetch Results
The actual URL to the resolved content, be it a local filesystem or http URL,
is never exposed to clients using the Playdar HTTP API. The "url" propery is
stripped out of result objects before they are returned to clients.
The "sid" GUID in every result object is used to request the content, like so:
Playdar will then fetch the content using the appropriate protocol handler
internally (file, http, p2p, custom, etc), and respond to the client with a 
well formed HTTP response. This means that clients only need to understand
HTTP. The details of how content is fetched by Playdar are hidden from clients.
Clients don't need to know where or how you access your music. 
The Playdar API lets them ask "Can you play this song". The details of where
and how you access the song are kept private.
To reiterate: clients can't tell whether you are playing a song you have on
your local disk, or are streaming over the internet from some other service.

How webpages interact with Playdar
Desktop apps can obviously just use the HTTP API on localhost without any 
special considerations. Webapps and anything running in the browser is 
subject to the browser security model, specifically the "same-origin policy".
This means that you can't access content in a document loaded from a domain
different to the domain your javascript executes in.

To solve this problem, playdar uses JSONP callbacks. Instead of requesting
and getting json in response, you inject a script tag into the dom like this:
<script language="javascript" 
Playdar responds with the json object wrapped in your padding:
 my_callback(...normal json response...);
which then fires the my_callback function - voilia, cross domain RPC.


Playdar - a content resolver for music







No releases published


No packages published