@hyperframes/inspector 0.0.0-stage → 0.8.152

package/dist/types/core/src/audioAutomation.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Automation envelopes for audio tracks.
+ *
+ * A lane is a list of breakpoints over one parameter — track volume, or one
+ * knob of one effect in the track's FX chain. Ableton's clip-envelope model:
+ * times are clip-local, so an envelope travels with the clip when it moves.
+ *
+ * Nothing here touches Web Audio. This module owns the format and the
+ * interpolation, and the same `sampleAutomationLane` is used to draw the lane
+ * in the timeline, to schedule it in preview, and to bake it at render — one
+ * curve, three consumers, or the picture and the sound disagree.
+ */
+import { type HfAudioFxChain } from "./audioFx.js";
+export declare const HF_AUDIO_AUTOMATION_ATTR = "data-automation";
+/** The same attribute as a `dataset` / `dataAttributes` key. See `HF_AUDIO_FX_DATA_KEY`. */
+export declare const HF_AUDIO_AUTOMATION_DATA_KEY: string;
+/** Automation files are versioned; a reader must refuse a version it doesn't know. */
+export declare const HF_AUDIO_AUTOMATION_VERSION = 1;
+/**
+ * A pathological document should not be able to hang the scheduler, which
+ * expands every segment into scheduled ramps. Well past any hand-drawn
+ * envelope; a lane is dense at 100 points.
+ */
+export declare const MAX_AUTOMATION_POINTS = 512;
+export interface HfAutomationPoint {
+    /** Seconds from the start of the clip, not the composition. */
+    t: number;
+    /** Value in the parameter's own unit — dB for a threshold, Hz for a cutoff. */
+    v: number;
+    /**
+     * Curvature of the segment *leaving* this point, -1..1. Absent or 0 is a
+     * straight line; positive holds low then rises late, negative rises early.
+     */
+    curve?: number;
+    /**
+     * An interior point the segment *leaving* this point passes through, in
+     * normalised segment space: `viaX` is progress 0..1 between the two
+     * breakpoints, `viaY` is how far the value has travelled by then. Both are
+     * needed for either to mean anything; without them the segment falls back to
+     * `curve` above, so everything authored before this existed reads unchanged.
+     *
+     * Two numbers rather than one because `curve` answers only "how hard", and an
+     * exponent cannot say "and where". Every upward bend a single exponent can
+     * draw has its deepest deviation in the first fifth of the segment, whatever
+     * the author aimed at, and an exponent steep enough to reach a point near
+     * either end runs past the ±1 the model accepts — so a bend dragged near the
+     * right-hand breakpoint bulged on the left and then stopped following the
+     * pointer at all. Naming the point the curve goes through makes both the
+     * height and the position of the bend the author's to choose, and takes the
+     * saturation with it: any interior point is reachable exactly.
+     */
+    viaX?: number;
+    viaY?: number;
+}
+export interface HfAutomationLane {
+    /** `volume`, or `fx.<nodeId>.<paramKey>`. */
+    target: string;
+    points: HfAutomationPoint[];
+}
+export interface HfAutomation {
+    version: number;
+    lanes: HfAutomationLane[];
+}
+export declare class AudioAutomationError extends Error {
+    constructor(message: string);
+}
+export declare const VOLUME_TARGET = "volume";
+/** Playback-rate lane: `v` is a speed multiplier over clip-local time. See `speedRamp.ts`. */
+export declare const RATE_TARGET = "rate";
+export type HfAutomationTarget = {
+    kind: "volume";
+} | {
+    kind: "rate";
+} | {
+    kind: "fx";
+    nodeId: string;
+    param: string;
+} | {
+    kind: "preset";
+    presetId: string;
+};
+/** Split a target string. Returns null for anything unrecognised. */
+export declare function parseAutomationTarget(target: string): HfAutomationTarget | null;
+export declare function fxAutomationTarget(nodeId: string, param: string): string;
+/**
+ * How much of a preset is applied, 0..1.
+ *
+ * A preset's nodes share no automatable parameter — and its worklet effects
+ * expose no AudioParams at all — so there is nothing to aim a lane at
+ * node-by-node. The graph wraps a preset's run in a wet/dry pair instead, and
+ * this drives the blend: 0 is the dry signal untouched, 1 is the preset fully
+ * applied, and between them it crossfades.
+ */
+export declare function presetAutomationTarget(presetId: string): string;
+/** 0..1 blend, the same shape as a wet/dry mix knob. */
+export declare const PRESET_RANGE: AutomationRange;
+/**
+ * The value range a lane is drawn and clamped against.
+ *
+ * Volume is linear over the full authoring gain range, matching `data-volume`
+ * and the existing volume envelope machinery — no dB conversion enters the
+ * volume path. Everything
+ * else is read from the effect registry, so a lane can never offer a value the
+ * renderer would reject, and the log-scaled knobs sweep the way a DAW's do.
+ */
+export interface AutomationRange {
+    min: number;
+    max: number;
+    step: number;
+    unit: string;
+    label: string;
+    scale: "linear" | "log";
+    /** Where an empty lane draws its flat line, and what a new point starts at. */
+    default: number;
+}
+/**
+ * One ceiling for the fader, the lane, the preview transport and the render
+ * mixer. Capping the lane at unity while the fader reached +12 dB made
+ * automating a boosted clip silently discard the boost — and the panel
+ * disables the fader while a lane owns it, so there was no way back.
+ */
+export declare const VOLUME_RANGE: AutomationRange;
+export declare const RATE_RANGE: AutomationRange;
+/**
+ * Resolve a lane's target against a chain. Returns null when the target names
+ * a node or parameter that is not there — the effect was deleted, or the
+ * parameter is an enum, which has no envelope between its values.
+ */
+export declare function resolveAutomationRange(target: string, chain: HfAudioFxChain | undefined): AutomationRange | null;
+/**
+ * The via point a segment will actually be drawn with, given one that was asked
+ * for — pulled into the steady region, or null when it describes no bend.
+ *
+ * Exported so an editor can write what the model will honour rather than what the
+ * pointer happened to ask for. Without it a lane's attribute claims a shape the
+ * renderer quietly declines to draw, and the two only agree once the file makes a
+ * round trip.
+ */
+export declare function steadyViaPoint(viaX: number | undefined, viaY: number | undefined): {
+    viaX: number;
+    viaY: number;
+} | null;
+/**
+ * Structural normalisation, with no knowledge of the chain: sort and clean the
+ * points of every lane and drop lanes that carry none. Range clamping and
+ * orphan removal need the chain and happen in `resolveAutomation`.
+ */
+export declare function normalizeAutomation(automation: HfAutomation): HfAutomation;
+/**
+ * Bind automation to a chain: clamp each lane into its parameter's declared
+ * range and drop lanes whose target no longer exists.
+ *
+ * Dropping is deliberate. An envelope on a deleted effect has nothing to
+ * drive, and keeping it would silently reattach if an unrelated effect later
+ * took the same node id.
+ */
+export declare function resolveAutomation(automation: HfAutomation, chain: HfAudioFxChain | undefined): HfAutomation;
+/**
+ * Parse an automation attribute.
+ *
+ * Malformed input throws rather than being skipped, matching the chain reader:
+ * a track that quietly loses its envelope renders differently from the project
+ * the author saved, which is worse than refusing.
+ */
+export declare function parseAutomation(json: string): HfAutomation;
+/** Serialise for the `data-automation` attribute. */
+export declare function serializeAutomation(automation: HfAutomation): string;
+/**
+ * Shape the 0..1 progress across a segment.
+ *
+ * `curve` is an exponent in disguise: 0 is linear, and the ends reach a
+ * quarter-power and a fourth-power bend, which is about the range a DAW's
+ * envelope handle covers before the segment stops reading as a curve.
+ */
+export declare function applyCurve(x: number, curve: number | undefined): number;
+/**
+ * The progress a segment leaving `point` has reached at normalised `x`.
+ *
+ * A via point wins when it is there, since it says strictly more than an
+ * exponent can. Everything authored before via points existed carries only
+ * `curve` and takes the exponent path unchanged.
+ */
+export declare function shapeProgress(x: number, point: {
+    curve?: number | undefined;
+    viaX?: number | undefined;
+    viaY?: number | undefined;
+}): number;
+/**
+ * Value of a lane at a clip-local time.
+ *
+ * Outside the points, the envelope holds — the first value before it starts
+ * and the last value after it ends, so a lane never snaps to zero at the edges.
+ */
+export declare function sampleAutomationLane(lane: HfAutomationLane, t: number, scale?: "linear" | "log"): number;
+/** True when the lane is a single value, i.e. worth setting once and not scheduling. */
+export declare function isConstantLane(lane: HfAutomationLane): boolean;
+/**
+ * Sample a lane onto evenly spaced times, for consumers that want a plain
+ * curve rather than a breakpoint list: `setValueCurveAtTime`, the render-side
+ * volume envelope, and the lane's own drawing code.
+ */
+export declare function sampleAutomationCurve(lane: HfAutomationLane, from: number, to: number, count: number, scale?: "linear" | "log"): Float32Array;

package/dist/types/core/src/audioFx.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Audio FX chain: the one description of every effect that can be applied to an
+ * audio track.
+ *
+ * Preview and render both run the same Web Audio graph — the studio in a live
+ * AudioContext, the engine in an OfflineAudioContext inside the headless
+ * browser it already drives. There is only one implementation of each effect,
+ * so preview predicting the render is a property of the architecture rather
+ * than something to measure and defend.
+ *
+ * This file holds what both ends need to agree on: the parameter set for each
+ * effect with its usable range, and the id of the graph builder that realises
+ * it. Parameters are declared in the units a person thinks in (dB, ms, Hz);
+ * the graph builders convert where the Web Audio node wants something else.
+ */
+export declare const HF_AUDIO_FX_ATTR = "data-fx-chain";
+/**
+ * The same attribute as a `dataset` / `dataAttributes` key — the `data-` prefix
+ * is not part of that spelling.
+ *
+ * Derived rather than restated: the studio writes through
+ * `HF_AUDIO_FX_ATTR` and reads through the key, so a hardcoded `"fx-chain"`
+ * on the read side is a rename waiting to half-land.
+ */
+export declare const HF_AUDIO_FX_DATA_KEY: string;
+/** Chain files are versioned; a reader must refuse a version it doesn't know. */
+export declare const HF_AUDIO_FX_CHAIN_VERSION = 1;
+export type HfAudioFxGroup = "filter" | "dynamics" | "nonlinear" | "time";
+export interface HfAudioFxNumberParam {
+    kind: "number";
+    key: string;
+    label: string;
+    /** Shown after the value in the panel; "" for a bare ratio. */
+    unit: string;
+    min: number;
+    max: number;
+    step: number;
+    default: number;
+    /** Frequency-style controls need a log knob to be usable. */
+    scale?: "linear" | "log";
+    /**
+     * The knob is backed by an AudioParam, so an automation lane can drive it.
+     *
+     * Not every knob can be: a WaveShaper curve, a convolution impulse and a
+     * worklet's `processorOptions` are all set wholesale rather than scheduled.
+     * A graph builder must expose an AudioParam for every parameter flagged here
+     * — `audioFxGraph.test.ts` builds each effect and checks it.
+     */
+    automatable?: boolean;
+    /** One line explaining what turning this does, shown on the control. */
+    hint?: string;
+}
+export interface HfAudioFxEnumParam {
+    kind: "enum";
+    key: string;
+    label: string;
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+    default: string;
+    hint?: string;
+}
+export type HfAudioFxParam = HfAudioFxNumberParam | HfAudioFxEnumParam;
+export type HfAudioFxParamValues = Record<string, number | string>;
+export interface HfAudioFxDef {
+    id: string;
+    label: string;
+    group: HfAudioFxGroup;
+    /** One sentence on what the effect is for, shown when adding it. */
+    description: string;
+    params: readonly HfAudioFxParam[];
+    /**
+     * Identifier for the Web Audio graph builder that realises this effect. Kept
+     * as a string rather than a function so this module stays free of browser
+     * globals and can be imported by the engine and the linter.
+     */
+    web: string;
+}
+/**
+ * Every effect, in panel order. Ranges are the usable span for each control;
+ * a value that survives `normalizeAudioFxParams` is always safe to realise.
+ */
+export declare const HF_AUDIO_FX: readonly HfAudioFxDef[];
+export declare function getAudioFxDef(id: string): HfAudioFxDef | undefined;
+export declare const HF_AUDIO_FX_IDS: readonly string[];
+/** Every parameter at its declared default, ready to seed a freshly added effect. */
+export declare function defaultAudioFxParams(id: string): HfAudioFxParamValues;
+/**
+ * Clamp and fill a parameter set so it is always renderable: unknown keys are
+ * dropped, missing keys take their default, numbers are clamped into their
+ * declared range, and an unrecognised enum value falls back to its default.
+ * A non-finite number is treated as missing rather than passed through, since
+ * NaN reaching an AudioParam silences the node for the rest of the render.
+ */
+export declare function normalizeAudioFxParams(id: string, values: Readonly<HfAudioFxParamValues> | undefined): HfAudioFxParamValues;
+export interface HfAudioFxNode {
+    /** Effect id from HF_AUDIO_FX. */
+    type: string;
+    /**
+     * Stable handle for this node within its chain, minted when the node is
+     * added. Automation lanes address nodes by id (`fx.<id>.<param>`) so that
+     * reordering the chain never re-points a lane at a different effect. Older
+     * chains have no ids; they load fine and simply cannot be automated until
+     * the panel touches them.
+     */
+    id?: string;
+    /** Set on nodes the carve analysis generated, so re-running replaces them
+     *  instead of stacking another set on top of hand-added effects. */
+    fromCarve?: boolean;
+    /**
+     * Id of the preset that wrote this node, for the same reason `fromCarve`
+     * exists: re-applying a preset replaces its own nodes rather than adding a
+     * second copy, and the rack can brace them together under the preset's name.
+     *
+     * The id rather than a flag, because a chain can carry more than one preset
+     * and each has to be able to find its own.
+     */
+    fromPreset?: string;
+    /**
+     * What the rack calls this node, when the effect's own name is not specific
+     * enough to be useful.
+     *
+     * A peaking filter is "Shape One Range" wherever it appears, so a chain that
+     * cuts mud at 250 Hz and lifts clarity at 3 kHz shows the same words twice
+     * and an author cannot tell the two apart. A preset names each node for the
+     * JOB it is doing instead — "Reduce Mud", "Add Clarity" — and the rack reads
+     * as a list of things that were done rather than a list of filter types.
+     */
+    label?: string;
+    /**
+     * Id of the multi-band EQ that owns this node, when it is one of its bands.
+     *
+     * Same device as `fromCarve`: the module gathers its own nodes out of the
+     * chain and presents them as one control surface, so an EQ needs no new
+     * effect type and its bands stay ordinary filters underneath.
+     */
+    fromEq?: string;
+    /**
+     * How much of this node's preset is applied, 0..1 — the wet/dry blend the
+     * graph wraps its run in.
+     *
+     * On every node of the run rather than beside the chain, because the chain has
+     * nowhere else to put it: `HfAudioFxChain` is a version and a list of nodes,
+     * and a preset is defined by which nodes carry its tag. The graph reads it off
+     * the first node of each run. Absent means fully applied, which is what every
+     * chain written before this means.
+     */
+    presetAmount?: number;
+    /**
+     * Set on the gain stage the leveller writes, so re-running replaces it rather
+     * than stacking a second one — the same contract `fromCarve` has.
+     */
+    fromLeveller?: boolean;
+    /** Absent means enabled — chain files written before the field existed still load. */
+    enabled?: boolean;
+    params?: HfAudioFxParamValues;
+}
+export interface HfAudioFxChain {
+    version: number;
+    nodes: HfAudioFxNode[];
+}
+export declare class AudioFxChainError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a chain file. Unknown effect ids are rejected rather than skipped: a
+ * chain that silently loses a node would render differently from the project
+ * the author saved, which is worse than refusing to render at all.
+ */
+export declare function parseAudioFxChain(json: string): HfAudioFxChain;
+/** The nodes that should process audio, in order. */
+export declare function enabledAudioFxNodes(chain: HfAudioFxChain): HfAudioFxNode[];
+/** Serialise a chain for the `data-fx-chain` attribute. */
+export declare function serializeAudioFxChain(chain: HfAudioFxChain): string;
+/**
+ * Next free node id for a chain, as `n1`, `n2`, … — counted rather than random
+ * so that adding an effect produces the same document on every machine, which
+ * compositions require.
+ */
+export declare function mintAudioFxNodeId(chain: HfAudioFxChain): string;

package/dist/types/core/src/audioGain.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Authoring gain for a media clip.
+ *
+ * HTMLMediaElement.volume is limited to 0..1, but HyperFrames' Web Audio
+ * preview and FFmpeg render paths both support gain above unity. Keep the
+ * shared ceiling here so Studio, preview, and render cannot drift.
+ */
+export declare const MAX_AUDIO_GAIN_DB = 12;
+/** Linear gain from a decibel value. Owner of the dB → gain formula. */
+export declare function audioDbToGain(db: number): number;
+/** Inverse of `audioDbToGain`. Caller must pass a positive finite gain. */
+export declare function audioGainToDb(gain: number): number;
+export declare const MAX_AUDIO_GAIN: number;
+/** Studio fader coordinates. Unity is deliberately the physical midpoint. */
+export declare const AUDIO_GAIN_FADER_MIN = -100;
+export declare const AUDIO_GAIN_FADER_MAX = 100;
+export declare function clampAudioGain(value: number): number;
+export declare function clampNativeMediaVolume(value: number): number;
+/**
+ * Serialize an authored gain for `data-volume`.
+ *
+ * The fader travels in dB, so its stops are irrational (position -70 is
+ * 10 ** (-42/20)). Rounding to two decimals — what the generic numeric
+ * attribute formatter does — collapses the whole bottom of the fader onto
+ * `"0"` (a hard mute) and makes the knob jump on release everywhere below
+ * unity. Six decimals round-trip every integer fader stop back to itself.
+ */
+export declare function formatAudioGain(gain: number): string;
+/**
+ * Run `probe` with `el.volume` shadowed by an accessor that keeps the authored
+ * value instead of the spec's [0,1] clamp.
+ *
+ * `HTMLMediaElement.volume` cannot hold gain above unity, so a clip authored
+ * at `data-volume="1.95"` reads back as 1 the moment the probe seeds it — and
+ * a GSAP tween started from that seed fades from 0 dB rather than from the
+ * authored boost. Both the FFmpeg mixer and the Web Audio transport carry gain
+ * up to MAX_AUDIO_GAIN, so the clamp is a probe artefact, not a real ceiling.
+ * The native setter still receives the clamped value, so nothing outside the
+ * probe observes an out-of-range volume, and the shadow is removed afterwards.
+ */
+export declare function withUnclampedVolume<T>(el: HTMLMediaElement, probe: () => T): T;
+export declare function audioFaderPositionToGain(position: number): number;
+export declare function audioGainToFaderPosition(gain: number): number;
+export declare function audioGainToText(gain: number): string;