Getting started

Welcome to the FreeSoundClient Tutorial! This part of the documentation follows a step-by-step approach to help you get started with the basic functionalities of the FreeSoundClient.

INFO you can find the source code of the final version of this tutorial on GitHub

Before you start

In order to use this software you need an account on freesound.org and apply for an API key following this link https://freesound.org/apiv2/apply/. The form is quite straight forward: in the Create new API credentials you must give a name and a description to your key, accept the terms of use and click on Request new access credentials

Please save your credentials in you project folder (either in a .env file or a credentials.txt file)

Get started

After downloading the repository, create a project folder and copy the freesound folder into it and create a new empty file called main.py. Your project directory should look like this:

.
├── freesound
│   ├── __init__.py
│   ├── filter_types.py
│   ├── formatting.py
│   ├── freesound_api.py
│   ├── freesound_client.py
│   ├── freesound_descriptors.py
│   ├── freesound_errors.py
│   ├── freesound_fields.py
│   ├── freesound_filters.py
│   ├── freesound_list_maker.py
│   ├── freesound_requests.py
│   └── freesound_sound.py
└──  main.py

Now open main.py and import the freesound library

from freesound import *

Then create two global variables to store your API Credentials

API_KEY=<your-api-key>
USER_ID=<your-user-id>

and create an instance of the FreeSoundClient

c = FreeSoundClient(USER_ID,API_KEY)

Your first access

Now run your program:

python main.py

If this is your first time that you use the freesound-client library when you run this program you will get the following output:

Output

No access token file found. Authorizing...
==================================================
Visit this page to authorize your user: https://freesound.org/apiv2/oauth2/authorize/?client_id=<your-client-id>&response_type=code&state=xyz 
Enter the authorization code from the redirect URL:

All the requests made by the FreeSoundClient use the OAuth2 authentication protocol, so the application needs an access token from the API to get access to the database.

If you follow the link posted in your terminal a browser page will display the following information:

Where app-name will be the name of the name value that you provided when applying for the API credentials. Copy <the-authorization-code-to-copy> (an alphanumeric string) and paste it into the terminal:

Output

Enter the authorization code from the redirect URL: <the-authorization-code-to-copy>
https://freesound.org/apiv2/oauth2/access_token/
Authorization succeded!
Getting Client Info
https://freesound.org/apiv2/me/
FreeSound Client <your-username> Initialized

You are now granted to access the Freesound database.

This process will create a file called access_token.json where your access token's data will be stored.

├── access_token.json
├── freesound
└── main.py

Note: If you delete this file the FreeSoundClient will simply repeat this authorization process and create a new access_token.json file for you

Your first `search`

Now that your client is authorized to query the Freesound Database let's make a simple research:

from freesound import *

API_KEY = "<your-api-key>"
USER_ID = "<your-user-id>"

c = FreeSoundClient(USER_ID,API_KEY)
c.search(query="piano detuned")

The query attribute needs a space-separated string of words that you want to search into the Freesound Database. Running this program will produce the following output:

Output

Loading token from file
________________
Getting Client Info
https://freesound.org/apiv2/me/
FreeSound Client <your-username> Initialized
________________
Searching for piano detuned
https://freesound.org/apiv2/search/text/?query=piano+detuned&fields=id%2Cname%2C&page_size=15&sort=score&normalized=0
Found 469 results

Because you already have an access_token.json the client will inform you that it is Loading token from file and then will perform the search.

With this research you got 469 results which are stored into the memory of the FreeSoundClient.

The client will also print the url generated by the search request. If you copy this url and paste it into a browser you should see the actual result of your reasearch (you must be logged in to see this result otherwise you will get an HTTP 401 Unauthorized response).

NOTICE: if you visit the url you will see a list of only 15 of the 469 results. You will understand why in the next paragraph.

Printing data from the `result`

By default, when performing a search the FreeSoundClient will get a dictionary that contains a parsed response from the server. Let's print it using the FreeSoundClient.results_list attribute:

print(c.results_list)

Output

{
"results": [
    {
    "id": 30274,
    "name": "piano_impression1.aif"
    },
    {
    "id": 382508,
    "name": "Piano 16 F4.wav"
    },
    {
    "id": 382532,
    "name": "Piano 45 G#5.wav"
    },
    {
    "id": 382541,
    "name": "Piano 57 G#6.wav"
    },
    {
    "id": 382539,
    "name": "Piano 59 A6.wav"
    },
    {
    "id": 382533,
    "name": "Piano 46 A5.wav"
    },
    {
    "id": 382510,
    "name": "Piano 20 G4.wav"
    },
    {
    "id": 382546,
    "name": "Piano 52 C#6.wav"
    },
    {
    "id": 382484,
    "name": "Piano 23 A4.wav"
    },
    {
    "id": 382504,
    "name": "Piano 12 D#4.wav"
    },
    {
    "id": 382505,
    "name": "Piano 11 D#4.wav"
    },
    {
    "id": 382511,
    "name": "Piano 19 G4.wav"
    },
    {
    "id": 382502,
    "name": "Piano 14 E4.wav"
    },
    {
    "id": 382531,
    "name": "Piano 44 G5.wav"
    },
    {
    "id": 382486,
    "name": "Piano 21 G4.wav"
    }
],
"timestamp": "2024-03-01T12:30:02.984110",
"count": 469
}

The response from the server is paginated which means that even if the client found 469 sound files that match your query ("piano detuned") you will only see a list of 15 files.

In this dictionary there are 3 keys:

search-results: a list containing data about the first 15 sound files matching the query.
timestamp: when the request has been submitted
count the total number of sound files found

Another way to print the result of a search request is to use the FreeSound.dump_results() method, a utility function that will just print a more human-readable version of c.results_list. Adding:

c.dump_results()

to your main.py will produce the following output

Output

Found 469 results
________________
id:30274
name:piano_impression1.aif
________________
id:382530
name:Piano 43 F#5.wav
________________
...

Notice that in both cases the only information about the sound files that you collected from the database are id and name

Download your `search` results

Downloading files from a search result it is pretty straight forward using the method FreeSoundClient.download_results(). Add:

c.download_results()

to your main.py

At this point you will be prompted with a few questions:

How many files do you want to download? [a number | all]

Let's set this value to 3. Then you need to specify the folder where the sound files will be downloaded:

Please set an output folder:

Press enter to download the files in your project directory

Output

Attribute 'download' not found! Please include the 'download' keyword in your fields' search list and retry
Logging out

There is an Exception! The reason is simple: when querying the database the FreeSoundClient did not retrieve the download link associated with the sound files but only their ids and names. You need to modify your search parameters. Go back to the line where you call the c.search() and modify it as follows:

c.search(query="piano detuned",fields="download")

The attribute fields is a feature that allows you to specify which attribute associate with a sound file should be included in the search results. In this case adding the keyword download will include the download link from which the FreeSoundClient will be then able to find and download the actual sound files. The url resulting of this query is now:

https://freesound.org/apiv2/search/text/?query=piano+detuned&fields=id%2Cname%2Cdownload&page_size=15&sort=score&normalized=0

Notice how the url generated by the search request now includes the download keyword in the 'fields' parameter

and c.dump_results() will produce

Output

________________
id:30274
name:piano_impression1.aif
download:https://freesound.org/apiv2/sounds/30274/download/
________________
id:382530
name:Piano 43 F#5.wav
download:https://freesound.org/apiv2/sounds/382530/download/
________________
id:382535
...

The download link is now available and c.download_results()should work as expected

Output

How many files do you want to download? [a number | all] 3
Please set an output folder:  
Downloading 3 files of 469
________________
piano_impression1.aif
Downloading piano_impression1.aif
https://freesound.org/apiv2/sounds/30274/download/
Downloaded Files: 1 of 3
________________
Piano-43-F#5.wav
Downloading Piano-43-F#5.wav
https://freesound.org/apiv2/sounds/382530/download/
Downloaded Files: 2 of 3
________________
...

You can now find these files in your project folder. When prompted, feel free to specify another folder either using an absolute or a relative path. You can avoid being prompted by adding the output_folder_path and the files_count arguments to c.download_results():

c.download_results("sounds", 3)

This instruction will create the folder sounds inside your project folder and download 3 files from the search result into it.

Conclusions

This tutorial allowed you to learn how to set up a simple project using the freesound-client library.

In the next section you will learn the basics of the Freesound API and how to take full advantage of this library.

Getting started

Before you start

Get started

Your first access

Your first search

Printing data from the result

Download your search results

Conclusions

Your first `search`

Printing data from the `result`

Download your `search` results