By

Dubset

1. Introduction

MixSCAN is a RESTful job-based API that allows you to fingerprint individual files that may contain more than one song or artist over time. What do we mean by job based? Each time you make a request to MixSCAN you will be returned with a small amount of metadata for the mix before the scan has actually taken place. This allows you to go back and ping the API about the status of your scan over time. The worker queue for our Limited Preview during Music Hack Day NYC isn't gigantic, so proceed with caution.

Note: All examples in this documentation are implemented using node.js, which is the underlying runtime environment powering MixSCAN

2. Authenticating

The first thing that you will need to do before you can start scanning and working with mixes is to authenticate with MixSCAN. The MixSCAN API uses HTTP Basic Auth to identify users. Basic Auth is actually incredibly simple to implement: just include the 'Authorization' header with the 'Basic' realm your 'username:password' base64 encoded:

      
        var http = require('http');
        
        var encodedCredentials = new Buffer('username:password').toString('base64')
        var options = {
          host: 'api.mixscan.com',
          port: 80,
          path: '/',
          method: 'POST',
          headers: {
            'Authorization': 'Basic ' + encodedCredentials
          }
        };
        
        http.request(options, function (response) {
          //
          // You just made an authenticated request to MixSCAN.
          //
        });
      
    

3. Scanning Mixes // [POST /scans]

So now that we know how to make an authenticated request, lets start fingerprinting mixes. There are two ways to do this with the MixSCAN API. The first is by sending 'application/json' content with a remote URL pointed to where your mix lives on the Web:

      
        var options = {
          host: 'api.mixscan.com',
          port: 80,
          path: '/scans',
          method: 'POST',
          body: JSON.stringify({
            download: true,
            media: http://forwardslashtheinternet.com/your-mix.mp3
          }),
          headers: {
            'Authorization': 'Basic ' + encodedCredentials,
            'Content-Type': 'application/json'
          }
        };
        
        //
        // Use http.request() to make the same request with these options
        //
      
    

The other way that you can start a scan is to POST raw 'audio/mpeg' to the same URL:

      
        var fs = require('fs');
        
        fs.readFile('your-mix.mp3', function (err, data) {
          if (err) return console.log('Hey your files wasnt on disk, what gives?');
          
          var options = {
            host: 'api.mixscan.com',
            port: 80,
            path: '/scans',
            method: 'POST',
            body: data,
            headers: {
              'Authorization': 'Basic ' + encodedCredentials
              'Content-Type': 'audio/mpeg'
            }
          };
          
          //
          // Use http.request() to make the same request with these options
          //
        });
      
    

4. Listing Results // [GET /scans/:id]

Whether you upload an audio file to MixSCAN or provide a URL of a mix to download remotely, you will always get back a a JSON literal with a small amount of metadata for your mix. Here's a quick sample:

      
        {
           "_id": "mixmDtMzs",
           "type": "mix",
           "createdAt": 1297508724866,
        }
      
    

The key property in that object is the '_id', which is the unique identifier for your pending mix scan and when completed, the results. Once you've created a job you can simply query the API by making a request to '/scans/:id'. When your mix scan is complete, the JSON object returned will have an array of 'samples' that look something like this:

      
        {
          "startTime": {
            "msecs": 526200
          },
          "length": {
            "msecs": 145628
          },
          "best": {
            "id": "915317",
            "ber": 0.377441,
            "album": "Make Her Say",
            "publisher": "UMG",
            "artist": "Kid Cudi",
            "title": "Make Her Say",
            "timeAt": {
              "msecs": 189835
            },
            "length": {
              "msecs": 2972
            }
          }
        }      
      
    

5. Adding Metadata // [PUT /scans/:id]

Currently MixSCAN is backed by CouchDB and we don't place a lot of restrictions on the data that can be stored in a given document. What this means to you is that you can store additional metadata about a given mix by simply making a PUT request to '/scans/:id'.

      
        var options = {
          host: 'api.mixscan.com',
          port: 80,
          path: '/scans/mixmDtMzs',
          method: 'PUT',
          body: JSON.stringify({
            somethingMeta: 'Really clever cross referencing data here'
          }),
          headers: {
            'Authorization': 'Basic ' + encodedCredentials,
            'Content-Type': 'application/json'
          }
        };
        
        //
        // Use http.request() to make the same request with these options
        //
      
    

6. Support & Feedback

We are opening this Limited Preview of MixSCAN beta exclusively for Music Hack Day NYC 2011. If you encounter any bugs or issues while using MixSCAN during the hackathon just look for the Dubset team or shoot and email to our Technology Director, Charlie Robbins.