@waveform-playlist/spectrogram 5.3.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Naomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,161 @@
+import { SpectrogramConfig, SpectrogramData, ColorMapValue, RenderMode } from '@waveform-playlist/core';
+import React, { ReactNode } from 'react';
+
+/**
+ * Compute spectrogram data from an AudioBuffer.
+ */
+
+/**
+ * Compute spectrogram for a single channel of audio.
+ *
+ * @param audioBuffer - Source audio buffer
+ * @param config - Spectrogram configuration
+ * @param offsetSamples - Start offset into the audio buffer
+ * @param durationSamples - Number of samples to process
+ * @param channel - Channel index (0 = left, 1 = right). Default: 0
+ */
+declare function computeSpectrogram(audioBuffer: AudioBuffer, config?: SpectrogramConfig, offsetSamples?: number, durationSamples?: number, channel?: number): SpectrogramData;
+/**
+ * Compute a mono (mixed-down) spectrogram from all channels.
+ */
+declare function computeSpectrogramMono(audioBuffer: AudioBuffer, config?: SpectrogramConfig, offsetSamples?: number, durationSamples?: number): SpectrogramData;
+
+/**
+ * Color maps for spectrogram rendering.
+ * Each map is a 256-entry RGB lookup table (768 bytes).
+ *
+ * Viridis, Magma, Inferno: Perceptually uniform colormaps from matplotlib.
+ * By Stéfan van der Walt, Nathaniel Smith, and Eric Firing. Released under CC0.
+ * Data from https://github.com/BIDS/colormap
+ *
+ * Roseus: Perceptually uniform colormap from https://github.com/dofuuz/roseus
+ * By dofuuz, licensed under CC0 1.0 Universal.
+ */
+
+type ColorLUT = Uint8Array;
+/**
+ * Get a 256-entry RGB LUT for the given color map.
+ */
+declare function getColorMap(value: ColorMapValue): ColorLUT;
+
+/**
+ * Frequency scale mapping functions.
+ * Each maps a frequency (Hz) to a normalized position [0, 1].
+ */
+type FrequencyScaleName = 'linear' | 'logarithmic' | 'mel' | 'bark' | 'erb';
+/**
+ * Returns a mapping function: (frequencyHz, minFrequency, maxFrequency) → [0, 1]
+ */
+declare function getFrequencyScale(name: FrequencyScaleName): (f: number, minF: number, maxF: number) => number;
+
+interface TrackMenuItem {
+    id: string;
+    label?: string;
+    content: ReactNode;
+}
+
+interface SpectrogramMenuItemsProps {
+    renderMode: RenderMode;
+    onRenderModeChange: (mode: RenderMode) => void;
+    onOpenSettings: () => void;
+    onClose?: () => void;
+}
+/**
+ * Returns TrackMenuItem[] for the spectrogram display mode radios and settings button.
+ */
+declare function SpectrogramMenuItems({ renderMode, onRenderModeChange, onOpenSettings, onClose, }: SpectrogramMenuItemsProps): TrackMenuItem[];
+
+interface SpectrogramSettingsModalProps {
+    open: boolean;
+    onClose: () => void;
+    config: SpectrogramConfig;
+    colorMap: ColorMapValue;
+    onApply: (config: SpectrogramConfig, colorMap: ColorMapValue) => void;
+}
+declare const SpectrogramSettingsModal: React.FC<SpectrogramSettingsModalProps>;
+
+interface SpectrogramWorkerComputeParams {
+    channelDataArrays: Float32Array[];
+    config: SpectrogramConfig;
+    sampleRate: number;
+    offsetSamples: number;
+    durationSamples: number;
+    mono: boolean;
+}
+interface SpectrogramWorkerRenderParams extends SpectrogramWorkerComputeParams {
+    render: {
+        canvasIds: string[][];
+        canvasWidths: number[];
+        canvasHeight: number;
+        devicePixelRatio: number;
+        samplesPerPixel: number;
+        colorLUT: Uint8Array;
+        frequencyScale: string;
+        minFrequency: number;
+        maxFrequency: number;
+    };
+}
+interface SpectrogramWorkerFFTParams {
+    clipId: string;
+    channelDataArrays: Float32Array[];
+    config: SpectrogramConfig;
+    sampleRate: number;
+    offsetSamples: number;
+    durationSamples: number;
+    mono: boolean;
+    sampleRange?: {
+        start: number;
+        end: number;
+    };
+}
+interface SpectrogramWorkerRenderChunksParams {
+    cacheKey: string;
+    canvasIds: string[];
+    canvasWidths: number[];
+    globalPixelOffsets: number[];
+    canvasHeight: number;
+    devicePixelRatio: number;
+    samplesPerPixel: number;
+    colorLUT: Uint8Array;
+    frequencyScale: string;
+    minFrequency: number;
+    maxFrequency: number;
+    gainDb: number;
+    rangeDb: number;
+    channelIndex: number;
+}
+interface SpectrogramWorkerApi {
+    compute(params: SpectrogramWorkerComputeParams): Promise<SpectrogramData[]>;
+    computeFFT(params: SpectrogramWorkerFFTParams): Promise<{
+        cacheKey: string;
+    }>;
+    renderChunks(params: SpectrogramWorkerRenderChunksParams): Promise<void>;
+    registerCanvas(canvasId: string, canvas: OffscreenCanvas): void;
+    unregisterCanvas(canvasId: string): void;
+    registerAudioData(clipId: string, channelDataArrays: Float32Array[], sampleRate: number): void;
+    unregisterAudioData(clipId: string): void;
+    computeAndRender(params: SpectrogramWorkerRenderParams): Promise<void>;
+    terminate(): void;
+}
+/**
+ * Wraps a Web Worker running `spectrogram.worker.ts` with a promise-based API.
+ *
+ * The caller is responsible for creating the Worker, e.g.:
+ * ```ts
+ * const worker = new Worker(
+ *   new URL('@waveform-playlist/spectrogram/worker/spectrogram.worker', import.meta.url),
+ *   { type: 'module' }
+ * );
+ * const api = createSpectrogramWorker(worker);
+ * ```
+ */
+declare function createSpectrogramWorker(worker: Worker): SpectrogramWorkerApi;
+
+interface SpectrogramProviderProps {
+    config?: SpectrogramConfig;
+    colorMap?: ColorMapValue;
+    children: ReactNode;
+}
+declare const SpectrogramProvider: React.FC<SpectrogramProviderProps>;
+
+export { type FrequencyScaleName, SpectrogramMenuItems, type SpectrogramMenuItemsProps, SpectrogramProvider, type SpectrogramProviderProps, SpectrogramSettingsModal, type SpectrogramSettingsModalProps, type SpectrogramWorkerApi, type SpectrogramWorkerRenderParams, type TrackMenuItem, computeSpectrogram, computeSpectrogramMono, createSpectrogramWorker, getColorMap, getFrequencyScale };

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+import { SpectrogramConfig, SpectrogramData, ColorMapValue, RenderMode } from '@waveform-playlist/core';
+import React, { ReactNode } from 'react';
+
+/**
+ * Compute spectrogram data from an AudioBuffer.
+ */
+
+/**
+ * Compute spectrogram for a single channel of audio.
+ *
+ * @param audioBuffer - Source audio buffer
+ * @param config - Spectrogram configuration
+ * @param offsetSamples - Start offset into the audio buffer
+ * @param durationSamples - Number of samples to process
+ * @param channel - Channel index (0 = left, 1 = right). Default: 0
+ */
+declare function computeSpectrogram(audioBuffer: AudioBuffer, config?: SpectrogramConfig, offsetSamples?: number, durationSamples?: number, channel?: number): SpectrogramData;
+/**
+ * Compute a mono (mixed-down) spectrogram from all channels.
+ */
+declare function computeSpectrogramMono(audioBuffer: AudioBuffer, config?: SpectrogramConfig, offsetSamples?: number, durationSamples?: number): SpectrogramData;
+
+/**
+ * Color maps for spectrogram rendering.
+ * Each map is a 256-entry RGB lookup table (768 bytes).
+ *
+ * Viridis, Magma, Inferno: Perceptually uniform colormaps from matplotlib.
+ * By Stéfan van der Walt, Nathaniel Smith, and Eric Firing. Released under CC0.
+ * Data from https://github.com/BIDS/colormap
+ *
+ * Roseus: Perceptually uniform colormap from https://github.com/dofuuz/roseus
+ * By dofuuz, licensed under CC0 1.0 Universal.
+ */
+
+type ColorLUT = Uint8Array;
+/**
+ * Get a 256-entry RGB LUT for the given color map.
+ */
+declare function getColorMap(value: ColorMapValue): ColorLUT;
+
+/**
+ * Frequency scale mapping functions.
+ * Each maps a frequency (Hz) to a normalized position [0, 1].
+ */
+type FrequencyScaleName = 'linear' | 'logarithmic' | 'mel' | 'bark' | 'erb';
+/**
+ * Returns a mapping function: (frequencyHz, minFrequency, maxFrequency) → [0, 1]
+ */
+declare function getFrequencyScale(name: FrequencyScaleName): (f: number, minF: number, maxF: number) => number;
+
+interface TrackMenuItem {
+    id: string;
+    label?: string;
+    content: ReactNode;
+}
+
+interface SpectrogramMenuItemsProps {
+    renderMode: RenderMode;
+    onRenderModeChange: (mode: RenderMode) => void;
+    onOpenSettings: () => void;
+    onClose?: () => void;
+}
+/**
+ * Returns TrackMenuItem[] for the spectrogram display mode radios and settings button.
+ */
+declare function SpectrogramMenuItems({ renderMode, onRenderModeChange, onOpenSettings, onClose, }: SpectrogramMenuItemsProps): TrackMenuItem[];
+
+interface SpectrogramSettingsModalProps {
+    open: boolean;
+    onClose: () => void;
+    config: SpectrogramConfig;
+    colorMap: ColorMapValue;
+    onApply: (config: SpectrogramConfig, colorMap: ColorMapValue) => void;
+}
+declare const SpectrogramSettingsModal: React.FC<SpectrogramSettingsModalProps>;
+
+interface SpectrogramWorkerComputeParams {
+    channelDataArrays: Float32Array[];
+    config: SpectrogramConfig;
+    sampleRate: number;
+    offsetSamples: number;
+    durationSamples: number;
+    mono: boolean;
+}
+interface SpectrogramWorkerRenderParams extends SpectrogramWorkerComputeParams {
+    render: {
+        canvasIds: string[][];
+        canvasWidths: number[];
+        canvasHeight: number;
+        devicePixelRatio: number;
+        samplesPerPixel: number;
+        colorLUT: Uint8Array;
+        frequencyScale: string;
+        minFrequency: number;
+        maxFrequency: number;
+    };
+}
+interface SpectrogramWorkerFFTParams {
+    clipId: string;
+    channelDataArrays: Float32Array[];
+    config: SpectrogramConfig;
+    sampleRate: number;
+    offsetSamples: number;
+    durationSamples: number;
+    mono: boolean;
+    sampleRange?: {
+        start: number;
+        end: number;
+    };
+}
+interface SpectrogramWorkerRenderChunksParams {
+    cacheKey: string;
+    canvasIds: string[];
+    canvasWidths: number[];
+    globalPixelOffsets: number[];
+    canvasHeight: number;
+    devicePixelRatio: number;
+    samplesPerPixel: number;
+    colorLUT: Uint8Array;
+    frequencyScale: string;
+    minFrequency: number;
+    maxFrequency: number;
+    gainDb: number;
+    rangeDb: number;
+    channelIndex: number;
+}
+interface SpectrogramWorkerApi {
+    compute(params: SpectrogramWorkerComputeParams): Promise<SpectrogramData[]>;
+    computeFFT(params: SpectrogramWorkerFFTParams): Promise<{
+        cacheKey: string;
+    }>;
+    renderChunks(params: SpectrogramWorkerRenderChunksParams): Promise<void>;
+    registerCanvas(canvasId: string, canvas: OffscreenCanvas): void;
+    unregisterCanvas(canvasId: string): void;
+    registerAudioData(clipId: string, channelDataArrays: Float32Array[], sampleRate: number): void;
+    unregisterAudioData(clipId: string): void;
+    computeAndRender(params: SpectrogramWorkerRenderParams): Promise<void>;
+    terminate(): void;
+}
+/**
+ * Wraps a Web Worker running `spectrogram.worker.ts` with a promise-based API.
+ *
+ * The caller is responsible for creating the Worker, e.g.:
+ * ```ts
+ * const worker = new Worker(
+ *   new URL('@waveform-playlist/spectrogram/worker/spectrogram.worker', import.meta.url),
+ *   { type: 'module' }
+ * );
+ * const api = createSpectrogramWorker(worker);
+ * ```
+ */
+declare function createSpectrogramWorker(worker: Worker): SpectrogramWorkerApi;
+
+interface SpectrogramProviderProps {
+    config?: SpectrogramConfig;
+    colorMap?: ColorMapValue;
+    children: ReactNode;
+}
+declare const SpectrogramProvider: React.FC<SpectrogramProviderProps>;
+
+export { type FrequencyScaleName, SpectrogramMenuItems, type SpectrogramMenuItemsProps, SpectrogramProvider, type SpectrogramProviderProps, SpectrogramSettingsModal, type SpectrogramSettingsModalProps, type SpectrogramWorkerApi, type SpectrogramWorkerRenderParams, type TrackMenuItem, computeSpectrogram, computeSpectrogramMono, createSpectrogramWorker, getColorMap, getFrequencyScale };