FreeSoundClient

The FreeSoundClient

`freesound.freesound_api.FreeSoundClient`

The core class of the library

The FreeSoundClient is a wrapper around the freeesound_api. It facilitates the formulation of queries to make requests to the Freesound Database. It handles bulk files download and can write json files from the queries.

Check the Tutorial and How-To sections of this documentation for a detailed explanation of its usage.

Parameters:

Name	Type	Description	Default
`user_id`	`str`	the User id	required
`api_key`	`str`	the API key	required
`download_folder`	`str \| None`	the path where sound files should be downloaded.	`None`
`token_file_path`	`str`	the Path to a `json` file containing the user's access token.	`'access_token.json'`

Usage

>>> c = FreesoundClient('<your-user-id>','<your-api-key>', 'sound_lib', 'access_token.json')

`username: str` `property`

read-only

Returns:

Type	Description
`str`	the username associated with this `FreeSoundClient` identified by `user_id`

`page_size: int` `property`

read-only

Returns:

Type	Description
`int`	the maximum count of items that should be returned by the search result specified in the `search` function.

`results_list: dict[str, Any]` `property`

read-only

Returns:

Type	Description
`dict[str, Any]`	a `json` object containing the response of a `search` request.

`download_count: int` `property`

read-only

Returns:

Type	Description
`int`	how many files have been downloaded

`download_list: dict[str, list[dict[str, Any]]]` `property`

read-only

Returns:

Type	Description
`dict[str, list[dict[str, Any]]]`	a detailed list of the downloaded files in `json` format

`download_folder: str | None` `property` `writable`

Returns:

Type	Description
`str \| None`	the name of the folder where audio files should be downladed

`search(query, filter='', fields='', descriptors='', sort_by='score', page_size=15, normalized=0)`

wrapper around the search() function

see: https://freesound.org/docs/api/resources_apiv2.html#search-resources for details

Parameters:

Name	Type	Description	Default
`query`	`str`	a string of space-separated word to search into the Freesound Database	required
`filter`	`str`	a string of valid filter:value string (see: `FreeSoundFilters` for help)	`''`
`fields`	`str`	a coma-separated string of valid `fields` (see: `FreeSoundFields` for help)	`''`
`descriptors`	`str`	a coma-separated string of valid `descriptors` (see: `FreeSoundDescriptors` for help). This attribute must be used in combination with the field `analysis`	`''`
`sort_by`	`str`	a string defining how the search results should be organised (see: `FreeSoundFilters` for help)	`'score'`
`page_size`	`int`	the maximum count of items that should be returned by the search result	`15`
`normalized`	`int`	whether the sound `descriptors` values should be normalized or not	`0`

Returns:

Type	Description
`dict[str, Any]`	a json object representing the Response from the freesound database https://freesound.org/docs/api/resources_apiv2.html#response

`get_track_info(track_id, track_name=None, fields=None, descriptors=None)`

a wrapper around the get_track_info() function

This function queries the database to get the infos of a sound identified by id. Check the documentation for more help: https://freesound.org/docs/api/resources_apiv2.html#sound-instance

Parameters:

Name	Type	Description	Default
`track_id`	`Any`	the `id` of the sound	required
`track_name`	`str \| None`	the name of the sound track with the provided `id`	`None`
`fields`	`str \| None`	a coma-separated string of valid `fields` (see: `FreeSoundFields` for help)	`None`
`descriptors`	`str \| None`	a coma-separated string of valid `descriptors` (see: `FreeSoundDescriptors` for help). This attribute must be used in combination with the field `analysis`	`None`

Returns:

Type	Description
`FreeSoundSoundInstance`	an instance of a sound with default or specified `fields`

`download_track(url, filename, outfolder=None, skip=False)`

a wrapper around the download_track() function

Downloads a track given a valid download url retrieved from the Freesound Database

See: https://freesound.org/docs/api/resources_apiv2.html#download-sound-oauth2-required for details

Parameters:

Name	Type	Description	Default
`url`	`str`	the download link for a specific sound	required
`filename`	`str`	the name of the file to download	required
`outfolder`	`str`	the folder where the file should be downloaded	`None`
`skip`	`bool`	deafult value to skip a file if it already exists.	`False`

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the file has been downloaded, `False` otherwise

`get_next_page(url)`

a wrapper around the get_next_page() function

Parameters:

Name	Type	Description	Default
`url`	`str`	a url retrieved from a previous 'search' request	required

Returns:

Type	Description
`dict[str, Any]`	a json object representing the Response from the freesound database https://freesound.org/docs/api/resources_apiv2.html#response

`download_results(output_folder=None, files_count=None)`

download files_count audio files into output_folder_path

This function takes care of pagination automatically

Parameters:

Name	Type	Description	Default
`output_folder`	`str \| None`	The name of the output folder.	`None`
`files_count`	`int \| None`	how many files should be downloaded.	`None`

`write_download_list(filename='downloads.json', folder=None)`

save a detailed list of the downloaded files in a json file

If folder is not provided the client will prompt the user for this information

Parameters:

Name	Type	Description	Default
`filename`	`str`	the name of the file to save	`'downloads.json'`
`folder`	`str \| None`	the name of the folder where to save the file	`None`

`write_results_list(filename='results_list.json', folder=None)`

save a simplified list of the search response in a json file

If folder is not provided the client will prompt the user for this information

Parameters:

Name	Type	Description	Default
`filename`	`str`	the file of the files where the list should be saved	`'results_list.json'`
`folder`	`str \| None`	the name of the folder where to save the file	`None`

`load_results_list(json_file)`

load a json file produced from write_results_list

Parameters:

Name	Type	Description	Default
`json_file`	`str`	a relative or an absolute path to a json file	required

`dump_results(data=None)`

pretty print the result of a search

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any] \| None`	a `dict` (for example the result of a `search`). By default it will print the result of the last performed search.	`None`

`logout()`

Closes the program

Should not normally need to be called explicitly

Calls sys.exit(0)

FreeSoundClient

The FreeSoundClient

freesound.freesound_api.FreeSoundClient

username: str property

page_size: int property

results_list: dict[str, Any] property

download_count: int property

download_list: dict[str, list[dict[str, Any]]] property

download_folder: str | None property writable

search(query, filter='', fields='', descriptors='', sort_by='score', page_size=15, normalized=0)

get_track_info(track_id, track_name=None, fields=None, descriptors=None)

download_track(url, filename, outfolder=None, skip=False)

get_next_page(url)

download_results(output_folder=None, files_count=None)

write_download_list(filename='downloads.json', folder=None)

write_results_list(filename='results_list.json', folder=None)

load_results_list(json_file)

dump_results(data=None)

logout()

`freesound.freesound_api.FreeSoundClient`

`username: str` `property`

`page_size: int` `property`

`results_list: dict[str, Any]` `property`

`download_count: int` `property`

`download_list: dict[str, list[dict[str, Any]]]` `property`

`download_folder: str | None` `property` `writable`

`search(query, filter='', fields='', descriptors='', sort_by='score', page_size=15, normalized=0)`

`get_track_info(track_id, track_name=None, fields=None, descriptors=None)`

`download_track(url, filename, outfolder=None, skip=False)`

`get_next_page(url)`

`download_results(output_folder=None, files_count=None)`

`write_download_list(filename='downloads.json', folder=None)`

`write_results_list(filename='results_list.json', folder=None)`

`load_results_list(json_file)`

`dump_results(data=None)`

`logout()`