Open Graph Music

    Open Graph Music

    Facebook is not whitelisting new partners for Facebook Open Graph Music at this time.

    Introduction

    Currently the Open Graph has a set of generic tags and one action type, namely the 'like' action. We are extending the Open Graph to be fully generic, to represent any object and any action type. In the music vertical we are defining additional open graph meta tags and new actions.

    Meta Tags

    Songs

    • og:title - The title of this song.
    • og:type - 'music.song'
    • og:image - An image URL which should represent your song within the graph (likely the album art). The image must be at least 50px by 50px (though minimum 200px by 200px is preferred) and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats.
    • og:url - The canonical URL of your song.
    • og:site_name - A human-readable name for your site, e.g., "IMDb".
    • fb:app_id - A Facebook Platform application ID that administers this page.
    • og:audio - The URL to play this song.
    • og:audio:type - This should be set to "audio/vnd.facebook.bridge"

    New tags:

    • music:musician - The artist of this song. This is a URL of a page with og:type profile. Multiple music:musician tags can be specified.
    • music:album - The album which contains this song. This is the URL of a page with og:type music.album. Multiple music:album tags can be specified.
    • music:album:disc - The disc number this song is on within this album [defaults to ‘1’]
    • music:album:track - The track number of this song on this album [relative to the disc number]
    • music:duration - The play time of the song in seconds.

    Song Example

    Example URL: http://open.spotify.com/track/2aSFLiDPreOVP6KHiWk4lF

     <meta property="og:title" content="Under Pressure"/>
 <meta property="og:type" content="music.song"/>
 <meta property="og:url" content="http://open.spotify.com/track/2aSFLiDPreOVP6KHiWk4lF"/>
 <meta property="og:image" content="http://o.scdn.co/image/e4c7b06c20c17156e46bbe9a71eb0703281cf345"/>
 <meta property="og:site_name" content="Spotify"/>
 <meta property="fb:app_id" content="174829003346"/>

    New tags:

     <meta property="music:musician" content="http://open.spotify.com/artist/1dfeR4HaWDbWqFHLkxsg1d">
 <meta property="music:musician" content="http://open.spotify.com/artist/0oSGxfWSnnOXhD2fKuz2Gy">
 <meta property="music:album" content="http://open.spotify.com/album/7rq68qYz66mNdPfidhIEFa">
 <meta property="music:album:track" content="2">
 <meta property="music:duration" content="236">

    Albums

    • og:title - The title of this album.
    • og:type - 'music.album'
    • og:image - An image URL which should represent this album within the graph (likely the album art). The image must be at least 50px by 50px (though minimum 200px by 200px is preferred) and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats.
    • og:url - The canonical URL of this album.
    • og:site_name - A human-readable name for your site, e.g., "IMDb".
    • fb:app_id - A Facebook Platform application ID that administers this page.
    • og:description - A one to two sentence description of this album.
    • og:audio - The URL to play this album.
    • og:audio:type - This should be set to "audio/vnd.facebook.bridge"

    New tags:

    • music:song - A song on this album. This is a URL of a page with og type music.song. Multiple music:song tags can be specified.
    • music:song:disc - The disc number this song is on within this album [defaults to ‘1’]
    • music:song:track - The track number of this song on this album [relative to the disc number]
    • music:musician - The artist of this album. This is a URL of a page with og type profile. Multiple music:musician tags can be specified.
    • music:release_date - The date this album was first released, expressed in ISO 8061 format.

    We support absolute ISO 8061 timestamps with the timezone defaulting to UTC. The format we are expecting is YYYY-MM-DDThh:mm:ssZ. Z is used to express different time zones, and represents an offset from UTC. Examples:

    • January 26th, 2011 = 2011-01-26
    • January 26th, 2011 at 7:15pm = 2011-01-26T19:15
    • January 26th, 2001 at 7:15pm Pacific Standard Time = 2011-01-26T19:15-8:00

    Album Example

    Example URL: http://open.spotify.com/album/7rq68qYz66mNdPfidhIEFa

     <meta property="og:title" content="Greatest Hits II"/>
 <meta property="og:type" content="music.album"/>
 <meta property="og:url" content="http://open.spotify.com/album/7rq68qYz66mNdPfidhIEFa"/>
 <meta property="og:image" content="http://o.scdn.co/image/e4c7b06c20c17156e46bbe9a71eb0703281cf345"/>
 <meta property="og:site_name" content="Spotify"/>
 <meta property="fb:app_id" content="174829003346"/>
 <meta property="og:description" content="Greatest Hits II, an album by Queen on Spotify."/>

    New tags:

     <meta property="music:release_date" content="2011-04-19">     
 <meta property="music:musician" content="http://open.spotify.com/artist/1dfeR4HaWDbWqFHLkxsg1d">
 <meta property="music:song" content="http://open.spotify.com/track/0pfHfdUNVwlXA0WDXznm2C">
 <meta property="music:song:disc" content="1">
 <meta property="music:song:track" content="1">     
 <meta property="music:song" content="http://open.spotify.com/track/2aSFLiDPreOVP6KHiWk4lF">
 <meta property="music:song:disc" content="1">
 <meta property="music:song:track" content="2">
 ...
 ...

    Musician Meta Tags

    • og:title - The name of this artist.
    • og:type - 'profile'
    • og:image - An image URL which should represent this musician within the graph. The image must be at least 50px by 50px (though minimum 200px by 200px is preferred) and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats.
    • og:url - The canonical URL of this musician.
    • og:site_name - A human-readable name for your site, e.g., "IMDb".
    • fb:app_id - A Facebook Platform application ID that administers this page.
    • og:description - A one to two sentence description of this musician.
    • og:audio - The URL to play this artist.
    • og:audio:type - This should be set to "audio/vnd.facebook.bridge"

    Musician Example

    Example URL: http://open.spotify.com/artist/0oSGxfWSnnOXhD2fKuz2Gy

     <meta property="og:title" content="David Bowie"/>
 <meta property="og:type" content="profile"/>
 <meta property="og:url" content="http://open.spotify.com/artist/0oSGxfWSnnOXhD2fKuz2Gy"/>
 <meta property="og:image" content="http://o.scdn.co/image/8421cd7440a644d691a8215a4ef95f730a54c2d1"/>
 <meta property="og:site_name" content="Spotify"/>
 <meta property="fb:app_id" content="174829003346"/>

    Playlist Meta Tags

    • og:title - The title of this playlist.
    • og:type - 'music.playlist'
    • og:image - An image URL which should represent this playlist within the graph. The image must be at least 50px by 50px (though minimum 200px by 200px is preferred) and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats.
    • og:url - The canonical URL of this playlist.
    • og:site_name - A human-readable name for your site, e.g., "IMDb".
    • fb:app_id - A Facebook Platform application ID that administers this page.
    • og:description - A one to two sentence description of this playlist.
    • og:audio - The URL to play this playlist.
    • og:audio:type - This should be set to "audio/vnd.facebook.bridge"

    New tags:

    • music:song - A song on this playlist. This is a URL of a page with og type music.song. Multiple music:song tags can be specified.
    • music:song:track - The track number of this song on this playlist.
    • music:creator - The creator of this playlist. This is the canonical URL of a page with og type profile. Multiple music:creator tags can be specified.

    Radio station

    • og:title - The title of this radio station.
    • og:type - 'music.radio_station'
    • og:image - An image URL which should represent this radio station within the graph. The image must be at least 50px by 50px (though minimum 200px by 200px is preferred) and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats.
    • og:url - The canonical URL of this radio station.
    • og:site_name - A human-readable name for your site, e.g., "IMDb".
    • fb:app_id - A Facebook Platform application ID that administers this page.
    • og:description - A one to two sentence description of this radio station.
    • og:audio - The URL to play this radio station.
    • og:audio:type - This should be set to "audio/vnd.facebook.bridge"

    New tags:

    • music:creator - The creator of this radio station. This is a URL of a page with og type profile. Multiple music:creator tags can be specified.
    • og:audio - The URL of the actual radio stream

    Profile Meta Tags

    This type captures user profiles on other sites (e.g. ebay profile)

    • og:title - The name of the user (e.g. Austin Haugen).
    • og:type - 'profile'
    • og:image - An image URL which should represent this profile within the graph. The image must be at least 50px by 50px (though minimum 200px by 200px is preferred) and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats.
    • og:url - The canonical URL of this profile.
    • og:site_name - A human-readable name for your site, e.g., "IMDb".
    • fb:app_id - A Facebook Platform application ID that administers this page.

    New tags:

    • fb:profile_id - This ties the user profile on your site to the user profile on Facebook. This can either be the user’s Facebook ID or a third party id, which can be obtained with: https://graph.facebook.com/{user_id}?fields=third_party_id&access_token={user_access_token}

    Music actions

    There are two built-in music actions, also see the generic action documentation.

    descriptionnametarget og:type

    Song listen

    music.listens

    music.song

    Playlist create

    music.playlists

    music.playlist

    The moment a user starts listening to a song a music.listens action should be published by POSTing like so:

    POST https://graph.facebook.com/me/music.listens?song=[song url]

    You can also supply several optional properties telling us what context the song is being played in. This includes from a playlist, album, musician, how long the song is and when it was started. By default the start_time will be set to now, and the expires_in time will be set to the duration of the song.

    If context is provided when adding the listen action, this will be present when reading the listen back from the API. However if no context is provided when adding the listen action the fields associated with the context won't be present when you retrieve that listen. This means you won't receive back a 'musician' parameter for a listen of a song which was listened to without a musician context, but retrieving the song details via the song ID will return all the fields of the song, including musician.

    descriptionparameter name

    Playlist is the primary context

    playlist

    Album is the primary context

    album

    Musician page is the primary context

    musician

    Radio station is the primary context

    radio_station

    Time the song was started

    start_time

    Length of the song in seconds

    expires_in*

    Time when the song is expected to end

    end_time*

    Whether or not the song is paused

    paused

    *Specify expires_in OR end_time (not both).

    So for example, if a user played a song from their playlist on May 5th, 2011 and they listened for two minutes, this action should be posted:

    POST https://graph.facebook.com/me/music.listens?
                                   song=[song url]
                                  &playlist=[playlist url]
                                  &start_time=2011-05-05T13:22:12
                                  &end_time=2011-05-05T13:24:12

    This call will return an id that represents that listen. If a user stops or pauses the music after less than 15 seconds of a song, the action should be deleted by issuing a DELETE:

    DELETE https://graph.facebook.com/[listen id]

    In this case if the user clicks play again, you should publish a new action with the end_time set to when the song is expected to end (which should be earlier than the song duration plus the current time, since the song was started at an offset).

    If the user stops or pauses the music after more than 15 seconds of a song, but less than the complete song, the action should be updated to reflect the user has stopped listening by setting end_time to the time when the song was paused (the current time), and the paused attribute to true.

    POST https://graph.facebook.com/[listen id]?end_time=2011-05-05T13:25:14

    In this case if the user clicks play again, you should update the action so that the end_time accurately reflects when the song is expected to end, and so that paused is set to false. However, if the user has waited longer than the total song length before clicking play again, you should instead delete the old action and create a new one, since we consider this a fresh new listen.

    Playlists

    The moment a user creates a playlist we expect a music.playlists action to be published:

    POST https://graph.facebook.com/me/music.playlists?playlist=[playlist_url]

    If a user un-publishes a playlist you should delete the music.playlists action for this playlist by issuing a DELETE to the returned id (if the id is not saved you can query /me/music.playlists to get the user's list).

    If the user updates the contents of the playlist, you should update the meta tags on the playlist URL to reflect the new contents, and then force a scrape of the page. You can force a scrape by hitting: https://graph.facebook.com?id={playlist_url}&scrape=true

    Pointers

    (Pointers are not specific to music)

    There are some URLs that could have thousands of meta tags. We can’t force developers to slow down page load times to specify all of this information. Open Graph pointers allow you to separate open graph tags among many URLs. A pointer has a source URL, and a destination URL. The source URL is the main URL for this object - it is where we link to from Facebook. The destination URL is not for users, its only present to house meta tags.

    Semantics for pointers:

    • The source URL must contain the six basic meta tags, and we would prefer that the source URL contain all meta tags that aren’t repeated.
    • The source URL can have as many pointers as it wants.
    • Pointers are expressed as link tags with the rel attribute equal to ‘opengraph’; e.g. <link rel="opengraph" href={destintation_url}/>
    • The destination URL must include two things:
      1. og:type = metadata
      2. a link tag which points back to the source URL and has the rel attribute equal to origin; e.g. <link rel="origin" href={source_url}/>
    • Pointers are only one level deep, so a page of type ‘metadata’ cannot contain another link reg ‘opengraph’

    Example with playlists

    Source URL:

     <meta property="og:title" content="on repeat"/>
 <meta property="og:type" content="music.playlist"/>
 <meta property="og:url" content="http://open.spotify.com/user/austinhaugen/playlist/1a8444uyNXVOpwtFdgakhv"/>
 <meta property="og:image" content="http://o.scdn.co/300/756df3afcb3d14cb362448b68ed2f5506479f313"/>
 <meta property="og:site_name" content="Spotify"/>
 <meta property="fb:app_id" content="174829003346"/>
 <meta property="music:creator" content="http://open.spotify.com/user/austinhaugen"/>
 <link rel="opengraph" href={DESTINATION_URL}/>

    Destination URL:

     <meta property="og:type" content="metadata"/>
 <link rel="origin" href={SOURCE_URL}/>
 <meta property="music:song" content="http://open.spotify.com/track/3yM53DMMIioxVy7Pha1hD0">
 <meta property="music:song:track" content="1">     
 <meta property="music:song" content="http://open.spotify.com/track/4vVYPpGmuNowTTqof3k2wP">
 <meta property="music:song:track" content="2"> 
 ....