Tomahawk Links

Jason Herskowitz edited this page Dec 1, 2015 · 3 revisions

Playlist

Import Playlist

 tomahawk://playlist/import/?xspf=<xspf url>&title=<optional> [LEGACY]
 tomahawk://import/playlist?xspf=<xspf url>&title=<optional> 
 http://toma.hk/import/playlist?xspf=<xspf url>&title=<optional>

Load/Play Playlist

 tomahawk://open/playlist/?xspf=<xspf> 

New Playlist

 tomahawk://playlist/new/?title=<>

Generate XSPF

 http://toma.hk/playlistgen.php?title={PLAYLIST_TITLE}&artists[]={ARTIST_ONE}&titles[]={TITLE_ONE}&artists[]={ARTIST_TWO}&titles[]={TITLE_TWO}

Add Track to Playlist - NOT YET IMPLEMENTED

 tomahawk://playlist/add/track/?playlistid=<>&artist=<artistname>&title=<trackname>

how to add multiple tracks to a playlist with a single URL? how to get playlist ID?

Library

Add local tracks to library - NOT YET IMPLEMENTED

 tomahawk://add/collection/track/?file=<file path>

Add hosted tracks to library - NOT YET IMPLEMENTED

 tomahawk://add/collection/track/?url=<mp3 url1>&url=<mp3 url2>...

Would be nice to handle both "file" and "url" in a single URL - NOT YET IMPLEMENTED

 tomahawk://add/collection/track/?file=<file path>&url=<mp3 url>...

Artist and Album pages

You can direct tomahawk to automatically load an artist or album page by using the following links:

 tomahawk://view/artist?name=<artist name>
 tomahawk://view/album?name=<album name>&artist=<artiist name>

Create Station or Automatic Playlist

Create a station or automatic playlist based on one or more seeds/parameters. See the echonest playlist page for more information about these parameters and what they mean Currently only The Echo Nest is supported. Below are the parameters required:

 type= echonest required
 title= the title of the playlist

At least one of 'artist', 'artist_limitto', or 'description' parameter is needed. A single playlist cannot mix artist, artist_limitto, and description elements--one or more of one type only are required. artist= Tracks similar to the given artist, e.g. "Foo Fighters" artist_limitto= Tracks only by the given artist, e.g. "Foo Fighters" description= Genre or similar description, for example "indie" "rap" "70s slowcore fubar"

The following limit the playlist to "at least":

 variety= double from 0 to 1
 tempo= int from 0 to 500 bpm
 duration= int from 0 to 3600 secs
 loudness= int from -100 to 100 dB
 danceability= double from 0 to 1
  energy= double from 0 to 1
 artist_familiarity= double from 0 to 1
 artist_hotttnesss= double from 0 to 1
 song_hotttnesss= double from 0 to 1
 longitude= int from -180 to 180deg
 latitude= int from -180 to 180deg
 mode= int which is 0 or 1 (major or minor)
 key= int from 0 to 11 (see http://developer.echonest.com/docs/v4/playlist.html#static for info)

It is possible to switch the meaning of the above controls by appending a "_max" to the name. So instead of "tempo", "tempo_max". Note that this is not valid for variety or mode.

 tomahawk://station/create/?type=echonest&title=<>&artist=U2&song_hotttnesss=0.657&tempo=120...
 tomahawk://autoplaylist/create/?type=echonest&title=<>&artist=U2&song_hotttnesss=0.657&tempo=120...

Search

Search for track, album (all tracks from album) or artist (all tracks from artist)

 tomahawk://search/?artist=<artistname> (may also include &title=<>, & album=<>)
 tomahawk://search/?query=<freeform global search>

Lookup (by URL)

 http://toma.hk/search.php?q=http://open.spotify.com/track/0GuYC53LUD7hS8BVHZiqt0

A hack that lets you create a Tomahawk embed directly from a Spotify/Deezer/Rdio track link: http://pipes.yahoo.com/jherskowitz/tomahawkembed

Open

Does "the right thing" given a query or link. If the user is currently playing a song, the song is queued; otherwise the song starts playing. This is a reasonable default link that should be used by most external apps, since it is user-configurable and will most likely do what the user expects.

 tomahawk://open/track/?artist=<artistname>&title=<trackname>&album=<optional>&url=<optional>

tries to resolve and play... if can't resolve then need some error messaging/handling

You can also open a playlist, which will cause the contents of the supplied xspf or jspf playlist to be queued and played directly. No permanent playlist will be created.

 tomahawk://open/playlist?xspf=http://some.website/test.xspf
 tomahawk://open/playlist?jspf=http://some.website/test.jspf

Spotify Urls

All track commands also alternatively accept a spotifyURL= argument with a spotify track url instead of artist/title/album:

 tomahawk://open/track/?spotifyURL=http://open.spotify.com/track/0GuYC53LUD7hS8BVHZiqt0
 http://toma.k/open/track/?spotifyURL=http://open.spotify.com/track/0GuYC53LUD7hS8BVHZiqt0
 tomahawk://open/track/?spotifyURI=spotify:track:0GuYC53LUD7hS8BVHZiqt0
 http://toma.hk/open/track/?spotifyURI=spotify:track:0GuYC53LUD7hS8BVHZiqt0

Rdio Urls

Like spotify, Tomahawk accepts rdio urls wherever a spotify url is accepted.

 http://www.rdio.com/#/artist/Jonathan_Coulton/album/Best._Concert._Ever./track/Still_Alive/
 http://rd.io/x/QVqdJzd-rqg
 tomahawk://open/track/?rdioURL=http://rd.io/x/QVqdJzd-rqg
 http://toma.hk/open/track/?rdioURL=http://rd.io/x/QVqdJzd-rqg

Play

Start playing an item or list immediately (like clicking play button). It will interrupt what the user is listening to. Be careful with this.

 tomahawk://play/track/?artist=<artistname>&title=<trackname>&album=<optional>&url=<optional>

tries to resolve and play... if can't resolve then need some error messaging/handling

Queue

Add local or remote track with metadata to queue. Url is optional, must be a remote url. The track will be resolved.

 tomahawk://queue/add/track/?artist=<artistname>&title=<trackname>&album=<optional>&url=<optional>

Add local or remote track to queue. Url can be a local or remote path

 tomahawk://queue/add/track/?url=<url1>&url=<url2>&...

Add list to queue -- PENDING how to get playlist id? does it matter? - NOT YET IMPLEMENTED

 tomahawk://queue/add/playlist?id=<>

Toma.hk

Toma.hk Links

Track Links

 http://toma.hk/?artist=<artist name>&title=<track name>

Artist Links

 http://toma.hk/artist/<artist name>

Album Links

 http://toma.hk/album/<artist name>/<album name>

XSPFs

 get the xspf by replacing /p/ through /xspf/ http://toma.hk/xspf/F7i2222M

Toma.hk Embeddable Players

Single Track

 <iframe src="http://toma.hk/embed.php?artist=<artist name>&title=<track name>" width="200" scrolling="no" height="200" frameborder="0" allowtransparency="true" ></iframe>

You can also add &autoplay=true onto the end of the url to make the player play as soon as loaded note you can also use a player (hidden in a div) to power playaback in other apps (e.g.: http://syddev.com/thiswasmyjam/):

 {{#widget:Iframe |url=http://toma.hk/embed.php?artist=Fridge&title=Long+Singing |width=200 |height=200 |scrolling=no |allowtransparency=true |border=0 }}

Playlist

 <iframe src="http://toma.hk/p/<playlist id>?embed=true" width="550" height="430" scrolling="no" frameborder="0" allowtransparency="true" ></iframe>

Album

 <iframe src="http://toma.hk/album/<artist name>/<album name>?embed=true" width="550" height="430" scrolling="no" frameborder="0" allowtransparency="true" ></iframe>