SonicFrame v1.3.2

Plugin API

The types a plugin works with, as TypeScript sees them. The API only ever gains members: a plugin written for an older version keeps working.

Plugin

type Plugin = {
    name: string;
    layer?: 'under' | 'over'; // 'over' by default
    setup?(host: PluginHost): void;
    draw?(paint: PaintContext): void;
    resize?(geometry: FrameGeometry): void;
    pointerDown?(point: WavePoint): 'take' | 'drag' | void; // asked last-added first
    pointerMove?(point: WavePoint): void;
    pointerUp?(point: WavePoint): void;
    pointerCancel?(): void;
    pointerHover?(point: WavePoint | null): string | void; // a CSS cursor
    keyDown?(key: string, modifiers: KeyModifiers): boolean;
    valueNote?(time: number | null, ratio: number): string | void;
    destroy?(): void;
};

PaintContext

type PaintContext = {
    ctx: CanvasRenderingContext2D; // device pixels
    width: number;
    height: number;
    pixelRatio: number;
    progress: number; // 0..1
    duration: number | null;
    hover: number | null; // ratio under the pointer
    view: ViewState; // { start, end, level, maxLevel }
    xAt(ratio: number): number; // through the view
    ratioAt(x: number): number;
    color(value: string): string; // resolves var(--name, fallback)
};

WavePoint

A press or hover, already in the sound's terms: ratio (through the view) and time (null while the length is unknown), the CSS pixel x and y in the wave box, its width and height, the pointerType ('mouse', 'touch' or 'pen') and shiftKey.

KeyModifiers

What keyDown hears with a key: the keys held with it (ctrlKey, altKey, metaKey, shiftKey) and repeat, true while the key is held down and repeating. Decide by shiftKey, never by the key's case, which Caps Lock turns around. A key that switches something (a loop, a mode) should act once and let a repeat go: hold L on a region and its loop turns on once.

PluginHost

See what the host gives for every member: the frame's state and language, repaints, lanes, the overlay, seeking, ranges, bar values, announcements and error reports.