PostProductionSDK - Examples¶

The SDK ships with two post-production example applications and three JSON configuration files. This guide walks through each example, explains the JSON config format, and shows how to build and run them. For feature details and parameter reference, see Post-Production Features. For initial setup, see Getting Started.

Building the Examples¶

All examples require libsndfile for WAV I/O and nlohmann/json (fetched automatically by CMake):

cd examples
mkdir build && cd build
cmake ..
make

This produces two post-production binaries: post_production_example and ad_mixing_example.

Film/TV Post-Production Example¶

Source: post_production_example.cpp

This example demonstrates a full film/TV post-production workflow: loading tracks from a JSON config, applying dialogue enhancement and sidechain ducking, mastering to a delivery format, and saving the final mix and processed stems.

Usage¶

export TONNSDK_LICENSE_KEY="your_license_key_here"

./post_production_example <config.json> [output.wav] [--format FILM|TV|STREAMING|YOUTUBE|BROADCAST|ADMIX|PODCAST]

The --format flag overrides the format specified in the config file.

What It Does¶

1. Reads the JSON config to determine track paths, types, and processing options
2. Initializes PostProductionSDK with the specified delivery format at 48 kHz
3. For each track in the config: - Maps the track type (via filmTrackType or instrumentGroup) to a PostProdGroupType - Applies dialogue enhancement to dialogue tracks by default - Marks dialogue tracks as sidechain sources - Enables ducking on non-dialogue tracks with MEDIUM preset by default - Applies any explicit overrides from the config (pan, reverb, ducking preset)
4. Processes the mix with stem generation enabled
5. Prints loudness measurements and compliance results
6. Saves the final mix as a WAV file
7. Saves each processed stem as an individual WAV file in an output/ directory

Example Run¶

./post_production_example ../configs/film_scene_config.json output/film_mix.wav --format FILM

Expected output:

PostProductionSDK initialized (48000 Hz, FILM format)
Loaded 5 tracks
Processing...
Mix complete (12.4s)

Loudness: -24.1 LUFS
Dialogue: -23.8 LUFS
True peak: -2.3 dBTP
Dynamic range: 14.2 LU

Compliance:
  Loudness spec: PASS
  Dialogue spec: PASS
  Peak spec:     PASS
  Program LRA:   PASS
  Dialogue LRA:  PASS

Saved: output/film_mix.wav
Saved: output/stem_dialogue.wav
Saved: output/stem_music.wav
Saved: output/stem_music2.wav
Saved: output/stem_birds.wav
Saved: output/stem_footsteps.wav

Ad/Commercial Mixing Example¶

Source: ad_mixing_example.cpp

This example targets advertising and commercial workflows where voiceover must be clearly intelligible over music and sound effects. It uses AD_ENHANCED dialogue enhancement mode for maximum clarity and AD_MIX ducking for fast, aggressive background attenuation.

Usage¶

export TONNSDK_LICENSE_KEY="your_license_key_here"

./ad_mixing_example <config.json> <output.wav>

Key Differences from the Film Example¶

Example Run¶

./ad_mixing_example ../configs/ad_commercial_config.json output/ad_mix.wav

JSON Configuration Format¶

Both examples read a JSON config with the following structure:

{
  "multitrackData": {
    "trackData": [
      {
        "trackURL": "path/to/audio.wav",
        "filmTrackType": "DIALOGUE",
        "presenceSetting": "LEAD",
        "panPreference": "CENTRE",
        "reverbPreference": "NONE",
        "dialogueEnhancementEnabled": true,
        "isDuckingSidechain": true
      },
      {
        "trackURL": "path/to/music.wav",
        "instrumentGroup": "MUSIC",
        "presenceSetting": "BACKGROUND",
        "duckingEnabled": true,
        "duckingPreset": "MEDIUM"
      }
    ],
    "format": "FILM"
  }
}

Track Fields¶

Session Fields¶

Available Configurations¶

The SDK ships with three example configs in examples/configs/:

film_scene_config.json¶

A film scene with five tracks: dialogue, two music tracks, birds (ambience), and footsteps (foley). Dialogue has enhancement enabled. All non-dialogue tracks duck with LIGHT or MEDIUM presets. Format: FILM.

./post_production_example ../configs/film_scene_config.json output/film_mix.wav --format FILM

ad_commercial_config.json¶

A commercial with four tracks: voiceover (sidechain source with enhancement), music, SFX, and ambience. Music and ambience use AD_MIX ducking for aggressive attenuation. SFX uses MEDIUM ducking. Format: ADMIX. Includes a mastering block with loudness normalization, compression, and EQ enabled.

./ad_mixing_example ../configs/ad_commercial_config.json output/ad_mix.wav

simple_postprod_config.json¶

A minimal three-track setup: dialogue (sidechain source with enhancement), music (medium ducking), and SFX (light ducking). Format: STREAMING. Good as a starting point for custom configs.

./post_production_example ../configs/simple_postprod_config.json output/streaming_mix.wav --format STREAMING

Creating Your Own Configuration¶

Start with simple_postprod_config.json and modify it:

1. Update trackURL paths to point to your audio files (relative to the working directory)
2. Set the correct instrumentGroup for each track (see the track types table)
3. Choose a delivery format that matches your target platform
4. Enable dialogueEnhancementEnabled on speech tracks
5. Set isDuckingSidechain on the primary dialogue track
6. Enable duckingEnabled on background tracks and choose a duckingPreset

For programmatic config generation, use the JSON serialization API:

tonn::PostProdTrackSettings settings(
    tonn::PostProdGroupType::DIALOGUE_MAIN,
    tonn::DialoguePriority::HIGH,
    tonn::PostProdFormat::STREAMING);
settings.setDialogueEnhancementEnabled(true);
settings.setIsDuckingSidechain(true);

std::string json = settings.toJson();
// Write to file or send over network

See JSON Serialization for details.