SuperCollider client for the Freesound API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

SuperCollider client for is a collaborative database of sound samples licensed under Creative Commons, supported by the Music Technology Group at Universitat Pompeu Fabra (Barcelona). In its current implementation, provides a web API based on REST principles. The general documentation for the API can be found at This quark provides a client for accessing the Freesound API from within SuperCollider. For the moment, only the Sound resource is supported. Prospective users are advised to apply for an API key at Being a web API, this form expects you to fill information about a hypothetical web application, but there is no restriction for using the API for music creation or performance. For general discussion about the API, join the google group:

The API provides several response formats, but JSON is generally preferred. This quark provides a convenience wrapper around the most important calls by requesting resources via curl, and mapping JSON responses to SC Dictionary objects.

This version supports APIv2, which introduced some differences with repect to APIv1. The most important change is that two types of authentication are used: Token and Oauth2 ( Oauth2 authentication is required for some calls, including downloading sounds at their original quality. These features require a Freesound account in the website, which could be circumvented by applications using the older API. In the case of SuperCollider programs, most often you will be both the developer and user of your program, in which case you simply use your Freesound account. Note that using the simpler token authentication method you can access the compressed previews in ogg and mp3 format. If you compile and link scsynth against a current version of libsndfile, you should be able to use the hi-quality ogg previews (192kbps).


// Token Authentication
// After obtaining the API key, this is the only thing you need to do for authenticating with the token method:

Freesound.authType = "token";// default, only needed if you changed it

// Oauth2 Authentication
// Slightly more involved, here's the recommended procedure:
// 1. Obtain the API key (note that old APIv1 keys will not work)
// 2. Get the authorization URL:

Freesound.clientSecret = "<your_client_secret>";
Freesound.authType = "oauth2";

// 3. Open the URL that shows in the post window in a web browser
// 4. Within the nex 10 minutes, request your first token:
// This will save the token in a file besides the Freesound class file (you can change this path if you need to manage multiple tokens). This token will last 24h. From then on you can renew it e.g. each time you start a session:

Freesound.clientId = "<your_client_id>";
Freesound.clientSecret = "<your_client_secret>";
Freesound.authType = "oauth2";

// Get sound by id

FSSound.getSound(31362, {|f|
    ~snd = f;

// Metadata about the sound is loaded from the JSON response into a dictionary, and also accessible using object syntax
// preview url keys have dashes, only work as dict keys

// download preview ( requires recent libsndfile)
~preview = ~snd.retrievePreview("/tmp/", {
        ~buf =, "/tmp/" ++ ~snd.previewFilename);

"/tmp/" ++ ~snd.previewFilename.postln;;

// Similar sounds

~snd.getSimilar( action:{|p| ~snd = p[1] ;})

// Analysis

~snd.getAnalysis( "lowlevel.pitch", {|val|
}, true)

// Text search

FSSound.textSearch( query: "glitch", filter: "type:wav",params:('page':2), action:{|p|
    ~snd = p[0]; // first result;

// Download (if you did oauth2 authentication!)

~snd.retrieve("/tmp/", {
    ~buf =, "/tmp/" ++;
	("/tmp/" ++;

// Content-based search:

	target: '.lowlevel.pitch.mean:600',
	filter: '.lowlevel.pitch_instantaneous_confidence.mean:[0.8 TO 1]',
	params: ('page':2), action: {|pager|
		    ~snd = pager[0];;

// Combined (text and content) search:

FSSound.combinedSearch(query: "glitch", filter: "type:wav",
    descriptorsFilter: ".lowlevel.pitch_instantaneous_confidence.mean:[0.8 TO 1]",
    params:('page': 4), action:{|pager|
        ~snd = pager[0];;