@libraz/libsonare 1.7.1 → 1.8.0

package/dist/mastering_chain.d.ts

@@ -0,0 +1,213 @@
+import type { MasteringChainConfig, MasteringChainResult, MasteringChainStereoResult, MasteringPreset } from './public_types';
+import type { ProgressCallback } from './sonare.js';
+import type { ValidateOptions } from './validation';
+export type NormalizeMode = 'peak' | 'rms';
+export interface NormalizeRequest extends ValidateOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+    targetDb?: number;
+    mode?: NormalizeMode;
+}
+/**
+ * Normalize audio to a target peak or RMS level.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param targetDb - Finite target at or below 0 dBFS (default: 0 dB = full scale).
+ *   For `mode: 'peak'`, this is the peak target; for `mode: 'rms'`, this is the RMS target.
+ * @param mode - Normalization mode: `'peak'` (default) or `'rms'`.
+ * @returns Normalized audio
+ */
+export declare function normalize(request: NormalizeRequest): Float32Array;
+export declare function normalize(samples: Float32Array, sampleRate: number, targetDb?: number, options?: ValidateOptions): Float32Array;
+export declare function normalize(samples: Float32Array, sampleRate: number, targetDb?: number, mode?: NormalizeMode, options?: ValidateOptions): Float32Array;
+export interface NormalizeStereoRequest extends ValidateOptions {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    targetDb?: number;
+    mode?: NormalizeMode;
+}
+/** A normalized channel pair and the gain both channels were moved by. */
+export interface NormalizeStereoResult {
+    left: Float32Array;
+    right: Float32Array;
+    /**
+     * One figure rather than a pair: the gain is one decision shared by both
+     * channels. Silence leaves the pair untouched and reports 0.
+     */
+    appliedGainDb: number;
+}
+/**
+ * Normalize a stereo pair on a gain measured across both channels.
+ *
+ * Normalizing the two channels separately lifts the quieter one until the peaks
+ * match, which changes the balance rather than the level. The level here is read
+ * from the pair and the resulting gain goes to both channels, so the image is
+ * preserved: for `mode: 'peak'` the louder channel reaches `targetDb` and the
+ * other keeps its distance from it; for `mode: 'rms'` the quantity driven to
+ * `targetDb` is the root mean square over both channels' samples together — the
+ * quadratic mean of the per-channel figures, not their average — and the output
+ * is hard-clipped to [-1, 1].
+ *
+ * @param request.left - Left channel samples (float32)
+ * @param request.right - Right channel samples, same length as `left`
+ * @param request.sampleRate - Sample rate in Hz (default: 22050)
+ * @param request.targetDb - Finite target at or below 0 dBFS. Defaults to 0 for
+ *   `mode: 'peak'` and -20 for `mode: 'rms'`, matching the library and the other
+ *   language surfaces.
+ * @param request.mode - `'peak'` (default) or `'rms'`
+ * @returns The normalized pair and the shared gain in dB
+ * @throws RangeError when the two channels differ in length
+ *
+ * @example
+ * ```ts
+ * const { left, right, appliedGainDb } = normalizeStereo({
+ *   left: leftSamples,
+ *   right: rightSamples,
+ *   sampleRate: 44100,
+ *   targetDb: -1,
+ * });
+ * ```
+ */
+export declare function normalizeStereo(request: NormalizeStereoRequest): NormalizeStereoResult;
+export interface MasteringChainRequest {
+    samples: Float32Array;
+    sampleRate?: number;
+    config?: MasteringChainConfig;
+    onProgress?: ProgressCallback;
+    cancel?: () => boolean;
+}
+export interface MasteringChainStereoRequest {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    config?: MasteringChainConfig;
+    onProgress?: ProgressCallback;
+    cancel?: () => boolean;
+}
+/** Canonical request form for one-shot preset mastering. */
+export interface MasterAudioRequest {
+    samples: Float32Array;
+    sampleRate?: number;
+    preset?: MasteringPreset;
+    overrides?: MasteringChainConfig;
+    onProgress?: ProgressCallback;
+    cancel?: () => boolean;
+}
+/** Canonical request form for one-shot stereo preset mastering. */
+export interface MasterAudioStereoRequest {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    preset?: MasteringPreset;
+    overrides?: MasteringChainConfig;
+    onProgress?: ProgressCallback;
+    cancel?: () => boolean;
+}
+/**
+ * Apply a configurable mastering chain in WASM.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param config - Chain stage configuration
+ * @returns Processed audio, loudness metadata, and applied stage names
+ */
+export declare function masteringChain(request: MasteringChainRequest): MasteringChainResult;
+export declare function masteringChain(samples: Float32Array, sampleRate?: number, config?: MasteringChainConfig, onProgress?: ProgressCallback): MasteringChainResult;
+/**
+ * Apply a configurable stereo mastering chain in WASM.
+ *
+ * @param left - Left channel samples
+ * @param right - Right channel samples
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Chain stage configuration
+ * @returns Processed stereo audio, loudness metadata, and applied stage names
+ */
+export declare function masteringChainStereo(request: MasteringChainStereoRequest): MasteringChainStereoResult;
+export declare function masteringChainStereo(left: Float32Array, right: Float32Array, sampleRate?: number, config?: MasteringChainConfig, onProgress?: ProgressCallback): MasteringChainStereoResult;
+/**
+ * Apply a configurable mastering chain in WASM with progress reporting.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param config - Chain stage configuration
+ * @param onProgress - Progress callback (progress: 0-1, stage: string)
+ * @returns Processed audio, loudness metadata, and applied stage names
+ */
+export declare function masteringChainWithProgress(request: MasteringChainRequest & Required<Pick<MasteringChainRequest, 'onProgress'>>): MasteringChainResult;
+export declare function masteringChainWithProgress(samples: Float32Array, sampleRate?: number, config?: MasteringChainConfig, onProgress?: ProgressCallback): MasteringChainResult;
+/**
+ * Apply a configurable stereo mastering chain in WASM with progress reporting.
+ *
+ * @param left - Left channel samples
+ * @param right - Right channel samples
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Chain stage configuration
+ * @param onProgress - Progress callback (progress: 0-1, stage: string)
+ * @returns Processed stereo audio, loudness metadata, and applied stage names
+ */
+export declare function masteringChainStereoWithProgress(request: MasteringChainStereoRequest & Required<Pick<MasteringChainStereoRequest, 'onProgress'>>): MasteringChainStereoResult;
+export declare function masteringChainStereoWithProgress(left: Float32Array, right: Float32Array, sampleRate?: number, config?: MasteringChainConfig, onProgress?: ProgressCallback): MasteringChainStereoResult;
+/**
+ * List built-in mastering preset identifiers.
+ *
+ * @returns Preset names in display order (e.g. "pop", "edm", "aiMusic")
+ */
+export declare function masteringPresetNames(): MasteringPreset[];
+/**
+ * The flat `{key: number|boolean}` params of preset `preset`'s built-in chain
+ * configuration, in the same key space {@link masteringAssistantSuggestChain}
+ * returns. Passing this straight through as `overrides` to {@link masterAudio}
+ * reproduces the preset unchanged, bit for bit in the C++ core.
+ *
+ * @param preset - Preset identifier from {@link masteringPresetNames}.
+ * @throws For an unknown `preset`.
+ */
+export declare function masteringPresetParams(preset: MasteringPreset): Record<string, number | boolean>;
+/**
+ * List the delivery targets the mastering assistant accepts as `targetPlatform`.
+ *
+ * Read from the library rather than from a list kept here, so a target added in
+ * the core is discoverable without a binding change.
+ *
+ * @returns Target names in index order (e.g. "streaming", "broadcast", "club")
+ */
+export declare function masteringPlatformNames(): string[];
+/**
+ * Apply a named mastering preset chain to mono audio.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param presetName - Preset identifier from {@link masteringPresetNames}
+ * @param overrides - Optional nested {@link MasteringChainConfig} applied on top of the preset (e.g. `{ loudness: { targetLufs: -14 } }`). Pass `null` for preset defaults.
+ * @param onProgress - Optional per-stage progress callback (progress: 0-1, stage: string).
+ * @returns Processed audio, loudness metadata, and applied stage names
+ */
+export declare function masterAudio(request: MasterAudioRequest): MasteringChainResult;
+export declare function masterAudio(samples: Float32Array, sampleRate?: number, presetName?: MasteringPreset, overrides?: MasteringChainConfig, onProgress?: ProgressCallback): MasteringChainResult;
+/**
+ * Apply a named mastering preset chain to stereo audio.
+ *
+ * @param left - Left channel samples
+ * @param right - Right channel samples
+ * @param sampleRate - Sample rate in Hz
+ * @param presetName - Preset identifier from {@link masteringPresetNames}
+ * @param overrides - Optional nested {@link MasteringChainConfig} applied on top of the preset (e.g. `{ loudness: { targetLufs: -14 } }`). Pass `null` for preset defaults.
+ * @param onProgress - Optional per-stage progress callback (progress: 0-1, stage: string).
+ * @returns Processed stereo audio, loudness metadata, and applied stage names
+ */
+export declare function masterAudioStereo(request: MasterAudioStereoRequest): MasteringChainStereoResult;
+export declare function masterAudioStereo(left: Float32Array, right: Float32Array, sampleRate?: number, presetName?: MasteringPreset, overrides?: MasteringChainConfig, onProgress?: ProgressCallback): MasteringChainStereoResult;
+/**
+ * Mono `masterAudio` with per-stage progress reporting. `onProgress` is invoked
+ * with `(progress, stage)` between each chain stage (progress is in [0,1]).
+ */
+export declare function masterAudioWithProgress(request: MasterAudioRequest & Required<Pick<MasterAudioRequest, 'onProgress'>>): MasteringChainResult;
+export declare function masterAudioWithProgress(samples: Float32Array, sampleRate?: number, presetName?: MasteringPreset, overrides?: MasteringChainConfig | null, onProgress?: ProgressCallback): MasteringChainResult;
+/**
+ * Stereo `masterAudio` with per-stage progress reporting.
+ */
+export declare function masterAudioStereoWithProgress(request: MasterAudioStereoRequest & Required<Pick<MasterAudioStereoRequest, 'onProgress'>>): MasteringChainStereoResult;
+export declare function masterAudioStereoWithProgress(left: Float32Array, right: Float32Array, sampleRate?: number, presetName?: MasteringPreset, overrides?: MasteringChainConfig | null, onProgress?: ProgressCallback): MasteringChainStereoResult;
+//# sourceMappingURL=mastering_chain.d.ts.map

package/dist/mastering_chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastering_chain.d.ts","sourceRoot":"","sources":["../src/mastering_chain.ts"],"names":[],"mappings":"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"}

package/dist/mastering_core.d.ts

@@ -0,0 +1,457 @@
+import type { LoudnessMatchResult, MasteringAssistantParams, MasteringInsertParamChoice, MasteringInsertSlot, MasteringOptions, MasteringProcessorParams, MasteringResult, MasteringStereoResult, PairAnalysis, PairProcessor, SoloProcessor, StereoAnalysis, StreamingPlatform } from './public_types';
+export type { MasteringInsertParamChoice, MasteringInsertSlot };
+/** Canonical request form for loudness/true-peak mastering. */
+export interface MasteringRequest extends MasteringOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+}
+export interface MasteringProcessRequest {
+    processorName: SoloProcessor;
+    samples: Float32Array;
+    sampleRate?: number;
+    params?: MasteringProcessorParams;
+}
+export interface MasteringProcessStereoRequest {
+    processorName: SoloProcessor;
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    params?: MasteringProcessorParams;
+}
+/** Canonical request form for a two-input match processor. */
+export interface MasteringPairProcessRequest {
+    processorName: PairProcessor;
+    source: Float32Array;
+    reference: Float32Array;
+    sampleRate?: number;
+    params?: MasteringProcessorParams;
+}
+/** Canonical request form for {@link masteringAbMatchLoudness}. */
+export interface MasteringAbMatchLoudnessRequest {
+    /** The take to gain-match. */
+    source: Float32Array;
+    /** The take whose loudness `source` is matched to; returned untouched. */
+    reference: Float32Array;
+    sampleRate?: number;
+}
+/** Canonical request form for a two-input match analysis. */
+export interface MasteringPairAnalyzeRequest {
+    analysisName: PairAnalysis;
+    source: Float32Array;
+    reference: Float32Array;
+    sampleRate?: number;
+    params?: MasteringProcessorParams;
+}
+/** Canonical request form for a stereo analysis. */
+export interface MasteringStereoAnalyzeRequest {
+    analysisName: StereoAnalysis;
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    params?: MasteringProcessorParams;
+}
+/** Canonical request form for assistant/profile calls. */
+export interface MasteringSamplesParamsRequest {
+    samples: Float32Array;
+    sampleRate?: number;
+    params?: MasteringProcessorParams;
+}
+/** Canonical request form for the assistant, whose params carry a target platform. */
+export interface MasteringAssistantParamsRequest {
+    samples: Float32Array;
+    sampleRate?: number;
+    params?: MasteringAssistantParams;
+}
+/** Canonical request form for streaming-platform preview. */
+export interface MasteringStreamingPreviewRequest {
+    samples: Float32Array;
+    sampleRate?: number;
+    platforms?: StreamingPlatform[];
+}
+/** Canonical request form for the stereo analysis entry points. */
+export interface MasteringStereoParamsRequest {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    params?: MasteringProcessorParams;
+}
+/** Stereo counterpart of {@link MasteringAssistantParamsRequest}. */
+export interface MasteringAssistantStereoParamsRequest {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    params?: MasteringAssistantParams;
+}
+/** Canonical request form for the stereo streaming-platform preview. */
+export interface MasteringStreamingPreviewStereoRequest {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+    platforms?: StreamingPlatform[];
+}
+/**
+ * Apply mastering loudness normalization with a true-peak ceiling.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param options - Loudness/ceiling settings ({@link MasteringOptions})
+ * @returns Processed audio and loudness metadata
+ */
+export declare function mastering(request: MasteringRequest): MasteringResult;
+export declare function mastering(samples: Float32Array, sampleRate?: number, options?: MasteringOptions): MasteringResult;
+export declare function masteringProcessorNames(): SoloProcessor[];
+/**
+ * Names of the insert processors the mastering chain can instantiate by name
+ * (`mastering::api::insert_factory_names`). Mirrors the C-ABI
+ * `sonare_mastering_insert_names` (which joins this list) as a `string[]`.
+ */
+export declare function masteringInsertNames(): string[];
+/**
+ * Returns the camelCase parameter names a given insert / FX processor reads, for
+ * tooling/validation. Any key NOT in this list is silently ignored by the
+ * processor (and would be reported via {@link Mixer.sceneWarnings} when a scene
+ * carrying it is loaded). Band/sub-band processors enumerate their indexed
+ * `band{i}.<field>` keys. Returns an empty array for an unknown name (or one
+ * whose insert needs an unavailable build feature, e.g. FX).
+ *
+ * @param name - Insert processor name (see {@link masteringInsertNames}).
+ */
+export declare function masteringInsertParamNames(name: string): string[];
+/**
+ * One parameter an insert processor's construction reads, whether or not it
+ * is realtime-automatable.
+ */
+export interface MasteringInsertParamInfo {
+    /** JSON-key parameter name, as used in scene insert params. */
+    name: string;
+    /**
+     * Integer param id for realtime automation lanes / MIDI-CC binding, or null
+     * for a construction-only key with no automation target.
+     */
+    id: number | null;
+    /** Whether the param can be changed live from the audio thread; false when `id` is null. */
+    rtSafe: boolean;
+    /**
+     * The C++ type the processor's config builder reads the key as. `"enum"` is
+     * sent as the number in its `choices` entry; `"string"` / `"array"` (an
+     * embedded impulse response, a per-band list) is construction-only and
+     * reports null for `min`, `max`, `default` and `choices`.
+     */
+    type: 'boolean' | 'number' | 'enum' | 'string' | 'array';
+    /**
+     * Smallest value construction accepts, or null when the catalog states no
+     * limit or `choices` is non-null. Measured, so it is a hard constraint
+     * rather than a UI range; see {@link CapabilityCatalogParameter} for what a
+     * measured bound does and does not promise.
+     */
+    min: number | null;
+    /** Largest value construction accepts, or null when the catalog states no limit or `choices` is non-null. */
+    max: number | null;
+    /**
+     * Value the processor uses when the key is absent — the config struct's own
+     * field initializer, an enum as its number. Null for a param id with no
+     * construction key, a `"string"` / `"array"` key, or a construction key with
+     * no fallback.
+     */
+    default: boolean | number | null;
+    /** Physical unit, or null when the parameter is unitless. */
+    unit: string | null;
+    /**
+     * The closed set of values construction accepts, in value order, or null
+     * when the accepted values are not a closed set. Non-null only for `"enum"`
+     * (every declared enumerator construction accepts) or a `"number"` key
+     * whose accepted integers have holes; `min` / `max` are then both null.
+     */
+    choices: MasteringInsertParamChoice[] | null;
+    /**
+     * The {@link MasteringInsertSlot} this key belongs to, or null for a key that
+     * always exists.
+     */
+    slot: string | null;
+}
+/**
+ * Returns every parameter an insert / FX processor's construction reads,
+ * including construction-time-only keys with no realtime automation target.
+ * Entries come in two runs: first the processor's realtime automation
+ * targets in id order (the keys accepted by
+ * {@link RealtimeEngine.setTrackStripInsertParamByName}, `id` non-null); then,
+ * sorted by name, every other construction key with `id` null and `rtSafe`
+ * false. The name set matches {@link masteringInsertParamNames} plus any
+ * automation target construction does not read. Returns an empty array for an
+ * unknown name.
+ *
+ * @param name - Insert processor name (see {@link masteringInsertNames}).
+ */
+export declare function masteringInsertParamInfo(name: string): MasteringInsertParamInfo[];
+/** Latency and tail of one insert instance, in samples. */
+export interface MasteringInsertTiming {
+    /** Latency in samples at the queried sample rate. */
+    latencySamples: number;
+    /** Audible decay tail in samples at the queried sample rate. */
+    tailSamples: number;
+}
+/** One built-in amp-sim rig with its resolved starting configuration. */
+export interface MasteringAmpPresetCatalogEntry {
+    /** Stable index used by the amp-sim `presetIndex` parameter. */
+    index: number;
+    /** Canonical preset identifier accepted by the amp-sim insert. */
+    name: string;
+    /** Effective values from the core preset, before sparse user overrides. */
+    params: Record<string, number | boolean>;
+}
+/**
+ * Returns the built-in amp-sim rigs and their resolved control values.
+ *
+ * The catalog is read-only metadata for hosts such as Studio. Persist only the
+ * preset index and explicit overrides in a project so future core updates can
+ * continue to define the canonical DSP configuration.
+ */
+export declare function masteringAmpPresetCatalog(): MasteringAmpPresetCatalogEntry[];
+/**
+ * Latency and tail of insert `name` built from `params` and prepared at
+ * `sampleRate` (`mastering::api::insert_timing`). Answers for the exact
+ * instance a scene or strip would build — an oversampled saturation path, a
+ * linear-phase crossover, a lookahead all change the reported latency. The
+ * capability catalog's `latencySamples` / `tailSamples` are this query at
+ * default parameters and 48 kHz. `effects.reverb.convolution` answers for its
+ * configuration without an impulse response: its latency is its fixed
+ * partition size and does not depend on one.
+ *
+ * A key `name`'s construction does not read is refused rather than ignored,
+ * because an ignored key would answer for a configuration the caller did not
+ * ask for.
+ *
+ * @param name - Insert processor name (see {@link masteringInsertNames}).
+ * @param params - Flat parameter values, keyed as in {@link masteringInsertParamInfo}.
+ * @param sampleRate - Rate the insert is prepared at.
+ * @throws For an unknown `name`, a key the insert does not read, a value its
+ *   construction or `prepare` refuses, or a `params` value that is not a
+ *   finite number or boolean.
+ */
+export declare function masteringInsertTiming(name: string, params: Record<string, number | boolean>, sampleRate: number): MasteringInsertTiming;
+/**
+ * How a processor handles a buffer with more than two channels (a surround
+ * bed). "multichannel" processes every plane in one call; "stereoPairOnly"
+ * operates on the front L/R pair and passes any surround planes through dry.
+ * "perChannel"/"passthrough" are reserved and unused by the current catalog.
+ */
+export type MasteringChannelPolicy = 'multichannel' | 'stereoPairOnly' | 'perChannel' | 'passthrough';
+/** Coarse algorithmic work estimate for a realtime insert; not a benchmark. */
+export type MasteringRealtimeCost = 'low' | 'moderate' | 'high';
+/**
+ * Catalog grouping for a processor picker, derived from the id's prefix
+ * ("eq.*" -> "eq", "match.*" -> "reference"); anything unprefixed is "other".
+ */
+export type MasteringProcessorCategory = 'dynamics' | 'effects' | 'eq' | 'final' | 'maximizer' | 'multiband' | 'other' | 'reference' | 'repair' | 'saturation' | 'spectral' | 'stereo' | 'utility';
+/** One processor's realtime/offline/pair classification in the catalog. */
+export interface MasteringProcessorCatalogEntry {
+    /** Processor id (the name used for scene inserts / named processors). */
+    id: string;
+    /**
+     * Primary classification, by precedence pair > realtime > offline: "pair" for
+     * two-input match.* processors, "realtime" for ids that build as a realtime
+     * scene insert, "offline" for whole-file-only processors.
+     */
+    kind: 'realtime' | 'offline' | 'pair';
+    /** True exactly for ids that always succeed as a realtime scene insert. */
+    realtimeInsertable: boolean;
+    /** True for processors with no mono implementation (stereo-only). */
+    stereoOnly: boolean;
+    /**
+     * Reported latency for the default 48 kHz / 512-sample probe configuration.
+     * Zero for offline processors; configuration-dependent values are estimates.
+     */
+    latencySamples: number;
+    /**
+     * Audible decay length for the same default prepared probe. Zero for
+     * offline, dry-only, and no-tail processors.
+     */
+    tailSamples: number;
+    /** Coarse realtime work estimate, or null when the processor is not an insert. */
+    realtimeCost: MasteringRealtimeCost | null;
+    /**
+     * How the mixer wraps the processor on a >2-channel (surround) bus insert:
+     * "multichannel" (one full-buffer call) or "stereoPairOnly" (front L/R pair,
+     * surround planes passed through dry).
+     */
+    channelPolicy: MasteringChannelPolicy;
+    /** Grouping for a processor picker; see {@link MasteringProcessorCategory}. */
+    category: MasteringProcessorCategory;
+    /**
+     * The processor's construction parameters, the same list
+     * {@link masteringInsertParamInfo} returns. Empty for entries that are not
+     * realtime-insertable.
+     */
+    params: MasteringInsertParamInfo[];
+    /**
+     * The insert's conditional key groups in declaration order, named by each
+     * parameter's `slot`. Empty for entries that are not realtime-insertable.
+     */
+    slots: MasteringInsertSlot[];
+}
+/**
+ * Returns the machine-readable classification catalog for every named processor
+ * id, merging the offline registry, the realtime insert factory, and the pair
+ * registry. Lets a host filter a processor picker by realtime insertability
+ * instead of offering ids the realtime strip would reject.
+ */
+export declare function masteringProcessorCatalog(): MasteringProcessorCatalogEntry[];
+export declare function masteringPairProcessorNames(): PairProcessor[];
+export declare function masteringPairAnalysisNames(): PairAnalysis[];
+export declare function masteringStereoAnalysisNames(): StereoAnalysis[];
+export declare function masteringProcess(request: MasteringProcessRequest): MasteringResult;
+export declare function masteringProcess(processorName: SoloProcessor, samples: Float32Array, sampleRate?: number, params?: MasteringProcessorParams): MasteringResult;
+export declare function masteringProcessStereo(request: MasteringProcessStereoRequest): MasteringStereoResult;
+export declare function masteringProcessStereo(processorName: SoloProcessor, left: Float32Array, right: Float32Array, sampleRate?: number, params?: MasteringProcessorParams): MasteringStereoResult;
+/**
+ * Apply a two-input `match.*` processor. `source` and `reference` may have
+ * independent lengths — the match primitives consume each buffer at its own
+ * length.
+ */
+export declare function masteringPairProcess(request: MasteringPairProcessRequest): MasteringResult;
+export declare function masteringPairProcess(processorName: PairProcessor, source: Float32Array, reference: Float32Array, sampleRate?: number, params?: MasteringProcessorParams): MasteringResult;
+/**
+ * Analyze a `source` against a `reference` with a two-input analysis. The two
+ * buffers may have independent lengths.
+ */
+export declare function masteringPairAnalyze(request: MasteringPairAnalyzeRequest): string;
+export declare function masteringPairAnalyze(analysisName: PairAnalysis, source: Float32Array, reference: Float32Array, sampleRate?: number, params?: MasteringProcessorParams): string;
+/**
+ * Gain-match `source` to `reference`'s integrated loudness, so an A/B between
+ * the two is not decided by level. `source` and `reference` may have
+ * independent lengths.
+ *
+ * The gain is applied with no upper bound and `matchedTruePeakDbtp` reports
+ * where that left the peak, rather than the call capping it: a headroom clamp
+ * would return `source` at its own loudness whenever it started near full
+ * scale. Both loudness values are non-finite for a silent or below-gate take,
+ * and `appliedGainDb` is then 0.
+ *
+ * @example
+ * ```ts
+ * const { samples, appliedGainDb, matchedTruePeakDbtp } = masteringAbMatchLoudness({
+ *   source: take,
+ *   reference: master,
+ *   sampleRate: 48000,
+ * });
+ * ```
+ */
+export declare function masteringAbMatchLoudness(request: MasteringAbMatchLoudnessRequest): LoudnessMatchResult;
+export declare function masteringStereoAnalyze(request: MasteringStereoAnalyzeRequest): string;
+export declare function masteringStereoAnalyze(analysisName: StereoAnalysis, left: Float32Array, right: Float32Array, sampleRate?: number, params?: MasteringProcessorParams): string;
+export declare function masteringAssistantSuggest(request: MasteringAssistantParamsRequest): string;
+export declare function masteringAssistantSuggest(samples: Float32Array, sampleRate?: number, params?: MasteringAssistantParams): string;
+/**
+ * Suggest a mastering chain, as the flat `{key: number|boolean}` params map
+ * {@link masteringAssistantSuggest}'s `chainConfig` carries, without needing to
+ * pull it out of the full assistant document. The returned map can be passed
+ * straight through as `overrides` to {@link mastering} / {@link masterAudio}.
+ */
+export declare function masteringAssistantSuggestChain(request: MasteringAssistantParamsRequest): Record<string, number | boolean>;
+/**
+ * The shape {@link masteringAudioProfile}'s JSON parses to.
+ *
+ * The profile crosses as a string, so nothing type-checks it on arrival; this
+ * declaration is what a conformance check compares against the paths the C++
+ * writer publishes, so a field added on one side and not the other fails there
+ * rather than reaching a caller as `undefined`.
+ */
+export interface MasteringAudioProfile {
+    durationSec: number;
+    bpm: number;
+    bpmConfidence: number;
+    loudness: {
+        integratedLufs: number;
+        lraLu: number;
+        truePeakDb: number;
+        crestFactorDb: number;
+    };
+    spectral: {
+        subRmsDb: number;
+        lowRmsDb: number;
+        lowMidRmsDb: number;
+        midRmsDb: number;
+        highMidRmsDb: number;
+        highRmsDb: number;
+        airRmsDb: number;
+        centroidHz: number;
+        flatness: number;
+        rolloffHz: number;
+    };
+    dynamics: {
+        shortTermLufsStd: number;
+        attackDensity: number;
+        sustainRatio: number;
+    };
+    /**
+     * What the repair detectors measured. `measured` is false when nothing ran —
+     * either `detectDefects` was not asked for or the input was too short — and
+     * every other field is then at its default rather than a reading.
+     */
+    defects: {
+        measured: boolean;
+        clickCount: number;
+        clickRejected: number;
+        clickLongestRunSamples: number;
+        clickPerSecond: number;
+        crackleSampleCount: number;
+        crackleSampleFraction: number;
+        cracklePerSecond: number;
+        clipSampleCount: number;
+        clipRunCount: number;
+        clipLongestRunSamples: number;
+        clipSampleFraction: number;
+        clipFlatRunCount: number;
+        clipFlatSampleCount: number;
+        clipLongestFlatRunSamples: number;
+        clipFlatLevel: number;
+        noiseFloorDbfs: number;
+        noiseBandPeakDbfs: number;
+        noiseBandPeakIndex: number;
+        humFundamentalHz: number;
+        humFundamentalProminence: number;
+        humHarmonics: number;
+        humFundamentalDbfs: number;
+        humPeakHarmonicDbfs: number;
+        lateDecayRatioDb: number;
+    };
+}
+export declare function masteringAudioProfile(request: MasteringSamplesParamsRequest): string;
+export declare function masteringAudioProfile(samples: Float32Array, sampleRate?: number, params?: MasteringProcessorParams): string;
+export declare function masteringStreamingPreview(request: MasteringStreamingPreviewRequest): string;
+export declare function masteringStreamingPreview(samples: Float32Array, sampleRate?: number, platforms?: StreamingPlatform[]): string;
+/**
+ * Suggest a mastering chain for a stereo pair, as shared JSON.
+ *
+ * Profiles through {@link masteringAudioProfileStereo}, so the loudness stage
+ * of the suggestion is built on the channel-summed program rather than a
+ * downmix that reads roughly 6 dB low.
+ */
+export declare function masteringAssistantSuggestStereo(request: MasteringAssistantStereoParamsRequest): string;
+/**
+ * Stereo counterpart of {@link masteringAssistantSuggestChain}: the flat
+ * `{key: number|boolean}` params map without the surrounding assistant
+ * document, ready to pass through as `overrides` to {@link masterAudioStereo}.
+ */
+export declare function masteringAssistantSuggestChainStereo(request: MasteringAssistantStereoParamsRequest): Record<string, number | boolean>;
+/**
+ * Mastering assistant profile of a stereo pair, as shared JSON.
+ *
+ * Only the `loudness` block is measured from the two channels: integrated LUFS
+ * and LRA come from the channel-summed program and the true peak is the larger
+ * of the two. The spectral, dynamics and tempo fields describe shape and timing
+ * rather than absolute level and are measured on the downmix, which keeps them
+ * comparable with {@link masteringAudioProfile}.
+ */
+export declare function masteringAudioProfileStereo(request: MasteringStereoParamsRequest): string;
+/**
+ * Preview streaming-platform normalization for a stereo pair, as shared JSON.
+ *
+ * Measures the integrated loudness with BS.1770 channel summing and reports the
+ * larger of the two channel true peaks. Passing a `0.5 * (left + right)` downmix
+ * to {@link masteringStreamingPreview} instead reads roughly 6 dB low on
+ * decorrelated material, and both the normalization gain and the ceiling-risk
+ * flag follow from that measurement.
+ */
+export declare function masteringStreamingPreviewStereo(request: MasteringStreamingPreviewStereoRequest): string;
+//# sourceMappingURL=mastering_core.d.ts.map