freesound-api

The freesound_api module implements the structure around which the FreeSoundClient is built

NOTE: you are not supposed to use these functions directly, but you can if you want

• get_access_token
• refresh_access_token
• get_my_infos
• search
• get_track_info
• get_next_page
• download_track

FreesoundAPI

freesound.freesound_api.get_access_token(user_id, api_key, authorization_code)

A utlity function which covers Step 3 of the OAuth2 Authentication process see: https://freesound.org/docs/api/authentication.html#step-3

You can apply for API credentials here: https://freesound.org/apiv2/apply/

You can save the response data in a file for future connections

Parameters:

Name	Type	Description	Default
user_id	str	the User id	required
api_key	str	the API key	required
authorization_code	str	the authorization code copied from the browser see: https://freesound.org/docs/api/authentication.html#step-2	required

Returns:

Type	Description
dict[str, Any]	a dict containing the following keys: "access_token", "expires_in", "token_type", "scope", "refresh_token"

freesound.freesound_api.refresh_access_token(user_id, api_key, refresh_token)

Refresh the User "access token" when expired

see: https://freesound.org/docs/api/authentication.html#once-you-have-your-access-token

Parameters:

Name	Type	Description	Default
user_id	str	your the User id	required
api_key	str	the API key	required
refresh_token	str	the "refresh_token" saved from the get_access_token() Response	required

Returns:

Type	Description
dict[str, Any]	a dict containing the following keys: "access_token", "expires_in", "token_type", "scope", "refresh_token"

freesound.freesound_api.get_my_infos(token)

get the info about the User identified by token

Parameters:

Name	Type	Description	Default
token	str	a valid OAuth2 access token	required

Returns:

Type	Description
dict[str, Any]	a dict containing data listed here: https://freesound.org/docs/api/resources_apiv2.html#user-instance

freesound.freesound_api.search(query, token, fields=None, filter=None, descriptors=None, sort_by='score', page_size=15, normalized=0)

Search in the FreeSound Database

For a full documentation see: https://freesound.org/docs/api/resources_apiv2.html#search-resources

Parameters:

Name	Type	Description	Default
query	str	a space-separatad string of words to search in the FreeSound Database	required
token	str	a valid OAuth2 access token	required
fields	str | None	a coma-separated string of fields of a SoundInstance	None
filter	str | None	a space-separated string of valid filter:value	None
descriptors	str | None	a coma-separated string of valid sound analysis descriptors	None
sort_by	str	a valid sort paramter	'score'
page_size	int	the max number of items inside the result array of the response	15
normalized	int	wheteher the analysis values are normalized or not either 0-1	0

Returns:

Type	Description
dict[str, Any]	a sound list. See: https://freesound.org/docs/api/resources_apiv2.html#response-sound-list

freesound.freesound_api.get_track_info(track_id, token, fields=None, descriptors=None)

Requests infos of a SoundInstance

see: https://freesound.org/docs/api/resources_apiv2.html#sound-instance

Parameters:

Name	Type	Description	Default
track_id	str	a valid id of a sound in the freesound database	required
token	str	a valid OAuth2 access token	required
fields	str | None	a coma-separated string of fields of a SoundInstance	None
descriptors	str | None	a coma-separated string of valid sound analysis descriptors	None

Returns:

Type	Description
dict[str, Any]	a dict containing all the info of a SoundInstance. see https://freesound.org/docs/api/resources_apiv2.html#sound-resources

freesound.freesound_api.get_next_page(url, token)

A utility function to handle pagination in sound results

It performs a search form the a url parsed from the 'next' field of a search result

Parameters:

Name	Type	Description	Default
url	str	a url retrieved from a previous 'search' request	required
token	str	a valid OAuth2 access token	required

Returns:

Type	Description
dict[str, Any]	a sound list. See: https://freesound.org/docs/api/resources_apiv2.html#response-sound-list

freesound.freesound_api.download_track(track_url, token)

Download a track from a url

Parameters:

Name	Type	Description	Default
track_url	str	a valid download url retrieved from a SoundInstance	required
token	str	a valid OAuth2 access token	required

Returns:

Type	Description
Response	a requests.Response whose content can be loaded in a ByteIO