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:

any	Match any terms
all	Match all terms
phrase	Match 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:

rss	Return a RSS 2.0 feed (default)
atom	Return an ATOM 1.0 feed
count	Return 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:

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

Search

Sample Pool API 2.0 [BETA]

Passive Sample Pools

Tracking Sample Pools

Example

Sample Feed