Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
//
// The audio-engine port: the instance-level surface of the real-time engine that
// the Application and Presentation layers program against. Infrastructure's
// NotaEngine implements it over the native handle. Handle-free utilities (version,
// self-tests, plugin catalog, device enumeration) are not part of this port — they
// live on separate ports / static helpers.
namespace Nota.Application;
/// <summary>Command-and-query surface of the real-time audio engine. All calls are
/// UI-thread safe: mutations enqueue commands, reads are lock-free snapshots.</summary>
public interface IAudioEngine : IDisposable
{
// --- Device / diagnostics ---------------------------------------------
double SampleRate { get; }
/// <summary>True while the output device is open and the audio thread runs.</summary>
bool IsRunning { get; }
void Start();
void Stop();
void SetTestTone(bool enabled);
void SetFrequency(float hz);
// --- Transport ---------------------------------------------------------
void Play();
/// <summary>Play, preceded by the count-in when one is set and the transport is stopped.
/// For user-initiated starts; exports / freezes use <see cref="Play"/>.</summary>
void PlayWithCountIn();
/// <summary>Count-in length in bars (0 = off). Also applies to Record started from stop.</summary>
void SetCountIn(int bars);
/// <summary>Beats of count-in still to click (0 = not counting in).</summary>
double CountInBeats { get; }
/// <summary>Loop record mode for MIDI recorded into the Arrangement with the loop on:
/// false = overdub (every pass adds to the take), true = replace (the first new note of a
/// pass removes what earlier passes of the take recorded). Applies from the next pass.</summary>
void SetLoopRecordMode(bool replace);
bool LoopRecordReplace { get; }
void StopTransport();
void SetBpm(double bpm);
double Bpm { get; }
void SetTimeSignature(int num, int denom);
void SetLoop(bool enabled, double startBeat, double endBeat);
void SetMetronome(bool enabled);
void Seek(double beat);
double PositionBeats { get; }
/// <summary>Display-only rendered-block snapshot. False before rendering or during publication.</summary>
bool TryGetTransportSnapshot(out NotaTransportSnapshot snapshot);
bool IsPlaying { get; }
/// <summary>Loop region mirror (for UI display + toggling).</summary>
bool LoopEnabled { get; }
double LoopStart { get; }
double LoopEnd { get; }
// --- Mixer -------------------------------------------------------------
void SetMasterVolume(float volume);
// --- Tracks & clips ----------------------------------------------------
int AddAudioTrack();
int AddAudioClip(int trackId, string path, double startBeat);
/// <summary>Starts a background decode of a WAV/FLAC/MP3 (null if it can't be opened).
/// Safe to drive off the UI thread — see <see cref="IAudioImport"/>.</summary>
IAudioImport? OpenAudioImport(string path);
/// <summary>Places a finished import on a track (no disk I/O). Returns the clip index or -1.</summary>
int AddImportedAudioClip(int trackId, IAudioImport import, double startBeat);
void SetTrackVolume(int trackId, float volume);
void SetTrackPan(int trackId, float pan);
void SetTrackMute(int trackId, bool mute);
void SetTrackSolo(int trackId, bool solo);
/// <summary>Cue (specs/089): the track's signal after its devices, before its fader, pan,
/// mute and solo, also goes to the private Cue mix. Any number of tracks.</summary>
void SetTrackCue(int trackId, bool on);
bool GetTrackCue(int trackId);
/// <summary>The Cue mix's level, linear 0–2 (+6 dB). Never changes Main.</summary>
float CueVolume { get; set; }
/// <summary>Where the metronome and count-in clicks go, and their level (linear 0–2).</summary>
ClickDestination ClickDestination { get; set; }
void SetClickVolume(float gain);
int TrackCount { get; }
int DuplicateTrack(int trackId); // deep copy after the source; new id or -1
int AddTrackLike(int trackId); // empty track with the source's instrument, devices and mix, before the returns; new id or -1
bool RemoveTrack(int trackId);
void MoveTrack(int trackId, int toIndex); // reorder a non-return track within the regular list
int AddGroupTrack(); // empty top-level group (submix) track
int CreateGroup(int[] trackIds); // group tracks under a new group; returns group id or -1
void Ungroup(int groupId); // dissolve; children reparent up one level
void SetTrackGroup(int trackId, int groupId); // move a track into groupId (-1 = top-level)
int[] DuplicateTracks(int[] trackIds); // set (+ group children) after its last member; new ids
bool RemoveTracks(int[] trackIds); // set (+ group children), one undo step
// --- Send / return buses (M6-1) ----------------------------------------
int AddReturnTrack();
void SetTrackSend(int trackId, int bus, float level);
float GetTrackSend(int trackId, int bus);
int ReturnTrackCount { get; }
int TrackReturnIndex(int trackId);
// --- Session view (M5) -------------------------------------------------
int SceneCount { get; }
void AddSessionMidiClip(int trackId, int scene, double lengthBeats = 4.0);
/// <summary>Empties a session slot (stops it if playing). False if already empty.</summary>
bool ClearSessionSlot(int trackId, int scene);
/// <summary>Appends a scene row; returns its index.</summary>
int AddScene();
/// <summary>Removes a scene row (always keeps at least one). False if it couldn't.</summary>
bool RemoveScene(int scene);
/// <summary>0 empty, 1 filled, 2 queued, 3 playing, 4 recording, 5 record pending (the take
/// starts capturing on the next launch quantum, specs/078).</summary>
int SessionSlotState(int trackId, int scene);
double SessionSlotLength(int trackId, int scene);
void SetSessionSlotLength(int trackId, int scene, double lengthBeats);
/// <summary>Audio-slot playback gain (linear; 1.0 when not an audio take).</summary>
float SessionSlotGain(int trackId, int scene);
void SetSessionSlotGain(int trackId, int scene, float gain);
void SetLaunchQuant(double beats);
void LaunchSlot(int trackId, int scene);
void StopSlot(int trackId);
void LaunchScene(int scene);
void StopScene(int scene);
void StopAllSession();
/// <summary>Stop every session clip and hand all tracks back to the Arrangement timeline.</summary>
void BackToArrangement();
/// <summary>True when the Arrangement is playing; false in a session-only jam.</summary>
bool ArrangementActive { get; }
void RecordSessionSlot(int trackId, int scene);
void StopSessionRecord();
/// <summary>Stop recording one slot: while other slots of the Session audio take still record,
/// only this track's lands and loops back (specs/086); otherwise as <see cref="StopSessionRecord"/>.</summary>
void StopSessionRecordSlot(int trackId);
int SessionSlotToArrangement(int trackId, int scene, double startBeat);
void ArrangementClipToSession(int trackId, int clipIndex, int scene);
/// <summary>Copies an arrangement audio clip into a session slot (loops the whole sample).</summary>
bool ArrangementAudioClipToSession(int trackId, int clipIndex, int scene);
bool AudioRecordSelfTest();
bool SessionAudioRecordSelfTest();
void SetSessionNotes(int trackId, int scene, NotaNote[] notes);
NotaNote[] GetSessionNotes(int trackId, int scene);
// --- Session P0: clip + scene properties, scene/slot editing, follow ------
/// <summary>Properties of a filled slot; false when the slot is empty.</summary>
bool TryGetSessionClipProps(int trackId, int scene, out NotaSessionClipProps props);
bool SetSessionClipProps(int trackId, int scene, NotaSessionClipProps props);
/// <summary>Clip name (empty = unnamed).</summary>
string GetSessionClipName(int trackId, int scene);
void SetSessionClipName(int trackId, int scene, string name);
/// <summary>An empty slot's stop button: true (default) = launching its scene stops the track.</summary>
bool GetSessionSlotStopButton(int trackId, int scene);
void SetSessionSlotStopButton(int trackId, int scene, bool on);
/// <summary>Copies a slot (clip + properties) onto a slot of a same-kind track.</summary>
bool CopySessionSlot(int srcTrackId, int srcScene, int dstTrackId, int dstScene);
bool TryGetSceneProps(int scene, out NotaSceneProps props);
void SetSceneProps(int scene, NotaSceneProps props);
string GetSceneName(int scene);
void SetSceneName(int scene, string name);
/// <summary>Inserts an empty row at <paramref name="at"/>; returns it or -1.</summary>
int InsertScene(int at);
/// <summary>Copies a row below itself; returns the new row or -1.</summary>
int DuplicateScene(int scene);
/// <summary>Inserts a row at <paramref name="at"/> holding the clips playing now.</summary>
int CaptureScene(int at);
/// <summary>Moves a scene row (slots + properties) to another index; players follow.</summary>
bool MoveScene(int from, int to);
/// <summary>True once after a launched scene applied its tempo / signature (0 = unchanged),
/// so the transport can show the new values.</summary>
bool TakeSceneTempoChange(out double bpm, out int num, out int den);
/// <summary>Launch with a velocity 0..1, scaled by the clip's velocity amount.</summary>
void LaunchSlotVelocity(int trackId, int scene, float velocity);
/// <summary>The launch button was released: stops a Gate / Repeat clip.</summary>
void ReleaseSlot(int trackId, int scene);
/// <summary>Hands one track back to the Arrangement (stops its session clip now).</summary>
void TrackBackToArrangement(int trackId);
/// <summary>Playing slot of a track, or -1.</summary>
int SessionPlayingSlot(int trackId);
/// <summary>Loop-local position of the playing slot, in beats.</summary>
double SessionSlotPosition(int trackId);
double LaunchQuant { get; }
/// <summary>Global follow-action switch.</summary>
bool SessionFollow { get; set; }
/// <summary>Fixed session record length in beats (0 = off).</summary>
double SessionRecordLength { get; set; }
/// <summary>Session Rec: records into the first armed track with an empty slot in the row; returns that track id or 0.</summary>
int RecordSessionScene(int scene);
/// <summary>The in-progress session take, if any.</summary>
bool TryGetSessionRecordTarget(out int trackId, out int scene, out double elapsedBeats);
/// <summary>Min/max peak pairs over an audio slot's take; returns the bucket count.</summary>
int GetSessionSlotPeaks(int trackId, int scene, float[] outMinMax, int maxPoints);
// --- Arrangement geometry (M4) -----------------------------------------
bool TryGetTrackInfo(int index, out NotaTrackInfo info);
bool TryGetClipInfo(int trackId, int clipIndex, out NotaClipInfo info);
// --- Clip editing (M4-2) -----------------------------------------------
void MoveClip(int trackId, int clipIndex, double newStartBeat);
/// <summary>Moves a clip to another same-type track — instrument→instrument or
/// audio→audio (atomic). Same-track == MoveClip.</summary>
void MoveClipToTrack(int srcTrackId, int clipIndex, int destTrackId, double newStartBeat);
/// <summary>Moves a group of clips at once (multi-selection drag): they carve only the
/// clips that stay put, never each other; same-track clips keep their index. One undo
/// step; <see cref="LastPlacedClips"/> reports each new position in request order.</summary>
bool MoveClipBlock((int trackId, int clipIndex, int destTrackId, double newStartBeat)[] moves);
void TrimClip(int trackId, int clipIndex, double newStartBeat, double newLengthBeats);
/// <summary>Grid resize for an audio clip (grid-relative): warped clips (or unwarped
/// clips dragged past their source length) stretch; unwarped clips within source
/// bounds trim. Auto-enables warp when a stretch is needed.</summary>
void ResizeAudioClip(int trackId, int clipIndex, double newStartBeat, double newLengthBeats);
/// <summary>Sets an unwarped audio clip's source region directly (clip Start/End):
/// which part of the sample plays. Timeline position is unchanged. No-op on warped clips.</summary>
void SetClipSourceRegion(int trackId, int clipIndex, double offsetFrames, long lengthFrames);
/// <summary>Trims a warped clip's played window (beats over the warp material). No-op on unwarped clips.</summary>
void SetClipWarpTrim(int trackId, int clipIndex, double playStart, double playEnd);
/// <summary>Sets an audio clip's linear playback gain (runtime).</summary>
void SetClipGain(int trackId, int clipIndex, float gain);
/// <summary>An audio clip's ADSR amplitude shape (<see cref="ClipAdsr.Identity"/> for a
/// MIDI clip or a bad index).</summary>
ClipAdsr GetClipAdsr(int trackId, int clipIndex);
/// <summary>Sets an audio clip's ADSR amplitude shape (one undo step).</summary>
void SetClipAdsr(int trackId, int clipIndex, ClipAdsr adsr);
/// <summary>Clip deactivate (key 0): an inactive clip stays on the timeline but plays
/// nothing (audio or MIDI). Works on audio and instrument tracks.</summary>
void SetClipActive(int trackId, int clipIndex, bool active);
/// <summary>Sets an audio clip's varispeed transpose in semitones (runtime).</summary>
void SetClipPitch(int trackId, int clipIndex, float semitones);
/// <summary>Reverses an audio clip (non-destructive): the played region is read
/// back-to-front. Composes with gain/pitch/warp; trims and splits mirror.</summary>
void SetClipReverse(int trackId, int clipIndex, bool reversed);
/// <summary>Enables/disables warp + mode for an audio clip (rebuilds the stretch cache).</summary>
void SetClipWarp(int trackId, int clipIndex, bool enabled, int mode);
/// <summary>Sets a warped clip's target musical length in beats.</summary>
void SetClipWarpLength(int trackId, int clipIndex, double beats);
/// <summary>Detects the clip's source tempo, enables warp, and snaps its length to
/// the beat grid so it conforms to the project BPM. Returns the detected BPM (0 = failed).</summary>
double AutoWarpClip(int trackId, int clipIndex);
/// <summary><see cref="AutoWarpClip"/> with an already-detected tempo (skips detection).</summary>
double AutoWarpClipAtBpm(int trackId, int clipIndex, double bpm);
/// <summary>Beats-mode warp: detects transients and pins a grid-snapped marker at each
/// hit so percussion locks tightly to the grid. Returns the detected BPM (0 = failed).</summary>
double BeatWarpClip(int trackId, int clipIndex);
/// <summary>Project load: when set, warp edits skip the heavy stretch so applying a
/// project stays fast; caches are then filled incrementally via <see cref="WarpBuildStep"/>.</summary>
void SetDeferWarpBuild(bool defer);
/// <summary>Builds ~<paramref name="maxFrames"/> device frames of warped audio into the
/// deferred caches; returns frames of warped audio still needing a cache (0 = done).</summary>
long WarpBuildStep(int maxFrames);
/// <summary>Frames of warped audio still needing a cache (progress denominator).</summary>
long WarpBuildRemaining { get; }
/// <summary>Background warp build: installs a cache a worker finished (if its clip is
/// unchanged), then starts the next clip needing one on a worker. Never blocks — poll it
/// from a timer until it returns 0. Clips keep playing their previous cache meanwhile.</summary>
long WarpBuildPoll();
/// <summary>Replaces a warped clip's source↔beat markers (≥2).</summary>
void SetClipWarpMarkers(int trackId, int clipIndex, double[] srcFrames, double[] beats);
/// <summary>Reads a warped clip's markers into the buffers; returns the total count.</summary>
int GetClipWarpMarkers(int trackId, int clipIndex, double[] outSrc, double[] outBeat);
int SplitClip(int trackId, int clipIndex, double atBeat);
int DuplicateClip(int trackId, int clipIndex);
void DeleteClip(int trackId, int clipIndex);
/// <summary>Deletes a clip, returning false (instead of throwing) when the engine rejects
/// the track/clip index — e.g. a stale multi-selection entry. Use for bulk deletes where a
/// single invalid index must not abort the whole operation.</summary>
bool TryDeleteClip(int trackId, int clipIndex);
/// <summary>Deletes clip content in the time range [start,end) across the given tracks,
/// splitting clips at the range edges (one undo step, no ripple). False = nothing changed.</summary>
bool DeleteClipsInRange(int[] trackIds, double start, double end);
/// <summary>Duplicates the [start,end) slice of the given tracks to [end, end+len), splitting
/// at the edges. Returns the range length (>0), or 0 when nothing was duplicated.</summary>
double DuplicateRange(int[] trackIds, double start, double end);
/// <summary>Opens a <paramref name="len"/>-beat gap at <paramref name="at"/> across the whole
/// arrangement (every track and the master): clips crossing it are cut, clips and automation
/// at or after it move right. <paramref name="duplicate"/> false = Insert Silence; true =
/// Duplicate Time, which fills the gap with a copy of [at-len, at). One undo step.
/// False = nothing moved.</summary>
bool InsertTime(double at, double len, bool duplicate);
/// <summary>Splits the given tracks' clips at both [start] and [end] (keeping all content) so
/// the covered slice becomes its own clip(s). One undo step, no ripple. False = nothing changed.</summary>
bool SplitClipsInRange(int[] trackIds, double start, double end);
/// <summary>When true (the default), splitting an audio clip writes a short fade at the cut
/// — release on the left piece, attack on the right — so the corner handles show it and
/// the user can drag them. MIDI splits are unchanged. An app preference, not project data.</summary>
bool SplitFades { get; set; }
/// <summary>Raises that short fade on both sides of every join where two audio clips abut
/// and at least one of the listed clips is in the pair. Does not shorten a longer fade.
/// One undo step. False when nothing changed. Runs even when <see cref="SplitFades"/> is off.</summary>
bool FadeSplits(int[] trackIds, int[] clipIndices);
/// <summary>Consolidate: replaces each given track's content in [start,end) with ONE clip
/// spanning the range — MIDI notes merged, audio clips rendered (gain/pitch/warp/fades/clip
/// envelopes baked) into a new sample. Parts of clips outside the range survive. One undo
/// step; <see cref="LastPlacedClips"/> then reports the new clips. False = nothing changed.</summary>
bool ConsolidateRange(int[] trackIds, double start, double end);
/// <summary>Locks track envelopes so clip moves stop carrying automation (req 8.3.3).</summary>
void SetAutomationLock(bool locked);
bool AutomationLock { get; }
/// <summary>True when the last cross-track move left device/plugin automation on the source
/// track (only Volume/Pan follow across tracks) — for an explicit UX hint (req 8.3.4).</summary>
bool LastMoveKeptDeviceAutomation();
/// <summary>Copies a clip to the engine clip clipboard.</summary>
bool CopyClip(int trackId, int clipIndex);
/// <summary>Cuts a clip: copies it (with its automation) to the clipboard, then removes
/// the clip and the track automation in its span. Delete, by contrast, leaves automation.</summary>
bool CutClip(int trackId, int clipIndex);
/// <summary>Pastes the clipboard clip onto a type-matching track at/after the beat (no overlap). Returns new index or -1.</summary>
int PasteClip(int destTrackId, double atBeat);
/// <summary>Clipboard clip kind: -1 empty, 0 audio, 1 midi.</summary>
int ClipboardClipKind();
/// <summary>Copies a set of clips to the block clipboard (with their automation). False if none valid.</summary>
bool CopyClipBlock((int trackId, int clipIndex)[] sel);
/// <summary>Cuts a set of clips: copies the block to the clipboard, then removes the clips + their automation.</summary>
bool CutClipBlock((int trackId, int clipIndex)[] sel);
/// <summary>Pastes the block clipboard at the beat (preserving geometry). destTrackId -1 = source
/// tracks; otherwise the block is remapped by the track-index delta to that track. Returns clips pasted.</summary>
int PasteClipBlock(double atBeat, int destTrackId = -1);
/// <summary>Duplicates a set of clips as one block placed right after itself. Returns the block length (>0), or -1.</summary>
double DuplicateClipBlock((int trackId, int clipIndex)[] sel);
/// <summary>Number of clips in the block clipboard (0 = empty).</summary>
int ClipboardBlockCount();
/// <summary>Copies the [start,end) slice of the given tracks' clips (with automation) to the
/// block clipboard, positioned relative to <paramref name="start"/>. The project is untouched;
/// a range block pastes overwriting what it lands on. False when the range covers no clip.</summary>
bool CopyRange(int[] trackIds, double start, double end);
/// <summary><see cref="CopyRange"/>, then carves the range out like <see cref="DeleteClipsInRange"/>
/// (one undo step). False when the range covers no clip.</summary>
bool CutRange(int[] trackIds, double start, double end);
/// <summary>Copies arrangement clips into session slots: each track's clips, in time order, fill
/// consecutive slots from startScene (-1 = the first scene row where every slot needed is empty;
/// missing rows are appended). One undo step. Returns the first scene row filled, or -1.</summary>
int ArrangementClipsToSession((int trackId, int clipIndex)[] sel, int startScene = -1);
/// <summary>Pastes the block clipboard into session slots, its top track remapped onto destTrackId
/// (-1 = the source tracks). Returns the first scene row filled, or -1.</summary>
int PasteClipBlockToSession(int destTrackId, int startScene);
/// <summary>Copies session slots (trackId, scene) into the arrangement: each track's slots, in scene
/// order, land back to back from atBeat, placed like a paste (no overlap) and remapped onto destTrackId
/// (-1 = their own tracks). One undo step; LastPlacedClips reports them. Returns clips placed.</summary>
int SessionSlotsToArrangement((int trackId, int scene)[] slots, double atBeat, int destTrackId = -1);
/// <summary>The (trackId, clipIndex) of every clip the last block paste/duplicate produced.</summary>
(int trackId, int clipIndex)[] LastPlacedClips();
/// <summary>Sets/gets a clip's user-facing name (empty = default).</summary>
void SetClipName(int trackId, int clipIndex, string name);
string GetClipName(int trackId, int clipIndex);
/// <summary>Sets/gets a track's user-facing name (empty = default).</summary>
void SetTrackName(int trackId, string name);
string GetTrackName(int trackId);
/// <summary>Sets/gets a track's palette colour slot (-1 = auto by position).</summary>
void SetTrackColorIndex(int trackId, int colorIndex);
int GetTrackColorIndex(int trackId);
/// <summary>Sets/gets a track's piano roll Fold (specs/045): a view flag saved with the project.</summary>
void SetTrackPianoFold(int trackId, bool on);
bool GetTrackPianoFold(int trackId);
/// <summary>Group Link (specs/076): links a group's tracks for arming and clip edits. One undo
/// step; false for a track that is not a group.</summary>
bool SetTrackEditLink(int trackId, bool on);
bool GetTrackEditLink(int trackId);
/// <summary>Copies a whole track to the clipboard; pastes it as a new track (-1 on fail).</summary>
bool CopyTrack(int trackId);
int PasteTrack();
bool CopyTracks(int[] trackIds); // a group brings its children
int[] PasteTracks(int afterTrackId); // after the anchor, inside its group (-1 = end); new ids
bool HasTrackClipboard();
/// <summary>Audio-track record input source: 0 hardware, -1 master, >0 source track id.</summary>
void SetTrackRecordInput(int trackId, int source);
int GetTrackRecordInput(int trackId);
/// <summary>Which hardware input channels an audio track takes: both as a stereo pair, or
/// input 1 / input 2 alone as a mono source in the middle (#340). Hardware input only.</summary>
void SetTrackInputChannels(int trackId, InputChannels channels);
InputChannels GetTrackInputChannels(int trackId);
/// <summary>An audio track's hardware input: any device channel alone or an odd-aligned
/// stereo pair (specs/086). False for an invalid pick or a non-audio track.</summary>
bool SetTrackInput(int trackId, InputPick pick);
InputPick GetTrackInput(int trackId);
/// <summary>Whether the track's input exists on the open (or probed) capture device.</summary>
bool TrackInputAvailable(int trackId);
/// <summary>An instrument track's MIDI input (specs/086): which live MIDI reaches it when
/// armed, and so what it records — a device by uid (null = All inputs, the computer keyboard
/// too) and a channel (0 = all, 1–16). The track keeps the uid; while that device is not
/// connected it receives nothing from hardware. False for a non-instrument track.</summary>
bool SetTrackMidiInput(int trackId, string? uid, int channel);
TrackMidiInput GetTrackMidiInput(int trackId);
/// <summary>The capture device's input channels (0 when none is open) and their names
/// ("" where the device gives none).</summary>
int AudioInputChannelCount();
string AudioInputChannelName(int index);
/// <summary>Opens the selected capture device just to read its channels; returns the count.</summary>
int ProbeAudioInput();
/// <summary>Inputs switched off on the Audio I/O page (0-based): a take skips a track on one.</summary>
void SetDisabledInputs(int[] channels);
/// <summary>Tests: pretend a capture device with this many inputs is open (0 clears it).</summary>
void SetTestInputDevice(int channels);
/// <summary>The playback device's output channels (0 when none is open) and their names
/// ("" where the device gives none) — specs/089.</summary>
int AudioOutputChannelCount();
string AudioOutputChannelName(int index);
/// <summary>Where Main (the audience mix) and Cue (the private cue mix) go: 0-based first
/// channel and width (1 or 2); cueFirst < 0 = no Cue output. Takes effect at once, no
/// device restart. False for a bad width, an odd stereo first or overlapping pairs.</summary>
bool SetOutputRouting(int mainFirst, int mainWidth, int cueFirst, int cueWidth);
/// <summary>The routing against the open device.</summary>
OutputRoutingState GetOutputRoutingState();
/// <summary>Tests: device frames into the capture ring, drained into the running take as poll() would.</summary>
void FeedInputForTest(float[] interleaved, int frames, int channels);
/// <summary>Tests: record <paramref name="frames"/> of <paramref name="channels"/>-wide
/// device frames into the track through the capture ring, the track taking its own input.</summary>
bool TakeRecordTestN(int trackId, float[] interleaved, int channels, int frames, double startBeat);
/// <summary>Live input monitoring (audio tracks, Monitor "In"): play the record-input
/// source through the track in place of its clips. A master source stays silent.</summary>
void SetTrackMonitor(int trackId, bool on);
bool GetTrackMonitor(int trackId);
/// <summary>Set an instrument track's MIDI input source — receive another instrument track's
/// MIDI output ("MIDI In"). sourceTrackId = -1 turns it off.</summary>
void SetTrackMidiSource(int trackId, int sourceTrackId);
int GetTrackMidiSource(int trackId);
/// <summary>Track-level MIDI playback offset in ms (negative = notes play earlier). Playback only:
/// the notes in the clips do not move. Clamped to ±2000 ms.</summary>
void SetTrackMidiOffsetMs(int trackId, double ms);
double GetTrackMidiOffsetMs(int trackId);
/// <summary>Gives an instrument track its articulation map (specs/085): the compiled table
/// (see ArticulationMapCompiler) plus the map as Nota's JSON, saved with the project. One undo
/// step. False, with nothing changed, when the engine rejects the table or the track.</summary>
bool SetTrackArticulationMap(int trackId, int defaultId, NotaArticulationEntry[] entries, NotaArticulationAction[] actions, string mapJson);
/// <summary>Removes the track's map; notes keep their articulation ids. One undo step.</summary>
bool ClearTrackArticulationMap(int trackId);
/// <summary>The map JSON the track holds, or null when it has none.</summary>
string? GetTrackArticulationMapJson(int trackId);
// --- freeze (M7): bounce a track's pre-fader audio to a buffer and play it back
// in place of the live instrument+device chain. Drive offline with the backend
// stopped (BeginFreeze → seek 0 → pump RenderOffline → EndFreeze). ---
/// <summary>Arms an offline freeze capture; returns frames to render (0 = unsupported).</summary>
long BeginFreeze(int trackId, double lengthBeats);
/// <summary>Publishes the captured buffer and marks the track frozen.</summary>
void EndFreeze(int trackId);
/// <summary>Aborts an armed freeze capture.</summary>
void CancelFreeze();
/// <summary>Arms a capture exactly <paramref name="lengthBeats"/> long (no ring-out tail); returns frames.</summary>
long BeginBounce(int trackId, double lengthBeats);
/// <summary>Paste Bounced Audio: copies the armed capture's frames into <paramref name="outFrames"/>
/// (interleaved stereo) and disarms it without freezing the track. Returns frames copied.</summary>
long TakeFreezeCapture(float[] outFrames);
/// <summary>Places device-rate interleaved-stereo PCM on an audio track as a new clip at
/// <paramref name="atBeat"/>, overwriting what it covers (one undo step). Clip index, or -1.</summary>
int PasteAudioFrames(int trackId, float[] interleaved, long frames, double atBeat, string? name);
/// <summary>Drops a track's freeze buffer (back to live processing).</summary>
void UnfreezeTrack(int trackId);
/// <summary>True when the track is frozen.</summary>
bool IsTrackFrozen(int trackId);
/// <summary>Reads a frozen track's audio blob for persistence (empty = not frozen).</summary>
byte[] GetFreezeState(int trackId);
/// <summary>Restores a frozen track's audio blob and marks it frozen.</summary>
void SetFreezeState(int trackId, byte[] data);
// Each peaks call also fills outRms (one RMS level per bucket, the waveform's body) when given.
int GetClipPeaks(int trackId, int clipIndex, float[] outMinMax, int maxPoints, float[]? outRms = null);
/// <summary>Peaks over the whole sample (ignores the trimmed region) for the clip editor's Start/End brackets.</summary>
int GetClipSourcePeaks(int trackId, int clipIndex, float[] outMinMax, int maxPoints, float[]? outRms = null);
/// <summary>Peaks over the full warped material (ignores the trim window) for the warped-clip Start/End brackets.</summary>
int GetClipWarpFullPeaks(int trackId, int clipIndex, float[] outMinMax, int maxPoints, float[]? outRms = null);
/// <summary>Peaks over warped beats [beat0, beat1] of the full material, file order (≤ 8192 points) — the zoomed clip editor's detail.</summary>
int GetClipWarpPeaksRange(int trackId, int clipIndex, double beat0, double beat1, float[] outMinMax, int maxPoints, float[]? outRms = null);
/// <summary>Peaks over source frames [frame0, frame1) of the whole sample (≤ 8192 points) — the zoomed clip editor's detail.</summary>
int GetClipSourcePeaksRange(int trackId, int clipIndex, double frame0, double frame1, float[] outMinMax, int maxPoints, float[]? outRms = null);
// --- Instrument tracks, MIDI clips & notes -----------------------------
int AddInstrumentTrack();
/// <summary>Adds an instrument track with the built-in Nota Physical (physical modeling) synth.</summary>
int AddPhysicalSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Aurora (wavetable) synth.</summary>
int AddWavetableSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Volt (virtual-analog) synth.</summary>
int AddVoltSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Bass synth.</summary>
int AddBassSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Pendulum synth.</summary>
int AddPendulumSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Operator FM synth.</summary>
int AddOperatorSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Grain granular synth.</summary>
int AddGrainSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Flux vector-morph synth.</summary>
int AddFluxSynthTrack();
/// <summary>Adds an instrument track with the built-in Nota Rhythm drum machine (kind 12).</summary>
int AddRhythmTrack();
/// <summary>Adds an instrument track with the built-in Nota Monolith mono synth (kind 13).</summary>
int AddMonolithTrack();
/// <summary>Adds an instrument track with the built-in Nota Pentad 5-voice poly synth (kind 14).</summary>
int AddPentadTrack();
/// <summary>Adds an instrument track with the built-in Nota Consort paraphonic semi-modular synth (kind 15).</summary>
int AddConsortTrack();
/// <summary>Adds an instrument track with the built-in Nota Keys modelled electric piano (kind 16).</summary>
int AddKeysTrack();
/// <summary>Adds an instrument track with the built-in Nota Mosaic multisample instrument (kind 17),
/// empty until a program is set.</summary>
int AddMosaicTrack();
/// <summary>Adds an instrument track with the built-in Nota Twin two-part morphing analog poly (kind 18).</summary>
int AddTwinTrack();
/// <summary>Sets a Nota Mosaic's program (MosaicProgram text) and starts loading its samples in
/// the background. <paramref name="undoable"/>: one undo step (sounding notes stop); false edits
/// the live instrument in place (a drag in progress). False when the track isn't a Mosaic.</summary>
bool MosaicSetProgram(int trackId, string text, bool undoable = true);
/// <summary>The Mosaic's program text ("" when none / not a Mosaic).</summary>
string MosaicProgram(int trackId);
/// <summary>The Mosaic's loading state; false when the track isn't a Mosaic.</summary>
bool TryGetMosaicStatus(int trackId, out NotaMosaicStatus status);
/// <summary>The sample id behind a zone (for TryGetSampleInfo / ReadSample), 0 = not loaded.</summary>
long MosaicZoneSampleId(int trackId, int zone);
// ---- Nota Aurora custom wavetables (specs/053) ----
/// <summary>Decodes a WAV / FLAC / MP3 and builds a conditioned, band-limited table on the
/// calling thread (any thread: it touches no engine state). Returns an
/// <see cref="AuroraTableResult"/>; on Ok, <paramref name="table"/> is a handle the caller
/// frees with <see cref="AuroraTableFree"/>.</summary>
int AuroraTableBuild(string path, out nint table);
/// <summary>A table from frames a project or preset saved (2048 floats each): only the mips
/// are rebuilt, so it plays exactly what was saved.</summary>
int AuroraTableFromFrames(float[] frames, int frameCount, string name, int origin, out nint table);
AuroraTableInfo AuroraTableInfoOf(nint table);
/// <summary>The handle's base frames (2048 × frames floats).</summary>
float[] AuroraTableFrames(nint table);
void AuroraTableFree(nint table);
/// <summary>Puts the table into Aurora oscillator <paramref name="osc"/> (0/1) and plays it.
/// <paramref name="undoable"/>: one undo step (sounding notes stop); false: in place (a project
/// load). The engine keeps its own reference. False when the track isn't an Aurora.</summary>
bool AuroraSetTable(int trackId, int osc, nint table, bool undoable = true);
/// <summary>Removes the imported table (one undo step).</summary>
bool AuroraClearTable(int trackId, int osc);
/// <summary>Imported table (true) or the built-in bank (false). Undoable: one undo step
/// (the instrument is republished); otherwise in place with no undo (loads).</summary>
bool AuroraSetSource(int trackId, int osc, bool useCustom, bool undoable = false);
/// <summary>Marks a table a project named but could not restore ("" clears).</summary>
bool AuroraSetMissing(int trackId, int osc, string name);
bool TryGetAuroraTableInfo(int trackId, int osc, out AuroraTableInfo info);
/// <summary>The slot's base frames, or an empty array.</summary>
float[] AuroraTableRead(int trackId, int osc);
/// <summary>A drawing preview: <paramref name="repFrames"/> then <paramref name="gridFrames"/>
/// evenly chosen frames of <paramref name="points"/> samples each; empty when there is no table.</summary>
float[] AuroraTablePreview(int trackId, int osc, int repFrames, int gridFrames, int points);
/// <summary>The Aurora's state blob with or without the table frames (a project save keeps
/// the tables as sample files beside it).</summary>
byte[] AuroraState(int trackId, bool includeTables);
/// <summary>UI editing channel for the track's instrument (e.g. Rhythm step patterns).</summary>
void InstrumentAction(int trackId, int id, int iarg, float farg);
/// <summary>Loads a state blob into the track's instrument and records what it changed in the
/// instrument's edit state (a Nota Twin's patterns) as an undo step. False when not applied.</summary>
bool SetInstrumentStateUndoable(int trackId, byte[] data);
/// <summary>Loads a sample file into a Nota Grain track (kind 10). True on success.</summary>
bool SetTrackGrainSample(int trackId, string path, int rootNote = 60);
/// <summary>Sets a Nota Grain's root note — the key that plays the sample at its own pitch.</summary>
bool SetTrackGrainRoot(int trackId, int rootNote);
/// <summary>Grain sample info (sample id / root). True if the track is a Nota Grain.</summary>
bool TryGetGrainInfo(int trackId, out NotaSamplerInfo info);
/// <summary>Nota Rhythm Phase 2 — load a one-shot into a drum voice (switches it to Sample).</summary>
bool SetRhythmVoiceSample(int trackId, int voice, string path);
/// <summary>Per-voice sample id (0 = none) for Nota Rhythm.</summary>
bool TryGetRhythmVoiceInfo(int trackId, int voice, out NotaSamplerInfo info);
/// <summary>Per-voice source: 0 = Synth, 1 = Sample.</summary>
int RhythmVoiceSource(int trackId, int voice);
/// <summary>Nota Rhythm per-voice insert chains: built-in effects (rack chain kinds) run on one
/// voice before the kit bus. Params are in each device's own units (min..max).</summary>
int RhythmVoiceDeviceCount(int trackId, int voice);
int RhythmAddVoiceDevice(int trackId, int voice, int kind);
bool RhythmRemoveVoiceDevice(int trackId, int voice, int dev);
void RhythmMoveVoiceDevice(int trackId, int voice, int from, int to);
string RhythmVoiceDeviceName(int trackId, int voice, int dev);
int RhythmVoiceDeviceBuiltinKind(int trackId, int voice, int dev);
int RhythmVoiceDeviceParamCount(int trackId, int voice, int dev);
string RhythmVoiceDeviceParamName(int trackId, int voice, int dev, int param);
float RhythmVoiceDeviceParamMin(int trackId, int voice, int dev, int param);
float RhythmVoiceDeviceParamMax(int trackId, int voice, int dev, int param);
float RhythmVoiceDeviceParamGet(int trackId, int voice, int dev, int param);
void RhythmVoiceDeviceParamSet(int trackId, int voice, int dev, int param, float value);
bool RhythmVoiceDeviceBypassed(int trackId, int voice, int dev);
void RhythmSetVoiceDeviceBypassed(int trackId, int voice, int dev, bool bypassed);
// Voice-device telemetry — mirrors DeviceGainReduction / DeviceScope / DeviceLayerWave /
// DeviceText / DeviceAction for an effect on a Rhythm voice.
float RhythmVoiceDeviceGainReduction(int trackId, int voice, int dev);
int RhythmVoiceDeviceScope(int trackId, int voice, int dev, float[] outSamples, int maxSamples);
int RhythmVoiceDeviceLayerWave(int trackId, int voice, int dev, int layer, float[] outSamples, int maxSamples);
string RhythmVoiceDeviceText(int trackId, int voice, int dev, int id);
void RhythmVoiceDeviceAction(int trackId, int voice, int dev, int id, int iarg, float farg);
/// <summary>The factory kit a Rhythm's voices were loaded from ("" = none) — display only, saved with the track.</summary>
string RhythmKitName(int trackId);
void RhythmSetKitName(int trackId, string name);
/// <summary>Nota Rhythm macros: their names and mappings (the values are the macro1..8 plugin
/// params). In a mapping, Chain is the voice; DeviceIndex -1 targets one of the Rhythm's own
/// params (ParamIndex = its plugin-param index, 0..1), ≥ 0 a device on that voice's FX chain
/// (the device's own units).</summary>
string RhythmMacroName(int trackId, int macro);
void RhythmSetMacroName(int trackId, int macro, string name);
int RhythmAddMacroMapping(int trackId, int macro, int voice, int device, int param, float lo, float hi);
int RhythmMacroMappingCount(int trackId);
bool RhythmTryGetMacroMapping(int trackId, int index, out RackMacroMapping mapping, out int curve);
bool RhythmRemoveMacroMapping(int trackId, int index);
bool RhythmSetMacroMappingRange(int trackId, int index, float lo, float hi);
bool RhythmSetMacroMappingCurve(int trackId, int index, int curve);
/// <summary>Drops every mapping and custom name (the macro values stay).</summary>
void RhythmClearMacros(int trackId);
/// <summary>Live Nota Grain read positions (0..1) of active voices into outPos; returns the count.</summary>
int GrainPlayPositions(int trackId, float[] outPos);
/// <summary>Active synth-voice count for a built-in instrument, or -1 if unsupported.</summary>
int InstrumentVoiceCount(int trackId);
/// <summary>Held chord pitches for a generative instrument (Nota Pendulum) into outNotes; returns the count.</summary>
int InstrumentHeldNotes(int trackId, int[] outNotes);
/// <summary>Currently-pressed live-input pitches (computer keyboard + MIDI), independent of track routing.</summary>
int LiveHeldNotes(int[] outNotes);
/// <summary>Live viz telemetry (Nota Operator harmonic spectrum) into outv; returns the count written.</summary>
int InstrumentScope(int trackId, float[] outv);
/// <summary>The newest output samples of the track's instrument (mono, oldest first, up to
/// 4096) into outv; returns the count. Reading keeps the engine's tap on for about a
/// second (#531, the filter graph's spectrum).</summary>
int InstrumentOutput(int trackId, float[] outv);
int AddSamplerTrack(string path, int rootNote = 60, bool loop = false);
/// <summary>Adds an empty Sampler instrument track (a sample is loaded later).</summary>
int AddSamplerInstrumentTrack();
/// <summary>Loads a sample into an existing Sampler track, keeping its params.</summary>
bool SetTrackSamplerSample(int trackId, string path, int rootNote = 60);
/// <summary>Sets the Sampler track's root note (lock-free).</summary>
bool SetTrackSamplerRoot(int trackId, int rootNote);
/// <summary>Live Sampler playback position (0..1 of the sample, -1 = silent) for the UI cursor.</summary>
float SamplerPlayPosition(int trackId);
/// <summary>The file name (no extension) a sample was loaded from, or "" when unknown —
/// the engine keeps only the audio, so the name is remembered here on load and carried
/// by the project (SamplerDto.Name). Used by the Sampler's "Detect from file name".</summary>
string SampleName(long sampleId);
/// <summary>Remember the source name of a sample (a project reload restores it).</summary>
void SetSampleName(long sampleId, string name);
/// <summary>The full path the sample was loaded from, or "" when unknown (a recording, a
/// render, a project's own copy). Managed-side only, like <see cref="SampleName"/>; Locate
/// uses it and projects save it (spec 092, #581).</summary>
string SampleSource(long sampleId) => "";
/// <summary>Restore a sample's source path (project load).</summary>
void SetSampleSource(long sampleId, string path) { }
int AddMidiClip(int trackId, double startBeat, double lengthBeats);
// --- Hosted plugins (M3-3) ---------------------------------------------
int AddPluginInstrumentTrack(int catalogIndex);
void SetTrackInstrumentPlugin(int trackId, int catalogIndex);
/// <summary>Replaces an instrument track's instrument with a fresh built-in synth of the
/// given kind. Returns false for Racks/unknown kinds or non-instrument tracks.</summary>
bool SetTrackBuiltinInstrument(int trackId, int kind);
int AddTrackEffectPlugin(int trackId, int catalogIndex);
int TrackDeviceCount(int trackId);
/// <summary>Copies an audio clip's played region down-mixed to mono for offline audio→MIDI
/// analysis. Pass null to query the frame count. Returns the frame count; sr = source rate.</summary>
int GetClipAudioMono(int trackId, int clipIndex, float[]? outOrNull, out double sr);
// --- Built-in devices + params (M4-4/5) --------------------------------
int AddBuiltinDevice(int trackId, int kind);
void MoveDevice(int trackId, int fromIndex, int toIndex);
void RemoveDevice(int trackId, int deviceIndex);
// Device clipboard (#238): a full clone held by the engine; paste is one undo step.
bool CopyDevice(int trackId, int deviceIndex);
bool CopyMidiEffect(int trackId, int index);
int DeviceClipboardKind(); // 0 empty, 1 audio effect, 2 MIDI effect, 3 instrument, 4 several
bool DeviceClipboardSidechain(); // the copied audio effect is keyed from another track
int PasteDevice(int trackId, int atIndex); // atIndex -1 = end; new index or -1
int PasteMidiEffect(int trackId, int atIndex);
// A full clone right after the device / MIDI effect, one undo step; clipboard untouched.
int DuplicateDevice(int trackId, int deviceIndex);
int DuplicateMidiEffect(int trackId, int index);
// The instrument on the same clipboard (specs/043). Paste replaces the track's instrument:
// 0 done, -1 nothing to paste, -2 not an instrument track, -3 the clone failed.
bool CopyInstrument(int trackId);
int PasteInstrument(int trackId);
// Move (or, keepSource, copy) a device to another track, both tracks in one undo step: the
// new index (0 for the instrument), -1 bad address, -2 the target can't take it, -3 the
// clone failed. A move takes the device's automation; the instrument's removes its track.
int TransferDevice(int srcTrackId, DeviceFamily family, int index, int dstTrackId, int atIndex, bool keepSource, out TransferFlags flags);
// ⌘G / ⌘⇧G on a device (#257): wrap an audio effect in an Audio Effect Rack (its index or
// -1), unwrap a one-chain Audio Effect Rack (count or -1). The one-device cases of:
int WrapDeviceInRack(int trackId, int deviceIndex);
int UnwrapRack(int trackId, int deviceIndex);
// Group a contiguous run into a rack in its place, links following (specs/044); one undo
// step. Returns the rack's address (>= 0 effect, -1 the instrument, -1000 - i MIDI effect)
// or a GroupRefusal (< -1). See nota_track_group_devices.
int GroupDevices(int trackId, int midiFirst, int midiCount, bool withInstrument, int fxFirst, int fxCount);
// Ungroup a one-chain rack: devices restored (>= 0) or an UngroupRefusal (< 0).
int UngroupRack(int trackId, DeviceFamily family, int index, out UngroupDropped dropped);
// Several devices on the clipboard (specs/044): count, or -1. Paste: the number pasted (>= 0,
// skipped = what the track can't take), -1 empty, -3 a clone failed.
int CopyDevices(int trackId, int[] midiIndices, bool withInstrument, int[] fxIndices);
int DeviceClipboardCount();
int PasteDevices(int trackId, int midiAt, int fxAt, out int skipped);
string DeviceName(int trackId, int deviceIndex);
int DeviceParamCount(int trackId, int deviceIndex);
string DeviceParamName(int trackId, int deviceIndex, int paramIndex);
float DeviceParamMin(int trackId, int deviceIndex, int paramIndex);
float DeviceParamMax(int trackId, int deviceIndex, int paramIndex);
float DeviceGetParam(int trackId, int deviceIndex, int paramIndex);
void DeviceSetParam(int trackId, int deviceIndex, int paramIndex, float value);
/// <summary>Live gain reduction (dB, ≥0) of a dynamics device (built-in Compressor); 0 otherwise.</summary>
float DeviceGainReduction(int trackId, int deviceIndex);
/// <summary>Factory-default value of a parameter, for double-click reset.</summary>
float DeviceParamDefault(int trackId, int deviceIndex, int paramIndex);
/// <summary>Factory default of a built-in effect KIND's parameter (rack chain devices).</summary>
float BuiltinDeviceParamDefault(int kind, int paramIndex);
float InstrumentParamDefault(int trackId, int paramIndex);
float MidiEffectParamDefault(int trackId, int index, int paramIndex);
// --- MIDI effects (before the instrument) ---
int AddMidiEffect(int trackId, int kind); // 0 = Arpeggiator; returns index or -1
int TrackMidiEffectCount(int trackId);
void MoveMidiEffect(int trackId, int fromIndex, int toIndex);
void RemoveMidiEffect(int trackId, int index);
int MidiEffectKind(int trackId, int index);
/// <summary>Last note-on IN/OUT pitch a MIDI effect remapped (Nota Scale readout); -1 = none.</summary>
int MidiEffectLastIn(int trackId, int index);
int MidiEffectLastOut(int trackId, int index);
/// <summary>Float scope buffer for a MIDI effect editor (Nota Velocity in/out pairs); returns count written.</summary>
int MidiEffectScope(int trackId, int index, float[] outv);
/// <summary>Send an editor command to a MIDI effect (Nota Arp: 1 = restart the pattern).</summary>
void MidiEffectCommand(int trackId, int index, int cmd);
/// <summary>A MIDI effect's opaque state blob (the MIDI Effect Rack: its whole structure); empty for params-only effects.</summary>
byte[] MidiEffectGetState(int trackId, int index);
/// <summary>Restores a MIDI effect's state blob; checkpoint makes it one undo step.</summary>
bool MidiEffectSetState(int trackId, int index, byte[] data, bool checkpoint);
string MidiEffectName(int trackId, int index);
int MidiEffectParamCount(int trackId, int index);
string MidiEffectParamName(int trackId, int index, int paramIndex);
float MidiEffectParamMin(int trackId, int index, int paramIndex);
float MidiEffectParamMax(int trackId, int index, int paramIndex);
float MidiEffectGetParam(int trackId, int index, int paramIndex);
void MidiEffectSetParam(int trackId, int index, int paramIndex, float value);
void SetMidiEffectBypassed(int trackId, int index, bool bypassed);
bool MidiEffectBypassed(int trackId, int index);
/// <summary>Fold (specs/022): the Devices panel draws the MIDI effect as a narrow strip.
/// A view flag kept on the device (follows moves and undo) and saved with the project.</summary>
void SetMidiEffectFolded(int trackId, int index, bool folded);
bool MidiEffectFolded(int trackId, int index);
void SetMidiEffectCcDest(int trackId, int index, int destDevice, int destParam);
void SetMidiEffectCcDepth(int trackId, int index, float depth);
int MidiEffectCcDestDevice(int trackId, int index);
int MidiEffectCcDestParam(int trackId, int index);
// The CC target inside a rack (specs/044): chain index + slot, (-1, -1) at track level.
(int Chain, int Slot) MidiEffectCcDestPath(int trackId, int index);
bool SetMidiEffectCcDestPath(int trackId, int index, int chain, int slot);
// What lives on rack chain children outside the rack blob (specs/044; save / load): a chain
// MIDI effect's CC target and a child's sidechain key (slot >= 0 a device, -1 the chain
// instrument). rackAddress as the rack calls take it (>= 0 effect, -1 instrument, -1000 - i).
NestedCcDest? RackChainMidiCcDest(int trackId, int rackAddress, int chain, int index);
bool RackChainMidiSetCcDest(int trackId, int rackAddress, int chain, int index, NestedCcDest dest);
NestedSidechain? RackChainSidechain(int trackId, int rackAddress, int chain, int slot);
/// <summary>0 = set, -1 = bad address, -2 = no free route (the key is left as it was).</summary>
int RackChainSetSidechain(int trackId, int rackAddress, int chain, int slot, NestedSidechain sc);
float MidiEffectCcDepth(int trackId, int index);
/// <summary>Copies up to maxSamples of the device's live readings into outSamples; returns
/// the count written. Each device defines its own layout (the analysers: a telemetry block,
/// then spectra — e.g. Nota EQ-8's in / out peaks, auto gain, then its pre and post
/// spectra); zero for devices without one. Lock-free.</summary>
int DeviceScope(int trackId, int deviceIndex, float[] outSamples, int maxSamples);
/// <summary>Interactive-device command channel (the looper's transport + per-layer mute/gain).
/// Applied at the next quantize boundary by the engine.</summary>
void DeviceAction(int trackId, int deviceIndex, int id, int iarg, float farg);
/// <summary>Per-layer waveform envelope for multi-layer devices (the looper): peak bins into
/// outSamples (oldest→newest); returns the count.</summary>
int DeviceLayerWave(int trackId, int deviceIndex, int layer, float[] outSamples, int maxSamples);
/// <summary>Opaque device-state blob (the looper's recorded PCM) for project save/restore;
/// empty for param-only devices.</summary>
byte[] DeviceGetState(int trackId, int deviceIndex);
void DeviceSetState(int trackId, int deviceIndex, byte[] data);
/// <summary>Load an auxiliary audio file into a device (Nota Chamber: a user impulse
/// response — WAV / FLAC / MP3, mono, stereo or 4-channel true stereo). False if unsupported.</summary>
bool DeviceLoadFile(int trackId, int deviceIndex, string path);
/// <summary>A device's resource text (Nota Chamber: 0 IR name, 1 IR category, 2 user IR
/// name, 10 the built-in IR list as "name\tcategory\tseconds" lines); "" when none.</summary>
string DeviceText(int trackId, int deviceIndex, int id);
/// <summary>Nota EQ-8 band labels and notes (specs/049): replace band 0..7's label (≤ 24
/// characters, one line) and note (≤ 2000) as one undo step; false when nothing changed or the
/// device isn't an EQ-8. EqBandText: which 0 = label, 1 = note ("" when none).</summary>
bool EqSetBandText(int trackId, int deviceIndex, int band, string label, string note);
string EqBandText(int trackId, int deviceIndex, int band, int which);
/// <summary>Sidechain routing: point a device's detector at another track's signal (-1 clears).</summary>
void SetDeviceSidechainSource(int trackId, int deviceIndex, int sourceTrackId);
int DeviceSidechainSource(int trackId, int deviceIndex);
/// <summary>Whether a device can key off a sidechain source: the Compressor, or a plugin
/// exposing a sidechain input bus (Phase C). Drives whether the UI offers a source picker.</summary>
bool DeviceAcceptsSidechain(int trackId, int deviceIndex);
/// <summary>Instrument sidechain ("React", Nota Flux): route a listening instrument to a
/// source track (-1 clears). Source is the previous-block, post-fader signal.</summary>
void SetInstrumentSidechainSource(int trackId, int sourceTrackId);
int InstrumentSidechainSource(int trackId);
/// <summary>Whether a track's instrument listens to a sidechain (Nota Flux).</summary>
bool InstrumentAcceptsSidechain(int trackId);
// Sidechain sub-sources (specs/050): a key may name one part of the source track's
// instrument (a Drum Rack pad, an Instrument Rack chain, a Rhythm voice) by its current
// index; the engine keeps the key on that part through reorder / insert / delete of others.
/// <summary>Parts of the track's instrument (0 = not a multi-part instrument).</summary>
int TrackPartCount(int trackId);
/// <summary>Display name of a part: the chain name, else its instrument's.</summary>
string TrackPartName(int trackId, int index);
/// <summary>Key a device off a track (part -1) or one part of it. 0 = set, -1 = bad address
/// or part, -2 = no free route (the key is left as it was).</summary>
int SetDeviceSidechainKey(int trackId, int deviceIndex, int sourceTrackId, int part);
SidechainKey DeviceSidechainKey(int trackId, int deviceIndex);
/// <summary>The same for an instrument's React key (Nota Flux) — always the Post tap.</summary>
int SetInstrumentSidechainKey(int trackId, int sourceTrackId, int part);
SidechainKey InstrumentSidechainKey(int trackId);
/// <summary>The part of a rack chain child's key (save / load; after RackChainSetSidechain).</summary>
int RackChainSidechainPart(int trackId, int rackAddress, int chain, int slot);
int RackChainSetSidechainPart(int trackId, int rackAddress, int chain, int slot, int part); // 0 / -1 / -2 as above
/// <summary>A rack child's whole key in one step (source, part — -1 whole track — and shaping), so
/// only the final key meets the route check. 0 / -1 / -2 as above; on -2 nothing changes.</summary>
int RackChainSetSidechainKey(int trackId, int rackAddress, int chain, int slot, NestedSidechain sc, int part);
/// <summary>The route pool whole tracks and parts share: size, free now, and whether
/// (source, part) already has a route (a further key on it needs none).</summary>
int SidechainRouteCapacity();
int SidechainRoutesFree();
bool SidechainRouteInUse(int sourceTrackId, int part);
/// <summary>Sidechain detector gain in dB (Phase D): how hard the source drives the effect.</summary>
void SetDeviceSidechainGain(int trackId, int deviceIndex, float gainDb);
float DeviceSidechainGain(int trackId, int deviceIndex);
/// <summary>Dry/wet of the device's effect, 0..1 (Phase D).</summary>
void SetDeviceSidechainMix(int trackId, int deviceIndex, float mix);
float DeviceSidechainMix(int trackId, int deviceIndex);
/// <summary>Source tap point (Phase D): true = pre-FX pre-fader, false = post-FX post-fader.</summary>
void SetDeviceSidechainTapPre(int trackId, int deviceIndex, bool pre);
bool DeviceSidechainTapPre(int trackId, int deviceIndex);
void OpenPluginEditor(int trackId, int deviceIndex);
void ClosePluginEditor(int trackId, int deviceIndex);
/// <summary>Whether the plugin's editor window is on screen (false when it failed to open).</summary>
bool PluginEditorIsOpen(int trackId, int deviceIndex);
byte[] GetPluginState(int trackId, int deviceIndex);
void SetPluginState(int trackId, int deviceIndex, byte[] data);
/// <summary>Editor preview (specs/046): the plug-in window's last look as JPEG, kept on the device;
/// set returns false for an unknown device, serial is 0 when there is none.</summary>
byte[] GetPluginPreview(int trackId, int deviceIndex);
bool SetPluginPreview(int trackId, int deviceIndex, byte[] jpeg);
int PluginPreviewSerial(int trackId, int deviceIndex);
void SetDeviceBypassed(int trackId, int deviceIndex, bool bypassed);
bool DeviceBypassed(int trackId, int deviceIndex);
/// <summary>Fold (specs/022): the Devices panel draws the device as a narrow strip.
/// deviceIndex -1 = the instrument. Kept on the device; saved with the project.</summary>
void SetDeviceFolded(int trackId, int deviceIndex, bool folded);
bool DeviceFolded(int trackId, int deviceIndex);
int TrackLatencySamples(int trackId);
// --- Instrument Rack (parallel chains + 8 macros) ----------------------
/// <summary>Adds an instrument track hosting an Instrument Rack with one default Synth chain.</summary>
int AddInstrumentRackTrack();
/// <summary>Adds an instrument track hosting an (empty) Drum Rack; pads are added via chains + trigger notes.</summary>
int AddDrumRackTrack();
/// <summary>Adds a Sampler chain (drum pad / sampler chain) loaded from a file to the track's rack. Returns the chain index or -1.</summary>
int RackAddSamplerChain(int trackId, string path, int rootNote, bool loop);
/// <summary>Load a sample file into a rack chain's Sampler (keeps its params + devices).</summary>
bool RackSetChainSamplerSample(int trackId, int chain, string path, int rootNote);
/// <summary>Adds a hosted-plugin (VST3/AU) instrument as a new chain to the track's rack. Returns the chain index or -1.</summary>
int RackAddPluginInstrumentChain(int trackId, int catalogIndex);
/// <summary>Adds a hosted-plugin effect into a chain of the track's instrument rack. Returns the device index or -1.</summary>
int RackAddPluginChainDevice(int trackId, int chain, int catalogIndex);
int RackChainTriggerNote(int trackId, int chain);
void RackSetChainTriggerNote(int trackId, int chain, int note);
/// <summary>The chain's display name — a Drum Rack pad label. Empty means "use the
/// chain instrument's own name" (every Sampler pad would otherwise read the same).</summary>
string RackChainName(int trackId, int chain);
void RackSetChainName(int trackId, int chain, string name);
int RackChainCount(int trackId);
int RackAddChain(int trackId, int instKind); // 0=Synth, 2=Physical
bool RackRemoveChain(int trackId, int chain);
bool RackSetChainInstrument(int trackId, int chain, int instKind);
int RackChainInstrumentKind(int trackId, int chain);
string RackChainInstrumentName(int trackId, int chain);
int RackChainInstrumentParamCount(int trackId, int chain);
string RackChainInstrumentParamName(int trackId, int chain, int param);
/// <summary>Stable id ("volume", "start", …) of a chain instrument param.</summary>
string RackChainInstrumentParamId(int trackId, int chain, int param);
float RackChainInstrumentParamGet(int trackId, int chain, int param);
void RackChainInstrumentParamSet(int trackId, int chain, int param, float normalized);
/// <summary>Factory-default value (0..1) of a chain instrument param, for double-click reset.</summary>
float RackChainInstrumentParamDefault(int trackId, int chain, int param);
// Chain-instrument telemetry — mirrors InstrumentScope / InstrumentVoiceCount /
// InstrumentHeldNotes / InstrumentAction for the instrument on a rack chain.
int RackChainInstrumentScope(int trackId, int chain, float[] outv);
int RackChainInstrumentVoiceCount(int trackId, int chain);
int RackChainInstrumentHeldNotes(int trackId, int chain, int[] outNotes);
void RackChainInstrumentAction(int trackId, int chain, int id, int iarg, float farg);
bool RackSetChainInstrumentStateUndoable(int trackId, int chain, byte[] data);
/// <summary>After param writes to a chain instrument: one undo step from <paramref name="before"/> (its state read first) to now.</summary>
bool RackChainInstrumentRecordStateUndo(int trackId, int chain, byte[] before);
/// <summary>Built-in Sampler settings for a chain instrument. False if it isn't a Sampler.</summary>
bool RackChainSamplerInfo(int trackId, int chain, out NotaSamplerInfo info);
/// <summary>Sets a chain Sampler's root note (lock-free). False if the chain isn't a Sampler.</summary>
bool RackSetChainSamplerRoot(int trackId, int chain, int rootNote);
/// <summary>A chain Sampler's live playback position (0..1), -1 when silent.</summary>
float RackChainSamplerPlayPosition(int trackId, int chain);
/// <summary>Opens the chain instrument's native editor (hosted plugins).</summary>
void RackOpenChainInstrumentEditor(int trackId, int chain);
/// <summary>Open a rack chain's hosted-plugin effect native editor window.</summary>
void RackOpenChainDeviceEditor(int trackId, int chain, int dev);
/// <summary>Stable plugin identifier of the chain instrument ("" for built-ins).</summary>
string RackChainInstrumentPluginId(int trackId, int chain);
/// <summary>Opaque state of the chain instrument (for preset capture).</summary>
byte[] RackGetChainInstrumentState(int trackId, int chain);
int RackChainDeviceCount(int trackId, int chain);
int RackAddChainDevice(int trackId, int chain, int deviceKind); // 0=EQ..4=Utility
bool RackRemoveChainDevice(int trackId, int chain, int dev);
bool RackMoveChainDevice(int trackId, int chain, int fromIndex, int toIndex);
string RackChainDeviceName(int trackId, int chain, int dev);
int RackChainDeviceBuiltinKind(int trackId, int chain, int dev);
int RackChainDeviceParamCount(int trackId, int chain, int dev);
string RackChainDeviceParamName(int trackId, int chain, int dev, int param);
float RackChainDeviceParamMin(int trackId, int chain, int dev, int param);
float RackChainDeviceParamMax(int trackId, int chain, int dev, int param);
float RackChainDeviceParamGet(int trackId, int chain, int dev, int param);
void RackChainDeviceParamSet(int trackId, int chain, int dev, int param, float value);
void RackSetChainDeviceBypassed(int trackId, int chain, int dev, bool bypassed);
bool RackChainDeviceBypassed(int trackId, int chain, int dev);
void RackSetChainGain(int trackId, int chain, float v);
void RackSetChainPan(int trackId, int chain, float v);
void RackSetChainMute(int trackId, int chain, bool mute);
void RackSetChainSolo(int trackId, int chain, bool solo);
float RackChainGain(int trackId, int chain);
float RackChainPan(int trackId, int chain);
bool RackChainMute(int trackId, int chain);
bool RackChainSolo(int trackId, int chain);
float RackMacroGet(int trackId, int macro);
void RackMacroSet(int trackId, int macro, float v);
int RackAddMacroMapping(int trackId, int macro, int chain, int deviceIndex, int paramIndex, float rangeMin, float rangeMax);
int RackMappingCount(int trackId);
bool RackTryGetMapping(int trackId, int index, out RackMacroMapping mapping);
bool RackRemoveMapping(int trackId, int index);
// Instrument-Rack extras (mockup 2p): key/velocity zones, per-chain meter, named
// macros, rack output (volume/glide), macro-map range/curve editing.
void RackChainZone(int trackId, int chain, out int keyLo, out int keyHi, out int velLo, out int velHi);
void RackSetChainZone(int trackId, int chain, int keyLo, int keyHi, int velLo, int velHi);
float RackChainMeter(int trackId, int chain);
string RackMacroName(int trackId, int macro);
void RackSetMacroName(int trackId, int macro, string name);
float RackVolume(int trackId);
void RackSetVolume(int trackId, float v);
/// <summary>Copies an Instrument Rack chain after itself (children, controls, its mappings); the new index or <0.</summary>
int RackDuplicateChain(int trackId, int chain);
/// <summary>Instrument Rack mono: one note at a time, last-note priority; glide bends between notes.</summary>
bool RackMono(int trackId);
void RackSetMono(int trackId, bool on);
float RackGlide(int trackId);
void RackSetGlide(int trackId, float v);
bool RackSetMappingRange(int trackId, int index, float rangeMin, float rangeMax);
int RackMappingCurve(int trackId, int index);
bool RackSetMappingCurve(int trackId, int index, int curve);
// Drum Rack per-pad shaping (choke group / tune semitones / decay 0..1) + kit swing/humanize.
void RackSetChainChoke(int trackId, int chain, int group);
int RackChainChoke(int trackId, int chain);
void RackSetChainTune(int trackId, int chain, int semitones);
int RackChainTune(int trackId, int chain);
void RackSetChainDecay(int trackId, int chain, float v);
float RackChainDecay(int trackId, int chain);
void RackSetSwing(int trackId, float v);
float RackSwing(int trackId);
void RackSetHumanize(int trackId, float v);
float RackHumanize(int trackId);
// --- Audio Effect Rack (a RackDevice in a track's device chain) --------
// Same surface, addressed by (trackId, deviceIndex). Add one via AddBuiltinDevice(trackId, 5).
int RackDevAddPluginChainDevice(int trackId, int deviceIndex, int chain, int catalogIndex);
int RackDevChainTriggerNote(int trackId, int deviceIndex, int chain);
void RackDevSetChainTriggerNote(int trackId, int deviceIndex, int chain, int note);
int RackDevChainCount(int trackId, int deviceIndex);
int RackDevAddChain(int trackId, int deviceIndex, int instKind);
bool RackDevRemoveChain(int trackId, int deviceIndex, int chain);
bool RackDevSetChainInstrument(int trackId, int deviceIndex, int chain, int instKind);
int RackDevChainInstrumentKind(int trackId, int deviceIndex, int chain);
string RackDevChainInstrumentName(int trackId, int deviceIndex, int chain);
int RackDevChainInstrumentParamCount(int trackId, int deviceIndex, int chain);
string RackDevChainInstrumentParamName(int trackId, int deviceIndex, int chain, int param);
float RackDevChainInstrumentParamGet(int trackId, int deviceIndex, int chain, int param);
void RackDevChainInstrumentParamSet(int trackId, int deviceIndex, int chain, int param, float normalized);
int RackDevChainDeviceCount(int trackId, int deviceIndex, int chain);
int RackDevAddChainDevice(int trackId, int deviceIndex, int chain, int deviceKind);
bool RackDevRemoveChainDevice(int trackId, int deviceIndex, int chain, int dev);
bool RackDevMoveChainDevice(int trackId, int deviceIndex, int chain, int fromIndex, int toIndex);
string RackDevChainDeviceName(int trackId, int deviceIndex, int chain, int dev);
int RackDevChainDeviceBuiltinKind(int trackId, int deviceIndex, int chain, int dev);
void RackDevOpenChainDeviceEditor(int trackId, int deviceIndex, int chain, int dev);
int RackDevChainDeviceParamCount(int trackId, int deviceIndex, int chain, int dev);
string RackDevChainDeviceParamName(int trackId, int deviceIndex, int chain, int dev, int param);
float RackDevChainDeviceParamMin(int trackId, int deviceIndex, int chain, int dev, int param);
float RackDevChainDeviceParamMax(int trackId, int deviceIndex, int chain, int dev, int param);
float RackDevChainDeviceParamGet(int trackId, int deviceIndex, int chain, int dev, int param);
void RackDevChainDeviceParamSet(int trackId, int deviceIndex, int chain, int dev, int param, float value);
void RackDevSetChainDeviceBypassed(int trackId, int deviceIndex, int chain, int dev, bool bypassed);
bool RackDevChainDeviceBypassed(int trackId, int deviceIndex, int chain, int dev);
// Chain-device telemetry (deviceIndex -1 = the track's Instrument Rack) — mirrors
// DeviceGainReduction / DeviceScope / DeviceLayerWave / DeviceText / DeviceAction.
float RackDevChainDeviceGainReduction(int trackId, int deviceIndex, int chain, int dev);
int RackDevChainDeviceScope(int trackId, int deviceIndex, int chain, int dev, float[] outSamples, int maxSamples);
int RackDevChainDeviceLayerWave(int trackId, int deviceIndex, int chain, int dev, int layer, float[] outSamples, int maxSamples);
string RackDevChainDeviceText(int trackId, int deviceIndex, int chain, int dev, int id);
void RackDevChainDeviceAction(int trackId, int deviceIndex, int chain, int dev, int id, int iarg, float farg);
void RackDevSetChainGain(int trackId, int deviceIndex, int chain, float v);
void RackDevSetChainPan(int trackId, int deviceIndex, int chain, float v);
void RackDevSetChainMute(int trackId, int deviceIndex, int chain, bool mute);
void RackDevSetChainSolo(int trackId, int deviceIndex, int chain, bool solo);
float RackDevChainGain(int trackId, int deviceIndex, int chain);
float RackDevChainPan(int trackId, int deviceIndex, int chain);
bool RackDevChainMute(int trackId, int deviceIndex, int chain);
bool RackDevChainSolo(int trackId, int deviceIndex, int chain);
float RackDevMacroGet(int trackId, int deviceIndex, int macro);
void RackDevMacroSet(int trackId, int deviceIndex, int macro, float v);
int RackDevAddMacroMapping(int trackId, int deviceIndex, int macro, int chain, int targetDevice, int paramIndex, float rangeMin, float rangeMax);
int RackDevMappingCount(int trackId, int deviceIndex);
bool RackDevTryGetMapping(int trackId, int deviceIndex, int index, out RackMacroMapping mapping);
bool RackDevRemoveMapping(int trackId, int deviceIndex, int index);
// Audio Effect Rack: rack-out (gain/dry-wet), routing (mode/PDC/chain selector), meter, select zone, macro names + mapping edit.
float RackDevChainMeter(int trackId, int deviceIndex, int chain);
void RackDevChainZone(int trackId, int deviceIndex, int chain, out int velLo, out int velHi);
void RackDevSetChainZone(int trackId, int deviceIndex, int chain, int velLo, int velHi);
string RackDevMacroName(int trackId, int deviceIndex, int macro);
void RackDevSetMacroName(int trackId, int deviceIndex, int macro, string name);
bool RackDevSetMappingRange(int trackId, int deviceIndex, int index, float rangeMin, float rangeMax);
int RackDevMappingCurve(int trackId, int deviceIndex, int index);
bool RackDevSetMappingCurve(int trackId, int deviceIndex, int index, int curve);
float RackDevVolume(int trackId, int deviceIndex);
void RackDevSetVolume(int trackId, int deviceIndex, float v);
int RackDevMode(int trackId, int deviceIndex);
void RackDevSetMode(int trackId, int deviceIndex, int mode);
// ---- racks inside racks (specs/041) ---------------------------------------------
// One level: a chain of a track's Instrument Rack may hold a Drum Rack, addressed by every
// RackDev* call as deviceIndex RackMacroMapping.NestedRackBase − chain. These are the Rack*
// calls the Drum Rack card makes, for any rack address.
int RackDevAddSamplerChain(int trackId, int deviceIndex, string path, int rootNote, bool loop);
bool RackDevSetChainSamplerSample(int trackId, int deviceIndex, int chain, string path, int rootNote);
int RackDevAddPluginInstrumentChain(int trackId, int deviceIndex, int catalogIndex);
string RackDevChainName(int trackId, int deviceIndex, int chain);
void RackDevSetChainName(int trackId, int deviceIndex, int chain, string name);
int RackDevChainChoke(int trackId, int deviceIndex, int chain);
void RackDevSetChainChoke(int trackId, int deviceIndex, int chain, int group);
int RackDevChainTune(int trackId, int deviceIndex, int chain);
void RackDevSetChainTune(int trackId, int deviceIndex, int chain, int semitones);
float RackDevChainDecay(int trackId, int deviceIndex, int chain);
void RackDevSetChainDecay(int trackId, int deviceIndex, int chain, float v);
float RackDevSwing(int trackId, int deviceIndex);
void RackDevSetSwing(int trackId, int deviceIndex, float v);
float RackDevHumanize(int trackId, int deviceIndex);
void RackDevSetHumanize(int trackId, int deviceIndex, float v);
bool RackDevChainSamplerInfo(int trackId, int deviceIndex, int chain, out NotaSamplerInfo info);
bool RackDevSetChainSamplerRoot(int trackId, int deviceIndex, int chain, int rootNote);
float RackDevChainSamplerPlayPosition(int trackId, int deviceIndex, int chain);
string RackDevChainInstrumentParamId(int trackId, int deviceIndex, int chain, int param);
float RackDevChainInstrumentParamDefault(int trackId, int deviceIndex, int chain, int param);
int RackDevChainInstrumentScope(int trackId, int deviceIndex, int chain, float[] outv);
int RackDevChainInstrumentVoiceCount(int trackId, int deviceIndex, int chain);
int RackDevChainInstrumentHeldNotes(int trackId, int deviceIndex, int chain, int[] outNotes);
void RackDevChainInstrumentAction(int trackId, int deviceIndex, int chain, int id, int iarg, float farg);
bool RackDevSetChainInstrumentStateUndoable(int trackId, int deviceIndex, int chain, byte[] data);
bool RackDevChainInstrumentRecordStateUndo(int trackId, int deviceIndex, int chain, byte[] before);
void RackDevOpenChainInstrumentEditor(int trackId, int deviceIndex, int chain);
string RackDevChainInstrumentPluginId(int trackId, int deviceIndex, int chain);
byte[] RackDevGetChainInstrumentState(int trackId, int deviceIndex, int chain);
/// <summary>Nota Mosaic as a chain instrument, as <see cref="MosaicSetProgram"/> & co. for a track.</summary>
bool RackDevChainMosaicSetProgram(int trackId, int deviceIndex, int chain, string text, bool undoable = true);
string RackDevChainMosaicProgram(int trackId, int deviceIndex, int chain);
bool RackDevTryGetChainMosaicStatus(int trackId, int deviceIndex, int chain, out NotaMosaicStatus status);
long RackDevChainMosaicZoneSampleId(int trackId, int deviceIndex, int chain, int zone);
// ---- MIDI Effect Rack (MIDI kind 6, specs/040; midiIndex = its MIDI effect index) and the
// MIDI effects in an Instrument Rack chain (#329). See nota_engine.h.
int RackChainMidiCount(int trackId, int chain);
int RackChainMidiAdd(int trackId, int chain, int midiKind);
bool RackChainMidiRemove(int trackId, int chain, int index);
bool RackChainMidiMove(int trackId, int chain, int fromIndex, int toIndex);
int RackChainMidiKind(int trackId, int chain, int index);
string RackChainMidiName(int trackId, int chain, int index);
int RackChainMidiParamCount(int trackId, int chain, int index);
string RackChainMidiParamName(int trackId, int chain, int index, int param);
float RackChainMidiParamMin(int trackId, int chain, int index, int param);
float RackChainMidiParamMax(int trackId, int chain, int index, int param);
float RackChainMidiParamGet(int trackId, int chain, int index, int param);
void RackChainMidiParamSet(int trackId, int chain, int index, int param, float value);
void RackChainMidiSetBypassed(int trackId, int chain, int index, bool bypassed);
bool RackChainMidiBypassed(int trackId, int chain, int index);
int RackChainMidiLastIn(int trackId, int chain, int index);
int RackChainMidiLastOut(int trackId, int chain, int index);
int RackChainMidiScope(int trackId, int chain, int index, float[] outv);
void RackChainMidiCommand(int trackId, int chain, int index, int cmd);
int MidiRackChainDeviceCount(int trackId, int midiIndex, int chain);
int MidiRackChainDeviceAdd(int trackId, int midiIndex, int chain, int midiKind);
bool MidiRackChainDeviceRemove(int trackId, int midiIndex, int chain, int index);
bool MidiRackChainDeviceMove(int trackId, int midiIndex, int chain, int fromIndex, int toIndex);
int MidiRackChainDeviceKind(int trackId, int midiIndex, int chain, int index);
string MidiRackChainDeviceName(int trackId, int midiIndex, int chain, int index);
int MidiRackChainDeviceParamCount(int trackId, int midiIndex, int chain, int index);
string MidiRackChainDeviceParamName(int trackId, int midiIndex, int chain, int index, int param);
float MidiRackChainDeviceParamMin(int trackId, int midiIndex, int chain, int index, int param);
float MidiRackChainDeviceParamMax(int trackId, int midiIndex, int chain, int index, int param);
float MidiRackChainDeviceParamGet(int trackId, int midiIndex, int chain, int index, int param);
void MidiRackChainDeviceParamSet(int trackId, int midiIndex, int chain, int index, int param, float value);
void MidiRackChainDeviceSetBypassed(int trackId, int midiIndex, int chain, int index, bool bypassed);
bool MidiRackChainDeviceBypassed(int trackId, int midiIndex, int chain, int index);
int MidiRackChainDeviceLastIn(int trackId, int midiIndex, int chain, int index);
int MidiRackChainDeviceLastOut(int trackId, int midiIndex, int chain, int index);
int MidiRackChainDeviceScope(int trackId, int midiIndex, int chain, int index, float[] outv);
void MidiRackChainDeviceCommand(int trackId, int midiIndex, int chain, int index, int cmd);
int MidiRackChainCount(int trackId, int midiIndex);
int MidiRackAddChain(int trackId, int midiIndex);
bool MidiRackRemoveChain(int trackId, int midiIndex, int chain);
int MidiRackDuplicateChain(int trackId, int midiIndex, int chain);
/// <summary>One undo step for the in-place edits that follow (chain mix, mode, selector,
/// output, macro values): forks the rack, keeping its MIDI effects and held notes.</summary>
bool MidiRackCheckpoint(int trackId, int midiIndex);
string MidiRackChainName(int trackId, int midiIndex, int chain);
void MidiRackSetChainName(int trackId, int midiIndex, int chain, string name);
void MidiRackSetChainMute(int trackId, int midiIndex, int chain, bool on);
bool MidiRackChainMute(int trackId, int midiIndex, int chain);
void MidiRackSetChainSolo(int trackId, int midiIndex, int chain, bool on);
bool MidiRackChainSolo(int trackId, int midiIndex, int chain);
void MidiRackSetChainZone(int trackId, int midiIndex, int chain, int keyLo, int keyHi, int velLo, int velHi);
void MidiRackChainZone(int trackId, int midiIndex, int chain, out int keyLo, out int keyHi, out int velLo, out int velHi);
void MidiRackSetChainSelect(int trackId, int midiIndex, int chain, int lo, int hi);
void MidiRackChainSelectRange(int trackId, int midiIndex, int chain, out int lo, out int hi);
void MidiRackSetChainTranspose(int trackId, int midiIndex, int chain, int semitones);
int MidiRackChainTranspose(int trackId, int midiIndex, int chain);
void MidiRackSetChainVelScale(int trackId, int midiIndex, int chain, float scale);
float MidiRackChainVelScale(int trackId, int midiIndex, int chain);
float MidiRackChainActivity(int trackId, int midiIndex, int chain);
void MidiRackSetMode(int trackId, int midiIndex, int mode);
int MidiRackMode(int trackId, int midiIndex);
void MidiRackSetSelector(int trackId, int midiIndex, float v);
float MidiRackSelector(int trackId, int midiIndex);
void MidiRackSetMerge(int trackId, int midiIndex, bool on);
bool MidiRackMerge(int trackId, int midiIndex);
void MidiRackSetThru(int trackId, int midiIndex, bool on);
bool MidiRackThru(int trackId, int midiIndex);
float MidiRackMacroGet(int trackId, int midiIndex, int macro);
void MidiRackMacroSet(int trackId, int midiIndex, int macro, float v);
string MidiRackMacroName(int trackId, int midiIndex, int macro);
void MidiRackSetMacroName(int trackId, int midiIndex, int macro, string name);
int MidiRackAddMacroMapping(int trackId, int midiIndex, int macro, int chain, int device, int param, float lo, float hi);
int MidiRackMappingCount(int trackId, int midiIndex);
int MidiRackMappingInfo(int trackId, int midiIndex, int index, out int macro, out int chain, out int device, out int param, out float lo, out float hi, out int curve);
bool MidiRackRemoveMapping(int trackId, int midiIndex, int index);
bool MidiRackSetMappingRange(int trackId, int midiIndex, int index, float lo, float hi);
bool MidiRackSetMappingCurve(int trackId, int midiIndex, int index, int curve);
int RackDevDuplicateChain(int trackId, int deviceIndex, int chain);
/// <summary>Rack chain devices on the shared device clipboard (specs/042); deviceIndex addresses
/// the rack as the other RackDev calls do (−1 Instrument/Drum Rack, ≥0 Audio Effect Rack,
/// −1000 − mi MIDI Effect Rack, NestedRackBase − chain). Paste returns the new index or −1 nothing,
/// −2 wrong family, −3 a rack in a rack, −5 MIDI past chain 16; each edit is one undo step.</summary>
/// <summary>One undo step for the in-place edits that follow on a rack (a fader drag, a mode or
/// switch change): forks the rack now, keeping its children and held notes.</summary>
bool RackDevCheckpoint(int trackId, int deviceIndex);
/// <summary>A chain's identity while chains move (0 = none); compare it, don't decode it.</summary>
long RackDevChainId(int trackId, int deviceIndex, int chain);
/// <summary>Loads a sample into a chain's Nota Grain (a Grain preset's source); one undo step.</summary>
bool RackDevChainGrainSetSample(int trackId, int deviceIndex, int chain, string path, int rootNote = 60);
bool RackDevChainDeviceCopy(int trackId, int deviceIndex, int chain, int index);
bool RackDevChainMidiCopy(int trackId, int deviceIndex, int chain, int index);
int RackDevChainDevicePaste(int trackId, int deviceIndex, int chain, int atIndex);
int RackDevChainMidiPaste(int trackId, int deviceIndex, int chain, int atIndex);
// Several devices on the clipboard into a chain (specs/044): the number pasted (>= 0), with the
// skipped count and the first new index per section (-1 none); -1 nothing / bad address, -3 clone failed.
int RackDevChainPasteDevices(int trackId, int deviceIndex, int chain, int midiAt, int fxAt, out int skipped, out int firstMidi, out int firstFx);
int RackDevChainDeviceDuplicate(int trackId, int deviceIndex, int chain, int index);
int RackDevChainMidiDuplicate(int trackId, int deviceIndex, int chain, int index);
int RackDevChainDeviceMoveTo(int trackId, int deviceIndex, int chain, int index, int toChain);
int RackDevChainMidiMoveTo(int trackId, int deviceIndex, int chain, int index, int toChain);
float RackDevDryWet(int trackId, int deviceIndex);
void RackDevSetDryWet(int trackId, int deviceIndex, float v);
bool RackDevPdc(int trackId, int deviceIndex);
void RackDevSetPdc(int trackId, int deviceIndex, bool on);
float RackDevChainSelect(int trackId, int deviceIndex);
void RackDevSetChainSelect(int trackId, int deviceIndex, float v);
bool RackDevSelFollow(int trackId, int deviceIndex);
void RackDevSetSelFollow(int trackId, int deviceIndex, bool on);
float RackDevLiveSelector(int trackId, int deviceIndex);
// --- Level meters (M6-2) -----------------------------------------------
bool TryGetTrackMeter(int trackId, out NotaMeter meter);
NotaMeter MasterMeter();
/// <summary>The Cue bus after the Cue level (specs/089).</summary>
NotaMeter CueMeter();
// --- MIDI clip notes ---------------------------------------------------
void SetClipNotes(int trackId, int clipIndex, NotaNote[] notes);
/// <summary>Live note update with no undo checkpoint (piano-roll drag pushing every frame).</summary>
void SetClipNotesLive(int trackId, int clipIndex, NotaNote[] notes);
NotaNote[] GetClipNotes(int trackId, int clipIndex);
/// <summary>Stores a note expression curve (recorded MPE) and returns its id for
/// <see cref="NotaNote.ExprId"/> (0 when there are no points). Ids live as long as the engine.</summary>
int CreateNoteExpression(NotaExprPoint[] points);
/// <summary>The curve behind an expression id (empty for 0 / unknown), per dim sorted by beat.</summary>
NotaExprPoint[] GetNoteExpression(int exprId);
// --- Live MIDI, arming & recording -------------------------------------
void SetTrackArmed(int trackId, bool armed);
void NoteOn(int pitch, float velocity);
void NoteOff(int pitch);
/// <summary>A live note addressed to one track, armed or not (Nota Remote: each phone plays
/// its own track). Recorded when that track holds the take. Safe to call from any thread.</summary>
void TrackNoteOn(int trackId, int pitch, float velocity);
void TrackNoteOff(int trackId, int pitch);
/// <summary>Per-note expression (MPE) for a live note: send it after the note-on (a note-on
/// resets it). Pitch −1 addresses the whole instrument, where Bend is the wheel −1..+1.</summary>
void NoteExpression(int pitch, NoteExpressionDim dim, float value);
void TrackNoteExpression(int trackId, int pitch, NoteExpressionDim dim, float value);
/// <summary>A live instrument-wide controller (<see cref="MidiController"/>): plays now and
/// is recorded into the take. The track form addresses one track.</summary>
void SendController(int ctl, float value);
void SendTrackController(int trackId, int ctl, float value);
/// <summary>The last controller value delivered to the track's instrument; NaN when none.</summary>
float DeliveredController(int trackId, int ctl);
/// <summary>Live notes also reach this track when unarmed (rack/drum pad audition). -1 = none.</summary>
void SetAuditionTrack(int trackId);
void SetRecording(bool enabled);
bool IsRecording { get; }
/// <summary>Discard the take in progress and record it again (#185, specs/078): nothing of
/// it stays, not even an undo step. The Arrangement goes back to where the transport was
/// started and counts in again if the take did; a Session slot records again from the next
/// launch quantum while everything else keeps playing.</summary>
RetryTakeResult RetryTake();
int RecordStartStatus { get; }
/// <summary>Track id of the in-progress audio take (0 when not capturing).</summary>
int AudioRecordTrackId { get; }
/// <summary>Beat where the in-progress audio take began.</summary>
double AudioRecordStartBeat { get; }
/// <summary>Length (beats) captured so far in the in-progress take (grows monotonically).</summary>
double AudioRecordLengthBeats { get; }
/// <summary>Reserved track id for the master effect chain (drive it via the track device ops).</summary>
int MasterTrackId { get; }
/// <summary>Live min/max peaks over the in-progress capture buffer (growing-take waveform). Returns buckets written.</summary>
int AudioRecordPeaks(float[] outMinMax, int maxPoints);
/// <summary>Every track the audio take is recording (specs/086: one take records every
/// armed audio track), and its live length / peaks per track.</summary>
int[] RecordingTracks();
double AudioRecordLengthBeatsOf(int trackId);
int AudioRecordPeaksOf(int trackId, float[] outMinMax, int maxPoints);
/// <summary>Armed tracks the last take start could not record, with why.</summary>
(int TrackId, RecordSkipReason Reason)[] RecordSkipped();
/// <summary>Tests: one take on every armed audio track from <paramref name="channels"/>-wide
/// device frames, through the real lane set-up; returns the lanes recorded.</summary>
int TakeRecordTestArmed(float[] interleaved, int channels, int frames, double startBeat);
/// <summary>Notes held into the in-progress MIDI take, for drawing them growing. Fills
/// <paramref name="buffer"/> and returns the count (0 when no MIDI take records); trackId is
/// the take's track (0 = none), sessionScene the Session scene (-1 = arrangement take),
/// nowBeat the capture clock — the held notes' right edge, running through the count-in.</summary>
int RecordHeldNotes(NotaRecordHeldNote[] buffer, out int trackId, out int sessionScene, out double nowBeat);
void Poll();
// --- Undo / redo (M6-6) ------------------------------------------------
bool Undo();
bool Redo();
bool CanUndo { get; }
bool CanRedo { get; }
/// <summary>Opens an undo group: the edits made until the matching
/// <see cref="EndUndoGroup"/> undo as one step. Nests.</summary>
void BeginUndoGroup();
void EndUndoGroup();
/// <summary>Forget the undo/redo history; the current state becomes the baseline.</summary>
void ClearUndoHistory();
// --- Pan law (specs/006) ---------------------------------------------
/// <summary>Project pan law (graph-level, undoable). See nota_engine_set_pan_law.</summary>
PanLaw PanLaw { get; }
/// <summary>Sets the project pan law; <paramref name="checkpoint"/> = false adds no undo
/// step (project load, the new-project baseline). No-op if unchanged.</summary>
void SetPanLaw(PanLaw law, bool checkpoint = true);
// --- Arrangement sections (specs/016) -------------------------------
/// <summary>The project's sections, sorted by start.</summary>
IReadOnlyList<SectionInfo> Sections { get; }
/// <summary>Replaces the sections (sorted; zero-length dropped). <paramref name="checkpoint"/>
/// = one undo step (an identical list makes none); false = baseline (project load).</summary>
void SetSections(IReadOnlyList<SectionInfo> sections, bool checkpoint = true);
/// <summary>Moves section <paramref name="index"/> (start order) with everything in its span
/// to boundary <paramref name="toBoundary"/> (0..Count: before section k, or after the last);
/// the sections in between shift by its length (specs/073). One undo step; false — nothing
/// changed — when out of range, overlapping, landing inside an overlap, or a no-op.</summary>
bool MoveSection(int index, int toBoundary);
/// <summary>Inserts a copy of the section and everything in its span right after it, moving
/// the rest of the song later (specs/073). One undo step; false as for <see cref="MoveSection"/>.</summary>
bool DuplicateSectionWithContent(int index);
/// <summary>Removes the section and everything in its span, moving the rest of the song
/// earlier (specs/073). One undo step; false as for <see cref="MoveSection"/>.</summary>
bool DeleteSectionWithContent(int index);
/// <summary>True when the section overlaps another: the with-content edits are unavailable.</summary>
bool SectionOverlaps(int index);
// --- Value undo (specs/009, specs/016) -------------------------------
/// <summary>Starts a gesture on volume / pan / master volume / device parameters: their
/// values now are what undo returns to. Returns a handle (0 = no valid target).</summary>
int BeginMixGesture(params MixTarget[] targets);
/// <summary>Ends the gesture: one undo step for whatever it changed (none → no step).</summary>
void EndMixGesture(int handle);
/// <summary>The engine's master volume (linear) — follows undo/redo.</summary>
float MasterVolume { get; }
// --- Stereo Map (specs/008) ------------------------------------------
/// <summary>Fills <paramref name="buffer"/> with one row per non-group track (track order)
/// and the master last; returns the total row count (grow the buffer if larger).</summary>
int GetStereoMeasures(StereoMeasure[] buffer);
// --- Project load (M7-6) -----------------------------------------------
void Reset();
int TrackInstrumentKind(int trackId);
/// <summary>Which instrument the track holds (specs/043): the same while it is edited, moved or
/// brought back by undo; another for a new, replaced or pasted one. 0 = none. Compare only.</summary>
long TrackInstrumentId(int trackId);
/// <summary>The track's instrument responds to per-note expression (MPE).</summary>
bool TrackInstrumentSupportsMpe(int trackId);
int TrackDeviceBuiltinKind(int trackId, int deviceIndex);
/// <summary>Which audio effect sits in the slot (#540): the same while it is edited, moved or
/// brought back by undo; another for a new, pasted or duplicated one. 0 = none. Compare only.</summary>
long TrackDeviceId(int trackId, int deviceIndex);
string TrackInstrumentPluginId(int trackId);
string TrackDevicePluginId(int trackId, int deviceIndex);
// --- Audio persistence (M7-6b) -----------------------------------------
bool TryGetAudioClipInfo(int trackId, int clipIndex, out NotaAudioClipInfo info);
int AddAudioClipEx(int trackId, string path, double startBeat, double sourceOffsetFrames, long lengthFrames, float gain);
// --- Take lanes (specs/067) --------------------------------------------
/// <summary>The takes on an audio track, in recording order.</summary>
int TakeCount(int trackId);
bool TryGetTakeInfo(int trackId, int index, out NotaTakeInfo info);
/// <summary>Min/max peaks over the take's recorded range; buckets written.</summary>
int GetTakePeaks(int trackId, int index, float[] outMinMax, int maxPoints);
/// <summary>The take plays over [startBeat, endBeat) (clamped to it). One undo step; false if nothing changed.</summary>
bool CompTake(int trackId, int takeId, double startBeat, double endBeat);
/// <summary>Removes a take; what plays is unchanged. One undo step.</summary>
bool DeleteTake(int trackId, int takeId);
/// <summary>Each recording's comp becomes one clip and its takes go. One undo step.</summary>
bool FlattenTakes(int trackId);
/// <summary>The take an arrangement audio clip plays a section of; 0 = none.</summary>
int ClipTakeId(int trackId, int clipIndex);
/// <summary>Project load (no undo entry): a take from a file; its new id, or -1.</summary>
int RestoreTake(int trackId, string path, int number, int group, double originBeat, double sourceOffsetFrames, long lengthFrames);
/// <summary>Project load (no undo entry): tag a restored clip as a section of a restored take.</summary>
void SetClipTakeId(int trackId, int clipIndex, int takeId);
/// <summary>The ends of an arrangement audio clip that play at full level (1 head, 2 tail):
/// a take join, or one a flatten kept. 0 = both ends fade.</summary>
int ClipJoinedEdges(int trackId, int clipIndex);
/// <summary>Project load (no undo entry): the saved <see cref="ClipJoinedEdges"/> of the track's
/// first clips. A join is kept only where both clips still meet.</summary>
void RestoreJoinedEdges(int trackId, int[] edges);
bool TryGetSampleInfo(long sampleId, out NotaSampleInfo info);
float[] ReadSample(long sampleId);
bool TryGetSamplerInfo(int trackId, out NotaSamplerInfo info);
bool TryGetSessionAudioSlot(int trackId, int scene, out NotaSessionAudioSlot info);
bool AddSessionAudioClip(int trackId, int scene, string path, double lengthBeats, double sourceOffsetFrames, long lengthFrames, float gain);
bool AddSessionAudioFile(int trackId, int scene, string path);
// --- Offline render (tests / export) -----------------------------------
void RenderOffline(float[] outBuffer, int frames);
void RenderOffline(float[] outBuffer, int frames, double sampleRate);
// --- Audio device settings (M7-1) --------------------------------------
void SetAudioOutputDevice(string uid);
void SetAudioInputDevice(string uid);
void SetAudioSampleRate(double sampleRate);
void SetAudioBufferFrames(int frames);
/// <summary>Stage WASAPI exclusive mode (Windows only; ignored elsewhere). Apply with <see cref="ApplyAudio"/>.</summary>
void SetAudioWasapiExclusive(bool on);
(string OutputUid, string InputUid, double SampleRate, int BufferFrames, bool WasapiExclusive) GetAudioConfig();
void ApplyAudio();
double NegotiatedSampleRate { get; }
int NegotiatedBufferFrames { get; }
/// <summary>True if the last <see cref="ApplyAudio"/> requested WASAPI exclusive but the device refused
/// it and the backend fell back to shared. Always false on platforms without exclusive mode.</summary>
bool AudioExclusiveFallback { get; }
/// <summary>True when no output device opened and the engine runs on a silent stand-in.</summary>
bool AudioSilentFallback { get; }
// --- ASIO (Windows; specs/049) -----------------------------------------
// Staged like the device settings; ApplyAudio() persists and restarts. No-ops off Windows.
AudioSystem AudioSystem { get; }
/// <summary>What actually runs: WASAPI after a failed ASIO start fell back.</summary>
AudioSystem ActiveAudioSystem { get; }
bool AsioAvailable { get; }
/// <summary>Installed ASIO drivers (re-scanned): Uid = CLSID, Name = display name.</summary>
IReadOnlyList<AudioDevice> AsioDrivers();
void SetAudioSystem(AudioSystem system);
void SetAsioDriver(string id);
string AsioDriver { get; }
/// <summary>The uid of the input device the staged config opens: the chosen device when it
/// is connected, else the system default ("" when there is none). Per-device input settings
/// key on it, so "System default" and a missing device never share another's (specs/086).</summary>
string EffectiveInputUid();
/// <summary>The same for the output device: per-device output setups key on it (specs/089).</summary>
string EffectiveOutputUid();
/// <summary>Channel names of the open ASIO driver; empty when ASIO isn't running.</summary>
IReadOnlyList<string> AsioChannels(bool input);
int AsioPair(bool input);
void SetAsioPair(bool input, int firstChannel);
bool OpenAsioControlPanel();
/// <summary>The driver's panel is open: an apply now would wait for it, so hold it back.</summary>
bool AsioPanelOpen { get; }
AudioDeviceEvent PollDeviceEvent();
string AudioFallbackReason { get; }
int InputLatencyFrames { get; }
int OutputLatencyFrames { get; }
// --- MIDI device settings (M7-2) ---------------------------------------
bool IsMidiInputEnabled(string uid);
void SetMidiInputEnabled(string uid, bool enabled);
(bool Enabled, int BendRange) GetMpe();
void SetMpe(bool enabled, int bendRange);
void ApplyMidi();
// --- MIDI learn: drain incoming CC/note-on events (4 int32 per event) ---
int PollMidiControlEvents(int[] quadBuffer);
// --- gamepad input (live note source) ----------------------------------
// Poll-driven: the UI ticks PollGamepadEvents and turns each edge into
// NoteOn/NoteOff — the same entry points the computer keyboard uses, so
// armed-track recording and the piano-roll highlight apply unchanged.
void GamepadStart();
void GamepadStop();
int GamepadCount { get; }
IReadOnlyList<GamepadDevice> Gamepads();
int PollGamepadEvents(GamepadButtonEvent[] buffer);
/// <summary>Latest position of every axis on <paramref name="pad"/>, written into
/// <paramref name="buffer"/> in <see cref="GamepadAxis"/> order as 0..127. Returns the
/// count written (0 for an out-of-range pad). Sampled rather than queued: a stick
/// would flood an event ring and only its latest position matters.</summary>
int GamepadAxisValues(int pad, int[] buffer);
// --- Audio preview / audition (M7-4a) ----------------------------------
void PreviewFile(string path);
/// <summary>Auditions <paramref name="path"/> from <paramref name="startSeconds"/> in;
/// the file already loaded is reused without a re-decode (waveform seek).</summary>
void PreviewFileAt(string path, double startSeconds);
void StopPreview();
bool IsPreviewActive { get; }
/// <summary>Loop the audition until stopped.</summary>
void SetPreviewLoop(bool on);
/// <summary>Audition level as linear gain (1 = unity).</summary>
void SetPreviewGain(float gain);
/// <summary>Audition playhead, seconds into the file.</summary>
double PreviewPosition { get; }
bool PreviewSelfTest();
/// <summary>The last <paramref name="output"/>.Length (≤ 4096) mono samples the preview
/// voice played, oldest first. Returns the count written.</summary>
int ReadPreviewScope(float[] output);
// --- Preset audition ------------------------------------------------------
/// <summary>A fresh offline audition chain at the engine's sample rate (see
/// <see cref="IAuditionRig"/>). Safe to call from any thread.</summary>
IAuditionRig CreateAuditionRig();
/// <summary>UI thread: keeps a rendered rig's audio under <paramref name="key"/> (small LRU).</summary>
void StoreAudition(IAuditionRig rig, string key);
bool IsAuditionCached(string key);
/// <summary>Plays the cached audition from <paramref name="startSeconds"/>; false = not cached.</summary>
bool PreviewAuditionAt(string key, double startSeconds);
// --- xrun / dropout telemetry (M7-8) -----------------------------------
int XrunCount { get; }
bool XrunSelfTest();
// --- Parameter automation (M9) -----------------------------------------
// Lanes are structural (snapshot + undo). AddAutomationLane returns the lane
// index, reusing an existing lane on the same target.
bool AutomationSelfTest();
bool AutomationCurveSelfTest(); // M9-D: device-free curvature check
bool PluginAutomationSelfTest(); // M9-B: device-free structural check
// Hosted-plugin params (M9-B): deviceIndex < 0 = the instrument. Values 0..1,
// identified by a stable string paramID.
int PluginParamCount(int trackId, int deviceIndex);
string PluginParamId(int trackId, int deviceIndex, int paramIndex);
// A param index saved before Nota Twin's layout grew (#531), as it is today; others unchanged.
int PluginParamIndexFromV1(int trackId, int deviceIndex, int paramIndex);
string PluginParamName(int trackId, int deviceIndex, int paramIndex);
float PluginParamGet(int trackId, int deviceIndex, int paramIndex);
/// <summary>The plugin's own text for a param's current value ("−12.0 dB"), or "" when it has none.</summary>
string PluginParamText(int trackId, int deviceIndex, int paramIndex);
/// <summary>The plugin's default for a param, normalized 0..1.</summary>
float PluginParamDefault(int trackId, int deviceIndex, int paramIndex);
void PluginParamSet(int trackId, int deviceIndex, int paramIndex, float normalized);
int AddPluginAutomationLane(int trackId, int deviceIndex, string paramId);
string AutomationLaneParamId(int trackId, int laneIndex);
// A lane on a device grouped into a rack (specs/044): (chain index, slot) in the rack at the
// lane's device index; (-1, -1) for a track-level lane. AddNested is for project load.
(int Chain, int Slot) AutomationLanePath(int trackId, int laneIndex);
int AddNestedAutomationLane(int trackId, AutomationTarget target, int deviceIndex, int chain, int slot, int paramIndex, string? paramId);
int PluginLastTouchedParam(int trackId, int deviceIndex); // "Learn" (M9-B3)
bool AutomationWriteSelfTest(); // M9-C: device-free write-path check
bool AutomationDeviceRemapSelfTest(); // lanes follow their device on reorder / remove
// Automation record (M9-C). There are no record modes: lanes always play back, and
// a control gesture records while automation record is on (the transport record
// button drives it). deviceIndex < 0 = instrument; paramId for PluginParam.
void SetAutomationRecord(bool on);
bool AutomationRecording { get; }
/// <summary><paramref name="latch"/> marks a hardware/MIDI control: it keeps writing past
/// the release until the transport stops. Mouse gestures pass false.</summary>
void BeginAutomationWrite(int trackId, AutomationTarget target, int deviceIndex, int paramIndex, string paramId, bool latch = false);
/// <summary>Raised (UI thread) when a control begins an automation-write gesture, so the
/// arrangement can follow the touched param in automation mode. Args: trackId, target,
/// deviceIndex, paramIndex, paramId.</summary>
event System.Action<int, AutomationTarget, int, int, string>? AutomationTouched;
void EndAutomationWrite(int trackId, AutomationTarget target, int deviceIndex, int paramIndex, string paramId);
/// <summary>Hand every lane a hand-moved control took over back to playback.</summary>
void ReenableAutomation();
bool AutomationOverridden { get; }
int AddAutomationLane(int trackId, AutomationTarget target, int deviceIndex, int paramIndex);
int AutomationLaneCount(int trackId);
AutomationLaneInfo AutomationLaneInfo(int trackId, int laneIndex);
AutomationPoint[] GetAutomationPoints(int trackId, int laneIndex);
void SetAutomationPoints(int trackId, int laneIndex, AutomationPoint[] points);
/// <summary>Set a lane's points without an undo checkpoint — for real-time updates while
/// dragging a point (the caller checkpoints once at drag start, commits via the undo path on release).</summary>
void SetAutomationPointsLive(int trackId, int laneIndex, AutomationPoint[] points);
void RemoveAutomationLane(int trackId, int laneIndex);
/// <summary>Master-volume automation (graph-level, not tied to a track).</summary>
AutomationPoint[] GetMasterVolumeAutomation();
void SetMasterVolumeAutomation(AutomationPoint[] points);
/// <summary>Per-clip volume envelope for an audio clip (0..1, clip-local beats).</summary>
AutomationPoint[] GetClipVolumeEnvelope(int trackId, int clipIndex);
void SetClipVolumeEnvelope(int trackId, int clipIndex, AutomationPoint[] points);
/// <summary>Per-clip pan envelope for an audio clip (-1..1, clip-local beats).</summary>
AutomationPoint[] GetClipPanEnvelope(int trackId, int clipIndex);
void SetClipPanEnvelope(int trackId, int clipIndex, AutomationPoint[] points);
/// <summary>MIDI clip envelope (velocity or volume; 0..1, clip-local beats).</summary>
AutomationPoint[] GetMidiClipEnvelope(int trackId, int clipIndex, MidiClipEnvelope kind);
void SetMidiClipEnvelope(int trackId, int clipIndex, MidiClipEnvelope kind, AutomationPoint[] points);
/// <summary>The controllers (<see cref="MidiController"/> ids, ascending) a MIDI clip holds
/// curves for, and each curve (clip-local beats). Set replaces it — empty removes; one undo
/// step. The Session forms address a slot's clip.</summary>
int[] GetMidiClipControllers(int trackId, int clipIndex);
AutomationPoint[] GetMidiClipController(int trackId, int clipIndex, int ctl);
void SetMidiClipController(int trackId, int clipIndex, int ctl, AutomationPoint[] points);
int[] GetSessionControllers(int trackId, int scene);
AutomationPoint[] GetSessionController(int trackId, int scene, int ctl);
void SetSessionController(int trackId, int scene, int ctl, AutomationPoint[] points);
/// <summary>Smoothed real-time DSP load, 0..1 (0 when no live device runs).</summary>
float CpuLoad { get; }
// --- CV modulation (Phase 3, Modular editor) ---------------------------
// Modulator (LFO) sources + CV links to built-in device params on the same track.
// Modulator field selector: 0 waveform, 1 tempoSync, 2 rateHz, 3 rateSyncBeats,
// 4 depth, 5 phase. CV modes: 0 Add, 1 Multiply, 2 Override.
int ModulatorAdd(int trackId, int kind);
void ModulatorRemove(int trackId, int modId);
int ModulatorCount(int trackId);
int ModulatorIdAt(int trackId, int index);
int ModulatorKind(int trackId, int modId);
float ModulatorGet(int trackId, int modId, int field);
void ModulatorSet(int trackId, int modId, int field, float value);
/// <summary>Live modulator output at the current transport position (for the node viz), -1..1×depth.</summary>
float ModulatorValue(int trackId, int modId);
/// <summary>Rolling CV history for a Scope modulator: the newest values, oldest→newest; returns count.</summary>
int ModulatorScope(int trackId, int modId, float[] outv);
/// <summary>Scope history with time steps (specs/047): the newest entries oldest→newest, and the
/// seconds each one follows the previous by (one audio block). Returns the count.</summary>
int ModulatorScopeTimed(int trackId, int modId, float[] values, float[] dts);
// ---- preset tags (specs/048) ----
/// <summary>The device's preset tag: 0 none, -1 no such device.</summary>
int DevicePresetTag(int trackId, PresetSurface surface, int index);
/// <summary>Tag the device with a preset (empty id = Init, clears it). <paramref name="loaded"/>
/// = the values the preset left (null = what the device holds now). No undo step of its own:
/// set it inside a mix gesture with a <see cref="MixTarget.PresetTag"/> target.</summary>
int SetDevicePresetTag(int trackId, PresetSurface surface, int index, string presetId, string name, float[]? loaded = null);
PresetTag? PresetTagInfo(int tag);
/// <summary>1 when a sound parameter moved away from the preset's values, 0 when not, -1 with no tag.</summary>
int DevicePresetModified(int trackId, PresetSurface surface, int index);
int CvLinkAdd(int trackId, int modId, int deviceIndex, int paramIndex);
/// <summary>Cross-track link: modulator on trackId modulates a param on targetTrack (-1 = self).</summary>
int CvLinkAddTo(int trackId, int modId, int targetTrack, int deviceIndex, int paramIndex);
/// <summary>Param → param link: a source param (srcDevice/srcParam on trackId) drives a target param.</summary>
int CvLinkAddFromParam(int trackId, int srcDevice, int srcParam, int targetTrack, int targetDevice, int targetParam);
/// <summary>Target-kind variant (0 device, 1 instrument [dev=-1], 2 MIDI-FX) for a modulator source.</summary>
int CvLinkAddToTarget(int trackId, int modId, int targetKind, int targetTrack, int targetDevice, int targetParam);
int CvLinkAddFromParamToTarget(int trackId, int srcDevice, int srcParam, int targetKind, int targetTrack, int targetDevice, int targetParam);
int CvLinkTargetKind(int trackId, int index);
/// <summary>True if (targetKind, track, device, param) is a modulation target.</summary>
bool ParamModulated(int targetKind, int trackId, int deviceIndex, int paramIndex);
void CvLinkRemove(int trackId, int index);
int CvLinkCount(int trackId);
int CvLinkSource(int trackId, int index);
/// <summary>CV source kind: 0 = modulator, 1 = parameter.</summary>
int CvLinkSourceKind(int trackId, int index);
int CvLinkSourceDevice(int trackId, int index);
int CvLinkSourceParam(int trackId, int index);
/// <summary>Target track id of a link (-1 = the modulator's own track).</summary>
int CvLinkTargetTrack(int trackId, int index);
int CvLinkDevice(int trackId, int index);
int CvLinkParam(int trackId, int index);
// Links reaching into a rack (specs/044): chain index + slot of the source / target, -1 at
// track level. AddNested is for project load (kinds as CvLinkAddFromParamToTarget).
CvLinkPath CvLinkPath(int trackId, int index);
int CvLinkAddNested(int trackId, int sourceKind, int modId, int srcDevice, int srcChain, int srcSlot, int srcParam,
int targetKind, int targetTrack, int targetDevice, int tgtChain, int tgtSlot, int targetParam);
float CvLinkDepth(int trackId, int index);
int CvLinkMode(int trackId, int index);
void SetCvLinkDepth(int trackId, int index, float depth);
void SetCvLinkMode(int trackId, int index, int mode);
/// <summary>Modulation centre (base) value the link swings around; edited by the UI.</summary>
float CvLinkBase(int trackId, int index);
void SetCvLinkBase(int trackId, int index, float baseValue);
bool DeviceParamModulated(int trackId, int deviceIndex, int paramIndex);
}