Tutorial - Tonn API: Mix Analysis

This guide explains how to use the Tonn API to analyse your mixed or mastered tracks, ensuring they are polished and ready for release on streaming platforms.

The code for this tutorial is available in the following code repository: https://github.com/roex-audio/TonnExamples

Using Tonn API for Mix Analysis leverages the same advanced technology behind RoEx's Mix Check Studio, which has already been used by DIY musicians and producers on 100,000's of tracks.

What is Mix Check Studio?

Mix Check Studio analyses your music tracks to identify potential issues in your mix or master, providing detailed feedback on loudness, dynamic range, clipping, stereo field, tonal profile, and more. This allows you to make informed adjustments before your music reaches listeners.

Why Analyse Your Tracks?

Before releasing music, it's crucial to ensure your tracks meet industry standards. Mix Check Studio helps by highlighting:

  • Clipping issues: Detects unwanted distortion or peaks that may degrade audio quality.
  • Dynamic range issues: Evaluates compression levels to ensure appropriate dynamics.
  • Loudness: Analyses how your track's loudness compares to standards set by Spotify, Apple Music, and YouTube.
  • Stereo field and mono compatibility: Assesses stereo imaging, ensuring your music sounds great on all devices.
  • Tonal balance: Offers insights to enhance warmth, clarity, and overall sonic presence.

Step-by-Step Tutorial

1. Prerequisites

Ensure you have:

  • An API key from Tonn API Portal

  • Python environment setup with requests library installed (pip install requests)

  • 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.

2. Upload Your Audio File

First, upload your audio file using our secure upload endpoint:

import requests

def upload_audio_file(filename):
    # Get upload URL
    response = requests.post(
        'https://tonn.roexaudio.com/upload',
        headers={'X-API-Key': 'your-api-key'},
        json={
            'filename': filename,
            'contentType': 'audio/wav'  # or 'audio/mpeg' for MP3
        }
    )
    result = response.json()

    # Upload the file
    with open(filename, 'rb') as f:
        upload_response = requests.put(
            result['signed_url'],
            data=f,
            headers={'Content-Type': 'audio/wav'}
        )

    return result['readable_url'] if upload_response.status_code == 200 else None

# Example usage
audio_url = upload_audio_file('your-track.wav')

3. Prepare Your Request

Create a payload containing:

{
    "mixDiagnosisData": {
        "audioFileLocation": audio_url,  # Use the URL from the upload step
        "musicalStyle": "ROCK",
        "isMaster": true
    }
}

Replace the audioFileLocation URL with your track's location, choose the appropriate musicalStyle, and set isMaster accordingly.

3. Run the Analysis

Use the provided Python script (roex_mix_analysis.py) to submit your track:

python roex_mix_analysis.py

4. Interpreting Results

Upon running the script, you'll receive detailed output similar to this example:

=== Mix Analysis Top-Level Response ===
Error: False
Message: Successfully initiated a diagnosis task.

=== Mix Diagnosis Results ===
Completion Time: 2025-03-17 11:05:18
Error Flag: False

--- Payload Details ---
bit_depth: 24
clipping: MINOR
if_master_drc: LESS
if_master_loudness: LESS
integrated_loudness_lufs: -8.88
mono_compatible: True
musical_style: hip_hop_grime
peak_loudness_dbfs: 1.3
phase_issues: False
sample_rate: 44100
stereo_field: STEREO_UPMIX

--- Summary ---
1. Minor clipping detected; use a limiter to control peaks.
2. Dynamic range is limited; avoid heavy compression.
3. Loudness exceeds streaming standards by 5.1 dB (Spotify, Tidal, YouTube) and 7.1 dB (Apple Music).
4. Recommended EQ adjustments: boost low-mid frequencies for warmth; subtle boosts in high-mid and highs for clarity; apply multiband compression to balance tonal profile.

Remember: Use this analysis as guidance. Always trust your ears for final decisions.

5. Improving Your Mix

You can use this feedback to go back to the DAW make changes to improve how it sounds based on the recommendations given. For example:

  • Adjust your track's loudness and dynamic range.
  • Correct any minor clipping using a limiter.
  • Enhance the tonal profile and stereo image.

6. Next Steps

After addressing the feedback:

  • Re-run your mix through Mix Check Studio.
  • Compare results to ensure improvements.
  • Confidently release your music knowing it meets professional standards.

Support

For further assistance, please visit the Tonn API Portal or contact our support team at support@roexaudio.com.