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.
//
// Engine contract data: the blittable value types the audio-engine port exchanges
// with callers. They mirror the native structs 1:1 and carry [StructLayout] so the
// Infrastructure P/Invoke layer can marshal them without a copy. Kept in the
// Application layer (not Infrastructure) so IAudioEngine — and the ViewModels that
// depend on it — never reach across into Infrastructure.
using System.Runtime.InteropServices;
namespace Nota.Application;
/// <summary>What <see cref="IAudioEngine.RetryTake"/> did (specs/078).</summary>
public enum RetryTakeResult
{
/// <summary>Recording could not start again after the take was discarded (see RecordStartStatus).</summary>
Failed = -1,
/// <summary>Nothing was recording: nothing changed.</summary>
None = 0,
/// <summary>An Arrangement take was discarded and records again.</summary>
Arrangement = 1,
/// <summary>A Session slot take was discarded and records again from the next launch quantum.</summary>
Session = 2,
}
/// <summary>A MIDI note, blittable and laid out to match the native NotaNoteData
/// struct. Times are in beats, relative to the containing clip's start.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaNote(int pitch, double startBeat, double lengthBeats, float velocity)
{
public int Pitch = pitch;
public double StartBeat = startBeat;
public double LengthBeats = lengthBeats;
public float Velocity = velocity;
/// <summary>The note's recorded MPE in the engine's expression store (0 = none). Copy the
/// note (don't rebuild it from its fields) and the expression travels with it.</summary>
public int ExprId;
/// <summary>The note's articulation: a stable id in its track's articulation map (0 = none /
/// the map's default). Copy the note (don't rebuild it from its fields) and it travels with it.</summary>
public int ArticulationId;
/// <summary>Every field equal. Use this to tell whether an edit changed a note: a comparison
/// that lists fields by hand misses the next one added (an articulation-only edit was once
/// never sent to the engine for that reason). The smoke test checks it covers every field.</summary>
public static bool Same(in NotaNote a, in NotaNote b) =>
a.Pitch == b.Pitch && a.StartBeat == b.StartBeat && a.LengthBeats == b.LengthBeats
&& a.Velocity == b.Velocity && a.ExprId == b.ExprId && a.ArticulationId == b.ArticulationId;
}
/// <summary>One articulation of a compiled articulation map (specs/085). Matches native
/// NotaArticulationEntry: ids > 0 and strictly ascending; actions are [ActionStart, ActionStart + ActionCount).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaArticulationEntry
{
public int Id;
/// <summary>0 latching, 1 momentary.</summary>
public int TriggerMode;
public double OffsetMs;
public double LeadMs;
public int ActionStart;
public int ActionCount;
}
/// <summary>One MIDI action of a compiled articulation map. Matches native NotaArticulationAction.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaArticulationAction
{
/// <summary>0 keyswitch, 1 control change, 2 program change, 3 bank select MSB, 4 bank select LSB.</summary>
public int Kind;
/// <summary>0 = the note's own channel, 1..16 explicit.</summary>
public int Channel;
public int Data1;
public int Data2;
}
/// <summary>One breakpoint of a note's recorded expression (MPE). Matches native NotaExprPoint:
/// Beat is the offset from the note's start; Value is semitones for Bend, 0..1 otherwise.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaExprPoint(NoteExpressionDim dim, float beat, float value)
{
public NoteExpressionDim Dim = dim;
public float Beat = beat;
public float Value = value;
}
/// <summary>A note held into the in-progress MIDI take (live-recording preview). Matches native
/// NotaRecordHeldNote. StartBeat is an absolute timeline beat for an arrangement take (it may
/// precede the take's clip and be negative — played on the count-in), slot-local for Session.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaRecordHeldNote
{
public int Pitch;
public int Source; // 0 live input, 1 routed MIDI ("MIDI In")
public double StartBeat;
public float Velocity;
}
/// <summary>Track summary for the Arrangement View. Matches native NotaTrackInfo.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaTrackInfo
{
public int Id;
public int Type; // 0 = audio, 1 = instrument, 2 = return bus (M6-1), 3 = group
public int ClipCount;
public int Muted;
public int Soloed;
public int Armed;
public float Volume;
public float Pan;
public int GroupId; // parent group track id, or -1 (top-level)
public readonly bool IsInstrument => Type == 1;
public readonly bool IsReturn => Type == 2;
public readonly bool IsGroup => Type == 3;
}
/// <summary>Clip geometry on the timeline. Matches native NotaClipInfo.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaClipInfo
{
public double StartBeat;
public double LengthBeats;
public int Kind; // 0 = audio, 1 = midi
public int Active; // 1 = plays, 0 = deactivated (key 0): stays on the timeline but silent
public readonly bool IsMidi => Kind == 1;
public readonly bool IsActive => Active != 0;
}
/// <summary>Full audio-clip geometry for project save. Matches native NotaAudioClipInfo (M7-6b).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaAudioClipInfo
{
public double StartBeat;
public double SourceOffsetFrames;
public long LengthFrames; // 0 = to end of sample
public float Gain;
public long SampleId; // 0 = none
public float PitchSemitones; // varispeed transpose (M-audio-editor)
public int WarpEnabled; // 0/1
public int WarpMode; // 0 Beats,1 Tones,2 Texture,3 Complex,4 ComplexPro,5 RePitch
public double WarpBeats; // full warped material length in beats (0 when unwarped)
public double WarpPlayStart; // trimmed play window start (beats within the warp)
public double WarpPlayEnd; // trimmed play window end (0 = to WarpBeats)
public int Reversed; // 0/1: plays back-to-front (non-destructive)
}
/// <summary>One take of an audio loop recording (specs/067). Matches native NotaTakeInfo. Every
/// take of a recording has a loop-length buffer whose frame 0 sits at <see cref="OriginBeat"/>;
/// the pass recorded <see cref="StartBeat"/> .. + <see cref="LengthBeats"/> of it.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaTakeInfo
{
public int Id; // comp clips carry it (IAudioEngine.ClipTakeId)
public int Number; // "Take N" on its track
public int Group; // the loop recording it came from
public int Reserved;
public double OriginBeat;
public double StartBeat;
public double LengthBeats;
public double SourceOffsetFrames;
public long LengthFrames;
public long SampleId;
}
/// <summary>Audio-clip ADSR amplitude shape in played time (clip-local beats). Matches native
/// NotaClipAdsr. Attack ramps 0→1 from the clip start when a decay follows, and straight to
/// <see cref="Sustain"/> when decay is 0, so a split that cleared the decay does not click.
/// Decay falls to <see cref="Sustain"/>, release fades to 0 over the clip's last
/// <see cref="ReleaseBeats"/>. <see cref="Identity"/> (the default for every clip) plays the
/// sample at its full length and level.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct ClipAdsr
{
public double AttackBeats;
public double DecayBeats;
public double ReleaseBeats;
public float Sustain; // 0..1 linear gain
public int Reserved;
public static ClipAdsr Identity => new() { Sustain = 1f };
public readonly bool IsIdentity => AttackBeats <= 0 && DecayBeats <= 0 && ReleaseBeats <= 0 && Sustain >= 1f;
/// <summary>Gain at clip-local beat <paramref name="t"/> of a clip <paramref name="len"/> beats
/// long — the same shape the engine renders (see Track.h ClipAdsr::gainAt).</summary>
public readonly double GainAt(double t, double len)
{
double g = DecayBeats <= 0
? AttackBeats > 0 && t < AttackBeats ? Sustain * (t / AttackBeats) : Sustain
: t < AttackBeats ? (AttackBeats > 0 ? t / AttackBeats : 0)
: t < AttackBeats + DecayBeats ? 1 - (1 - Sustain) * ((t - AttackBeats) / DecayBeats)
: Sustain;
if (ReleaseBeats > 0 && t > len - ReleaseBeats) g *= Math.Max(0, (len - t) / ReleaseBeats);
return Math.Clamp(g, 0, 1);
}
/// <summary>Fits the stages into a clip <paramref name="len"/> beats long: attack+decay and
/// release each stay within the clip and never cross each other.</summary>
public readonly ClipAdsr Fit(double len)
{
var a = this;
len = Math.Max(0, len);
a.Sustain = Math.Clamp(a.Sustain, 0f, 1f);
a.AttackBeats = Math.Clamp(a.AttackBeats, 0, len);
a.DecayBeats = Math.Clamp(a.DecayBeats, 0, len - a.AttackBeats);
a.ReleaseBeats = Math.Clamp(a.ReleaseBeats, 0, len - a.AttackBeats - a.DecayBeats);
return a;
}
}
/// <summary>Decoded-sample metadata. Matches native NotaSampleInfo (M7-6b).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaSampleInfo
{
public int Channels;
public long Frames;
public double SampleRate;
}
/// <summary>Built-in Sampler settings. Matches native NotaSamplerInfo (M7-6b).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaSamplerInfo
{
public long SampleId;
public int RootNote;
public int Loop; // 0/1
}
/// <summary>Nota Mosaic's loading state. Matches native NotaMosaicStatus. State: 0 empty ·
/// 1 loading · 2 ready; Disk* are the files' bytes on disk (progress), RamBytes the decoded
/// samples' size; Missing = files that didn't decode.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaMosaicStatus
{
public int State;
public int FilesDone;
public int FilesTotal;
public int Missing;
public int Zones;
public int Serial; // changes whenever another program is set
public long DiskDone;
public long DiskTotal;
public long RamBytes;
}
/// <summary>A Nota Aurora custom wavetable, as the engine reports it (specs/053): its frame
/// count (0 = the slot is empty), how the file was read (0 wavetable file, 1 single cycle,
/// 2 recording), whether it was cut to 60 s or 256 frames, and, for a track's slot, the source
/// flag and whether a project could not restore it (then <see cref="Name"/> is the name it had).
/// <see cref="Serial"/> changes whenever the slot's table does; <see cref="Hash"/> is the
/// engine's 128-bit content hash of the frames, as hex.</summary>
public readonly record struct AuroraTableInfo(int Frames, int Origin, bool TruncatedLength, bool TruncatedFrames,
bool UseCustom, bool Missing, uint Serial, string Hash, string Name)
{
public bool HasTable => Frames > 0;
}
/// <summary>Results of the Aurora table builders (native NOTA_AURORA_*).</summary>
public static class AuroraTableResult
{
public const int Ok = 0, ErrDecode = -1, ErrFormat = -2, ErrSilent = -3, ErrEmpty = -4, ErrArgs = -5;
}
/// <summary>Captured session audio take. Matches native NotaSessionAudioSlot (M7-6b).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaSessionAudioSlot
{
public long SampleId;
public double LengthBeats;
public double SourceOffsetFrames;
public long LengthFrames;
public float Gain;
}
/// <summary>Session audio slots edit through the audio-clip API: a slot's take is the clip at
/// index <c>-(scene + 2)</c> on its track (arrangement clips are >= 0). Matches the engine's
/// kSessionClipBase addressing.</summary>
public static class SessionClip
{
public const int Base = -2;
public static int Index(int scene) => Base - scene;
/// <summary>The scene a clip index addresses, or -1 for an arrangement clip.</summary>
public static int SceneOf(int clipIndex) => clipIndex <= Base ? Base - clipIndex : -1;
}
/// <summary>How a session clip reacts to its launch button (Session P0).</summary>
public enum SessionLaunchMode { Trigger = 0, Gate = 1, Toggle = 2, Repeat = 3 }
/// <summary>What a session clip does once it has played its follow time (Session P0).</summary>
public enum SessionFollowAction { None = 0, Stop, Again, Previous, Next, First, Last, Any, Other, Jump }
/// <summary>Session clip (slot) properties. Matches native NotaSessionClipProps (Session P0).
/// Color is a track-palette index (-1 = the track's colour); QuantBeats < 0 = global;
/// ChanceA/B are relative weights 0..100; FollowBeats 0 = one pass.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaSessionClipProps
{
public int Color;
public int LaunchMode;
public double QuantBeats;
public int Legato;
public int Loop;
public float VelocityAmount;
public int FollowA;
public int FollowB;
public int ChanceA;
public int ChanceB;
public double FollowBeats;
public int JumpScene;
}
/// <summary>Scene row properties. Matches native NotaSceneProps (Session P0). Color is a
/// track-palette index (-1 = neutral); Tempo / SigNum+SigDen > 0 apply on launch.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaSceneProps
{
public int Color;
public double Tempo;
public int SigNum;
public int SigDen;
public int Follow;
public double FollowBeats;
}
/// <summary>Post-fader level meter (linear 0..1). Matches native NotaMeter (M6-2).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct NotaMeter
{
public float PeakL;
public float PeakR;
public float RmsL;
public float RmsR;
public readonly float Peak => PeakL > PeakR ? PeakL : PeakR;
public readonly float Rms => RmsL > RmsR ? RmsL : RmsR;
}
/// <summary>What a parameter-automation lane drives (M9). Matches native AutomationTarget.
/// <see cref="Send"/> (specs/072) is a track's send level into the return bus held in the
/// lane's device index (0..3), values 0..1.</summary>
public enum AutomationTarget { Volume = 0, Pan = 1, DeviceParam = 2, PluginParam = 3, MidiDeviceParam = 4, Send = 5 }
/// <summary>What a device transfer (specs/043) moves: an audio effect, a MIDI effect or the
/// track's instrument. Matches nota_track_transfer_device's family.</summary>
public enum DeviceFamily { Audio = 0, Midi = 1, Instrument = 2 }
/// <summary>What a device transfer did besides moving the device (nota_track_transfer_device's out_flags).</summary>
[Flags]
public enum TransferFlags { None = 0, SidechainCleared = 1, LinksDropped = 2, SourceTrackRemoved = 4 }
/// <summary>Where a CV link's source and target sit when they reach into a rack (specs/044):
/// chain index and slot, -1 at track level.</summary>
public readonly record struct CvLinkPath(int SourceChain, int SourceSlot, int TargetChain, int TargetSlot);
/// <summary>A rack chain MIDI effect's CC target (specs/044): a device on the track, or the
/// child (Chain, Slot) of the rack at Device; Chain -1 = track level.</summary>
public readonly record struct NestedCcDest(int Device, int Chain, int Slot, int Param, float Depth);
/// <summary>A rack chain child's sidechain key (specs/044); SourceTrack -1 = none.</summary>
public readonly record struct NestedSidechain(int SourceTrack, bool TapPre, float GainDb, float Mix);
/// <summary>A sidechain key (specs/050): the source track (-1 = none) and the part of its
/// instrument — a Drum Rack pad, an Instrument Rack chain or a Rhythm voice — as its current
/// index; -1 = the whole track, -2 = the keyed part is gone (the key is silent).</summary>
public readonly record struct SidechainKey(int Source, int Part)
{
public const int WholeTrack = -1, Missing = -2;
public static readonly SidechainKey None = new(-1, WholeTrack);
}
/// <summary>Why nota_track_group_devices refused a run (specs/044).</summary>
public enum GroupRefusal
{
BadRun = -2, NotContiguous = -3, RackInRun = -4, CantHost = -5, InstrumentCantNest = -6, NotInstrumentTrack = -7,
}
/// <summary>Why nota_track_ungroup_rack refused (specs/044).</summary>
public enum UngroupRefusal { NotARack = -2, SeveralChains = -3, DrumRack = -4, NoInstrument = -5 }
/// <summary>What an ungroup left behind (nota_track_ungroup_rack's out_dropped).</summary>
[Flags]
public enum UngroupDropped { None = 0, MacroMappings = 1, ChainMix = 2 }
/// <summary>Project pan law (specs/006). Matches NOTA_PAN_LAW_*: Balance drops the far
/// channel as a track pans, Stereo folds it into the near side.</summary>
public enum PanLaw { Balance = 0, Stereo = 1 }
/// <summary>Which hardware input channels an audio track records and monitors (#340): both as a
/// stereo pair (1/2), or input 1 / input 2 alone — a mono source, placed in the middle.</summary>
public enum InputChannels { Stereo = 0, Mono1 = 1, Mono2 = 2 }
/// <summary>Why an armed track didn't record (specs/086); matches nota_engine_record_skipped.</summary>
public enum RecordSkipReason { InputUnavailable = 1, TooMany = 2, SwitchedOff = 3, MixedSources = 4 }
/// <summary>An instrument track's MIDI input (specs/086): the device's uid (null = All inputs)
/// and channel (0 = all, 1–16); <see cref="Connected"/> is false while that device is away.</summary>
public readonly record struct TrackMidiInput(string? Uid, int Channel, bool Connected)
{
public static TrackMidiInput All => new(null, 0, true);
}
/// <summary>An audio track's hardware input (specs/086): device channel <see cref="First"/>
/// (0-based) alone — a mono source, heard and recorded in the middle — or the stereo pair
/// First/First+1 (First even).</summary>
public readonly record struct InputPick(int First, int Width)
{
public const int MaxChannels = 64;
public static readonly InputPick Stereo12 = new(0, 2);
public static InputPick Mono(int first) => new(first, 1);
public static InputPick Pair(int first) => new(first, 2);
public bool IsStereo => Width == 2;
public bool IsValid => First >= 0 && (Width == 1 || Width == 2) && First + Width <= MaxChannels && (Width == 1 || First % 2 == 0);
/// <summary>The old three-value pick, when this is one of them.</summary>
public InputChannels? AsChannels => this == Stereo12 ? InputChannels.Stereo
: this == Mono(0) ? InputChannels.Mono1 : this == Mono(1) ? InputChannels.Mono2 : null;
public static InputPick From(InputChannels c) => c switch
{
InputChannels.Mono1 => Mono(0),
InputChannels.Mono2 => Mono(1),
_ => Stereo12,
};
}
/// <summary>One Stereo Map row (specs/008), laid out like native NotaStereoMeasure: what a
/// track / return / the master sends to the master, averaged over ~300 ms. Balance is on the
/// pan scale (a mono source panned to p reads p); width = 1 − correlation, clamped 0..1.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct StereoMeasure
{
public int TrackId;
public float LevelDb;
public float Balance;
public float Width;
public float Correlation;
/// <summary>Below −60 dBFS: no cloud is drawn.</summary>
public readonly bool Silent => LevelDb < -60f;
}
/// <summary>What a value gesture targets (specs/009 volume / pan, specs/016 device
/// parameters). Matches NOTA_MIX_*.</summary>
public enum MixKind { TrackVolume = 0, TrackPan = 1, MasterVolume = 2, DeviceParam = 3, MidiDeviceParam = 4, PluginParam = 5, PresetTag = 6, TrackSend = 8 }
/// <summary>One value a gesture records for undo; laid out like native NotaMixTarget.
/// <see cref="TrackId"/> is ignored for the master volume; <see cref="DeviceIndex"/> /
/// <see cref="ParamIndex"/> address a device parameter (−1 otherwise; a plugin parameter's
/// device −1 is the track's instrument).</summary>
[StructLayout(LayoutKind.Sequential)]
public readonly record struct MixTarget(MixKind Kind, int TrackId, int DeviceIndex = -1, int ParamIndex = -1)
{
public static MixTarget Volume(int trackId) => new(MixKind.TrackVolume, trackId);
public static MixTarget Pan(int trackId) => new(MixKind.TrackPan, trackId);
/// <summary>A track's send level into return bus <paramref name="bus"/> (specs/072).</summary>
public static MixTarget Send(int trackId, int bus) => new(MixKind.TrackSend, trackId, bus);
public static MixTarget Master => new(MixKind.MasterVolume, -1);
/// <summary>A built-in audio effect's parameter (its own min..max range).</summary>
public static MixTarget DeviceParam(int trackId, int deviceIndex, int paramIndex) => new(MixKind.DeviceParam, trackId, deviceIndex, paramIndex);
/// <summary>A MIDI effect's parameter.</summary>
public static MixTarget MidiDeviceParam(int trackId, int index, int paramIndex) => new(MixKind.MidiDeviceParam, trackId, index, paramIndex);
/// <summary>A normalized plugin / built-in instrument parameter (device −1 = the instrument).</summary>
public static MixTarget PluginParam(int trackId, int deviceIndex, int paramIndex) => new(MixKind.PluginParam, trackId, deviceIndex, paramIndex);
/// <summary>A device's preset tag (specs/048), so a preset applied in the gesture undoes with its name.</summary>
public static MixTarget PresetTag(int trackId, PresetSurface surface, int index) => new(MixKind.PresetTag, trackId, index, (int)surface);
}
/// <summary>Which of a track's devices a preset tag is on (specs/048).</summary>
public enum PresetSurface { Effect = 0, Instrument = 1, MidiEffect = 2 }
/// <summary>The preset a device was loaded from: its id ("" = a user preset by path), name
/// and the parameter values right after it applied (specs/048).</summary>
public sealed record PresetTag(string Id, string Name, float[] Loaded);
/// <summary>A named span of arrangement time — Intro / Verse / Drop (specs/016). Project
/// data held by the engine: undoable, saved with the project.</summary>
public readonly record struct SectionInfo(double StartBeat, double LengthBeats, string Name);
/// <summary>MIDI clip envelope target (M9 follow-up). Velocity scales note velocities;
/// Volume scales the instrument output during the clip.</summary>
public enum MidiClipEnvelope { Velocity = 0, Volume = 1 }
/// <summary>Instrument-wide MIDI controllers (specs/020), one id space matching native
/// NOTA_CTL_*: 0..127 the CC, <see cref="PitchWheel"/>, <see cref="ChannelPressure"/>. Values
/// are normalised: a CC 0..1 (data / 127; CC64–69 are switches, on at ≥ 0.5), the wheel −1..+1,
/// pressure 0..1.</summary>
public static class MidiController
{
public const int PitchWheel = 128;
public const int ChannelPressure = 129;
public const int Count = 130;
public const int ModWheel = 1;
public const int Sustain = 64;
/// <summary>Data entry / RPN / NRPN and the channel mode messages: never recorded,
/// drawn or automated.</summary>
public static bool IsReserved(int ctl) =>
ctl < 0 || ctl >= Count || ctl == 6 || ctl == 38 || (ctl >= 96 && ctl <= 101) || (ctl >= 120 && ctl <= 127);
/// <summary>CC64–69 (sustain, portamento, sostenuto, soft, legato, hold 2): on/off.</summary>
public static bool IsSwitch(int ctl) => ctl >= 64 && ctl <= 69;
public static (float Min, float Max) Range(int ctl) => ctl == PitchWheel ? (-1f, 1f) : (0f, 1f);
private static readonly Dictionary<int, string> Names = new()
{
[0] = "Bank select", [1] = "Mod wheel", [2] = "Breath", [4] = "Foot", [5] = "Portamento time",
[7] = "Volume", [8] = "Balance", [10] = "Pan", [11] = "Expression", [12] = "Effect 1", [13] = "Effect 2",
[64] = "Sustain", [65] = "Portamento", [66] = "Sostenuto", [67] = "Soft pedal", [68] = "Legato", [69] = "Hold 2",
[71] = "Resonance", [72] = "Release", [73] = "Attack", [74] = "Brightness", [75] = "Decay",
[76] = "Vibrato rate", [77] = "Vibrato depth", [78] = "Vibrato delay",
[84] = "Portamento control", [91] = "Reverb", [92] = "Tremolo", [93] = "Chorus", [94] = "Detune", [95] = "Phaser",
[PitchWheel] = "Pitch wheel", [ChannelPressure] = "Channel pressure",
};
/// <summary>The controller's standard name ("Mod wheel", "Sustain"), or "CC 3" when it has none.</summary>
public static string Name(int ctl) => Names.TryGetValue(ctl, out var n) ? n : $"CC {ctl}";
/// <summary>A short label for a lane tab: "Sustain", "Mod wheel", "Pressure", "CC 74".</summary>
public static string ShortName(int ctl) => ctl switch
{
ChannelPressure => "Pressure",
PitchWheel or ModWheel or Sustain or 2 or 11 => Name(ctl),
_ => $"CC {ctl}",
};
}
/// <summary>A per-note expression dimension (MPE). Matches native ExprDim: Bend in semitones
/// (the whole-instrument wheel −1..+1), Pressure 0..1, Slide (CC74 timbre) 0..1 with 0.5 neutral.</summary>
/// <remarks>Sustain (the CC64 pedal, 0/1) is instrument-wide only — send it with pitch −1.</remarks>
public enum NoteExpressionDim { Bend = 0, Pressure = 1, Slide = 2, Sustain = 3 }
/// <summary>An automation breakpoint, blittable and laid out to match native
/// NotaAutomationPoint (M9). Value is in the target's native units; Curve (M9-D)
/// shapes the segment to the next point (0 linear, [-1,1]).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct AutomationPoint(double beat, float value, float curve = 0f)
{
public double Beat = beat;
public float Value = value;
public float Curve = curve;
}
/// <summary>An automation lane's binding + point count (M9).</summary>
public readonly record struct AutomationLaneInfo(AutomationTarget Target, int DeviceIndex, int ParamIndex, int PointCount);
/// <summary>An audio device: a stable UID (persistence key) and a display name (M7-1).</summary>
public readonly record struct AudioDevice(string Uid, string Name);
/// <summary>The audio system on Windows (specs/049). Elsewhere always <see cref="Wasapi"/>, meaning
/// the platform's native backend.</summary>
public enum AudioSystem { Wasapi = 0, Asio = 1 }
/// <summary>What the audio driver asked for since the last poll (NotaAudioDeviceEvent).</summary>
public enum AudioDeviceEvent { None = 0, ResetRequested = 1, DriverFailed = 2 }
/// <summary>A MIDI input source: a stable UID (persistence key) and a display name (M7-2).</summary>
public readonly record struct MidiDevice(string Uid, string Name);
/// <summary>A game controller usable as a live note source (macOS v1). The UID is
/// the stable IORegistryEntryID stringified; the name is the HID product string.</summary>
public readonly record struct GamepadDevice(string Uid, string Name);
/// <summary>One gamepad button edge, blittable and matching NotaGamepadButtonEvent
/// in the native C ABI. Pad is the slot for the pad that pressed it (a session-
/// local index; pads are matched back to <see cref="GamepadDevice"/> by it).</summary>
[StructLayout(LayoutKind.Sequential)]
public struct GamepadButtonEvent
{
public int Pressed; // 1 = down, 0 = up
public int ButtonId; // 1..N = HID usage; GamepadButton.Dpad* for the d-pad
public int Pad; // pad slot at the time of the event
}
/// <summary>Stable ids for the gamepad d-pad (resolved from a hatswitch). All other
/// buttons carry their raw HID usage (1..N); the label a user sees is cosmetic and
/// lives in the mapping UI.</summary>
public enum GamepadButton
{
DpadUp = -1000,
DpadDown = -1001,
DpadLeft = -1002,
DpadRight = -1003,
}
/// <summary>The pad's continuous controls, in the order
/// <see cref="IAudioEngine.GamepadAxisValues"/> writes them. Values are 0..127: a stick
/// axis is bipolar and rests at 64, trigger travel is unipolar and rests at 0. The
/// triggers also fire L2/R2 button edges — the edge plays a note, the travel drives a
/// mapped parameter.</summary>
public enum GamepadAxis
{
LeftX = 0, LeftY = 1, RightX = 2, RightY = 3, LeftTrigger = 4, RightTrigger = 5,
Count = 6,
}
/// <summary>An Instrument Rack macro mapping: macro <paramref name="Macro"/> drives the target
/// param over [<paramref name="RangeMin"/>, <paramref name="RangeMax"/>] in the target's own units.
/// <paramref name="DeviceIndex"/> -1 targets the chain's instrument (plugin-param index), -2
/// (<see cref="PadControls"/>) the chain's own strip — a Drum Rack pad's Volume / Pan / Tune /
/// Decay; otherwise the device at that chain position (generic-param index).</summary>
public readonly record struct RackMacroMapping(
int Macro, int Chain, int DeviceIndex, int ParamIndex, float RangeMin, float RangeMax)
{
/// <summary>DeviceIndex of a mapping onto the chain's own controls (RackCore::kPadControls).</summary>
public const int PadControls = -2;
/// <summary>DeviceIndex of a mapping onto a rack-level control (NOTA_RACK_CONTROL); ParamIndex 0 = the selector.</summary>
public const int RackControl = -3;
/// <summary>DeviceIndex of a chain's MIDI effect j is MidiDeviceBase − j (NOTA_RACK_MIDI_DEVICE_BASE).</summary>
public const int MidiDeviceBase = -1000;
/// <summary>The rack address (RackDev* deviceIndex) of the Drum Rack in chain c of a track's
/// Instrument Rack is NestedRackBase − c (NOTA_RACK_NESTED_BASE, specs/041).</summary>
public const int NestedRackBase = -100000;
/// <summary>The pad controls a mapping can drive, by ParamIndex, with their ranges (gain is linear,
/// pan −1..1, tune in semitones, decay 0..1 with 1 = hold).</summary>
public static readonly string[] PadParamNames = { "Volume", "Pan", "Tune", "Decay" };
public static readonly float[] PadParamMin = { 0f, -1f, -48f, 0f };
public static readonly float[] PadParamMax = { 2f, 1f, 48f, 1f };
public const int PadVolume = 0, PadPan = 1, PadTune = 2, PadDecay = 3;
}