ilesinge / freesound-api

python client for the freesound API

freesound.py

A Python client for the Freesound APIv2.

This is a cold fork of https://github.com/MTG/freesound-python for publishing on pypi

Find the API documentation at http://www.freesound.org/docs/api/. Apply for an API key at https://www.freesound.org/apiv2/apply/.

The client automatically maps function arguments to http parameters of the API. JSON results are converted to python objects, but are also available in their original form (JSON loaded into dictionaries) using the method .as_dict() of returned objets (see examples file). The main object types (Sound, User, Pack) are augmented with the corresponding API calls.

Note that POST resources are not supported. Downloading full quality sounds requires Oauth2 authentication (see https://freesound.org/docs/api/authentication.html). Oauth2 authentication is supported by passing an access token, but you are expected to implement the workflow to obtain that access token. Here is an example implementation of the Freesound OAuth2 workflow using Flask.

Example usage:

import freesound

client = freesound.FreesoundClient()
client.set_token("<your_api_key>","token")

results = client.text_search(query="dubstep",fields="id,name,previews")

for sound in results:
    sound.retrieve_preview(".",sound.name+".mp3")
    print(sound.name)

Installation

pip install freesound-api

Advanced usage

Modifying the requests' session:

You can easily extend/modify the way how requests are done by interacting directly with the session object of the client.

For example, adding proxies:

proxies = {
  'http': 'http://10.10.1.10:3128',
  'https': 'http://10.10.1.10:1080',
}
client.session.proxies.update(proxies)

or adding rate limiting:

from requests_ratelimiter import LimiterSession

# Apply a rate-limit (59 requests per minute) to all requests
client.session = LimiterSession(per_minute=59)

Authenticating with OAuth

Here is an example authentication flow with the help of Requests-OAuthlib.

from requests_oauthlib import OAuth2Session

import freesound

client_id = "<your_client_id>"
client_secret = "<your_client_secret>"

# do the OAuth dance
oauth = OAuth2Session(client_id)

authorization_url, state = oauth.authorization_url(
    "https://freesound.org/apiv2/oauth2/authorize/"
)
print(f"Please go to {authorization_url} and authorize access.")

authorization_code = input("Please enter the authorization code:")
oauth_token = oauth.fetch_token(
    "https://freesound.org/apiv2/oauth2/access_token/",
    authorization_code,
    client_secret=client_secret,
)

client = freesound.FreesoundClient()
client.set_token(oauth_token["access_token"], "oauth")