Playdar Protocol

The Playdarcontent resolution protocol is used by Tomahawk to communicate to the various loaded script resolvers. This page is a simple description of the communication protocol. Notes:

• Messages are prepended with a 4 byte long number representing the message length in bytes. This length must be big endian.
• Messages are encoded in JSON.
• All communication is done via stdin and stdout. Tomahawk will send messages to the resolvers via the resolvers' stdin, and it will read the resolver output via stdout.

Messages should be a JSON map, with a '_msgtype' key that contains the type of message as a value. Below is a description of potential 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. 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. This message has the type "settings", and it contains:

• _msgtype: settings
• name: The name to show in Tomahawk for this resolver
• weight: How reliable and fast this resolver is. Int from 0-100. 100 is reserved for the "local tracks" resolver.
• timeout: How long, approximately, this resolver will take. Tomahawk will wait for this amount of time before dispatching the next-lowest-weight resolver.

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 }

Track Search Request

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

At this point the resolver can return results in the following message:

• _msgtype: results
• qid: qid (from 'rq' message above)
• results: a list of JSON entries:
  • artist: Artist of the track.
  • track: The track name
  • album: Track album
  • albumpos: The track number of this track on the album, if one exists
  • 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