cd _do.. _resources:

Resources

Search resources

Warning

When using the search resources make sure to include the fields parameter (see Response (sound list)) so that you get all needed metadata for each search result in a single request. In this way you’ll avoid having to perform one extra API request to retreive the desired metadata for each individual result.

Sound resources

Sound Instance

GET /apiv2/sounds/<sound_id>/

This resource allows the retrieval of detailed information about a sound.

Warning

If you’re using this resource to get metadata for each individual result returned after a search request, try instead to include the fields parameter in your search request (see Response (sound list)). This will allow you to specify which metadata is to be returned for each search result, and remove the need of making an extra query for each individual result.

Response (sound instance)

The Sound Instance response is a dictionary including the following properties/fields:

Name Type Description
id number The sound’s unique identifier.
url URI The URI for this sound on the Freesound website.
name string The name user gave to the sound.
tags array[strings] An array of tags the user gave to the sound.
description string The description the user gave to the sound.
geotag string Latitude and longitude of the geotag separated by spaces (e.g. “41.0082325664 28.9731252193”, only for sounds that have been geotagged).
created string The date when the sound was uploaded (e.g. “2014-04-16T20:07:11.145”).
license string The license under which the sound is available to you.
type string The type of sound (wav, aif, aiff, mp3, m4a or flac).
channels number The number of channels.
filesize number The size of the file in bytes.
bitrate number The bit rate of the sound in kbps.
bitdepth number The bit depth of the sound.
duration number The duration of the sound in seconds.
samplerate number The samplerate of the sound.
username string The username of the uploader of the sound.
pack URI If the sound is part of a pack, this URI points to that pack’s API resource.
download URI The URI for retrieving the original sound.
bookmark URI The URI for bookmarking the sound.
previews object Dictionary containing the URIs for mp3 and ogg versions of the sound. The dictionary includes the fields preview-hq-mp3 and preview-lq-mp3 (for ~128kbps quality and ~64kbps quality mp3 respectively), and preview-hq-ogg and preview-lq-ogg (for ~192kbps quality and ~80kbps quality ogg respectively). API authentication is required for retrieving sound previews (Token or OAuth2).
images object Dictionary including the URIs for spectrogram and waveform visualizations of the sound. The dinctionary includes the fields waveform_l and waveform_m (for large and medium waveform images respectively), and spectral_l and spectral_m (for large and medium spectrogram images respectively).
num_downloads number The number of times the sound was downloaded.
avg_rating number The average rating of the sound.
num_ratings number The number of times the sound was rated.
rate URI The URI for rating the sound.
comments URI The URI of a paginated list of the comments of the sound.
num_comments number The number of comments.
comment URI The URI to comment the sound.
similar_sounds URI URI pointing to the similarity resource (to get a list of similar sounds).
analysis object Dictionary containing requested descriptors information according to the descriptors request parameter (see below). This field will be null if no descriptors were specified (or invalid descriptor names specified) or if the analysis data for the sound is not available.
analysis_stats URI URI pointing to the complete analysis results of the sound (see Analysis Descriptor Documentation).
analysis_frames URI The URI for retrieving a JSON file with analysis information for each frame of the sound (see Analysis Descriptor Documentation).
ac_analysis object Dictionary containing the results of the AudioCommons analysis for the given sound.

The contents of the field analysis of the Sound Instance response can be determined using an additional request parameter descriptors. The descriptors parameter should include a comma separated list of content-based descriptor names, just like in the Response (sound list). Descriptor names can be any of those listed in available-descriptors (e.g. descriptors=lowlevel.mfcc,rhythm.bpm). The request parameter normalized can also be used to return content-based descriptor values in a normalized range instead of the absolute values.

The parameter fields can also be used to restrict the number of fields returned in the response.

Examples

Complete sound information:

https://freesound.org/apiv2/sounds/1234/

Complete sound information plus some descriptors:

https://freesound.org/apiv2/sounds/213524/?descriptors=lowlevel.mfcc,rhythm.bpm

Getting only id and tags for a particular sound:

https://freesound.org/apiv2/sounds/1234/?fields=id,tags

Getting sound name and spectral centroid values (second example gets normalized centroid values):

https://freesound.org/apiv2/sounds/1234/?fields=name,analysis&descriptors=lowlevel.spectral_centroid
https://freesound.org/apiv2/sounds/1234/?fields=name,analysis&descriptors=lowlevel.spectral_centroid&normalized=1

Sound Analysis

GET /apiv2/sounds/<sound_id>/analysis/

This resource allows the retrieval of analysis information (content-based descriptors) of a sound. Although content-based descriptors can also be retrieved using the descriptors request parameter in any API resource that returns sound lists or with the Sound Instance resource, using the Sound Analysis resource you can retrieve all sound descriptors at once.

Response

The response to a Sound Analysis request is a dictionary with the values of all content-based descriptors listed in Analysis Descriptor Documentation. That dictionary can be filtered using an extra descriptors request parameter which should include a list of comma separated descriptor names chosen from those listed in available-descriptors (e.g. descriptors=lowlevel.mfcc,rhythm.bpm). The request parameter normalized can also be used to return content-based descriptor values in a normalized range instead of the absolute values.

Examples

Full analysis information:

https://freesound.org/apiv2/sounds/1234/analysis/

Getting only tristimulus descriptor:

https://freesound.org/apiv2/sounds/1234/analysis/?descriptors=sfx.tristimulus

Getting normalized mean mfcc descriptors:

https://freesound.org/apiv2/sounds/1234/analysis/?descriptors=lowlevel.mfcc.mean&normalized=1

Similar Sounds

GET /apiv2/sounds/<sound_id>/similar/

This resource allows the retrieval of sounds similar to the given sound target.

Request parameters

Essentially, the Similar Sounds resource is like a Content Search resource with the parameter target fixed to the sound id indicated in the url. You can still use the descriptors_filter request parameter to restrict the query results to those sounds whose content descriptor values comply with the defined filter. Use descriptors_filter in the same way as in Content Search.

Response

Similar Sounds resource returns a sound list just like Response (sound list). The same extra request parameters apply (page, page_size, fields, descriptors and normalized).

Examples

Getting similar sounds:

https://freesound.org/apiv2/sounds/80408/similar/
https://freesound.org/apiv2/sounds/80408/similar/?page=2
https://freesound.org/apiv2/sounds/1234/similar/?fields=name,analysis&descriptors=lowlevel.pitch.mean&descriptors_filter=.lowlevel.pitch.mean:%5B90%20TO%20110%5D

Sound Comments

GET /apiv2/sounds/<sound_id>/comments/

This resource allows the retrieval of the comments of a sound.

Response

Sound Comments resource returns a paginated list of the comments of a sound, with a similar structure as Response (sound list):

{
  "count": <total number of comments>,
  "next": <link to the next page of comments (null if none)>,
  "results": [
      <most recent comment for sound_id>,
      <second most recent comment for sound_id>,
      ...
  ],
  "previous": <link to the previous page of comments (null if none)>
}

Comments are sorted according to their creation date (recent comments in the top of the list). Parameters page and page_size can be used just like in Response (sound list) to deal with the pagination of the response.

Each comment entry consists of a dictionary with the following structure:

{
  "username": <username of the user who made the comment>
  "comment": <the comment itself>,
  "created": <the date when the comment was made, e.g. "2014-03-15T14:06:48.022">
}

Examples

Get sound comments:

https://freesound.org/apiv2/sounds/14854/comments/
https://freesound.org/apiv2/sounds/14854/comments/?page=2

Download Sound (OAuth2 required)

GET /apiv2/sounds/<sound_id>/download/

This resource allows you to download a sound in its original format/quality (the format/quality with which the sound was uploaded). It requires OAuth2 authentication.

Examples

Download a sound:

curl -H "Authorization: Bearer {{access_token}}" 'httpss://freesound.org/apiv2/sounds/14854/download/'

Upload Sound (OAuth2 required)

POST /apiv2/sounds/upload/

This resource allows you to upload an audio file into Freesound and (optionally) describe it. If no file description is provided (see below), only the audio file will be uploaded and you will need to describe it later using the Describe Sound (OAuth2 required) resource. If the file description is also provided, the uploaded file will be ready for the processing and moderation stage. A list of uploaded files pending description, processing or moderation can be obtained using the Pending Uploads (OAuth2 required) resource.

The author of the uploaded sound will be the user authenticated via OAuth2, therefore this method requires OAuth2 authentication.

Request parameters

The uploaded audio file must be attached to the request as an audiofile POST parameter. Supported file formats include .wav, .aif, .flac, .ogg and .mp3.

Additionally, the request can include the following POST parameters to provide a description for the file:

Name Type Description
name string (OPTIONAL) The name that will be given to the sound. If not provided, filename will be used.
tags string The tags that will be assigned to the sound. Separate tags with spaces and join multi-words with dashes (e.g. “tag1 tag2 tag3 cool-tag4”).
description string A textual description of the sound.
license string The license of the sound. Must be either “Attribution”, “Attribution Noncommercial” or “Creative Commons 0”.
pack string (OPTIONAL) The name of the pack where the sound should be included. If user has created no such pack with that name, a new one will be created.
geotag string (OPTIONAL) Geotag information for the sound. Latitude, longitude and zoom values in the form lat,lon,zoom (e.g. “2.145677,3.22345,14”).

Note that tags, description and license parameters are REQUIRED when providing a description for the file, but can be omitted if no description is provided. In other words, you can either only provide the audiofile parameter, or provide audiofile plus tags, description, license and any of the other optional parameters. In the first case, a file will be uploaded but not described (you will need to describe it later), and in the second case a file will both be uploaded and described.

Response

If file description was provided, on successful upload, the Upload Sound resource will return a dictionary with the following structure:

{
  "detail": "Audio file successfully uploaded and described (now pending processing and moderation)",
  "id": "<sound_id for the uploaded and described sound instance>"
}

Note that after the sound is uploaded and described, it still needs to be processed and moderated by the team of Freesound moderators. Therefore, accessing the Sound Instance using the returned ``id`` will lead to a 404 Not Found error until the sound is approved by the moderators. If some of the required fields are missing or some of the provided fields are badly formatted, a 400 Bad Request response will be returned with a detail field describing the errors.

If file description was NOT provided, on successful upload, the Upload Sound resource will return a dictionary with the following structure:

{
  "detail": "Audio file successfully uploaded (<file size>, now pending description)",
  "filename": "<filename of the uploaded audio file>"
}

In that case, you will probably want to store the content of the filename field because it will be needed to later describe the sound using the Describe Sound (OAuth2 required) resource. Alternatively, you can retrieve later a the filenames of uploads pending description using the Pending Uploads (OAuth2 required) resource.

Examples

Upload a sound (audiofile only, no description):

curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" 'httpss://freesound.org/apiv2/sounds/upload/'

Upload and describe a sound all at once:

curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" -F "tags=field-recording birds nature h4n" -F "description=This sound was recorded...<br>bla bla bla..." -F "license=Attribution" 'httpss://freesound.org/apiv2/sounds/upload/'

Upload and describe a sound with name, pack and geotag:

curl -X POST -H "Authorization: Bearer {{access_token}}" -F audiofile=@"/path/to/your_file.wav" -F "name=Another cool sound" -F "tags=field-recording birds nature h4n" -F "description=This sound was recorded...<br>bla bla bla..." -F "license=Attribution" -F "pack=A birds pack" -F "geotag=2.145677,3.22345,14" 'httpss://freesound.org/apiv2/sounds/upload/'

Describe Sound (OAuth2 required)

POST /apiv2/sounds/describe/

This resource allows you to describe a previously uploaded audio file that has not yet been described. This method requires OAuth2 authentication. Note that after a sound is described, it still needs to be processed and moderated by the team of Freesound moderators, therefore it will not yet appear in Freesound. You can obtain a list of sounds uploaded and described by the user logged in using OAuth2 but still pending processing and moderation using the Pending Uploads (OAuth2 required) resource.

Request parameters

A request to the Describe Sound resource must include the following POST parameters:

Name Type Description
upload_filename string The filename of the sound to describe. Must match with one of the filenames returned in Pending Uploads (OAuth2 required) resource.
name string (OPTIONAL) The name that will be given to the sound. If not provided, filename will be used.
tags string The tags that will be assigned to the sound. Separate tags with spaces and join multi-words with dashes (e.g. “tag1 tag2 tag3 cool-tag4”).
description string A textual description of the sound.
license string The license of the sound. Must be either “Attribution”, “Attribution Noncommercial” or “Creative Commons 0”.
pack string (OPTIONAL) The name of the pack where the sound should be included. If user has created no such pack with that name, a new one will be created.
geotag string (OPTIONAL) Geotag information for the sound. Latitude, longitude and zoom values in the form lat,lon,zoom (e.g. “2.145677,3.22345,14”).

Response

If the audio file is described successfully, the Describe Sound resource will return a dictionary with the following structure:

{
  "detail": "Sound successfully described (now pending processing and moderation)",
  "id": "<sound_id for the uploaded and described sound instance>"
}

Note that after the sound is described, it still needs to be processed and moderated by the team of Freesound moderators. Therefore, accessing the Sound Instance using the returned ``id`` will lead to a 404 Not Found error until the sound is approved by the moderators.

If some of the required fields are missing or some of the provided fields are badly formatted, a 400 Bad Request response will be returned with a detail field describing the errors.

Examples

Describe a sound (only with required fields):

curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&tags=field-recording birds nature h4n&description=This sound was recorded...<br>bla bla bla...&license=Attribution" 'httpss://freesound.org/apiv2/sounds/describe/'

Also add a name to the sound:

curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&name=A cool bird sound&tags=field-recording birds nature h4n&description=This sound was recorded...<br>bla bla bla...&license=Attribution" 'httpss://freesound.org/apiv2/sounds/describe/'

Include geotag and pack information:

curl -X POST -H "Authorization: Bearer {{access_token}}" --data "upload_filename=your_file.wav&name=A cool bird sound&tags=field-recording birds nature h4n&description=This sound was recorded...<br>bla bla bla...&license=Attribution&pack=A birds pack&geotag=2.145677,3.22345,14" 'httpss://freesound.org/apiv2/sounds/describe/'

Pending Uploads (OAuth2 required)

GET /apiv2/sounds/pending_uploads/

This resource allows you to retrieve a list of audio files uploaded by the Freesound user logged in using OAuth2 that have not yet been described, processed or moderated. In Fressound, when sounds are uploaded they first need to be described by their uploaders. After the description step, sounds are automatically processed and then enter the moderation phase, where a team of human moderators either accepts or rejects the upload. Using this resource, your application can keep track of user uploads status in Freesound. This method requires OAuth2 authentication.

Response

The Pending Uploads resource returns a dictionary with the following structure:

{
  "pending_description": [
      "<filename #1>",
      "<filename #2>",
      ...
  ],
  "pending_processing": [
      <sound #1>,
      <sound #2>,
      ...
  ],
  "pending_moderation": [
      <sound #1>,
      <sound #2>,
      ...
  ],
}

The filenames returned under “pending_description” field are used as file identifiers in the Describe Sound (OAuth2 required) resource. Each sound entry either under “pending_processing” or “pending_moderation” fields consists of a minimal set of information about that sound including the id, name, tags, description, created and license fields that you would find in a Response (sound instance).

Sounds under “pending_processing” contain an extra processing_state field that indicates the status of the sound in the processing step. Processing is done automatically in Freesound right after sounds are described, and it normally takes less than a minute. Therefore, you should normally see that the list of sounds under “pending_processing” is empty. However, if there are errors during processing, uploaded sounds will remain in this category exhibiting a processing_state equal to Failed.

Sounds under “pending_moderation” also contain an extra images field containing the uris of the waveform and spectrogram images of the sound as described in Response (sound instance).

Examples

Get uploaded sounds that are pending description, processing or moderation:

curl -H "Authorization: Bearer {{access_token}}" 'httpss://freesound.org/apiv2/sounds/pending_uploads/'

Edit Sound Description (OAuth2 required)

POST /apiv2/sounds/<sound_id>/edit/

This resource allows you to edit the description of an already existing sound. Note that this resource can only be used to edit descriptions of sounds created by the Freesound user logged in using OAuth2. This method requires OAuth2 authentication.

Request parameters

A request to the Edit Sound Description resource must include mostly the same POST parameters that would be included in a Describe Sound (OAuth2 required) request:

Name Type Description
name string (OPTIONAL) The new name that will be given to the sound.
tags string (OPTIONAL) The new tags that will be assigned to the sound. Note that if this parameter is filled, old tags will be deleted. Separate tags with spaces and join multi-words with dashes (e.g. “tag1 tag2 tag3 cool-tag4”).
description string (OPTIONAL) The new textual description for the sound.
license string (OPTIONAL) The new license of the sound. Must be either “Attribution”, “Attribution Noncommercial” or “Creative Commons 0”.
pack string (OPTIONAL) The new name of the pack where the sound should be included. If user has created no such pack with that name, a new one will be created.
geotag string (OPTIONAL) New geotag information for the sound. Latitude, longitude and zoom values in the form lat,lon,zoom (e.g. “2.145677,3.22345,14”).

Note that for that resource all parameters are optional. Only the fields included in the request will be used to update the sound description (e.g. if only name and tags are included in the request, these are the only properties that will be updated from sound description, the others will remain unchanged).

Response

If sound description is updated successfully, the Edit Sound Description resource will return a dictionary with a single detail field indicating that the sound has been successfully edited. If some of the required fields are missing or some of the provided fields are badly formatted, a 400 Bad Request response will be returned with a detail field describing the errors.

Bookmark Sound (OAuth2 required)

POST /apiv2/sounds/<sound_id>/bookmark/

This resource allows you to bookmark an existing sound. The sound will be bookmarked by the Freesound user logged in using OAuth2, therefore this method requires OAuth2 authentication.

Request parameters

A request to the Bookmark Sound resource can include the following POST parameters:

Name Type Description
name string (OPTIONAL) The new name that will be given to the bookmark (if not specified, sound name will be used).
category string (OPTIONAL) The name of the category under the bookmark will be classified (if not specified, bookmark will have no category). If the specified category does not correspond to any bookmark category of the user, a new one will be created.

Response

If the bookmark is successfully created, the Bookmark Sound resource will return a dictionary with a single detail field indicating that the sound has been successfully bookmarked.

Examples

Simple bookmark:

curl -X POST -H "Authorization: Bearer {{access_token}}" --data "name=Classic thunderstorm" 'httpss://freesound.org/apiv2/sounds/2523/bookmark/'

Bookmark with category:

curl -X POST -H "Authorization: Bearer {{access_token}}" --data "name=Nice loop&category=Nice loops" 'httpss://freesound.org/apiv2/sounds/1234/bookmark/'

Rate Sound (OAuth2 required)

POST /apiv2/sounds/<sound_id>/rate/

This resource allows you to rate an existing sound. The sound will be rated by the Freesound user logged in using OAuth2, therefore this method requires OAuth2 authentication.

Request parameters

A request to the Rate Sound resource must only include a single POST parameter:

Name Type Description
rating integer Integer between 0 and 5 (both included) representing the rating for the sound (i.e. 5 = maximum rating).

Response

If the sound is successfully rated, the Rate Sound resource will return a dictionary with a single detail field indicating that the sound has been successfully rated. If some of the required fields are missing or some of the provided fields are badly formatted, a 400 Bad Request response will be returned with a detail field describing the errors. Note that in Freesound sounds can only be rated once by a single user. If attempting to rate a sound twice with the same user, a 409 Conflict response will be returned with a detail field indicating that user has already rated the sound.

Examples

Rate sounds:

curl -X POST -H "Authorization: Bearer {{access_token}}" --data "rating=5" 'httpss://freesound.org/apiv2/sounds/2523/rate/'
curl -X POST -H "Authorization: Bearer {{access_token}}" --data "rating=4" 'httpss://freesound.org/apiv2/sounds/1234/rate/'

Comment Sound (OAuth2 required)

POST /apiv2/sounds/<sound_id>/comment/

This resource allows you to post a comment to an existing sound. The comment will appear to be made by the Freesound user logged in using OAuth2, therefore this method requires OAuth2 authentication.

Request parameters

A request to the Comment Sound resource must only include a single POST parameter:

Name Type Description
comment string Comment for the sound.

Response

If the bookmark is successfully created, the Comment Sound resource will return a dictionary with a single detail field indicating that the sound has been successfully commented.

Examples

Comment sounds:

curl -X POST -H "Authorization: Bearer {{access_token}}" --data "comment=Cool! I understand now why this is the most downloaded sound in Freesound..." 'httpss://freesound.org/apiv2/sounds/2523/comment/'
curl -X POST -H "Authorization: Bearer {{access_token}}" --data "comment=A very cool sound!" 'httpss://freesound.org/apiv2/sounds/1234/comment/'

User resources

User Instance

GET /apiv2/users/<username>/

This resource allows the retrieval of information about a particular Freesound user.

Response

The User Instance response is a dictionary including the following properties/fields:

Name Type Description
url URI The URI for this users’ profile on the Freesound website.
username string The username.
about string The ‘about’ text of users’ profile (if indicated).
homepage URI The URI of users’ homepage outside Freesound (if indicated).
avatar object Dictionary including the URIs for the avatar of the user. The avatar is presented in three sizes Small, Medium and Large, which correspond to the three fields in the dictionary. If user has no avatar, this field is null.
date_joined string The date when the user joined Freesound (e.g. “2008-08-07T17:39:00”).
num_sounds number The number of sounds uploaded by the user.
sounds URI The URI for a list of sounds by the user.
num_packs number The number of packs by the user.
packs URI The URI for a list of packs by the user.
num_posts number The number of forum posts by the user.
num_comments number The number of comments that user made in other users’ sounds.
bookmark_categories URI The URI for a list of bookmark categories by the user.

Examples

User information:

https://freesound.org/apiv2/users/reinsamba/
https://freesound.org/apiv2/users/Freed/

User Sounds

GET /apiv2/users/<username>/sounds/

This resource allows the retrieval of a list of sounds uploaded by a particular Freesound user.

Response

Similar Sounds resource returns a sound list just like Response (sound list). The same extra request parameters apply (page, page_size, fields, descriptors and normalized).

Examples

Getting user sounds:

https://freesound.org/apiv2/users/Jovica/sounds/
https://freesound.org/apiv2/users/Jovica/sounds/?page=2
https://freesound.org/apiv2/users/Jovica/sounds/?fields=id,bitdepth,type,samplerate

User Packs

GET /apiv2/users/<username>/packs/

This resource allows the retrieval of a list of packs created by a particular Freesound user.

Response

User Packs resource returns a paginated list of the packs created by a user, with a similar structure as Response (sound list):

{
  "count": <total number of packs>,
  "next": <link to the next page of packs (null if none)>,
  "results": [
      <most recent pack created by the user>,
      <second most recent pack created by the user>,
      ...
  ],
  "previous": <link to the previous page of packs (null if none)>
}

Each pack entry consists of a dictionary with the same fields returned in the Pack Instance response. Packs are sorted according to their creation date (recent packs in the top of the list). Parameters page and page_size can be used just like in Response (sound list) to deal with the pagination of the response.

Examples

Getting user packs:

https://freesound.org/apiv2/users/reinsamba/packs/
https://freesound.org/apiv2/users/reinsamba/packs/?page=2

User Bookmark Categories

GET /apiv2/users/<username>/bookmark_categories/

This resource allows the retrieval of a list of bookmark categories created by a particular Freesound user.

Response

User Bookmark Categories resource returns a paginated list of the bookmark categories created by a user, with a similar structure as Response (sound list):

{
  "count": <total number of bookmark categories>,
  "next": <link to the next page of bookmark categories (null if none)>,
  "results": [
      <first bookmark category>,
      <second bookmark category>,
      ...
  ],
  "previous": <link to the previous page of bookmark categories (null if none)>
}

Parameters page and page_size can be used just like in Response (sound list) to deal with the pagination of the response.

Each bookmark category entry consists of a dictionary with the following structure:

{
  "url": "<URI of the bookmark category in Freesound>",
  "name": "<name that the user has given to the bookmark category>",
  "num_sounds": <number of sounds under the bookmark category>,
  "sounds": "<URI to a page with the list of sounds in this bookmark category>",
}

Examples

Users bookmark categories:

https://freesound.org/apiv2/users/frederic.font/bookmark_categories/

User Bookmark Category Sounds

GET /apiv2/users/<username>/bookmark_categories/<bookmark_category_id>/sounds/

This resource allows the retrieval of a list of sounds from a bookmark category created by a particular Freesound user.

Response

User Bookmark Category Sounds resource returns a sound list just like Response (sound list). The same extra request parameters apply (page, page_size, fields, descriptors and normalized).

Examples

Getting uncategorized bookmarks:

https://freesound.org/apiv2/users/frederic.font/bookmark_categories/0/sounds/

Getting sounds of a particular bookmark cateogry:

https://freesound.org/apiv2/users/frederic.font/bookmark_categories/11819/sounds/
https://freesound.org/apiv2/users/frederic.font/bookmark_categories/11819/sounds/?fields=duration,previews

Pack resources

Pack Instance

GET /apiv2/packs/<pack_id>/

This resource allows the retrieval of information about a pack.

Response

The Pack Instance response is a dictionary including the following properties/fields:

Name Type Description
id number The unique identifier of this pack.
url URI The URI for this pack on the Freesound website.
description string The description the user gave to the pack (if any).
created string The date when the pack was created (e.g. “2014-04-16T20:07:11.145”).
name string The name user gave to the pack.
username string Username of the creator of the pack.
num_sounds number The number of sounds in the pack.
sounds URI The URI for a list of sounds in the pack.
num_downloads number The number of times this pack has been downloaded.

Examples

Getting a pack:

https://freesound.org/apiv2/packs/9678/

Pack Sounds

GET /apiv2/packs/<pack_id>/sounds/

This resource allows the retrieval of the list of sounds included in a pack.

Response

Pack Sounds resource returns a sound list just like Response (sound list). The same extra request parameters apply (page, page_size, fields, descriptors and normalized).

Examples

Getting pack sounds:

https://freesound.org/apiv2/packs/9678/sounds/
https://freesound.org/apiv2/packs/9678/sounds/?fields=id,name

Download Pack (OAuth2 required)

GET /apiv2/packs/<pack_id>/download/

This resource allows you to download all the sounds of a pack in a single zip file. It requires OAuth2 authentication.

Examples

Download a pack:

curl -H "Authorization: Bearer {{access_token}}" 'httpss://freesound.org/apiv2/packs/9678/download/'

Other resources

Me (information about user authenticated using OAuth2, OAuth2 required)

GET /apiv2/me/

This resource returns basic information of the user that is logged in using the OAuth2 procedure. It can be used by applications to be able to identify which Freesound user has logged in.

Response

The Me resource response consists of a dictionary with all the fields present in a standard User Instance, plus additional email and unique_id fields that can be used by the application to uniquely identify the end user.

Available Audio Descriptors

GET /apiv2/descriptors/

This resource returns information about the available audio descriptors that are extracted from Freesound sounds. These descriptors can be used in content and combined search targets and filters, in similarity search and in the descriptors parameter of any sound list.

Response

The Available Audio Descriptors resource response consists of a dictionary with the list of descriptor names divided in some categories:

{
  "fixed-length": {
     "one-dimensional": [
        <descriptor name>,
        <descriptor name>,
        ...
     ],
     "multi-dimensional": [
        <descriptor name>,
        <descriptor name>,
        ...
     ]
  },
  "variable-length": [
      <descriptor name>,
      <descriptor name>,
      ...
  ]
}

Descriptors under the field fixed-length are those that can be used in content, combined and similarity searches. They are divided among one-dimensional (descriptors that consist in a single value like spectral centroid or pitch) and multi-dimensional (descriptors with several dimensions like mfcc or tristimulus).

Descriptors under the field variable-length may have different length depending on the sound, are can only be used in the descriptors parameter of Response (sound list).

For more information check the Analysis Descriptor Documentation.