The exfm Javascript API allows sites to talk directly to exfm and tell it what songs are on the site. It can also listen for and dispatch events to exfm.
If you would like to build an app using exfm data, check out our Server API.
We’d love to hear about what you’re working on, get your feedback, or answer any questions. Please don’t hesitate to contact us at api@ex.fm.
There are two ways sites can tell exfm about songs. The simplest way is to include anchor elements on the page with an href attribute that end in '.mp3' or have the class 'exfm_song'. Exfm will detect these (even if they are hidden) and also look for other attributes such as artist, album, etc.
<a href="foo.mp3" title="Some Title" artist="Some Artist"</a>
<a class="exfm_song" href="foo" title="Some Title" artist="Some Artist"</a>
Sites can also let exfm know about songs by creating an array of valid JSON objects that it can parse. These arrays can be embedded on the page inside of script tags. Script tags must include a class name of "exfm_songs" to be detected. There can be multiple Script tags on a single page.
<script class="exfm_songs">...</script>
In order for exfm to parse the array, it MUST be valid JSON:
[{"title" : "Some Title", "artist" : "Some Artist", "album" : "Some Album", "url" : "http://example.com/foo.mp3"}, {..}]
url string (required)
Location of the song file. Song files must be .mp3 or .aac format. This is the only required field.
title string
The title of the song.
artist string
The song's artist.
album string
The song's album.
source string
Permalink page where the song comes from. If empty, defaults to the current page.
image string
URL of an image associated with the song (coverart, artist image, etc).
buy_link string
URL of a page where this song may be purchased.
To listen for events from the extension, you must first set up a listener. Your handler function will receive an event object with a target that is a hidden HTML element appended to the page. The event data will be inside the element as JSON text. To turn it into an object, call JSON.parse on the text. It's recommended to wrap these in try/catch statements
try {
document.addEventListener('someNameEvent', function(event) {
var eventData = JSON.parse(event.target.innerText);
});
} catch(e){}
exfmEnabledEvent
This event will fire slightly after the page loads telling your page that exfm has loaded.
To dispatch events to the extension, you must first create an event and then dispatch it to the document. It's recommended to wrap these in try/catch statements.
try {
var event = document.createEvent('Event');
event.initEvent('someNameEvent', true, true);
document.dispatchEvent(event);
} catch(e){}
exfmSongsAsyncEvent
Firing this event will cause exfm to rescan the page for songs. Use this if you are loading songs asynchronously after the page loads.