Tweetvine: Notes on writing a Spotify App


#NOTE: Since posting this article Spotify have released a new version of the API (c49e02a392) with new and improved functions to make some of the things mentioned in here easier.

Introduction

Hello and welcome everyone, in this article I am going to detail my experiences using the Spotify Apps API to build an app called TweetVine. Hopefully if you’re building your own first app the info, tips and tricks from my experience will help you with building your own.


TweetVine running inside Spotify

So let’s dive right in and get started with …

What is a Spotify App?

According to Spotify:

Spotify Apps are a bunch of cool, exciting and integrated apps inside Spotify, created by some of the best and brightest in the world. Each app brings you a new music experience tailored to you…

So a Spotify app is whatever you want really.

Technically a Spotify app is:

  • HTML
  • Javascript
  • CSS

Familiar? Should be - Spotify itself is essentially a glorified web browser and a Spotify App is a ‘web app’ that sits within Spotify. Spotify itself is based on the open-source version of Google Chrome, Chromium. This is an excellent idea - building apps is dead simple for anyone with HTML/CSS/JS experience.

I stopped writing websites a long time ago as it just sucked up far too much of my time working with incompatible browsers and the seemingly endless stream of standards / formats being released. Spotify have pretty much eliminated all those issues by by locking down the browser and integrated libraries - you can get away with slightly hacky code as you know it will render the same in every Spotify instance. They do say they may change away from Chromium some time in the future however, so don’t be too hacky.

This gives great benefits to prototyping ideas though, as you can just build your app as a website then ‘merge’ it into Spotify. This is how we did Tweetvine:

Simplified process of building a Spotify app

  1. Have an idea.
  2. Build it as a website first.
  3. Get Spotify developer access.
  4. Re-factor into Spotify.
  5. Done.

What tutorials and documentation is out there?

Not a lot. The documentation provided by Spotify is, frankly, dreadful. I learnt by using the built-in inspector on the other apps that were included, but Spotify have disabled this thus not allowing learning by this route any more. But as the official docs are dreadful I still recommend downloading the sample code and having a look with the inspector - especially the API tutorial example in the unofficial resources zip (more information below) as it gives you a rough idea how to put some elements on the page.

Official Documentation / Resources

  • Integration Guidelines
    A great introduction to the Spotify API with instructions on how to get up and running with a simple ‘Hello World’ app. Lists all the basic rules you should adhere to.
  • UX Guidelines
    Basically a ‘dont make a MySpace’ page document.
  • UI Guidelines
    Spotify are pretty anal about the look and feel of apps, this document outlines those rules. Unfortunately this is where the start of Spotify’s utterly useless documentation begins - this is a lengthy document outlining all the styling info, but absolutely nowhere does it tell you how to actually do it, with no example code and no references on where to find out. You just have to dig through the API and CSS manually to find out.
  • Tutorial
    This tutorial is similar to the Integration Guidelines example but includes extra information about using the manifest (the manifest is a JSON object with metadata about your app) and some extra code on how to listen to playback events within Spotify.
  • Design Resources
    I’m not entirely sure why they included this - it’s a zip file with all the images for various overlays etc. extracted out from Spotify. Everything in there can be applied using CSS classes and JS API functions. It would be much more useful if they had documentation for that instead! 

Unofficial Documentation / Resources

  • Stack Overflow has some useful posts and discussions on where to find things and common stuff.
  • There is a great little hidden gem inside Spotify where you can get the exploded view of the file structure. You can then look at the HTML/CSS/JS for things like the ‘whats new’ page and - oddly - some test applications Spotify built themselves. On Windows you can find it. at C:\Users\buchetics\AppData\Roaming\Spotify\Data\resources.zip, on a Mac it’s in the application bundle at Spotify.app/Contents/Resources/apps
  • Good old Google search.

A warning on how the API works

As mentioned above, the Spotify API is essentially a bunch of exposed CSS libraries and JS functions/objects. Spotify uses the same functions, so as a developer you pretty much have access to the same things that Spotify does. 

This means there is a lot of potentially juicy information for the taking for those of the maliciously inclined. There is no outbound permission model, so theoretically it is possible for an app to take all your personal ID’s (inc for Facebook), URL’s for all your playlists, your music collection and just upload it somewhere - and the only way you’d know is by using a traffic analyser (if the connection is not secured)!

Making Spotify do Something

The best way to learn the Spotify API is to play around with the objects and CSS. Create the test application from the tutorial and fire up the inspector.


The Spotify Tutorial app with Inspector

Click on Resources and have a look at the CSS files that are imported, particularly adam, core and shared. Modify your app so instead of loading the adam.css, load eve.css, and look again. You’ll see the classes that wrap around buttons and things pop out at you and you’ll get a feel for the design / programming methodology Spotify has adopted.

Finally head over to the console and execute the following commands:

sp = getSpotifyApi(1)
sp.core

Expand the objects returned in the console and hello hello, you’re getting a feel for what’s available through the API.


Some of the functions available through the Spotify API

A good and common paradigm used amongst the dev’s I have seen so far is to declare some standard objects for the API alongside the model / view pattern and use them throughout the app.

var sp = getSpotifyApi(1);
var m = sp.require("sp://import/scripts/api/models");
var v = sp.require("sp://import/scripts/api/views");
var fx = sp.require('sp://import/scripts/fx');
var ui = sp.require('sp://import/scripts/ui');

var playlist = new m.Playlist();
var player = new v.Player();

I’d definitely recommend lobbing that in a JS file and browsing through the objects using the Inspector alongside the terrible Javascript API Documentation.

Here’s some code examples to help you get up and running:

Some useful code examples

Playing a track from a playlist, keeping the playlist context

var player = new v.Player();
player.context = playlist;
player.play(spotifyUri, playlist, sequenceNo); // optional sequenceNo

Creating a playlist, adding tracks to it, and showing it

var playlist = new m.Playlist();
playlist.add(m.Track.fromURI('spotify:track:4vcag14xhbbTNP6HqQ5xsy'));
var uilist = new v.List(playlist);
$('#playlistDiv').html(uilist.node); // attach to a Div using JQuery

Using the ‘light style’ buttons

<span id="myButton" class="sp-button sp-flat sp-light">My Light Button</span>

Adding a button

<button id="addPlaylist" class="button icon" value="spotify:album:0fqSVcXza5It71LS2BJdLR"><span class="plus"></span>Add as Playlist</button>

Design Considerations

Here are some useful ideas to consider whilst devving:

  1. Essentially you will be distributing a static HTML file:
    a) Think about your update / change strategy. You will either have to build your app in a way where it is totally dynamically brought in over the web (your app is an app that loads the JS and HTML from somewhere on the web - yes, some of the <nameless> apps already on Spotify behave this way), or you will have to write some clever dynamic stuff, or tolerate the fact that without distributing a new version of your app to Spotify, you’re not going to get updated.
    b) All your content will be AJAX’d in. Think about how much bandwidth you will need, think about what happens if your service becomes unreachable. Really. It will look rubbish if you don’t.
  2. Keep to the design guidelines. Sounds like a no-brainer, but really, after much playing around and tinkering, they really do make sense and work.
  3. Use all built-in stuff where you can (like use Spotify for album art, don’t rely on last.fm, metadata etc).
  4. Trying to do anything out of the box can be a real pain in the butt, especially things like modifying the look and feel of playlists etc.
  5. Use the local storage features of Chromium. Makes things really nippy, keeps your potential bandwidth costs down.
  6. Test test test test test test test, then test again. Cater for every path. Remember once it’s in the wild, you’re screwed.
  7. Check your screen resolutions, remember you will only be getting a part of the screen for your app.
  8. Keep things asynchronous otherwise you will end up locking up the whole of Spotify - I’ve even managed to make Spotify crash on occasion.
  9. Assume the internet will be slow and broken, build your app to cope with it transparently. Use throbbers, use error messages, cache things. Think how much you have it when programs don’t feed back when they misbehave. 
  10. The max height you can get out of a playlist is 1000px.

Conclusion

I do not mean for this to be yet another tutorial on how to build an app, but I hope you find the above tips, tricks and my experiences useful when developing your Spotify app. I wish you the best of luck, thanks for reading!

More Help

If you know any other good resources please let me know, likewise if there are any particular functions or things you want to know, leave a comment!

  1. badgeringaway posted this