Sound Design Recommendations Endpoint

🎵 This guide walks you through using the Sound Design Recommendation endpoint (http://v2.api.audio/production/sound/recommendations) to find similar sound designs based on an audio file you provide. You can use this endpoint in two ways: with a Sound Design you've already uploaded and tagged via AudioStack's labelling feature, or by importing any sound file, which will be automatically tagged and then used to find similar Sound Designs.

Set Up Your API Key and Audio File Path

• Begin by importing the AudioStack SDK and inserting your AudioStack API key and the path of your audio file. The SDK can be installed using pip install audiostack if not already installed.

import audiostack
import requests

API_KEY = "<insert your audiostack API key here>"
audioPath = "<insert the path of your audio file here>"

audiostack.api_key = API_KEY

Upload Your Audio File using AudioStack SDK

• Use audiostack.Content.File.create to upload the file to AudioStack. Specify localPath as your audio file path and set the uploadPath name (e.g., "audio.wav"). This step will return a unique fileId associated with your uploaded file.

r = audiostack.Content.File.create(
    localPath=audioPath, uploadPath="audio.wav", fileType="audio"
)
fileId = r.fileId

Create the Request to Retrieve Recommendations

• Define the URL for the Sound Design Recommendation endpoint and structure your request body.

Parameters in the Request Body:

• "fileId": The ID of the uploaded file, obtained from the previous step.
• "numberOfResults": The number of similar sound designs you want to retrieve (e.g., numberOfResults=3).
• "filters": Filter options to narrow down results, such as genre or key. Here, we’re filtering for "Pop" genre and "aMinor" key.
• "force_apply_filters": A boolean value that, if set to True, strictly enforces filters. If False, the filter will not be applied if there are less than x results after filtering.

url = "http://v2.api.audio/production/sound/recommendations"
body = {
    "fileId": fileId,
    "numberOfResults": 3,
    "filters": [{"in": {"genre": ["Pop"]}}, {"in": {"key": ["aMinor"]}}],
    "force_apply_filters": False,
}

Send the Request and Retrieve Recommendations

• Use a POST request to send the data and retrieve the response, specifying the x-api-key in the headers.

response = requests.post(
    url=url,
    json=body,
    headers={"x-api-key": API_KEY},
)

Process and Print the Recommendations

• Parse the response JSON to extract and print the recommended sound designs.

data = response.json()["data"]
print(data)

Clean Up by Deleting the Uploaded File

• After completing the recommendation process, delete the uploaded file using audiostack.Content.File.delete to remove from the platform.

audiostack.Content.File.delete(fileId=r.fileId)

Example Code

Here is the complete example code for using the Sound Design Recommendation endpoint:

import audiostack
import requests

# Insert your API key and audio file path
API_KEY = "<insert your audiostack API key here>"
audioPath = "<insert the path of your audio file here>"

audiostack.api_key = API_KEY

# Step 1: Upload audio file
r = audiostack.Content.File.create(
    localPath=audioPath, uploadPath="audio.wav", fileType="audio"
)
fileId = r.fileId

# Step 2: Prepare and send the recommendation request
url = f"http://v2.api.audio/production/sound/recommendations"
body = {
    "fileId": fileId,
    "numberOfResults": 3,
    "filters": [{"in": {"genre": ["Pop"]}}, {"in": {"key": ["aMinor"]}}],
    "force_apply_filters": False,
}

response = requests.post(
    url=url,
    json=body,
    headers={"x-api-key": API_KEY},
)

# Step 3: Print the recommended sound designs
data = response.json()["data"]
print(data)

# Step 4: Delete the uploaded file
audiostack.Content.File.delete(fileId=r.fileId)

By following these steps, you can seamlessly retrieve similar sound designs to streamline your audio production process. The cost of this service is 5 production credits if your file is already tagged, and 15 production credits including tagging a new asset.