Audiobaba Public API (APAPI) Documentation

Last updated on October 3, 2007

Overview

The Audiobaba API was written using the XML RPC interface, which is accessible from a variety of languages. In order to use this interface, you will need to obtain a special key from Audiobaba.

Sample source code is provided at the bottom of this documentation.

Quick Index

Sample Code

Perl

API Reference

Method: audiobaba.submit_track
Description: Submits a track to the Audiobaba processing queue
Inputs:

Required

api_key: key obtained from Audiobaba
url: link to the track media (in http:// format)
provider_url: link to the store page for this track
indie: boolean 1 or 0 indicating whether the track is indie
price: price of the track, in US $ cents (for example 99)
preview_duration: number of seconds to use for preview (minimum is 30 seconds, use 0 for entire track)

Optional

art_url: link to the album art (in http:// format)
title: string containing track title
artist: string containing artist name
album: string containing album name
genre: string containing genre, if known
year: year the track was released
language: language of the vocals
email: email address of the artist, if available

Returns

success: an 8 character uid (unique identifier) that can later be used to refer to this track
failure: 0 and error string

Comments

The track will be downloaded at some point in the future, have its acoustic features extracted and the metadata stored on our servers
If the track is free, and you give Audiobaba permission to freely distribute it, specify 0 as the price
If the track price flactuates, or is unavailable, use a negative number
If the year of release is unavailable, either skip the parameter or use "0"
Use "none" for language if the track is purely acoustic, or "unknown" if unavailable

Method: audiobaba.track_status
Description: Check whether a track has been processed
Inputs:

Required

api_key: key obtained from Audiobaba
uid: unique identifier obtained from submit_track

Optional

Returns

success: non-zero and a string describing the status of the file
failure: 0 and error string

Comments

Some common status results are noted below:
Pending: track has not been processed yet
OK: track has been processed and should be available shortly via the API / Search Engine
Track is missing: the Audiobaba bot was unable to download the file at the specified URL

Method: audiobaba.remove_track
Description: Removes a track from the Audiobaba database
Inputs:

Required

api_key: key obtained from Audiobaba
uid: unique identifier obtained from submit_track

Optional

Returns

success: non-zero value
failure: 0 and error string

Comments

The specified track will be marked for removal from the Audiobaba database
** NOTE: this method is currently NOT implemented

Method: audiobaba.search_keyword_count
Description: Performs a keyword search on the Audiobaba music database and returns the # of matches
Inputs:

Required

api_key: key obtained from Audiobaba
keywords: keywords to search for (whitespace separated)

Optional

Returns

the number of keyword matches (0 if none found)

Comments

this search spans every available track in the Audiobaba music database

Method: audiobaba.search_keyword
Description: Performs a keyword search on the Audiobaba music database
Inputs:

Required

api_key: key obtained from Audiobaba
keywords: keywords to search for (whitespace separated)
offset: offset to start returning tracks from
max_results: maximum number of tracks to return

Optional

Returns

success: list of comma-separated track_ids, sorted alphabetically by track title and then by artist name
failure: 0 and error string

Comments

this search spans every available track in the Audiobaba music database

Method: audiobaba.search_acoustic
Description: Performs an acoustic search on the Audiobaba music database
Inputs:

Required

api_key: key obtained from Audiobaba
track_id: track to use as seed for acoustic search
max_results: maximum number of results
global: boolean 0 or 1 specifying whether you want results from your submitted tracks or our entire collection (1=entire)

Optional

Returns

success: list of comma-separated track_ids, sorted by similarity (most->least)
failure: 0 and error string

Comments

Currently the maximum # of results is capped at 45

Method: audiobaba.get_metadata
Description: Retrieves the metadata for a specified set of tracks
Inputs:

Required

api_key: key obtained from Audiobaba
track_ids: comma separated tracks to return metadata for

Optional

Returns

success: metadata for the set of songs
failure: 0 and error string

Comments

retrieves an array of track_id, title, artist, album, duration for the requested tracks, separated with |
tracks are returned in the order they were requested
metadata retrieval is capped at 30 tracks per call

Method: audiobaba.track_to_uid
Description: Converts from track_id to uid
Inputs:

Required

api_key: key obtained from Audiobaba
track_ids: comma separated tracks to return uids for (will only match ones submitted using this api_key)

Optional

Returns

success: comma-separated uids (0 for any non-mappable track)
failure: 0 and error string

Comments

none

Method: audiobaba.uid_to_track
Description: Converts from uid to track_id
Inputs:

Required

api_key: key obtained from Audiobaba
uids: comma separated uids to return track_ids for (will only match ones submitted using this api_key)

Optional

Returns

success: comma-separated track_ids (0 for any non-mappable track)
failure: 0 and error string

Comments

none

Method: audiobaba.reflection
Description: Retrieve a list of valid methods for this API
Inputs:

Required

api_key: key obtained from Audiobaba

Optional

Returns

list of all valid API methods

Comments

this function is for debugging purposes only

Method: audiobaba.echo
Description: Returns all the arguments that are passed into it
Inputs:

Required

api_key: key obtained from Audiobaba

Optional

any number of arguments

Returns

the list of arguments, unmodified

Comments

this function is for debugging purposes only

Method: audiobaba.testing
Description: Returns the string 'yes' always
Inputs:

Required

api_key: key obtained from Audiobaba

Optional

any number of arguments

Returns

'yes' always

Comments

this function is for debugging purposes only

Method: audiobaba.null
Description: Takes no arguments and always returns success. Use to test simplest possible case
Inputs:

Required

Optional

Returns

true

Comments

this function is for debugging purposes

Sample Code

Language: Perl (tested under v5.8.8)

#!/usr/bin/perl -w

use strict;
use XMLRPC::Lite;
use Data::Dumper;

my $result;

my $server = 'http://webservices.audiobaba.com/audiobaba';
my $api_key = 'your_api_key_goes_here';

# lets perform a keyword search first
my @args = ($api_key, 'killers somebody', 0, 100);
$result =  XMLRPC::Lite
      -> proxy($server)
      -> call('audiobaba.search_keyword', @args)
      -> result;

print Dumper($result);

if ($result && $result->[0])
{
    my $tracks = $result->[1];
    print "keyword matches are $tracks\n";

    my @matches = split(',', $tracks);

    my $first = $matches[0];

    print "first match is $first\n";

    print "Performing acoustic matching...\n";
    my @args = ($api_key, $first, 10, 1);
    $result =  XMLRPC::Lite
          -> proxy($server)
          -> call('audiobaba.search_acoustic', @args)
          -> result;

    print Dumper($result);

    if ($result && $result->[0])
    {
        # append the original seed track so we get the metadata for it as well
        $tracks = "$first," . $result->[1];

        print "Retrieving metadata for acoustic matches\n";
        my @args = ($api_key, $tracks);
        print "args are @args\n";
        $result =  XMLRPC::Lite
              -> proxy($server)
              -> call('audiobaba.get_metadata', @args)
              -> result;

        if ($result && $result->[0])
        {
            my @results = map( [ split('\|', $_) ], @{ $result->[1] } );
            my %hashed= map { shift @$_, [ @$_ ] } @results;

            # print Dumper(%hashed);

            print "\nFinal results are:\n";

            foreach my $track_id ( split(',', $tracks) )
            {
                my $track = $hashed{$track_id};
                if ($track)
                {
                    print "$track_id\t$track->[0] by $track->[1]\n";
                }
            }       
        }
    }
}

Save source code

Home