TonnSDK API Reference

This document provides a comprehensive reference to the TonnSDK API, listing all public classes, methods, and enums with detailed descriptions.

Table of Contents

Core Classes

TonnSDK

The main entry point for the SDK that handles mixing operations.

Note: The TonnSDK header (TonnSDK.h) provides the main interface. Detailed enums and class methods are defined in separate headers like MixTrackSettings.h and License.h which are included automatically.

namespace tonn {
    class TONNSDK_API TonnSDK {
        // Constructors and initialization
        TonnSDK(float sampleRate, MusicalStyle style = MusicalStyle::ROCK_INDIE, 
               bool skipQuietTracks = false, bool enableCreativeCompression = true);
        ~TonnSDK();

        // Initialization
        bool initialize(const std::string& licenseKey);

        // Track handling
        void addTrack(const std::string& filePath, const MixTrackSettings& settings);
        void addTrackFromBuffer(const std::vector<std::vector<float>>& audioBuffer, 
                               const MixTrackSettings& settings);
        void addTrackFromBuffer(const std::vector<std::vector<float>>& audioBuffer, 
                               const MixTrackSettings& settings,
                               const std::string& trackName);

        // Processing
        MixResult process(bool settingsOnly = false, bool generateStems = true);

        // Mixing Model (NEW in v1.6)
        void setMixingModel(MixingModel model);
        MixingModel getMixingModel() const;

        // Creative Compression
        void setCreativeCompressionEnabled(bool enabled);
        bool isCreativeCompressionEnabled() const;

        // License handling
        LicenseStatus setLicenseKey(const std::string& licenseKey);
        bool isLicenseValid() const;
        std::string getLicenseStatus() const;
        std::string getLicensee() const;
        int getRemainingDays() const;

        // Access to processors
        MixingProcessor* getMixingProcessor();
        MasteringProcessor* getMasteringProcessor();

        // AudioReprocessor integration
        std::unique_ptr<AudioReprocessor> createReprocessor() const;
        bool saveOriginalStems(const std::string& directoryPath, bool includeSettings = true) const;
        std::vector<std::string> getOriginalFilePaths() const;

        // Error handling
        std::string getLastErrorMessage() const;
    };
}

Constructor

TonnSDK::TonnSDK(float sampleRate, MusicalStyle style = MusicalStyle::ROCK_INDIE, bool skipQuietTracks = false);

Creates a new TonnSDK instance with the specified sample rate, musical style, and quiet track handling behavior.

  • Parameters:
  • sampleRate: The sample rate of the audio to be processed (e.g., 44100, 48000)
  • style: The musical style to optimize for, from the MusicalStyle enum
  • skipQuietTracks: (STABLE in v1.3.1) Optional flag to skip quiet tracks instead of throwing errors. When true, tracks below the silence threshold (-70 LUFS or RMS < 0.0001) are skipped with user notification. Defaults to false for backward compatibility.

initialize

bool TonnSDK::initialize(const std::string& licenseKey);

Initializes the SDK with the provided license key.

  • Parameters:
  • licenseKey: A valid license key string
  • Returns: true if initialization was successful, false otherwise

addTrack

void TonnSDK::addTrack(const std::string& filePath, const MixTrackSettings& settings);

Adds a track to the mixing session from a file path.

  • Parameters:
  • filePath: Path to the audio file
  • settings: MixTrackSettings object containing track configuration

addTrackFromBuffer

void TonnSDK::addTrackFromBuffer(const std::vector<std::vector<float>>& audioBuffer, 
                                const MixTrackSettings& settings);

void TonnSDK::addTrackFromBuffer(const std::vector<std::vector<float>>& audioBuffer, 
                                const MixTrackSettings& settings,
                                const std::string& trackName);

Adds a track to the mixing session from a multi-channel audio buffer.

  • Parameters:
  • audioBuffer: Vector of vectors containing audio data [channel][sample]
  • settings: MixTrackSettings object containing track configuration
  • trackName: Optional name for the track. Appears in FX Chain JSON and stem exports. Defaults to "buffer_track" if not provided.

setMixingModel (NEW in v1.6)

void TonnSDK::setMixingModel(MixingModel model);

Sets the mixing model (processing mode) for the SDK. Call before process().

  • Parameters:
  • model: The MixingModel enum value. CPU_STATIC (default) or GPU_STATIC (GPU-accelerated, recommended with NVIDIA/CUDA).

getMixingModel (NEW in v1.6)

MixingModel TonnSDK::getMixingModel() const;

Returns the currently configured mixing model.

  • Returns: The current MixingModel value

setCreativeCompressionEnabled

void TonnSDK::setCreativeCompressionEnabled(bool enabled);

Enables or disables genre-specific creative compression.

  • Parameters:
  • enabled: When true, applies stylized compression presets based on musical style and instrument type. When false, only corrective compression is applied.

Creative compression is enabled by default. Disable it for a more transparent, natural sound without genre-specific compression character.

isCreativeCompressionEnabled

bool TonnSDK::isCreativeCompressionEnabled() const;

Checks if creative compression is currently enabled.

  • Returns: true if creative compression is enabled, false otherwise

process

MixResult TonnSDK::process(bool settingsOnly = false);

Processes all added tracks to create an optimized mix.

  • Parameters:
  • settingsOnly: Optional parameter. If true, only calculates optimized settings without generating audio output
  • Returns: MixResult object containing the final mix, processed stems, and optimized settings

setLicenseKey

LicenseStatus TonnSDK::setLicenseKey(const std::string& licenseKey);

Sets the license key for the SDK.

  • Parameters:
  • licenseKey: A valid license key string
  • Returns: LicenseStatus indicating the result of license validation

isLicenseValid

bool TonnSDK::isLicenseValid() const;

Checks if the current license is valid.

  • Returns: true if the license is valid, false otherwise

getLastErrorMessage

std::string TonnSDK::getLastErrorMessage() const;

Gets the most recent error message from the SDK.

  • Returns: A string describing the most recent error

createReprocessor

std::unique_ptr<AudioReprocessor> TonnSDK::createReprocessor() const;

Creates an AudioReprocessor instance configured with the same sample rate and musical style as this TonnSDK instance.

  • Returns: Unique pointer to AudioReprocessor instance

saveOriginalStems

bool TonnSDK::saveOriginalStems(const std::string& directoryPath, bool includeSettings = true) const;

Saves the original, unprocessed audio files for later reprocessing with AudioReprocessor.

  • Parameters:
  • directoryPath: Directory to save original stems
  • includeSettings: Whether to save settings files alongside audio
  • Returns: true if saving succeeded, false otherwise

getOriginalFilePaths

std::vector<std::string> TonnSDK::getOriginalFilePaths() const;

Returns the original file paths that were added to this SDK instance for use with AudioReprocessor.

  • Returns: Vector of original file paths (empty for buffer-added tracks)

AudioReprocessor

The AudioReprocessor class provides offline audio reprocessing capabilities, allowing you to take original stems and apply modified MixTrackSettings to generate new mixes without re-rendering from source.

namespace tonn {
    class TONNSDK_API AudioReprocessor {
        // Constructor/Destructor
        AudioReprocessor(float sampleRate, MusicalStyle style = MusicalStyle::ROCK_INDIE);
        ~AudioReprocessor();

        // Stem loading
        bool loadStem(const std::string& filePath, const MixTrackSettings& originalSettings);
        bool loadStem(const std::vector<std::vector<float>>& audioBuffer,
                      const MixTrackSettings& originalSettings,
                      const std::string& trackName = "");

        // Reprocessing
        ReprocessResult reprocess(std::vector<MixTrackSettings> modifiedSettings);

        // Output methods
        bool saveReprocessedMix(const ReprocessResult& result, const std::string& filePath);
        bool saveReprocessedStem(const ReprocessResult& result, size_t stemIndex, const std::string& filePath);

        // Utility methods
        void clearStems();
        size_t getStemCount() const;
        std::vector<std::string> getStemNames() const;
        float getSampleRate() const;
        std::string getLastError() const;
    };
}

Constructor

AudioReprocessor::AudioReprocessor(float sampleRate, MusicalStyle style = MusicalStyle::ROCK_INDIE);

Creates a new AudioReprocessor instance.

  • Parameters:
  • sampleRate: Sample rate for processing
  • style: Musical style for processing optimization

loadStem (from file)

bool AudioReprocessor::loadStem(const std::string& filePath, const MixTrackSettings& originalSettings);

Loads an original stem from an audio file for reprocessing.

  • Parameters:
  • filePath: Path to the original audio file
  • originalSettings: The original MixTrackSettings used with this stem
  • Returns: true if loading succeeded, false otherwise

loadStem (from buffer)

bool AudioReprocessor::loadStem(const std::vector<std::vector<float>>& audioBuffer,
                                const MixTrackSettings& originalSettings,
                                const std::string& trackName = "");

Loads an original stem from an audio buffer for reprocessing.

  • Parameters:
  • audioBuffer: Raw audio data (channels x samples)
  • originalSettings: The original MixTrackSettings used with this stem
  • trackName: Optional name for this track
  • Returns: true if loading succeeded, false otherwise

reprocess

ReprocessResult AudioReprocessor::reprocess(std::vector<MixTrackSettings> modifiedSettings);

Reprocesses all loaded stems with modified settings using the complete TonnSDK processing pipeline.

  • Parameters:
  • modifiedSettings: New settings for each stem (must match number of loaded stems)
  • Returns: ReprocessResult containing the new mix and processed stems

saveReprocessedMix

bool AudioReprocessor::saveReprocessedMix(const ReprocessResult& result, const std::string& filePath);

Saves the reprocessed mix to an audio file.

  • Parameters:
  • result: Result from reprocess() containing the mix
  • filePath: Output file path (format determined by extension)
  • Returns: true if saving succeeded, false otherwise

saveReprocessedStem

bool AudioReprocessor::saveReprocessedStem(const ReprocessResult& result, size_t stemIndex, const std::string& filePath);

Saves a specific reprocessed stem to an audio file.

  • Parameters:
  • result: Result from reprocess() containing the stems
  • stemIndex: Index of the stem to save (0-based)
  • filePath: Output file path
  • Returns: true if saving succeeded, false otherwise

clearStems

void AudioReprocessor::clearStems();

Clears all loaded stems from the reprocessor.

getStemCount

size_t AudioReprocessor::getStemCount() const;

Gets the number of currently loaded stems.

  • Returns: Number of stems currently loaded

getStemNames

std::vector<std::string> AudioReprocessor::getStemNames() const;

Gets the names of all loaded stems.

  • Returns: Vector of stem names

getSampleRate

float AudioReprocessor::getSampleRate() const;

Gets the sample rate being used for processing.

  • Returns: Sample rate in Hz

getLastError

std::string AudioReprocessor::getLastError() const;

Gets the last error message from the AudioReprocessor.

  • Returns: Error message string (empty if no error)

MixTrackSettings

Controls settings for individual tracks in the mix.

namespace tonn {
    class MixTrackSettings {
        // Constructors
        MixTrackSettings();
        MixTrackSettings(GroupType type, PresenceSetting presence, MusicalStyle style);
        MixTrackSettings(const MixTrackSettings& other);

        // Core settings
        void setGroupType(GroupType type);
        GroupType getGroupType() const;

        void setPresence(PresenceSetting presence);
        PresenceSetting getPresence() const;

        void setPanPreference(PanPreference preference);
        PanPreference getPanPreference() const;

        // Get/set the actual pan angle (in degrees, -90 to +90, where 0 is center)
        float getPanAngle() const;
        void setPanAngle(float angle);

        void setGain(float gain);
        float getGain() const;

        void setReverbSetting(ReverbSetting setting);
        ReverbSetting getReverbSetting() const;

        void setSampleRate(int rate);
        int getSampleRate() const;

        void setIsStem(bool isStem);
        bool getIsStem() const;

        // EQ settings
        void setFilterFreqSettings(const std::vector<float>& freqs);
        const std::vector<float>& getFilterFreqSettings() const;

        void setEQGains(const std::vector<float>& gains);
        const std::vector<float>& getEQGains() const;

        void setPresenceQSettings(const std::vector<float>& qFactors);
        const std::vector<float>& getPresenceQSettings() const;

        // Compression settings
        void setCompressorThreshold(float threshold);
        float getCompressorThreshold() const;

        void setCompressorRatio(float ratio);
        float getCompressorRatio() const;

        void setCompressorAttack(float attackMs);
        float getCompressorAttack() const;

        void setCompressorRelease(float releaseMs);
        float getCompressorRelease() const;
    };
}

setGroupType / getGroupType

void MixTrackSettings::setGroupType(GroupType type);
GroupType MixTrackSettings::getGroupType() const;

Sets/gets the instrument group type for this track.

  • Parameters:
  • type: The GroupType enum value (e.g., DRUMS_GROUP, BASS_GROUP, etc.)

setPresence / getPresence

void MixTrackSettings::setPresence(PresenceSetting presence);
PresenceSetting MixTrackSettings::getPresence() const;

Sets/gets the presence setting (importance) of the track.

  • Parameters:
  • presence: The PresenceSetting enum value (BACKGROUND, NORMAL, LEAD)

setPanPreference / getPanPreference

void MixTrackSettings::setPanPreference(PanPreference preference);
PanPreference MixTrackSettings::getPanPreference() const;

Sets/gets the preferred panning position for this track using the PanPreference enum.

  • Parameters:
  • preference: The PanPreference enum value (NO_PREFERENCE, LEFT, CENTER, RIGHT)

getPanAngle / setPanAngle

float MixTrackSettings::getPanAngle() const;
void MixTrackSettings::setPanAngle(float angle);

Gets/sets the actual pan angle in degrees (-90 to +90, where 0 is center).

  • Parameters:
  • angle: The pan angle in degrees

setReverbSetting / getReverbSetting

void MixTrackSettings::setReverbSetting(ReverbSetting setting);
ReverbSetting MixTrackSettings::getReverbSetting() const;

Sets/gets the reverb setting for this track using the ReverbSetting enum.

  • Parameters:
  • setting: The ReverbSetting enum value (NONE, LOW, MEDIUM, HIGH)

MixResult Structure

Contains the results of the mixing process.

struct MixResult {
    std::pair<std::vector<float>, std::vector<float>> audio_x;  // Final stereo mix [L,R]
    std::vector<MixTrackSettings> mixTrackSettings;  // Optimized track settings
    std::vector<std::pair<std::vector<float>, std::vector<float>>> stems;  // Processed stems
    std::vector<std::string> trackNames;  // Track names to match stems
    float trackLengthInSecs = 0.0f;  // Duration of the tracks in seconds
    std::string fxChainsJson;  // Complete FX chain data as ordered JSON
};
  • audio_x: The final stereo mix as a pair of vectors (left and right channels)
  • mixTrackSettings: Optimized settings for each track after processing
  • stems: Processed individual stems for each track as pairs of vectors (left and right channels)
  • trackNames: Track names corresponding to the stems
  • trackLengthInSecs: Duration of the tracks in seconds
  • fxChainsJson: Complete effects chain data for all tracks as ordered JSON. Contains the exact sequence of effects applied to each track with all parameters, like a virtual mixing desk.

FX Chain JSON Structure

The fxChainsJson field contains an array of track objects with the following structure:

[
  {
    "trackId": 0,
    "trackName": "vocals.wav",
    "groupType": "VOCAL_GROUP",
    "musicalStyle": "ROCK_INDIE",
    "analysis": {
      "isLowCutApplied": true,
      "isStem": true
    },
    "fxChain": [
      {"type": "LOW_CUT", "order": 0, "enabled": true, "params": {"frequency": 80.0, "slope": 12.0}},
      {"type": "GAIN", "subtype": "PRE_GAIN", "order": 1, "enabled": true, "params": {"gainDb": -3.5, "gainLinear": 0.668}},
      {"type": "EQ", "order": 2, "enabled": true, "bands": [{"frequency": 100, "gain": -2.0, "q": 1.5}, ...]},
      {"type": "COMPRESSOR", "subtype": "CORRECTIVE", "order": 3, "enabled": true, "params": {"threshold": -18.0, "ratio": 3.0, "attack": 10.0, "release": 100.0}},
      {"type": "COMPRESSOR", "subtype": "CREATIVE", "order": 4, "enabled": true, "params": {"threshold": -12.0, "ratio": 4.0, "attack": 5.0, "release": 50.0, "makeupGain": 2.0}},
      {"type": "PAN", "order": 5, "enabled": true, "params": {"angleDegrees": 0.0, "preference": "CENTRE"}},
      {"type": "GAIN", "subtype": "POST_GAIN", "order": 6, "enabled": true, "params": {"gainDb": 2.0, "gainLinear": 1.26}},
      {"type": "REVERB", "order": 7, "enabled": false, "params": {"setting": "NONE"}},
      {"type": "SIDECHAIN_COMPRESSOR", "order": 8, "enabled": false}
    ]
  }
]

ReprocessResult Structure

Contains the results of AudioReprocessor reprocessing operations.

struct ReprocessResult {
    std::pair<std::vector<float>, std::vector<float>> mixedAudio;  // Final stereo mix [L,R]
    std::vector<std::pair<std::vector<float>, std::vector<float>>> processedStems;  // Individual processed stems
    std::vector<std::string> trackNames;  // Track names corresponding to stems
    float lengthInSeconds = 0.0f;  // Length of the audio in seconds
    bool success = false;  // Whether the reprocessing was successful
    std::string errorMessage;  // Error message if success is false

    // Utility methods
    bool hasValidAudio() const;
    size_t getStemCount() const;
};
  • mixedAudio: The reprocessed stereo mix as a pair of vectors (left and right channels)
  • processedStems: Reprocessed individual stems for each track as pairs of vectors (left and right channels)
  • trackNames: Track names corresponding to the stems
  • lengthInSeconds: Duration of the audio in seconds
  • success: Whether the reprocessing operation was successful
  • errorMessage: Error message if the operation failed
  • hasValidAudio(): Utility method to check if result contains valid audio
  • getStemCount(): Get the number of processed stems

Enums

MixingModel (NEW in v1.6)

Selects the processing mode for mixing.

enum class MixingModel {
    CPU_STATIC,  // CPU-only processing with static optimization (default, no GPU required)
    GPU_STATIC   // GPU-accelerated with static optimization (faster, higher quality — requires CUDA)
};

Use setMixingModel() before calling process() to select a mode:

// Enable GPU-accelerated mixing (requires NVIDIA GPU with CUDA)
sdk.setMixingModel(tonn::MixingModel::GPU_STATIC);

// If GPU is not available, the SDK falls back to CPU automatically
tonn::MixResult result = sdk.process();

GroupType

Classifies the track by instrument type.

enum class GroupType {
    BASS_GROUP = 1,
    MIDS_GROUP = 2,
    DRUMS_GROUP = 3,
    VOCAL_GROUP = 4,
    KICK_GROUP = 5,
    SNARE_GROUP = 6,
    STRINGS_GROUP = 7,
    REVERB_SEND_GROUP = 8,
    CYMBALS_GROUP = 9,
    E_GUITAR_GROUP = 10,
    ACOUSTIC_GUITAR_GROUP = 11,
    BRASS_GROUP = 12,
    FX_GROUP = 13,
    SYNTH_GROUP = 14,
    PERCS_GROUP = 15,
    OTHER1_GROUP = 16,
    KEYS_GROUP = 17,
    MASTERING = 18,
    BACKING_VOX_GROUP = 19,
    BACKING_TRACK_GROUP = 20,
    OTHER_GROUP = 16  // Alias for OTHER1_GROUP for backward compatibility
};

PresenceSetting

Defines the importance level of the track in the mix.

enum class PresenceSetting {
    BACKGROUND = 1,  // Background elements
    NORMAL = 2,      // Standard mix elements
    LEAD = 3         // Lead/focal elements
};

PanPreference

Defines panning preference options for tracks.

enum class PanPreference {
    NO_PREFERENCE = 0,
    LEFT = 1,
    CENTER = 2,
    RIGHT = 3
};

ReverbSetting

Defines reverb level options for tracks.

enum class ReverbSetting {
    NONE = 0,
    LOW = 1,
    MEDIUM = 2,
    HIGH = 3
};

MusicalStyle

Defines the musical genre to optimize the mix for.

enum class MusicalStyle {
    ROCK_INDIE = 1,
    POP = 2,
    ACOUSTIC = 3,
    HIPHOP_GRIME = 4,
    ELECTRONIC = 5,
    REGGAE_DUB = 6,
    ORCHESTRAL = 7,
    METAL = 8,

    OTHER = 9
};

Stable Features

Skip Quiet Tracks Feature

Version 1.3.1 provides stable and enhanced support for gracefully handling quiet or silent audio tracks through the skipQuietTracks parameter in the TonnSDK constructor.

Usage Example:

// Enable skip quiet tracks for batch processing
tonn::TonnSDK sdk(44100.0f, tonn::MusicalStyle::ROCK_INDIE, true);

// Add tracks - quiet tracks will be skipped instead of throwing errors
sdk.addTrack("quiet_track.wav", settings);  // Will be skipped with notification
sdk.addTrack("normal_track.wav", settings); // Will be processed normally

Key Benefits: - Perfect for batch processing workflows where some tracks might be below threshold - Clear user notifications when tracks are skipped - Supports both RMS-based (< 0.0001) and ITU loudness-based (< -70 LUFS) silence detection - Backward compatible - defaults to existing behavior

Pre-gain Preservation Fix

Version 1.3.1 provides stable and enhanced pre-gain preservation functionality where pre-gain values calculated during loudness normalization are properly preserved throughout processing and available in the final MixResult.

What This Means: - Pre-gain values from loudness normalization to -23 LUFS are now accurately preserved - Users can access correct pre-gain information in processing results - Consistent loudness normalization data throughout the entire processing pipeline

Error Handling

The SDK provides robust error handling through the following mechanisms:

  1. Return Values: Many methods return boolean values to indicate success/failure
  2. Error Messages: The getLastErrorMessage() method retrieves detailed error information
  3. Exceptions: In critical failure cases, the SDK may throw exceptions
  4. Validation: Input validation is performed to prevent invalid operations

For optimal error handling:

try {
    // SDK operation
    if (!sdkOperation()) {
        std::cerr << "Operation failed: " << tonnSDK.getLastErrorMessage() << std::endl;
        // Handle the error appropriately
    }
} catch (const std::exception& e) {
    std::cerr << "Critical error: " << e.what() << std::endl;
    // Handle catastrophic failure
}

Ready to integrate?

You've covered the full SDK documentation. Take the next step and get access to TonnSDK for your project.

Request SDK Access