@libraz/libsonare 1.7.2 → 1.8.1

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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"}