Facebook Music bridge

The Facebook Music bridge is only available to whitelisted partners at this time.


Enable play buttons on feed stories on Facebook.com that can play and pause tracks and indicate which is playing.


The client loads part of the Facebook JS SDK which provides an interface for FB to send play and pause commands to the client, and allows the client to send status updates back to Facebook.

Installation instruction

Tell us what songs, albums, radio_stations, playlists, users, musicians, etc you can play

For any object that can be played on your site, include og:audio and og:audio:type tags on that URL. These tags can be included on songs, artists, albums, playlists, radio stations, and user profiles. When we display these objects on Facebook they will have play buttons on them, and we will pass you the URL specified in the og:audio tag.

<meta property="og:audio" content="{url_to_play_from}" />

<meta property="og:audio:type" content="audio/vnd.facebook.bridge" />

Add the Bridge to your player page

The bridge is part of the Javascript SDK. The music component isn't public yet, so you'll have to load it specifically from http://connect.facebook.net/en_US/vb.js. If you also need all.js (which most of you will), you can load both modules by loading 'https://connect.facebook.net/en_US/all/vb.js'. We highly recommend loading the js library asynchronously for performance reasons; see the SDK doc for more info. Once the js is loaded, simply call:

FB.init({music: true});

to install the bridge on your page.

Subscribe to Music Events

After you initialize the bridge, you should subscribe to a couple Music action events that we will send. There are four important commands to support: PLAY, PAUSE, RESUME, and STATUS.

The callback functions for these events have two parameters: the command, and a dictionary of parameters.

Example invocations:

function initMusicBridge(app_id) {
    { music: true,
      appId: app_id
      // include any other parameters to FB.init that you need, see           
      // https://developers.facebook.com/docs/reference/javascript/ for details

  // PLAY means start playing a new track, the song URL is passed in
  FB.Event.subscribe('fb.music.PLAY', play_callback);
  // RESUME means the user hit play on the paused track
  FB.Event.subscribe('fb.music.RESUME', resume_callback);
  // The user hit pause on the currently playing track
  FB.Event.subscribe('fb.music.PAUSE', pause_callback);
  // Facebook is polling for status, send a status message to Facebook so it can display the current song
    function(params) {FB.Music.send('STATUS', {playing: true, song: url, ... })});

function play_callback(params) {
  // start playing params.song, see full format below

We send two other ops that might be useful for debugging and providing feedback:

  • fb.music.BRIDGE_READY, meaning the bridge is up on the local end and ready to receive updates
  • fb.music.ALREADY_CONNECTED, meaning there's already another player attached from your domain (we want to avoid playing music in two windows simultaneously).
  • fb.music.USER_MISMATCH, meaning the facebook user_id of the user logged into the client is different from the one logged into facebook.com. All subsequent commands sent across the bridge will be ignored.

Currently the only params we pass are for PLAY/PAUSE/RESUME, where we pass as much information about the context as we can:

  • radio_station indicating the URL of the radio station to play
  • song indicating the URL of the song to play
    • with song we attempt to include one of album, playlist, or musician if the song was played in that context; after the song finishes, the next song from that collection should be played
    • song_list if the song is played from a list but we can't find a shared album/playlist/musician context, we'll send a simple array of song URLs including this one, the list should start playing at song and continue
  • album giving the URL of the album to play, or that the song was played from
  • playlist giving the URL of the playlist to play, or that the song was played from
  • musician giving the URL of the musician to play, or that the song was played from
  • title user-readable description of the currently playing item(s), most important for song_list
  • offset if present, gives the number of seconds into a song to begin playing

Example invocations:

    'song': 'http://example.com/song/2',
    'song_list': ['http://example.com/song/1', 'http://example.com/song/2', 'http://example.com/song/3'],
    'title': 'Most popular songs from Bob'

    'radio_station': 'http://example.com/radio_station/1',
    'title': 'Bob Marley radio'

    'song': 'http://example.com/song/1',
    'album': 'http://example.com/album/1',
    'title': 'Album name that you probably already have'

Generally it is okay to play just the song (or radio station), and make a best effort to continue from there based on the other parameters.

Add code to send a message down the bridge whenever the user plays or pauses something on the page.

If a song is playing or queued up, the URL should be included in the parameter song. Optionally the time the song started playing can be in start_time and the expected length of the song in seconds can be in expires_in

Tell us the context in which the song is being played -- if there is a radio station, playlist, album, or musician that the user is playing multiple songs from, include that url in the appropriate parameter (playlist, radio_station, album, musician).

Include the facebook user_id of the user currently logged into the client with every STATUS message. We crosscheck the user_id you provide with the logged in user at facebook.com. If there is a mismatch (or no user_id passed in), we will ignore any messages from the client as well as suppress any PLAY commands from facebook.com. We will also send you a 'fb.music.USER_MISMATCH' event so you can force the user to relogin (or connect their account to facebook in the case of no user_id).

Example invocations:

function playURL(url) {
    // start the URL playing
    // update the status
            playing: true,
            song: <current song url>,
            start_time: '2011-05-05T13:22',
            expires_in: 182,
            radio_station: <radio station URL>,
            user_id: <facebook user id>

function pause() {
    // pause the current track
          // IMPORTANT: you must include the 'song' param for the paused track in order for
          // pause/resume to work
          playing: false,
          song: <current song url>,
          musician: <musician url>,
          album: <album url>,
          user_id: <facebook user id>

Figure out which Facebook User is Logged in

If you load the full Javascript SDK, you can use FB.getLoginStatus to figure out which Facebook user is logged in. This can allow you to customize the experience for your user, and also help determine whether they're a new user or an existing one. For users who have not yet authorized your app, you should upsell them on logging into your music experience with their FB credentials.

Parameters to the player

When we open your player's window, we will also pass the song or radio_station url that the user has requested to play. We will also include any context ('playlist', 'album', etc) as GET params. If you can start playing this immediately, that would be the optimal experience. You could also store this url so the song immediately starts after the user has logged in or created his/her account. We will still send a PLAY command (with the same params) through the flash bridge after we get the first STATUS from you.

Tell us what player URL we should open when somebody clicks play and they don't already have a window open.

For now this is a whitelist, eventually you may be able to specify on your song pages what page should be used to play them.

Notify Facebook when the user closes the player.

However you detect this, it would help make the integration smoother if you sent Facebook a STATUS with the offline parameter set to true.

function unloadPage() {
    { offline: true, 
      user_id: <facebook user id> }
window.onbeforeunload = unloadPage; 

Send back error codes when you can't play music.

If for whatever reason you are unable to play a song, you should send us back one of the following error codes. You can pass an optional 'redirect_url' that the user can go to for more info about the error or to perform some action to remedy the situation (ie. buy premium, buy song).

Service Availability Errors

  • 1: Service unavailable - need to upgrade to premium [service passes URL of where to buy premium]
  • 2: Service unavailable - need to upgrade to premium or wait [service passes URL of where to buy premium and an integer indicating the number of days the user needs to wait]
  • 3: Service unavailable - billing issue [service passes URL to account settings]
  • 4: Service unavailable - technical issues
  • 5: Audio Ad Playing - your music will continue after this ad

Song Availability Errors

  • 101: Song unavailable - click here to purchase the song [service passes URL of where to buy the song]
  • 102: Song unavailable - click here to buy premium [service passes URL of where to buy premium]
  • 103: Song unavailable - will never be available

You can include an 'error_code' as part of any status message:

            error_code: 101,
            redirect_url: url,
            playing: false,
            song: url,
            user_id: <facebook user id>