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
AudioReprocessor
MixTrackSettings
MixResult Structure
ReprocessResult Structure
Enums
MixingModel
GroupType
PresenceSetting
MusicalStyle
Error Handling

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
        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¶

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

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¶

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:

Return Values: Many methods return boolean values to indicate success/failure
Error Messages: The getLastErrorMessage() method retrieves detailed error information
Exceptions: In critical failure cases, the SDK may throw exceptions
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 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;

    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.

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

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

DialogueEnhancementMode¶

Enumerator	Value	Description
`PRESERVE`	1	Minimal processing; natural speech.
`ENHANCE`	2	Standard clarity enhancement.
`AD_ENHANCED`	3	Stronger enhancement for commercial clarity.

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.