Content Resolvers




A content resolver is simply a Tomahawk plug-in for any searchable/streamable source of music.


Whenever Tomahawk is looking for a song, it searches all of your available content resolvers and then plays it from your best available source.



Currently Available Resolvers





What About Others?

We are always looking to add more resolvers for subscription services (Rdio, Deezer, Mog, Rhapsody, Slacker, etc.), online music and storage lockers (Amazon, Google Music, Dropbox) and more. Unfortunately many do not yet have public APIs that enable us to support them. We look forward to adding them once they do.


Want to Write Your Own?

Great! You will find everything you need to know below. Whenever possible we suggest writing them in javacript to ensure that they work across platforms. You can jump right in just by checking out some examples.



Want to share you resolver with the rest of the Tomahawk community? Just submit a pull request and we will see about adding it to Tomahawk's resolver gallery.




Resolver Protocol

Tomahawk communicates to external resolvers via an extended version of the Playdar Protocol. The protocol Tomahawk uses is a superset of the Playdar protocol, and remains backwards compatible.


To write a resolver you will need to parse messages from standard input and write any results to standard output. The messages sent and received are expected to be JSON formatted map (associative array) as a string prepended with a 4-byte long number, representing the message length in bytes. The length must be big-endian, and the JSON map must specify the _msgtype key that contains the type of message as a value.


Payload length (4 bytes) Payload (JSON map with _msgtype property)


Messages

Setup

When a resolver script is started and it is ready to start resolving, it must output an initial settings message that sets some configuration information. This message has the type "settings", and it contains:


  • _msgtype: settings
  • name: The name to show for this resolver
  • weight: How reliable and fast this resolver is. Int from 0-100. 100 is reserved for the "local tracks" resolver.
  • targettime: How long this resolver may be expected to take to produce results. Playdar will wait for this amount of time before dispatching the next-lowest-weight resolver.
  • localonly: Local-only results are not forwarded on to LAN clients using the LAN resolver.

Note that if your resolver requires configuration (and you do not have the proper settings configured) you should not send this message. Only send it once you are ready to resolve tracks.



Configuration Widget

If a resolver can be configured, it can send to Tomahawk a description of the configuration widget to display. The message is of type "confwidget" The "widget" item is a textual representation of a widget, as a .ui file. This is the output from Qt Designer, see this page for more information.


If you wish to include images in your widget, you must send them separately as individual members of the message. This is because .ui files contain images as resource paths rather than embedded, and Tomahawk will not have your image in its resource file. Since it can't load them, the UI file should have an image path for each image that corresponds to the image name in the 'images' map.


  • _msgtype: confwidget
  • compressed: true/false. Reports whether the widget .ui file is compressed by qCompress().
  • widget: The file contents should be base64-encoded.
  • images: Map of imagename: base64-enc data (compressed if compressed is true).

If a resolver has a valid config widget, it will be displayed to the user. When the user closes the config dialog, the resolver will be notified with the changes in the dialog with a "setpref" message.



Preferences Set Request

This message is sent to a resolver to notify it of a certain preferences change. It will only be sent for resolvers that have a valid preferences widget. Tomahawk will send each resolver all of the properties in each QWidget in the dialog.


  • _msgtype: setpref
  • widgets: Map of widgets. Each contains a map:
  • widgetname: { property: value; property: value }


Search

This message is sent to a resolver to ask it for a track. This message has type "rq" and contains:


  • _msgtype: rq
  • qid: A unique ID used to identify this request. Needed in the response.
  • artist: Artist of the track.
  • track: The track name to search for.
  • album: Optional album name.


Search Results

Results are returned from the resolver using this message. This message has type "results" and contains:


  • _msgtype: results
  • qid: qid (from 'rq' message above)
  • results: a list of JSON entries:
  • artist: Artist of the track.
  • track: Track name.
  • album: Track album.
  • year: The release year of the album.
  • url: The url to play the track from.
  • mimetype: The mimetype of the audio data, e.g. audio/mpeg.
  • extension: The file type of the track, for example, mp3, ogg, flac. If both extension and mimetype are present, mimetype is used.
  • source: The name to show as the source to the user.
  • duration: The duration, in seconds, of the track.
  • score: How accurate this search result is, a float, from 0-1.
  • bitrate: The bitrate of this track.
  • albumpos: The position of this track on the current disc
  • discnumber: The number of the current disc

If you work for a company that is interested in having your content available in Tomahawk, or just need general help in writing a resolver, just contact us or join us in our chat room. We are always around.