FreeSound provides access to the sample database at freesound.org


Inherits from: Object


This class downloads samples from the freesound database (http://www.freesound.org ) based on flexible criterias the user supplies. The downloaded file can then be loaded into a buffer and used in the SC environment.


Some Important Issues Regarding FreeSound


Querying and downloading files over the Internet is an asynchronous operation, and this class provides a non-blocking approach, that is, the operation(s) takes some time to complete but the sclang environment and further code execution while performing searches and downloading files is not blocked. 


The user class provides a callback function to this class, and the class "calls back" that function with arguments that tell about the status of the operation(s) requested.


Creation / Class Methods



*new (argSearchOptions, argUserPass, argCallbackFunc)

argSearchOptions - This is a Dictionary of search options. The keys and default values are:

\keyword -> "train", //who doesn't like trains?

\searchDescriptions -> 1, //should search the keyword in freesound file descriptions? should be 1 or 0

\searchTags -> 1, //should search the keyword in freesound tags? should be 1 or 0

\searchFileNames -> 0, //should search the keyword in filenames? should be 1 or 0

\searchUserNames -> 0, //should search the keyword in user names?

\durationMin -> 1, //minimum duration in seconds

\durationMax -> 20, //maximum duration in seconds

\startFrom -> 0, //the results start from this index

\limit -> 100, //maximum number of results

\order -> 0, //ordering of results, according to freesound, this value is:

/*

ORDER_DEFAULT = 0;

ORDER_DOWNLOADS_DESC = 1;

ORDER_DOWNLOADS_ASC = 2;

ORDER_USERNAME_DESC = 3;

ORDER_USERNAME_ASC = 4;

ORDER_DATE_DESC = 5;

ORDER_DATE_ASC = 6;

ORDER_DURATION_DESC = 7;

ORDER_DURATION_ASC = 8;

ORDER_FILEFORMAT_DESC = 9;

ORDER_FILEFORMAT_ASC = 10;

*/


argUserPass - This is an array. You MUST fill this array with your freesound username and password. eg: ["username", "password"]

argCallbackFunc - Since the operations this class do are asynchronous, you provide this callback function to the class, and your instance calls this function with three parameters: 

arg fsInstance, status, info;

fsInstance: The instance of FreeSound this callback is bound to.

info: (see below)

status: This is to be interpreted with the info argument. There are several cases for this argument:

1: trying to login

2: login successful

-2: login failed

3: performing search

4: search complete, second info arg is number of results returned (integer)

-4: there was an error in searching.

5: returning sample info, the argument info is a dictionary about the properties of the file. The keys of the info dictionary are:

\numDownloads, //number of times this file has been downloaded (integer)

\extension, //extension of the file (symbol)

\sampleRate, //sampleRate of the file (integer)

\bitRate, //useful for compressed files. Bitrate of the file. (integer)

\bitDepth, //bit depth of the file. (integer) (ex: 16, 24)

\numChannels, //number of channels of the file (integer)

\duration, //duration of the file in seconds (float)

\fileSize, //size of the file (integer)

\index, //index of the file meaningful for the internal state of your instance. (integer) For example, if you want to download THIS particular file, you'll need to call fsInstance.downloadSample(info.at(\index));

-5: there was an error getting sample info.

6: file downloaded. info argument is the file path for the downloaded file.

-6: there was an error in downloading the file.

// example

s.boot;

(

//remember to fill your own username and password here!

a = FreeSound((\keyword: "train", \durationMax: 5), ["username", "password"])

.verbose_(true)

.callbackFunc_

({|fs, argStat, argInfo|

argStat.switch

(

4, //search is complete

{

fs.getSampleInfo(argInfo.rand);

},

5,

{ //got info for the sample

if(argInfo.at(\extension) == \wav 

and: { argInfo.at(\sampleRate) == 44100 }

and: { argInfo.at(\bitDepth) == 16 },

{

fs.downloadSample(argInfo.at(\index));

},

{//choose another

fs.getSampleInfo(fs.numSamples.rand);

});

},

6, //download complete

{

"Seems like its downloaded! Will play it now.".postln;

b = Buffer.read(s, argInfo, action: { b.play; });

}

);

});

)

a.doSearch;


Accessing Instance and Class Variables

verbose_(boolean)

verbose

verbose mode on or off. If true, info about the operation will be posted to the post window.

Default is false.

numSamples

Number of samples returned from the search. You can use a number between 0 and (numSamples-1) as an argument for the getSampleInfo and downloadSample methods.

Methods



doSearch

See the above example for usage. Performs a search based on given data. When the search is complete, the callback function is called with the second argument set to 4.


getSampleInfo (argIndex)

Queries the properties of the soundfile from the freesound database. When it is done, the callback function is called with the second argument set to 5. The third argument passed to the callback function is a dictionary filled with properties of the sound file. Try the above example to see it in action.



downloadSample (argIndex, argPath)

Downloads the sample no argIndex to argPath (default /tmp/). The index should be between 0 and (numSamples-1). When it finishes downloading, the callback function is called with the second argument set to 6. The third argument is set to the path of the downloaded file (path + name).