Sample Pool API 2.0 [BETA]
The Sample Pool API allows two media hosting servers to keep track of when one uses samples from another. It is a RESTful API meaning URL goes in and XML comes out. The returning XML is in the form of a feed (RSS or Atom) with enclosures for downloading media.
Passive Sample Pools
To be a 'passive' sample pool means that you make sources available for sampling, but you don't care to keep track of how those samples are being used. In that case you only need to implement two URLs:
ccHost installations (like ccMixter.org) will keep a detailed sample history of your material with links back to your site (Example.)
URL | Query string | Returns | ||||||
---|---|---|---|---|---|---|---|---|
key | value | |||||||
/info | The general info for a pool. Just return a channel info without any items. (Example: http://ccmixter.org/api/pool/info) | |||||||
/search | query | search terms | RSS or Atom feed of matching results. The 'guid' (or 'id') element in these are used for further inquiries like '/file' and '/ubeensampled'. Default type of search is 'any' if none is specified. (Example: http://ccmixter.org/api/pool/search?query=mustang) | |||||
type | One of:
|
|||||||
limit* | Limits the number of items returned (e.g. limit=20) | |||||||
offset* | Return items starting at a given zero-based offset (e.g. offset=40) | |||||||
format* | One of:
|
Tracking Sample Pools
If you do want to keep track of who is remixing material on your site, then you need to implement two more:
URL | Query string | Returns | ||
---|---|---|---|---|
key | value | |||
/file | guid | file_guid | An RSS feed with a single item in it as identified by 'guid' (Example: http://ccmixter.org/api/pool/file?guid=http://ccmixter.org/files/RinkyD/3964) | |
/ubeensampled | guid | source_guid |
Returns nothing (or an 'OK' xml status if you like) -- This is strictly a notification
to let you know that something on your site has been remixed. The ccHost implementation
will call back to the pool site to get information about the remix so it can display
this information in the 'Sampled from this have been used in' user interface.
|
|
remixguid | remix_guid | |||
poolsite | url to calling pool |
Example
Assume that example1.com has source media for an artist called 'Brad Sucks' that a user at example2.com has downloaded, remixed and wants to upload to example2.com. Assume that base API url for both is at /api/pool.
example2.com calls to example1.com to query for the exact information:
http://example1.com/api/pool/search?query=brad+sucks&type=phrase
example1.com responds with an RSS feed with all sources matching the phrase 'brad sucks'.
The user at example2.com selects the matching source and example2.com extracts the guid for that source, combines it with the new guid for the user's upload and notifies example1.com of that the remix has occured (URL has been broken across lines for readability):
http://example2.com/api/pool/ubeensampled
?guid=http://example1.com/files/49565
&remixid=http://example2.com/files/43923
&pootsite=http://example2.com/api/pool
The actual guids are extracted from the RSS feed results from '/search' so it does not matter what format they are. In this case both servers use URLs but that is totally up to each implementation.
Sample Feed
When exchanging media information a standard, validing RSS or ATOM is expected (the same thing you're already putting out for podcasts in the case of music sites). Creative Commons license information should be included:
<?xml version="1.0" encoding="utf-8" ?>
<rss version="2.0"
xmlns:content="http://purl.org/rss/1.0/modules/content/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd">
<channel>
<title>ccMixter (spoken_word)</title>
<link>http://cchost.org</link>
<description>Download, Sample, Cut-up, Share.</description>
<language>en-us</language>
<pubDate>Mon, 06 Feb 2006 19:34:55 PST</pubDate>
<lastBuildDate>Mon, 06 Feb 2006 19:34:55 PST</lastBuildDate>
<item>
<title>Generation Defects</title>
<link>http://cchost.org/files/aerosolspray/3374</link>
<pubDate>Tue, 20 Dec 2005 21:32:04 PST</pubDate>
<dc:creator>aerosolspray</dc:creator>
<description> A piece of music by me.</description>
<content:encoded><![CDATA[A piece of music by me.]]></content:encoded>
<enclosure
url="http://cchost.org/people/aerosolspray/aerosolspray_-_Generation_Defects.wma"
length="952466"
type="audio/x-ms-wma"></enclosure>
<category>media</category>
<category>remix</category>
<category>non_commercial</category>
<category>audio</category>
<category>wma</category>
<category>44k</category>
<category>stereo</category>
<category>CBR</category>
<category>chill</category>
<category>drums</category>
<category>electronic</category>
<category>spoken_word</category>
<category>synth</category>
<guid>http://cchost.org/files/aerosolspray/3374</guid>
<cc:license>http://creativecommons.org/licenses/by-nc/2.5/</cc:license>
</item>
</channel>
</rss>
The ATOM version is still being tested but this is the current format that should work:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>ccMixter (spoken_word) [BETA]</title>
<link rel="self" href="http://cchost.org/feed/atom/spoken_word"></link>
<link rel="alternate" href="http://cchost.org/tags/spoken_word"></link>
<updated>2006-02-06T19:34:55-08:00</updated>
<id>http://cchost.org/tags/spoken_word</id>
<entry>
<id>http://cchost.org/files/aerosolspray/3374</id>
<title>Generation Defects</title>
<author>
<name>aerosolspray</name>
</author>
<link rel="alternate"
href="http://cchost.org/files/aerosolspray/3374" type="text/html">
</link>
<link rel="enclosure"
href="http://cchost.org/people/aerosolspray/aerosolspray_-_Generation_Defects.wma"
length="952466"
type="audio/x-ms-wma">
</link>
<category term="media"></category>
<category term="remix"></category>
<category term="non_commercial"></category>
<category term="audio"></category>
<category term="wma"></category>
<category term="44k"></category>
<category term="stereo"></category>
<category term="CBR"></category>
<category term="chill"></category>
<category term="drums"></category>
<category term="electronic"></category>
<category term="spoken_word"></category>
<category term="synth"></category>
<updated>2005-12-20T21:32:04-08:00</updated>
<content type="text/plain"> A piece of music by me.</content>
<link rel="license"
href="http://creativecommons.org/licenses/by-nc/2.5/"
type="text/html">
</link>
</entry>
</feed>