soundcloud / api

Home | Edit | New

oEmbed API

oEmbed is an open standard for embedding external content into a website. In the case of SoundCloud it will embed the Flash player for a track or set. You can use the normal URL of any track or set to easily obtain the embed code for it. To find out more about oEmbed, view the spec or check out Webmonkey’s Get Started With oEmbed tutorial.

API Endpoints

You can use the API endpoint to request the embed code for a track/set/group from its URL. The response format can be either xml, json or js (for JSONP).

http://soundcloud.com/oembed

Soundcloud currently supports embedding of users, tracks, sets and groups. The accepted URL schemes are:

http://soundcloud.com/*
http://soundcloud.com/*/*
http://soundcloud.com/*/sets/*
http://soundcloud.com/groups/*

Both return the same data, though the embedded player will have a different height.

Discovery

Soundcloud also supports discovery of the oEmbed URL. Each set and track page has two link tags with types application/json+oembed and application/xml+oembed containing the URLs for JSON and XML oEmbed responses.

Arguments

All arguments are sent as query parameters and must be urlencoded (as per RFC 1738).

url The Soundcloud URL for a track or set.
format (optional) Either xml, json or js (for JSONP). Defaults to json.
maxwidth (optional) The maximum width for the player. Defaults to 100%
maxheight (optional) The maximum height for the player. Defaults to 81 for tracks and 305 for sets.
color (optional) The color for the player. Defaults to orange.
auto_play (optional) Whether the widget auto plays or not. Defaults to false.
show_comments (optional) Whether the player displays timed comments for each track. Defaults to true.
callback (optional) In case you request a jsonp response by setting format=js, this callback function will be executed

Notes: The embedded player has some size limitations that the maxwidth and maxheight arguments can’t override. The exact limitations depends on whether it is a track or set player.

Track player Height is always 81. Requesting a maxheight will do nothing.
Set player Minimum height is 225. A request maxheight larger than that will generate a correctly sized player, smaller than that will produce a 501 error.
Both players Minimum width is 180, a request with a maxwidth of less than 180 will return a 501 error.

Example Call

http://soundcloud.com/oembed?url=http%3A//soundcloud.com/forss/flickermood

Example Responses

As mentioned above, the default width for the player is 100%. The current oembed specification requires the returned data to specify the width in pixels, which is not practical. Therefore is you did not specify a maxwidth the returned width parameter will be 0. If you require the width to be correctly set please provide a maxwidth.

XML

Call:

http://soundcloud.com/oembed?url=http%3A//soundcloud.com/forss/flickermood&format=xml

Response:

<oembed>
	<html><![CDATA[<object height="81" ... ]]></html>
	<user>Forss</user>

	<permalink>http://soundcloud.com/forss/flickermood</permalink>
	<title>Flickermood</title>
	<type>rich</type>
	<provider-url>http://soundcloud.com</provider-url>
	<description>From the Soulhack album...</description>
	<version type="float">1.0</version>

	<user-permalink-url>http://soundcloud.com/forss</user-permalink-url>
	<height type="integer">81</height>
	<provider-name>Soundcloud</provider-name>
	<width type="integer">0</width>
</oembed>

JSON

Call:

http://soundcloud.com/oembed?url=http%3A//soundcloud.com/forss/flickermood&format=json

Response:

{
	"html":"<object height=\"81\" ... ",
	"user":"Forss",
	"permalink":"http:\/\/soundcloud.com\/forss\/flickermood",
	"title":"Flickermood",
	"type":"rich",
	"provider_url":"http:\/\/soundcloud.com",
	"description":"From the Soulhack album...",
	"version":1.0,
	"user_permalink_url":"http:\/\/soundcloud.com\/forss",
	"height":81,
	"provider_name":"Soundcloud",
	"width":0
}

JSONP

Call:

http://soundcloud.com/oembed?url=http%3A//soundcloud.com/forss/flickermood&format=js&callback=MyCallback

Response:

MyCallback({
	"html":"<object height=\"81\" ... ",
	"user":"Forss",
	"permalink":"http:\/\/soundcloud.com\/forss\/flickermood",
	"title":"Flickermood",
	"type":"rich",
	"provider_url":"http:\/\/soundcloud.com",
	"description":"From the Soulhack album...",
	"version":1.0,
	"user_permalink_url":"http:\/\/soundcloud.com\/forss",
	"height":81,
	"provider_name":"Soundcloud",
	"width":0
});

Pages feed

Last edited by lenberg, Wed Sep 16 03:15:57 -0700 2009
Home | Edit | New
Versions: