API Reference (Core.Abstractions)

1. Plugin Interfaces

public interface IPlugin
{
    string Id { get; }
    string DisplayName { get; }
    Version Version { get; }
    void OnLoad(IHostContext context);
    void OnUnload();
}

public interface IProvidesDockPanes
{
    IEnumerable<DockPaneRegistration> GetDockPanes();
}

public interface IProvidesMenuContributions
{
    IEnumerable<MenuContribution> GetMenuContributions();
}

public interface IAudioEffectProcessor
{
    string EffectId { get; }
    string EffectName { get; }
    void Process(SampleBuffer sampleBuffer, SampleControllerState state);
}

public interface IAudioAnalyzer
{
    string AnalyzerId { get; }
    void Attach(IAudioSystemBus audioSystemBus);
    void Detach();
}

• IPlugin: required entry interface.
• IProvidesDockPanes: optional docked pane registration.
• IProvidesMenuContributions: optional declarative menu list.

2. Host and Window Interfaces

public interface IHostContext
{
    ISampleControllerBus SampleControllerBus { get; }
    IWaveHoverEventBus WaveHoverEventBus { get; }
    IAudioSystemBus AudioSystemBus { get; }
    ITransportOptionsBus TransportOptionsBus { get; }
    ISelectionEventBus SelectionEventBus { get; }
    IDocumentService DocumentService { get; }
    IPresetStore PresetStore { get; }
    ICodecRegistry CodecRegistry { get; }
    IWindowManagerApi WindowManager { get; }
}

public interface IWindowManagerApi
{
    void AddMenuContribution(int sort, string menuPath, Action<MenuCommandContext> callback, Func<bool>? isEnabled = null);
    void AddContextMenuContribution(string surfaceId, int sort, string menuPath, Action<MenuCommandContext> callback, Func<bool>? isEnabled = null);
    IReadOnlyList<MenuContribution> GetContextMenuContributions(string surfaceId);
    void AddDockPane(DockPaneRegistration pane);
    void SetPaneVisible(string paneId, bool visible);
    bool IsPaneVisible(string paneId);
    bool IsPaneFloating(string paneId);
}

2.1 Menu and dock payload types

public enum DockPlacement
{
    Left,
    Right,
    Top,
    Bottom,
    Center
}

public sealed record DockPaneRegistration(
    string PaneId,
    string Title,
    DockPlacement DefaultPlacement,
    Func<object> CreateView,
    bool AllowVerticalNeighbour = true,
    bool AllowHorizontalNeighbour = true,
    bool CanUndock = true);

public sealed record MenuContribution(
    string MenuPath,
    Action<MenuCommandContext> Execute,
    int Sort,
    Func<bool>? IsEnabled = null);

public sealed class MenuCommandContext
{
    public required ISampleControllerBus SampleControllerBus { get; init; }
    public required IAudioSystemBus AudioSystemBus { get; init; }
    public required ITransportOptionsBus TransportOptionsBus { get; init; }
    public required IWindowManagerApi WindowManager { get; init; }
}

• CreateView should return a WinForms control instance for dock embedding.
• AllowVerticalNeighbour/AllowHorizontalNeighbour drive dock-target eligibility.
• CanUndock controls whether a pane may detach to floating mode.
• MenuContribution.Sort contributes to host ordering (root/group/item ordering is detailed in Menus).

3. Sample APIs

public readonly record struct SampleControllerState(
    int SampleRate,
    int Channels,
    int ViewStart,
    int ViewLength,
    int SelectionStart,
    int SelectionEnd,
    int Cursor,
    int FocusChannel = -1);

public sealed class SampleBuffer
{
    public float[] InterleavedSamples { get; }
    public int Channels { get; }
    public int SampleRate { get; }
    public int BitDepth { get; }
}

public interface ISampleControllerBus
{
    SampleControllerState State { get; }
    SampleBuffer? Buffer { get; }

    event EventHandler<SampleControllerState>? StateChanged;
    event EventHandler? BufferChanged;

    void UpdateState(SampleControllerState state);
    void UpdateBuffer(SampleBuffer sampleBuffer);
}

FocusChannel convention: -1 means all channels, otherwise channel index.

4. Document APIs

public sealed record DocumentModel(
    string DocumentId,
    string FilePath,
    string DisplayName,
    SampleBuffer Buffer,
    DateTimeOffset LoadedAtUtc);

public interface IDocumentService
{
    IReadOnlyList<DocumentModel> Documents { get; }
    DocumentModel? ActiveDocument { get; }

    event EventHandler<DocumentModel>? DocumentOpened;
    event EventHandler<DocumentModel>? DocumentClosed;
    event EventHandler<DocumentModel>? DocumentSaved;
    event EventHandler<DocumentModel?>? ActiveDocumentChanged;

    string? LastBufferEditAction { get; }
    long LastBufferEditRevision { get; }

    DocumentModel Open(string filePath);
    void Close(string documentId);
    void CloseMany(IReadOnlyList<string> documentIds);
    void CloseAll();

    DocumentModel SaveActive();
    DocumentModel SaveActiveAs(string filePath);
    DocumentModel SaveActiveCopyAs(string filePath);

    void SetActive(string documentId);
    void UpdateActiveBuffer(SampleBuffer buffer, string? action = null, string callerMember = "", string callerFile = "");
    DocumentModel CreateFromBuffer(SampleBuffer buffer, string baseDisplayName);

    SampleBuffer CopyRangeToBuffer(int startFrame, int endFrameExclusive);
    SampleBuffer CopyEffectiveRangeToBuffer(int startFrame, int endFrameExclusive);
    SampleBuffer CopyRangeToBuffer(int startFrame, int endFrameExclusive, int focusChannel);

    SampleBuffer ReplaceActiveRange(int startFrame, int endFrameExclusive, SampleBuffer replacement, string? action = null, string callerMember = "", string callerFile = "");
    SampleBuffer ReplaceActiveEffectiveRange(int startFrame, int endFrameExclusive, SampleBuffer replacement, string? action = null, string callerMember = "", string callerFile = "");
    SampleBuffer ReplaceActiveChannelRange(int startFrame, int endFrameExclusive, int targetChannel, SampleBuffer replacementMono, string? action = null, string callerMember = "", string callerFile = "");

    IEditPreviewSession BeginPreview(int startFrame, int endFrameExclusive);
}

public interface IEditPreviewSession : IDisposable
{
    int StartFrame { get; }
    int EndFrameExclusive { get; }
    SampleBuffer OriginalSelection { get; }

    void ApplyPreview(SampleBuffer previewSelection);
    void Commit();
    void Cancel();
}

5. Audio APIs

public readonly record struct MeterFrame(double LeftPeak, double RightPeak);

public interface IPlaybackSampleProcessor
{
    bool TryProcess(float[] interleavedBuffer, int offset, int sampleCount, int channels, int sampleRate);
}

public enum PlaybackCommandType
{
    Play,
    Pause,
    Stop,
    StartRecording,
    StopRecording,
    TogglePlayPause,
    PlayBuffer,
    SeekRelative,
    SetPlaybackMotion,
    ReloadOutputDevice
}

public readonly record struct PlaybackCommand(
    PlaybackCommandType Type,
    SampleBuffer? Buffer = null,
    int StartFrame = 0,
    int EndFrameExclusive = 0,
    bool SuppressUiEvents = false,
    bool Loop = false,
    bool UpdateInPlace = false,
    string? PreviewOwnerId = null,
    IPlaybackSampleProcessor? SampleProcessor = null,
    int SeekDeltaFrames = 0,
    int MotionDirection = 1,
    float MotionSpeedFactor = 1f,
    string? OutputDeviceId = null);

public readonly record struct PlaybackState(bool IsPlaying, int CurrentFrame);
public readonly record struct RecordingState(bool IsRecording, long CapturedFrames);

public interface IAudioSystemBus
{
    event EventHandler<MeterFrame>? MeterFrameAvailable;
    event EventHandler<PlaybackCommand>? PlaybackCommandRequested;
    event EventHandler<PlaybackState>? PlaybackStateChanged;
    event EventHandler<RecordingState>? RecordingStateChanged;

    void PublishMeterFrame(MeterFrame meterFrame);
    void RequestPlayback(PlaybackCommand command);
    void PublishPlaybackState(PlaybackState state);
    void PublishRecordingState(RecordingState state);
}

6. Selection APIs

public enum SelectionChangePhase
{
    Started,
    Dragging,
    Finished,
    Programmatic
}

public readonly record struct SelectionChange(
    int Start,
    int EndExclusive,
    int Cursor,
    SelectionChangePhase Phase);

public interface ISelectionEventBus
{
    event EventHandler<SelectionChange>? SelectionChanged;
    void PublishSelectionChanged(SelectionChange change);
}

7. Transport APIs

public enum TransportPlayScope
{
    Smart,
    Selection,
    View,
    EntireWave
}

public readonly record struct TransportOptionsState(
    TransportPlayScope PlayScope,
    bool LoopPlayback,
    bool FollowPlayback,
    bool CenterPlayhead,
    bool StartFromCursor);

public interface ITransportOptionsBus
{
    TransportOptionsState State { get; }
    event EventHandler<TransportOptionsState>? StateChanged;
    void UpdateState(TransportOptionsState state);
}

8. Hover APIs

public readonly record struct WaveHoverInfo(
    bool HasValue,
    int Channel,
    int Frame,
    float SampleValue,
    double Decibels);

public interface IWaveHoverEventBus
{
    event EventHandler<WaveHoverInfo>? HoverChanged;
    void PublishHoverChanged(WaveHoverInfo info);
}

9. Preset APIs

public sealed record PresetListEntry(string Name);

public interface IPresetStore
{
    IReadOnlyList<PresetListEntry> GetPresetList(string pluginName);
    bool PresetExists(string pluginName, string presetName);
    string? LoadPreset(string pluginName, string presetName);
    void SavePreset(string pluginName, string presetName, string jsonObject);
    bool DeletePreset(string pluginName, string presetName);
    string? LastUsed(string pluginName);
}

10. Codec APIs

public interface ICodecRegistry
{
    IReadOnlyList<IFileTypeCodec> Codecs { get; }
    void Register(IFileTypeCodec codec);
    IFileTypeCodec ResolveForRead(string filePath);
    IFileTypeCodec ResolveForWrite(string filePath);
}

public interface IFileTypeCodec
{
    string CodecId { get; }
    string DisplayName { get; }
    IReadOnlyList<string> Extensions { get; }

    SampleBuffer Read(string filePath);
    void Write(string filePath, SampleBuffer buffer);
}

11. Records and Enums