Skip to content

Utilities

API Utlities Overview

FreeSoundFields

freesound.freesound_fields.FreeSoundFields

Bases: ListMaker

A Utility Class that creates a coma-separated string from a list of Field calling the method aslist

The result is a ready formatted string to be used in the fields parameter of FreeSoundClient

For more information visit: https://freesound.org/docs/api/resources_apiv2.html#response-sound-instance

Usage 
>>> print(FreeSoundFields([Field.id,Field.filesize]).aslist)
id,filesize

aslist: str property

use this property to pass the list of Fieldto a FreeSoundClient

Returns:

Name Type Description
str str

a coma-separated string of valid fields

Field

freesound.freesound_fields.Field

Field is a class that provides hints for valid fields to query the freesound.org database

FreeSoundDescriptors

freesound.freesound_descriptors.FreeSoundDescriptors

Bases: ListMaker

A Utility Class that creates a coma-separated string from a list of Descriptor calling the method aslist

The result is a ready formatted string to be used in the descriptors parameter of the FreeSoundClient. Don't forget to use this parameter in combination with the field analysis

Parameters:

Name Type Description Default
fields list[Any]

a list of Descriptor

 required
Usage 
>>> print(FreeSoundDescriptors([Descriptor.low_level_average_loudness,Descriptor.low_level_mfcc]).aslist)
lowlevel.average_loudness,lowlevel.mfcc

aslist: str property

use this method to pass the list of Descriptor to a FreeSoundClient

Returns:

Name Type Description
str str

a coma-separated string of valid sound descriptors

Descriptor

freesound.freesound_descriptors.Descriptor

A list of valid descriptors for FreeSound Analysis

This should not be used outside a FreeSoundDescriptors

Usage 
>>> FreeSoundDescriptors([Descriptor.lowlevel.spectral_complexity])

FreeSoundFilters

freesound.freesound_filters.FreeSoundFilters

Bases: ListMaker

A Utility Class that creates a space-separated string of filter:value calling the method aslist

It makes use of TypeFilter (a TypeDict) to provide type annotation for valid filters to query the freesound.org database The result is a ready formatted string to be used as a filter parameter in the FreeSoundClient including ac_filter

For more information visit: https://freesound.org/docs/api/resources_apiv2.html#text-search Check the audio common project at: http://www.audiocommons.org/

Usage 
>>> print(FreeSoundFilters(tag=['fret','plucked'], type="wav", samplerate=44100).aslist)
tag:fret tag:plucked type:wav samplerate:44100

aslist: str property

use this property to pass the list of filters to a FreeSoundClient.

Returns:

Name Type Description
str str

a space-separated string of valid filter:value

Filter

freesound.filter_types.Filter

A utility class that allows you to create conditional and range filters

OR(val1, val2) classmethod

conditional OR

you should not use this class method outside the FreeSoundFilters class parameters.

Usage 
>>> FreeSoundFilters(type=Filter.OR('wav','aiff')).aslist
'type:(wav OR aiff)'

Args: val1 (Any): first value val2 (Any): second value

Returns:

Name Type Description
str str

a well-formatted string for the filter url parameter

AND(val1, val2) classmethod

conditional AND

you should not use this class method outside the FreeSoundFilters class parameters.

Usage 
>>> FreeSoundFilters(tag=Filter.AND('nature','soundscape')).aslist
'tag:(nature AND soundscape)'

Args: val1 (Any): first value val2 (Any): second value

Returns:

Name Type Description
str str

a well-formatted string for the filter url parameter

RANGE(minimum, maximum) classmethod

range from minimum TO maximum

you should not use this class method outside the FreeSoundFilters class parameters.

Usage 
>>> FreeSoundFilters(duration=Filter.RANGE(3,5)).aslist
'duration:[3 TO 5]'

Args: minimum (Any): range minimum maximum (Any): range maximum

Returns:

Name Type Description
str str

a well-formatted string for the filter url parameter

AT_LEAST(minimum) classmethod

range from a minimum value

you should not use this class method outside the FreeSoundFilters class parameters.

Usage 
>>> FreeSoundFilters(duration=Filter.AT_LEAST(3)).aslist
'duration:[3 TO *]'

Args: minimum (Any): the minimum value

Returns:

Name Type Description
str str

a well-formatted string for the filter url parameter

UP_TO(maximum) classmethod

range up to a maximum value

you should not use this class method outside the FreeSoundFilters class parameters.

Usage 
>>> FreeSoundFilters(duration=Filter.UP_TO(3)).aslist
'duration:[* TO 3]'

Args: maximum (Any): the maximum value

Returns:

Name Type Description
str str

a well-formatted string for the filter url parameter

FreeSoundSort

freesound.freesound_filters.FreeSoundSort

A Utility Class that outputs a valid string to be used as a sort parameter in the FreeSoundClient. Useful for linting

Usage 
>>> print(FreeSoundSort.DURATION_DESC)
duration_desc

FreeSoundSoundInstance

freesound.freesound_sound.FreeSoundSoundInstance

Bases: Field

A Utility class the stores the details of a SoundInstance request from the freesound.org database. Notice that the name of the input SoundInstance will be manipulated automatically by calling self._set_file_name. A name such as Piano12 B Flat will be automatically transformed in Piano12-B-Flat.mp3

for more information visit: https://freesound.org/docs/api/resources_apiv2.html#sound-instance

Parameters:

Name Type Description Default
track_data dict[Any, Any]

a dictionary of information about a SoundInstance

 required

Raises:

Type Description
AttributeError

if the passed dictonary does not contain the fields id and name it raises an error
DataError

if the passed dictonary does not contain a valid field it raises an error
Usage 
>>> t = FreeSoundSoundInstance({'id': 524545, 'name': 'Piano12', 'tags': ['note', 'synthesizer', 'Piano'], 'type': 'mp3', 'download': 'https://freesound.org/apiv2/sounds/524545/download/'})
>>> print(t.name)
Piano12.mp3

ensure_value(field)

a utility function which ensure the presence of a field inside the input dictionary

Parameters:

Name Type Description Default
field str

which field must be store in this FreeSoundSoundInstance

 required

Raises:

Type Description
FieldError

raises an error if field is not store in this FreeSoundSoundInstance

Returns:

Name Type Description
str str

the value of the field
Usage 
>>> t = FreeSoundSoundInstance({'id': 524545, 'name': 'Piano12', 'type': 'mp3'})
>>> t.ensure_value('download')
FieldError
>>> t.ensure_value('type')
mp3

as_dict()

a function to generate a dictionary out of self

Returns:

Type Description
dict[str, Any]

dict[str, Any]: the same dict that you would get from one element of FreeSoundClient.results_list['results']