Tutorial - Tonn API: Automating Audio Mixing¶
Check out the associated GitHub repository for further details: https://github.com/roex-audio/TonnExamples
Introduction¶
Imagine you have multiple audio tracks recorded separately—instruments like drums, bass, guitar, plus vocals—and you need a professional mix that balances them seamlessly. The Tonn API allows you to automate this process, ensuring clarity, depth, and consistency in your audio mix. This guide will walk you through: - Creating a preview mix to test your setup - Polling for mix status updates so you know when it's ready - Using webhooks instead of polling for real-time updates - Retrieving the final mix for your production - Extracting audio effect settings for fine-tuning - Applying advanced audio effects including gain, panning, EQ, and compression
Why Use the Tonn API?¶
Mixing music manually can be time-consuming and technically challenging. Whether you're an independent musician, producer, or developer integrating audio features into an application, the Tonn API provides an easy way to get professional-quality mixes in just a few steps.
Prerequisites¶
Before you begin, make sure you have:
- Python installed on your system
- The requests library (pip install requests)
- A valid API key for authentication
Alternatively, you can use our Python client library to simplify interactions with the API. Install it via pip:
pip install roex-python
Find more details on the PyPI project page.
Base API URL¶
All API requests should be made to:
https://tonn.roexaudio.com
Step 1: Uploading Your Audio Files¶
Before creating a mix, you'll need to upload your audio files. Tonn API provides a secure way to upload files directly to our temporary storage.
Getting Upload URLs¶
First, request a signed URL for each file you want to upload:
import requests
def get_upload_url(filename, content_type):
response = requests.post(
'https://tonn.roexaudio.com/upload',
headers={'X-API-Key': 'your-api-key'},
json={
'filename': filename,
'contentType': content_type
}
)
return response.json()
# Example usage
result = get_upload_url('drums.wav', 'audio/wav')
upload_url = result['signed_url'] # Use this to upload the file
readable_url = result['readable_url'] # Use this in other API calls
Uploading Files¶
Once you have the signed URL, upload your file:
def upload_file(signed_url, filename, content_type):
with open(filename, 'rb') as f:
response = requests.put(
signed_url,
data=f,
headers={'Content-Type': content_type}
)
return response.status_code == 200
Step 2: Creating a Preview Mix¶
After uploading your files, you can create a preview mix using the readable URLs. This lets you hear how your tracks sound together before committing to a final mix.
How It Works¶
When you send a POST request to /mixpreview, the API takes your tracks, applies professional mixing techniques, and generates a preview mix. This step doesn't consume any credits, allowing you to tweak and experiment freely.
Including a webhookURL in your request payload is mandatory. This ensures you receive a notification when the preview mix is ready, eliminating the need for polling.
Endpoint Details¶
- Endpoint:
POST /mixpreview - Consumes:
application/json - Response Codes:
200: Success, returnsmultitrack_task_id400: Bad Request (Invalid input)401: Unauthorized (API key missing/invalid)500: Internal Server Error
Example JSON Payload with Webhook¶
Save this as preview_payload.json:
{
"multitrackData": {
"trackData": [
{
"trackURL": "https://example.com/vocals.wav",
"instrumentGroup": "VOCAL_GROUP",
"presenceSetting": "LEAD",
"panPreference": "CENTRE",
"reverbPreference": "LOW"
},
{
"trackURL": "https://example.com/drums.wav",
"instrumentGroup": "DRUMS_GROUP",
"presenceSetting": "NORMAL",
"panPreference": "CENTRE",
"reverbPreference": "NONE"
}
],
"musicalStyle": "POP",
"returnStems": false,
"sampleRate": 44100,
"webhookURL": "https://example.com/webhook"
}
}
Step 2: Polling for Preview Mix Completion (For Debugging)¶
Polling is generally not required since webhooks provide real-time updates. However, you can use polling as a backup method for debugging or verifying status manually.
Retrieving Mix Output Settings¶
Once the preview mix is complete, the API returns mix output settings for each track, including: - Dynamic range compression (DRC) settings - Equalization (EQ) settings - Gain adjustments - Panning preferences
Example of Mix Output Settings¶
Track: masks-bass.wav
drc_settings:
attack_ms: 0.074
ratio: 1.8
release_ms: 0.022
threshold: -3.89
eq_settings:
band_1: {"centre_freq": 46.5, "gain": -1.69, "q": 2.66}
band_2: {"centre_freq": 96.69, "gain": -2.73, "q": 2.42}
gain_settings:
gain_db: -11.8
These settings allow you to fine-tune the mix before finalizing it.
Step 3: Applying Audio Effects & Retrieving the Final Mix¶
Once you're happy with the preview mix, you can apply audio effects and adjustments to individual tracks before retrieving the final mix.
The API now supports advanced audio processing parameters:
- Gain adjustment (gainDb) - Volume control in decibels
- Panning (panning_settings) - Stereo positioning
- EQ (eq_settings) - 6-band parametric equalization
- Compression (compression_settings) - Dynamic range control
Basic Example JSON Payload (Gain Only)¶
Save this as final_payload_basic.json:
{
"applyAudioEffectsData": {
"multitrackTaskId": "TASK_ID_HERE",
"trackData": [
{
"trackURL": "https://example.com/vocals.wav",
"gainDb": 0.0
},
{
"trackURL": "https://example.com/drums.wav",
"gainDb": -2.0
}
],
"returnStems": false,
"sampleRate": "44100"
}
}
Advanced Example with Audio Effects¶
For more control over your mix, you can apply panning, EQ, and compression to individual tracks:
{
"applyAudioEffectsData": {
"multitrackTaskId": "TASK_ID_HERE",
"trackData": [
{
"trackURL": "https://example.com/vocals.wav",
"gainDb": 0.0,
"panning_settings": {
"panning_angle": 0
},
"eq_settings": {
"band_1": {
"gain": 2.5,
"q": 1.0,
"centre_freq": 100.0
},
"band_2": {
"gain": -1.5,
"q": 2.0,
"centre_freq": 800.0
},
"band_3": {
"gain": 3.0,
"q": 1.5,
"centre_freq": 3000.0
}
},
"compression_settings": {
"threshold": -20.0,
"ratio": 3.0,
"attack_ms": 5.0,
"release_ms": 50.0
}
},
{
"trackURL": "https://example.com/drums.wav",
"gainDb": -2.0,
"panning_settings": {
"panning_angle": 0
},
"compression_settings": {
"threshold": -15.0,
"ratio": 4.0,
"attack_ms": 1.0,
"release_ms": 100.0
}
}
],
"returnStems": false,
"createMaster": false,
"desiredLoudness": "MEDIUM",
"sampleRate": "44100",
"webhookURL": "https://example.com/webhook"
}
}
Parameter Reference¶
Panning Settings:
- panning_angle: -60.0 to +60.0 degrees (0 = center, negative = left, positive = right)
EQ Settings (6 bands available):
- gain: -12.0 to 12.0 dB
- q: 0.1 to 10.0 (bandwidth/resonance)
- centre_freq: 20.0 to 20000.0 Hz
Compression Settings:
- threshold: -60.0 to 0.0 dB
- ratio: 1.0 to 20.0
- attack_ms: 0.1 to 100.0 milliseconds
- release_ms: 1.0 to 1000.0 milliseconds
All audio effect parameters are optional - you can use any combination or none at all.
Conclusion¶
By following these steps, you can effortlessly automate professional-quality mixing with the Tonn API. - Start with a preview mix. - Use webhooks to receive real-time notifications when the mix is ready. - Extract mix output settings to analyze how the API processed each track. - Apply audio effects including gain, panning, EQ, and compression to refine the final mix.
Whether you're developing a music app or mixing tracks at scale, this API streamlines your workflow. For more customization, check out the full API documentation!