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,
                               const std::string& sourceDescription = "");

        // Mastering
        void addMix(const std::string& filePath, const MasteringSettings& settings);
        void addMixFromBuffer(const std::vector<std::vector<float>>& audioBuffer,
                             const MasteringSettings& settings,
                             const std::string& sourceDescription = "");

        // Processing
        MixResult process(bool settingsOnly = false, bool generateStems = true);
        MixResult process(const MixTrackSettings& settings, bool settingsOnly = false);
        MasteringResult processMastering();

        // Mixing Model
        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;
        LicenseStatus getLicenseStatus() const;
        std::string getLicenseCustomerName() const;
        int getLicenseRemainingDays() const;

        // Access to processors
        MixingProcessor* getMixingProcessor();

        // 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, bool enableCreativeCompression = true);

Creates a new TonnSDK instance with the specified sample rate, musical style, quiet track handling, and creative compression 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: 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.
  • enableCreativeCompression: Optional flag to enable genre-specific stylized compression at construction time. Defaults to true. Can also be toggled later via setCreativeCompressionEnabled().

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,
                                const std::string& sourceDescription = "");

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
  • sourceDescription: Optional name for the track. Appears in FX Chain JSON and stem exports. Defaults to empty string.

setMixingModel

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

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, bool generateStems = true);

Processes all added tracks to create an optimized mix.

  • Parameters:
  • settingsOnly: If true, only calculates optimized settings without generating audio output (10-50x faster)
  • generateStems: If true (default), generates individual processed stems in MixResult::stems. Set to false to skip stem generation when only the final mix is needed.
  • Returns: MixResult object containing the final mix, processed stems (if requested), and optimized settings

process (with explicit settings)

MixResult TonnSDK::process(const MixTrackSettings& settings, bool settingsOnly = false);

Processes all added tracks using the provided mix track settings for more control over the mixing process.

  • Parameters:
  • settings: Mix track configuration and parameters to apply
  • settingsOnly: If true, only optimize settings without processing audio
  • Returns: MixResult containing the mix and processed stems

addMix

void TonnSDK::addMix(const std::string& filePath, const MasteringSettings& settings);

Loads a stereo mix file for mastering. This is separate from the mixing workflow and will replace any previously loaded mastering mix.

  • Parameters:
  • filePath: Path to mix file to master
  • settings: MasteringSettings to apply

addMixFromBuffer

void TonnSDK::addMixFromBuffer(const std::vector<std::vector<float>>& audioBuffer,
                               const MasteringSettings& settings,
                               const std::string& sourceDescription = "");

Loads mix data from memory for mastering. Replaces any previously loaded mastering mix.

  • Parameters:
  • audioBuffer: Mix data as channel vectors (typically stereo)
  • settings: MasteringSettings to apply
  • sourceDescription: Optional description for the source

processMastering

MasteringResult TonnSDK::processMastering();

Processes the loaded mix with mastering algorithms. Call addMix() or addMixFromBuffer() first.

  • Returns: MasteringResult containing processed audio and metadata

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);

        // Pre-gain and post-gain (linear amplitude multipliers)
        void setPreGain(float pre_gain);
        float getPreGain() const;
        void setPostGain(float post_gain);
        float getPostGain() const;

        // Convenience gain methods in dB
        void setPreGainDb(float gainDb);
        float getPreGainDb() const;
        void setPostGainDb(float gainDb);
        float getPostGainDb() const;

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

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

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

        // Musical style
        void setMusicalStyle(MusicalStyle style);
        MusicalStyle getMusicalStyle() const;

        // Alias for getPresence()
        PresenceSetting getPresenceSetting() 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;

        // FX chain export
        TrackFxChain getFxChain(int trackId, const std::string& trackName) const;
        std::string toFxChainJson(int trackId, const std::string& trackName) 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

setPreGain / getPreGain, setPostGain / getPostGain

void MixTrackSettings::setPreGain(float pre_gain);
float MixTrackSettings::getPreGain() const;
void MixTrackSettings::setPostGain(float post_gain);
float MixTrackSettings::getPostGain() const;

Sets/gets the pre- and post-processing gain as linear amplitude multipliers. Values: 1.0f = unity gain (0 dB), 2.0f = +6 dB, 0.5f = -6 dB.

setPreGainDb / getPreGainDb, setPostGainDb / getPostGainDb

void MixTrackSettings::setPreGainDb(float gainDb);
float MixTrackSettings::getPreGainDb() const;
void MixTrackSettings::setPostGainDb(float gainDb);
float MixTrackSettings::getPostGainDb() const;

Convenience methods to set/get gains in dB.

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)

setMusicalStyle / getMusicalStyle

void MixTrackSettings::setMusicalStyle(MusicalStyle style);
MusicalStyle MixTrackSettings::getMusicalStyle() const;

Sets/gets the musical style for this track.

getFxChain / toFxChainJson

TrackFxChain MixTrackSettings::getFxChain(int trackId, const std::string& trackName) const;
std::string MixTrackSettings::toFxChainJson(int trackId, const std::string& trackName) const;

Returns the complete FX chain for this track as a structured TrackFxChain object or as a JSON string. Useful for DAW integration and visualization.

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

    // Automation (DAW integration)
    std::string automationJson;  // JSON export of automation data
    std::vector<ExportedTrackAutomation> automations;  // Structured automation data
    int problemRegionsDetected = 0;  // Number of problem regions detected
};
  • 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.
  • automationJson: JSON export of per-track automation keyframes (EQ and dynamics deltas over time) for debugging or DAW import.
  • automations: Structured automation data for programmatic DAW integration. See ExportedTrackAutomation below.
  • problemRegionsDetected: Number of problem regions detected during analysis (e.g. frequency masking conflicts).

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}
    ]
  }
]

Automation Structs (DAW Integration)

The following structs are used by MixResult::automations for exporting per-track processing automation to DAWs.

ExportedKeyframe

struct ExportedKeyframe {
    float time_seconds = 0.0f;        // Time position in seconds
    std::vector<float> eq_delta;      // EQ gain deltas per band
    float drc_threshold_delta = 0.0f; // DRC threshold change in dB
    float drc_ratio_delta = 0.0f;     // DRC ratio change
    float drc_attack_delta = 0.0f;    // DRC attack change in seconds
    float drc_release_delta = 0.0f;   // DRC release change in seconds
    float fade_in_seconds = 0.03f;    // Fade-in duration for smooth transitions
    float fade_out_seconds = 0.03f;   // Fade-out duration for smooth transitions
};

Represents a point in time where the processing parameters change relative to the baseline.

ExportedTrackAutomation

struct ExportedTrackAutomation {
    size_t track_index = 0;                        // Track index (0-based)
    std::string track_name;                        // Track filename or identifier
    std::vector<float> baseline_eq_gains;          // Baseline EQ gains per band
    std::vector<float> baseline_eq_center_frequencies; // EQ center frequencies in Hz
    std::vector<float> baseline_eq_q_factors;      // EQ Q factors per band
    float baseline_drc_threshold = -20.0f;         // Baseline DRC threshold in dB
    float baseline_drc_ratio = 4.0f;               // Baseline DRC ratio
    float baseline_drc_attack = 0.01f;             // Baseline DRC attack in seconds
    float baseline_drc_release = 0.1f;             // Baseline DRC release in seconds
    std::vector<ExportedKeyframe> keyframes;       // Automation keyframes
};

Contains baseline EQ and dynamics settings (from the optimiser) plus automation keyframes. Use this data to recreate the time-varying processing in a DAW or audio application.

MasteringResult Structure

Contains the results of mastering operations.

struct MasteringResult {
    std::pair<std::vector<float>, std::vector<float>> audio;  // Mastered stereo audio [L,R]
    float measuredLUFS = 0.0f;   // Measured loudness in LUFS
    float peakLevel = 0.0f;     // Peak level in dB
    float trackLengthInSecs = 0.0f;  // Duration in seconds
    bool success = false;       // Whether mastering was successful
};
  • audio: Mastered stereo audio as a pair of vectors (left and right channels)
  • measuredLUFS: Measured integrated loudness in LUFS
  • peakLevel: Peak level in dB
  • trackLengthInSecs: Duration of the mastered audio in seconds
  • success: Whether the mastering operation completed successfully

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

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
}

PostProductionSDK (New in v2.0)

The PostProductionSDK class is the main entry point for video post-production audio processing (film, TV, streaming, ads, podcasts). It handles dialogue enhancement, auto-ducking, format-specific mastering, and loudness normalization. Include PostProductionSDK.h (this pulls in PostProdTrackSettings.h and License.h).

All symbols are in the tonn namespace.

namespace tonn {
    class POSTPROD_SDK_API PostProductionSDK {
    public:
        PostProductionSDK(float sampleRate = 48000.0f,
                          PostProdFormat format = PostProdFormat::BROADCAST);
        ~PostProductionSDK();

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

        bool addTrack(const std::string& filePath, const PostProdTrackSettings& settings);
        bool addTrackFromBuffer(const std::vector<std::vector<float>>& audioBuffer,
                                const PostProdTrackSettings& settings,
                                const std::string& name = "");

        using ProgressCallback = std::function<bool(float progress, const std::string& stage)>;
        PostProdResult process(bool generateStems = false, ProgressCallback callback = nullptr);

        void setFormat(PostProdFormat format);
        PostProdFormat getFormat() const;

        void setAutoDuckingEnabled(bool enabled);
        bool getAutoDuckingEnabled() const;

        void setDialogueEnhancementEnabled(bool enabled);
        bool getDialogueEnhancementEnabled() const;

        void setMasteringEnabled(bool enabled);
        bool getMasteringEnabled() const;

        LicenseStatus setLicenseKey(const std::string& licenseKey);
        bool isLicenseValid() const;
        LicenseStatus getLicenseStatus() const;
        std::string getLicenseCustomerName() const;
        int getLicenseRemainingDays() const;

        std::string getLastErrorMessage() const;
        float getTargetLoudness() const;
        float getMaxTruePeak() const;
        std::string getFormatDescription() const;
        float getLoudnessTolerance() const;

        size_t getTrackCount() const;
        void clearTracks();
        void setDebugEnabled(bool enabled);
        bool getDebugEnabled() const;
    };
}

The class is non-copyable and movable.

Constructor

PostProductionSDK(float sampleRate = 48000.0f,
                  PostProdFormat format = PostProdFormat::BROADCAST);
Parameter Description
sampleRate Session sample rate in Hz (commonly 48000).
format Target output format; drives loudness/true-peak targets and compliance behavior.

initialize

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

Validates the license and prepares the SDK for processing. Call before adding tracks and process().

Parameter Description
licenseKey TonnSDK license key string.

Returns: true if initialization succeeded; false on failure (see getLastErrorMessage()).

addTrack

bool addTrack(const std::string& filePath, const PostProdTrackSettings& settings);

Adds a track from a file. On failure, returns false and sets a descriptive error via getLastErrorMessage().

addTrackFromBuffer

bool addTrackFromBuffer(const std::vector<std::vector<float>>& audioBuffer,
                        const PostProdTrackSettings& settings,
                        const std::string& name = "");

Adds a track from in-memory audio. audioBuffer is organized as [channel][sample]. name is optional (used for identification in outputs).

process

PostProdResult process(bool generateStems = false, ProgressCallback callback = nullptr);

Runs the full post-production pipeline on all added tracks.

Parameter Description
generateStems If true, fills PostProdResult::stems with per-track processed stereo pairs.
callback Optional progress hook: invoked with progress in [0,1] and a stage description. Return false to cancel; return true to continue.

Returns: PostProdResult with mix audio, measurements, compliance flags, and optional stems.

Format and processing toggles

Method Description
void setFormat(PostProdFormat format) Sets the output/target format (affects targets and mastering behavior).
PostProdFormat getFormat() const Returns the current format.
void setAutoDuckingEnabled(bool enabled) Enables or disables automatic ducking of background material when dialogue is present.
bool getAutoDuckingEnabled() const Current auto-ducking state.
void setDialogueEnhancementEnabled(bool enabled) Enables or disables dialogue enhancement on applicable tracks.
bool getDialogueEnhancementEnabled() const Current dialogue enhancement state.
void setMasteringEnabled(bool enabled) Enables or disables final mastering pass.
bool getMasteringEnabled() const Current mastering state.

License methods

Method Description
LicenseStatus setLicenseKey(const std::string& licenseKey) Sets and validates the license key. Returns a LicenseStatus code (VALID, EXPIRED, INVALID, etc.; see License.h).
bool isLicenseValid() const true if the current license is valid for use.
LicenseStatus getLicenseStatus() const Detailed validation status enum value.
std::string getLicenseCustomerName() const Licensed customer name from the key, if available.
int getLicenseRemainingDays() const Days remaining on the license (semantics depend on license type).

Format information and errors

Method Description
std::string getLastErrorMessage() const Human-readable description of the most recent error.
float getTargetLoudness() const Target integrated loudness for the current PostProdFormat (LUFS).
float getMaxTruePeak() const Maximum allowed true peak for the current format (dBTP).
std::string getFormatDescription() const Short description of the active format/spec.
float getLoudnessTolerance() const Loudness tolerance window used for compliance checks (LU).

Additional public methods

The header also exposes size_t getTrackCount() const, void clearTracks(), void setDebugEnabled(bool enabled), and bool getDebugEnabled() const for session management and diagnostics.

PostProdResult

Structure returned by PostProductionSDK::process(). Defined in PostProductionSDK.h.

struct PostProdResult {
    bool success = false;
    std::string errorMessage;

    std::vector<float> audioLeft;
    std::vector<float> audioRight;

    float trackLengthInSecs = 0.0f;

    float measuredLUFS = -23.0f;
    float dialogueLUFS = -70.0f;
    float dialogueLRA = 0.0f;
    float truePeakDb = -1.0f;
    float dynamicRangeLU = 0.0f;
    float shortTermLoudnessMax = -70.0f;

    bool meetsLoudnessSpec = false;
    bool meetsDialogueSpec = false;
    bool meetsPeakSpec = false;
    bool meetsProgramLRASpec = false;
    bool meetsDialogueLRASpec = false;
    std::string formatDescription;

    std::vector<std::pair<std::vector<float>, std::vector<float>>> stems;
    std::vector<std::string> trackNames;
};

Fields

Field Description
success true if processing completed successfully.
errorMessage Error text when success is false.
audioLeft, audioRight Final stereo mix samples (same length).
trackLengthInSecs Duration of the mixed program in seconds.
measuredLUFS Integrated loudness of the full program (LUFS).
dialogueLUFS Dialogue-only loudness (LUFS), relevant for streaming/film-style specs.
dialogueLRA Dialogue loudness range (LU).
truePeakDb Measured true peak of the mix (dBTP).
dynamicRangeLU Program loudness range / LRA (LU).
shortTermLoudnessMax Maximum short-term loudness observed (LUFS).
meetsLoudnessSpec Program loudness within spec for the target format.
meetsDialogueSpec Dialogue loudness within spec (e.g. streaming/film where applicable).
meetsPeakSpec True peak within spec.
meetsProgramLRASpec Program LRA within allowed range (e.g. platform window).
meetsDialogueLRASpec Dialogue LRA within spec (e.g. maximum LRA).
formatDescription Textual summary of the format/spec used for the run.
stems When stems are requested, each element is {left, right} for one processed track.
trackNames Names aligned with stems (and session track order).

PostProdTrackSettings

Per-track configuration for post-production. Defined in PostProdTrackSettings.h.

class PostProdTrackSettings {
public:
    PostProdTrackSettings();
    PostProdTrackSettings(PostProdGroupType type, DialoguePriority priority,
                          PostProdFormat format);
    // Copy/move assignable

    void setGroupType(PostProdGroupType type);
    PostProdGroupType getGroupType() const;

    void setFormat(PostProdFormat format);
    PostProdFormat getFormat() const;

    void setDialoguePriority(DialoguePriority priority);
    DialoguePriority getDialoguePriority() const;

    void setPreGain(float gain);
    float getPreGain() const;
    void setPostGain(float gain);
    float getPostGain() const;
    void setPreGainDb(float gainDb);
    float getPreGainDb() const;
    void setPostGainDb(float gainDb);
    float getPostGainDb() const;

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

    void setDialogueEnhancementEnabled(bool enabled);
    bool getDialogueEnhancementEnabled() const;
    void setDialogueEnhancementMode(DialogueEnhancementMode mode);
    DialogueEnhancementMode getDialogueEnhancementMode() const;

    void setNarrativeImportance(NarrativeImportance importance);
    NarrativeImportance getNarrativeImportance() const;

    void setDuckingEnabled(bool enabled);
    bool getDuckingEnabled() const;
    void setDuckingPreset(DuckingPreset preset);
    DuckingPreset getDuckingPreset() const;
    void setIsDuckingSidechain(bool isSidechain);
    bool getIsDuckingSidechain() const;
    void setCustomDuckAmount(float amountDb);
    float getCustomDuckAmount() const;
    void setCustomDuckThreshold(float thresholdDb);
    float getCustomDuckThreshold() const;
    void setCustomDuckAttack(float attackMs);
    float getCustomDuckAttack() const;
    void setCustomDuckRelease(float releaseMs);
    float getCustomDuckRelease() const;

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

    void setADRReferencePath(const std::string& path);
    std::string getADRReferencePath() const;
    void setADRMatchEnabled(bool enabled);
    bool getADRMatchEnabled() const;

    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 setEQQFactors(const std::vector<float>& qFactors);
    const std::vector<float>& getEQQFactors() const;

    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;
    bool isCompressorSet() const;

    // Intelligent Mix Balancing
    void setOptimizationEnabled(bool enabled);
    bool getOptimizationEnabled() const;

    bool isDialogueTrack() const;
    bool shouldDuckToDialogue() const;

    std::string toJson() const;
    static PostProdTrackSettings fromJson(const std::string& json);
};

Constructor

PostProdTrackSettings(PostProdGroupType type, DialoguePriority priority, PostProdFormat format);

Constructs settings with group type, dialogue priority, and format context. A default constructor is also available.

Core accessors

Method Description
setGroupType / getGroupType Post-production role of the track (dialogue, music, SFX, etc.).
setFormat / getFormat Format context for this track’s processing targets.
setDialoguePriority / getDialoguePriority How prominently dialogue should sit versus other elements.
setNarrativeImportance / getNarrativeImportance Story-driven preset for non-dialogue tracks (NarrativeImportance::LOW, MEDIUM, HIGH). Controls how prominently the track sits in the mix.

Gain and pan

Method Description
setPreGain / getPreGain Linear pre-processing gain multiplier.
setPostGain / getPostGain Linear post-processing gain multiplier.
setPreGainDb / getPreGainDb Pre-gain in dB.
setPostGainDb / getPostGainDb Post-gain in dB.
setPanAngle / getPanAngle Pan angle in degrees (-90 to +90; 0 is center).

Dialogue enhancement

Method Description
setDialogueEnhancementEnabled / getDialogueEnhancementEnabled Turn per-track dialogue enhancement on or off.
setDialogueEnhancementMode / getDialogueEnhancementMode Selects preserve vs enhance vs ad-style enhancement.

Ducking

Method Description
setDuckingEnabled / getDuckingEnabled Whether this track participates in ducking behavior.
setDuckingPreset / getDuckingPreset Preset curve/depth (or CUSTOM).
setIsDuckingSidechain / getIsDuckingSidechain Marks the track as the sidechain source (typically dialogue) that triggers ducking on others.
setCustomDuckAmount / getCustomDuckAmount Duck depth in dB when preset is CUSTOM.
setCustomDuckThreshold / getCustomDuckThreshold Sidechain threshold in dB (custom mode).
setCustomDuckAttack / getCustomDuckAttack Attack time in ms (custom mode).
setCustomDuckRelease / getCustomDuckRelease Release time in ms (custom mode).

Reverb, EQ, compressor

Method Description
setReverbSetting / getReverbSetting Room/reverb character (PostProdReverbSetting).
setFilterFreqSettings / getFilterFreqSettings EQ band center frequencies (Hz).
setEQGains / getEQGains Per-band gain in dB.
setEQQFactors / getEQQFactors Per-band Q values.
setCompressorThreshold / getCompressorThreshold Compressor threshold.
setCompressorRatio / getCompressorRatio Compression ratio.
setCompressorAttack / getCompressorAttack Attack time in ms.
setCompressorRelease / getCompressorRelease Release time in ms.

ADR matching

Method Description
setADRReferencePath / getADRReferencePath Path to location sound reference audio. Setting a non-empty path auto-enables ADR matching.
setADRMatchEnabled / getADRMatchEnabled Explicitly enable or disable ADR matching (spectral, reverb, and dynamics matching to the reference).

Intelligent Mix Balancing

Method Description
setOptimizationEnabled / getOptimizationEnabled Enable per-track auto-balance against dialogue clarity for the chosen format. When enabled, the SDK automatically adjusts levels to maintain dialogue intelligibility.

Utilities

Method Description
isDialogueTrack() true if the group type is a dialogue-related role.
shouldDuckToDialogue() true if this track is a candidate to be ducked under dialogue.
isCompressorSet() true if any compressor parameter was explicitly configured.
toJson() Serializes all settings to a JSON string.
fromJson() Parses settings from JSON; static factory.

The header also provides conversion helpers: postProdGroupTypeToString, stringToPostProdGroupType, postProdFormatToMasteringFormat, dialogueEnhancementModeToString, and duckingPresetToString.

Post-Production Enums

Defined in PostProdTrackSettings.h.

PostProdGroupType

Enumerator Value Description
DIALOGUE_MAIN 1 Primary dialogue (main character, narrator).
DIALOGUE_SECONDARY 2 Secondary / background dialogue.
MUSIC 3 Background music.
SFX 4 Sound effects.
AMBIENCE 5 Ambience / atmosphere.
FOLEY 6 Foley.
ADR 7 Automated dialogue replacement.
VOICEOVER_LP 8 Voice-over optimized for low-pitched voices.
OTHER 9 Miscellaneous.
VOICEOVER_HP 10 Voice-over optimized for high-pitched voices.

PostProdFormat

Enumerator Value Description
FILM 0 Cinema-style targets (e.g. -24 LUFS).
TV 1 Television / EBU R128-style (-23 LUFS).
STREAMING 2 Streaming platform delivery (-27 LUFS).
YOUTUBE 3 YouTube (-14 LUFS).
BROADCAST 4 Strict broadcast (-23 LUFS, -1 dBTP).
ADMIX 5 Commercial / ad mixing (-23 LUFS, auto-ducking).
PODCAST 6 Podcast (-16 LUFS).
SOCIAL_MEDIA 7 Instagram Reels / TikTok / Shorts (-14 LUFS, mono-safe).

DialogueEnhancementMode

Enumerator Value Description
PRESERVE 1 Minimal processing; natural speech.
ENHANCE 2 Standard clarity enhancement.
AD_ENHANCED 3 Stronger enhancement for commercial clarity.
SOCIAL_MEDIA_VO 4 Mobile-optimised voice-over for vertical short-form delivery.

DuckingPreset

Enumerator Value Description
NONE 0 No ducking.
LIGHT 1 Subtle reduction.
MEDIUM 2 Balanced reduction.
HEAVY 3 Strong reduction.
AD_MIX 4 Commercial-style fast, deep ducking.
CUSTOM 5 Use custom ducking parameters on the track settings.

DialoguePriority

Enumerator Value Description
LOW 1 Background dialogue.
NORMAL 2 Standard priority.
HIGH 3 Prominent dialogue.
CRITICAL 4 Must remain fully intelligible on top of the mix.

PostProdReverbSetting

Enumerator Value Description
NONE 0 No added reverb.
DRY 1 Minimal room.
SMALL_ROOM 2 Small room ambience.
MEDIUM_ROOM 3 Medium room.
LARGE_ROOM 4 Large room or hall.
MATCH 5 Match to reference material.

NarrativeImportance

Story-driven preset for non-dialogue tracks. Controls how prominently the track sits in the mix relative to dialogue.

Enumerator Value Description
LOW 0 Subtle background element (e.g. distant traffic, soft underscore).
MEDIUM 1 Noticeable but supporting element (e.g. scene music, key SFX).
HIGH 2 Featured element prominent in the story (e.g. scored cue, dramatic SFX).