Last week, we released the very first version of our app called Combo.fm. It’s a neat little music discovery tool (you should probably go check it out) for finding new songs & artists — and out of the box, we offered full streaming support for Spotify premium users, with a fallback to 30-second previews. Probably enough for now, right?

We put it out there, and here’s what happened:

…which left me last week paddling frantically through the choppy waters known as the Apple Music API. Seeing as it’s something which has only been about for a few months, online documentation’s fairly limited; so I thought I’d share everything I’ve picked up. In this post, we’re going to get permission from the user to use their Apple Music account and play some tracks back. It’s going to be fun. I promise.

Stuff you can do with the Apple Music API

You can play tracks out Apple Music if the user is logged in and has a valid membership. And that’s rad. Again, if you’re a subscriber, you can create Apple Music playlists & add tracks to them. Again, pretty sweet. You may not delete anything from them. Guessing this is damage control from Apple’s side; I guess it wouldn’t be too difficult to write a couple of lines of horrible code that would wipe out any instance of My Chemical Romance from a designated playlist. And that would be terrible.

Gotchas

(you should actually read these, or prepare to be doomed to hours of fruitless Stack Overflow sifting)

Make sure you’re testing all this stuff out on a real device running iOS 9.3+. You’ll get some some seriously bizarre behaviour when you try to interact with the API using the Simulator (probably because it doesn’t actually have the Music app installed, and everything plays from it).

You’re (obviously) going to need an Apple Music subscription. If you’ve not signed up before, you’re in luck — you get a sweet three months pro bono to test this stuff out. Otherwise, fork out £9.99.

Wanna play stuff in the background?

Make sure you’ve got Audio, Airplay and Picture in Picture ticked in your Background Modes.

You’re going to need these two frameworks linked to your app:

StoreKit

MediaPlayer

…and don’t forget to import them at the top of your class.

Checking the device actually has Apple Music capabilities

This is fairly straightforward. We get a nice enum which we can check whether or not the device is capable of playing back any music, which allows us to assume the next step — asking for permission.

Asking for permission to access Apple Music

Again, another simple one:

Once the requestAuthorization method fires, the user will receive a prompt that looks like this:

(But it probably won’t be called AppleMusicTest for you)

If you’re on the other end of a user tapping “Don’t Allow”, then running this function again will return .Denied without re-prompting the user. To deal with this, you’ll need to flesh out the above method by checking the authorizationStatus first.

If you wanted to keep things really clean, I’d probably advise splitting these into two separate methods — but for this example, early exiting makes things a little bit easier to read.

Playing a track

Alright, time for the fun part.

First and foremost, you’re going to need a MPMusicPlayerController instance declared as a class property. Why’s this? If it’s not a class property, it’ll immediately be deallocated and won’t play anything back otherwise. And that’s no good.

That’s actually it. Two lines of code to queue and cue.

applicationMusicPlayer vs systemMusicPlayer: which should I pick?

systemMusicPlayer: This is a shared instance of Apple’s native Music player. This means that if you play a track using this player, then quit your app, you could continue playing your playlist through Apple’s Music app.

applicationMusicPlayer: This is a shared instance of a player that behaves independently to Apple’s player. I picked this one for Combo.fm.

Hold up — where did these IDs come from?

Every track from Apple Music has a unique ID linked to it. Unfortunately, that ID can variate depending on which region you’re playing back from.

For example, Drake’s If You’re Reading This… album ID in the US is 966997496, whereas in the UK it’s 966984970.

To find out more about getting the correct IDs, you’ll need to familiarise yourself with the iTunes Search API. It’s a REST API that’s not too difficult to get around (simple URL queries to get results), but it’s really important you understand it. If the ID doesn’t match the ID for the user’s region, then your app might end up playing a totally different song to what the user wanted!

These region IDs are referred to in the Apple Music API as storefront IDs, so now we’re now going to get the user’s storefront ID to guarantee the track they play is the one the user wants.

Fetching the user’s Storefront ID

But hold on just a second. When the final line is printed, we’re given a seemingly random string of numbers that looks like this:

Yeuch.

After a bit of back-and-forth from the documentation, I managed to find that the Storefront ID is actually in there — it’s the first six characters (the rest is irrelevant), so we’re going to need to check the string length is 6 or more, then pull it out as a separate string. I’m going to amend the above function so it does just that…

Much better. We now get this lovely string instead:

Lovely.

I’m not going to go into too much depth into the iTunes Search API, but now you have this information, you could fetch some sweet My Chemical Romance tracks from the iTunes Search API with the following query:

By appending s=143444 to the end of the query, we can guarantee all the results will have IDs that are playable from the user’s Apple Music account, as the value is the user’s storefront ID we fetched from the Apple Music API.

The Black Parade

Provided you’ve got permission from the user to use their Apple Music, you can now safely blast out some sweet My Chemical Romance by running the following commands:

My Chemical Romance is the ultimate way to test out any music playback functionality. Period.

And that’s all there is to it. You can now sit back and enjoy Welcome To The Black Parade the way it was supposed to be enjoyed: through your iPhone’s tiny speaker using your Apple Music membership. Give yourself a pat on the back. You’ve earned it.

Combo.fm and Apple Music?

My thoughts on the API?

It really makes me wish promises were more of a thing in Swift.

Functions like requesting the device’s capabilities require a completion handler; and it only takes a couple of these before you’re wading through the murky depths of callback hell. Bleurgh.

Because Combo’s a curated platform with 5–6 new tracks per day, we’ve got a fairly sophisticated backend system set up that’s requesting the IDs relevant to the user’s storefront ID on the fly if they’ve not been played before.

It’s working pretty well for now, but it really does make me appreciate the simplicity of Spotify’s single-ID approach.

Combo also integrates additional functionality with Apple Music, such as creating a custom playlist to store user’s saved tracks and adding them from the app. If it’s something people are interested in knowing more about, I’d be delighted to pull together some steps on how that’s managed, too.

Alright, gloves off; I’ve been shamelessly and unapologetically plugging Combo throughout this entire blog post — but in all seriousness, if you’re looking to see how the Apple Music API is handled in-app using these techniques, download the app — I’d really appreciate any feedback you have on it.

You can drop me an email on sam@combo.fm.