Tracktion Engine

Tracktion Engine is the audio engine powering MAGDA. This skill covers core patterns for working with the API.

Core Object Hierarchy

Engine (singleton, app lifecycle)
└── Edit (project/session)
    ├── TrackList
    │   ├── AudioTrack (contains clips + plugins)
    │   ├── FolderTrack (groups other tracks)
    │   ├── MasterTrack
    │   └── TempoTrack, ChordTrack, MarkerTrack...
    ├── TransportControl (playback/recording)
    ├── PluginList (master plugins)
    └── UndoManager

Quick Reference

Creating an Edit

#include <tracktion_engine/tracktion_engine.h>
namespace te = tracktion;

// Initialize engine (once, at app startup)
te::Engine engine("MAGDA");

// Create a new edit
auto edit = te::Edit::createSingleTrackEdit(engine);

// Or with options
te::Edit::Options options;
options.editState = valueTree;  // Load from saved state
options.engine = &engine;
auto edit = te::Edit::createEdit(options);

Working with Tracks

// Get all tracks
for (auto track : edit->getTrackList()) {
    DBG(track->getName());
}

// Add a new audio track
auto track = edit->insertNewAudioTrack(
    te::TrackInsertPoint::getEndOfTracks(*edit),
    nullptr,  // SelectionManager (optional)
    true      // addDefaultPlugins (volume, pan, level meter)
);

// Find tracks by type
for (auto audioTrack : te::getAudioTracks(*edit)) {
    // audioTrack is AudioTrack*
}

// Track properties
track->setName("Lead Vocal");
track->setMuted(true);
track->setSolo(true);

Working with Clips

// Insert MIDI clip
auto midiClip = track->insertMIDIClip(
    te::TimeRange { 0_tp, 8_tp },  // start, end (TimePosition)
    nullptr  // SelectionManager
);

// Insert audio clip
auto audioClip = track->insertWaveClip(
    "My Audio",
    juce::File("/path/to/audio.wav"),
    te::ClipPosition { { 0_tp, 8_tp }, {} },
    te::DeleteExistingClips::no
);

// Iterate clips on a track
for (auto clip : track->getClips()) {
    auto pos = clip->getPosition();
    DBG("Clip: " + clip->getName() + " at " + juce::String(pos.getStart().inSeconds()));
}

// Clip manipulation
clip->setPosition(te::ClipPosition { { 2_tp, 10_tp }, {} });
clip->setName("Verse 1");
clip->setMuted(true);

MIDI Editing

if (auto midiClip = dynamic_cast<te::MidiClip*>(clip)) {
    auto& sequence = midiClip->getSequence();

    // Add notes
    sequence.addNote(
        60,     // pitch (middle C)
        0.0,    // start beat
        1.0,    // length in beats
        100,    // velocity
        0,      // colour index
        nullptr // undo manager
    );

    // Iterate notes
    for (auto note : sequence.getNotes()) {
        DBG("Note: " + juce::String(note->getNoteNumber()));
    }
}

Transport Control

auto& transport = edit->getTransport();

// Playback
transport.play(false);
transport.stop(false, false);
transport.playFromStart(false);

// Position
transport.setPosition(te::TimePosition::fromSeconds(10.0));
auto pos = transport.getPosition();

// Recording
transport.record(false);
transport.stopRecording(false);

// Loop
transport.setLoopRange(te::TimeRange { 0_tp, 16_tp });

// Check state
if (transport.isPlaying()) { /* ... */ }
if (transport.isRecording()) { /* ... */ }

Plugin Management

// Get track's plugin list
auto& plugins = track->getPlugins();

// Built-in plugins
if (auto vol = track->getVolumePlugin()) {
    vol->setVolumeDb(-6.0f);
    vol->setPan(-0.5f);  // -1 to 1
}

// Find plugins by type
auto eqs = plugins.getPluginsOfType<te::EqualiserPlugin>();

// Iterate all plugins
for (auto plugin : plugins) {
    if (plugin->isEnabled()) {
        DBG("Plugin: " + plugin->getName());
    }
}

// Plugin parameters
for (auto param : plugin->getAutomatableParameters()) {
    DBG("Param: " + param->getParameterName());
}

Important Patterns

RAII Helpers

// Prevent playback graph rebuilds during batch edits
{
    te::TransportControl::ReallocationInhibitor inhibitor(transport);
    // ... make many changes ...
}  // Graph rebuilds once here

// Inhibit undo grouping
{
    te::Edit::UndoTransactionInhibitor inhibitor(*edit);
    // ... operations won't be grouped ...
}

// Resume playback after scope
{
    te::TransportControl::ScopedPlaybackRestarter restarter(transport);
    transport.stop(false, false);
    // ... do work ...
}  // Playback resumes here

Time Types

// TimePosition - absolute time
te::TimePosition pos = te::TimePosition::fromSeconds(5.0);
te::TimePosition pos2 = 5_tp;  // User-defined literal

// TimeDuration - relative duration
te::TimeDuration dur = te::TimeDuration::fromSeconds(2.0);

// BeatPosition / BeatDuration - musical time
te::BeatPosition beat = te::BeatPosition::fromBeats(4.0);

// TimeRange - start + end
te::TimeRange range { startPos, endPos };

Edit State & Undo

// Undo/Redo
edit->undo();
edit->redo();

// Check for changes
if (edit->hasChangedSinceSaved()) {
    // Prompt to save
}

// Mark as saved
edit->resetChangedStatus();

// Flush state to ValueTree (for saving)
edit->flushState();
juce::ValueTree state = edit->state;

Listeners

// Transport listener
struct MyListener : te::TransportControl::Listener {
    void playbackContextChanged() override { /* ... */ }
    void recordingStarted(te::SyncPoint, std::optional<te::TimeRange>) override { /* ... */ }
    void recordingFinished(te::InputDeviceInstance&, te::EditItemID, te::Clip::Array) override { /* ... */ }
};

transport.addListener(&myListener);

Common Pitfalls

1. Always initialize Engine first - Before creating any Edit
2. Don't block audio thread - Use AsyncUpdater for UI updates from audio callbacks
3. Use inhibitors for batch operations - Prevents expensive graph rebuilds
4. Check for nullptr - getVolumePlugin() etc. can return nullptr
5. TimePosition vs BeatPosition - They're different types, convert explicitly

File Locations

Key headers in third_party/tracktion_engine/modules/tracktion_engine/:

• model/edit/tracktion_Edit.h - Edit class
• model/tracks/tracktion_Track.h - Track base class
• model/clips/tracktion_Clip.h - Clip base class
• playback/tracktion_TransportControl.h - Transport
• plugins/tracktion_Plugin.h - Plugin base class