Music for Healing-Pells, Samples, Remixes
skip

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.)

URLQuery stringReturns
keyvalue
/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:
anyMatch any terms
allMatch all terms
phraseMatch exact phrase
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:
rssReturn a RSS 2.0 feed (default)
atomReturn an ATOM 1.0 feed
countReturn a count of times
*Proposed for version 2.0

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:

URLQuery stringReturns
keyvalue
 
/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.
  • 'guid' refers to an upload on your server
  • 'remixguid' refers to the remote remix
  • 'poolsite' base API URL of the remote pool.
Use the form poolsite/file?guid=remixguid to find out more about the remix.
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>