Accessing the FreeSound Database From Your Own Programs

I’ve received a couple of mails asking me about the details of the facilities freesound provides for easy sample search and retrieval from programs one can write in different languages to incorporate the system in ones own programs. When I first started looking at this some months ago, I found it hard to find info about this, and I had to dissect other peoples codes that do the job, I can’t really remember what they were but there were 2 source files (one in python and one in C++), both were not functioning correctly but with countless trial and error I managed to get things right. I’ve coded the freesound class for SuperCollider last week, and figured things were changed by then, so I’ve searched for the changes in the freesound forum, and found info about the little changes. Anyway, I’ll summarize the whole thing for anyone who is interested.

We’ll be using cURL for the examples, you can deal with the URL’s using the faciliites your programming language provides, or just pipe through cURL. Here we go…

Freesound uses a login system, so you need a username and password that can be obtained for free from the freesound website. Once you have your username and password ready, your program needs to login to the system, and store the cookie freesound provides for you. You’ll be using this cookie for your future queries. The way to go with this using cURL is:

curl -c cookie.txt -d "username=<username>&password=<password>&redirect=../index.php&login=login&autologin=0" http://www.freesound.org/forum/login.php

You should change the <username> and <password> with your own username and password. Once you run this, you will get a cookie from the freesound site called cookie.txt. We’ll need that cookie to make queries. But first we need to check if login was successful. A way to find it out is trying to fetch this page: http://www.freesound.org/searchTextXML.php and see if the header for the returned page lists text/xml as content type. The way to do this with cURL is:

curl -b cookie.txt -I http://www.freesound.org/searchTextXML.php

Parse the returning response. If you see Content-Type: text/xml; somewhere, that means your login was successful.

Once you make sure you have a valid login, you can make searches. There are many parameters available for directing search results. This is an example:

curl -b cookie.txt -d "search=train&start=0&searchDescriptions=1&searchTags=1&searchFilenames=0&searchUsernames=0&durationMin=0&durationMax=20&order=0&limit=100" http://www.freesound.org/searchTextXML.php

This searches for the samples with keyword train in descriptions, tags but not in filenames and usernames, which has a duration between 0 and 20 seconds, and limits the maximum number of resulting samples to 100. The “order”, according to the info I found at the freesound forum means this:

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;

You can tweak the other search options for your own liking. When you make this query, the freesound server will return you an XML file with the list of sample ids matching your criteria. It may look something like this:

<freesound nresults="335">
<sample id="74054" />
<sample id="74053" />
<sample id="74052" />
<sample id="74051" />
<sample id="74050" />
<sample id="74049" />
<sample id="74048" />
<sample id="74047" />
<sample id="74046" />
...
...
....
.....
<sample id="71687" />
<sample id="71686" />
</freesound>

Although number of found samples are 335 here, you will get 100 id numbers as dictated by your limit=100 choice above. You’ll need to get the sample ids from this XML file. If you need more info about a sample, you should do this:

curl -b cookie.txt http://www.freesound.org/samplesViewSingleXML.php?id=<id number for your sample>

You should put the id you want at the place of <id number for your sample> above. This will return some useful info about the sample you’ve chosen like duration, samplerate, bitrate, bitdepth, filesize, extension, geotag etc. in XML format.

If you find a sample that seems fit for you, you might want to download it.

Freesound redirects download requests so we need the get the exact URL of the file first, parse the header response from this to get the URL:

curl -b cookie.txt -I http://www.freesound.org/samplesDownload.php?id=<my sample id>

When you parse the URL (let me know if there is an easy way to get this when there are redirects) store it somewhere, and use this to download the file:

curl -b cookie.txt URL > filename

Where URL is the URL of the file you want to download and filename is the name of the file you want to download. When cURL finishes, you should have the file ready to be used in your programs.