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

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

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

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

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

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()) { /* ... */ }

// 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());
}

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

// 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 };

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

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