spectral-display 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +174 -0
- package/dist/index.d.ts +129 -0
- package/dist/index.js +1751 -0
- package/package.json +45 -0
package/README.md
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Spectral Display
|
|
2
|
+
|
|
3
|
+
WebGPU-accelerated audio visualization for React. Renders spectrograms, waveforms, and BS.1770-4 loudness metrics from raw audio samples.
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- GPU-accelerated spectrogram via WebGPU compute shaders (Cooley-Tukey FFT)
|
|
10
|
+
- Waveform rendering with min/max peak envelope
|
|
11
|
+
- BS.1770-4 loudness measurement — momentary, short-term, and integrated LUFS
|
|
12
|
+
- Configurable frequency scales: linear, log, mel, ERB
|
|
13
|
+
- Built-in colormaps (lava, viridis) with custom colormap support
|
|
14
|
+
- BS.1770-4 true peak measurement via 4x oversampling
|
|
15
|
+
- Configurable computation toggles — disable spectrogram, loudness, or true peak independently
|
|
16
|
+
- Streaming architecture — processes audio in chunks without loading entire files into memory
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
npm install spectral-display
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Peer dependencies: `react >= 18`, `react-dom >= 18`
|
|
25
|
+
|
|
26
|
+
## Quick Start
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
import { useSpectralCompute, SpectrogramCanvas, WaveformCanvas, LoudnessCanvas } from "spectral-display";
|
|
30
|
+
|
|
31
|
+
function AudioDisplay({ device, metadata, readSamples }) {
|
|
32
|
+
const computeResult = useSpectralCompute({
|
|
33
|
+
metadata,
|
|
34
|
+
query: { startMs: 0, endMs: 30000, width: 800, height: 200 },
|
|
35
|
+
readSamples,
|
|
36
|
+
config: { device, frequencyScale: "mel", colormap: "lava" },
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
return (
|
|
40
|
+
<div style={{ position: "relative", width: 800, height: 200 }}>
|
|
41
|
+
<SpectrogramCanvas computeResult={computeResult} />
|
|
42
|
+
<div style={{ position: "absolute", inset: 0 }}>
|
|
43
|
+
<WaveformCanvas computeResult={computeResult} />
|
|
44
|
+
</div>
|
|
45
|
+
<div style={{ position: "absolute", inset: 0 }}>
|
|
46
|
+
<LoudnessCanvas computeResult={computeResult} />
|
|
47
|
+
</div>
|
|
48
|
+
</div>
|
|
49
|
+
);
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Pass your own `GPUDevice` via `config.device` to share it across components. If omitted, the hook acquires one automatically.
|
|
54
|
+
|
|
55
|
+
The `readSamples` callback provides audio data on demand:
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
const readSamples = (channel: number, sampleOffset: number, sampleCount: number) => {
|
|
59
|
+
// Return a Float32Array of samples for the given channel and range
|
|
60
|
+
return Promise.resolve(channelData[channel].subarray(sampleOffset, sampleOffset + sampleCount));
|
|
61
|
+
};
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Visualizations
|
|
65
|
+
|
|
66
|
+
### Spectrogram
|
|
67
|
+
|
|
68
|
+
Frequency content over time. Supports linear, log, mel, and ERB frequency scales with configurable FFT size, dB range, and colormap.
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
### Waveform
|
|
73
|
+
|
|
74
|
+
Peak amplitude envelope showing min/max sample values per time column.
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
### Loudness
|
|
79
|
+
|
|
80
|
+
BS.1770-4 loudness metrics: RMS envelope (filled), momentary LUFS (400ms window), short-term LUFS (3s window), and integrated LUFS (horizontal dashed line). LUFS values are mapped to amplitude (`10^(lufs/20)`) so they visually correspond to the waveform scale. True peak is shown as a red dashed horizontal line at the interpolated peak amplitude.
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
## API
|
|
85
|
+
|
|
86
|
+
### `useSpectralCompute(options: SpectralOptions): ComputeResult`
|
|
87
|
+
|
|
88
|
+
The main hook. Manages the GPU engine lifecycle, runs the processing pipeline, and returns results reactively.
|
|
89
|
+
|
|
90
|
+
#### SpectralOptions
|
|
91
|
+
|
|
92
|
+
| Field | Type | Description |
|
|
93
|
+
| ------------- | --------------------------------------------------- | --------------------------------- |
|
|
94
|
+
| `metadata` | `SpectralMetadata` | Audio file properties |
|
|
95
|
+
| `query` | `SpectralQuery` | Time range and output dimensions |
|
|
96
|
+
| `readSamples` | `(channel, offset, count) => Promise<Float32Array>` | Callback to provide audio samples |
|
|
97
|
+
| `config` | `Partial<SpectralConfig>` | Optional processing configuration |
|
|
98
|
+
|
|
99
|
+
#### SpectralMetadata
|
|
100
|
+
|
|
101
|
+
| Field | Type | Description |
|
|
102
|
+
| ---------------- | ----------------------- | ----------------------------------------------------- |
|
|
103
|
+
| `sampleRate` | `number` | Sample rate in Hz |
|
|
104
|
+
| `sampleCount` | `number` | Total samples per channel |
|
|
105
|
+
| `channelCount` | `number` | Number of audio channels |
|
|
106
|
+
| `channelWeights` | `ReadonlyArray<number>` | Optional BS.1770-4 channel weights (default: all 1.0) |
|
|
107
|
+
|
|
108
|
+
#### SpectralQuery
|
|
109
|
+
|
|
110
|
+
| Field | Type | Description |
|
|
111
|
+
| --------- | -------- | -------------------------- |
|
|
112
|
+
| `startMs` | `number` | Start time in milliseconds |
|
|
113
|
+
| `endMs` | `number` | End time in milliseconds |
|
|
114
|
+
| `width` | `number` | Output width in pixels |
|
|
115
|
+
| `height` | `number` | Output height in pixels |
|
|
116
|
+
|
|
117
|
+
#### SpectralConfig
|
|
118
|
+
|
|
119
|
+
All fields are optional — defaults are applied automatically.
|
|
120
|
+
|
|
121
|
+
| Field | Type | Default | Description |
|
|
122
|
+
| ---------------- | ------------------------------ | ----------- | ------------------------------------------------- |
|
|
123
|
+
| `fftSize` | `number` | `4096` | FFT window size (power of 2) |
|
|
124
|
+
| `frequencyScale` | `FrequencyScale` | `"log"` | `"linear"`, `"log"`, `"mel"`, or `"erb"` |
|
|
125
|
+
| `dbRange` | `[number, number]` | `[-120, 0]` | Spectrogram dB range [min, max] |
|
|
126
|
+
| `colormap` | `string \| ColormapDefinition` | `"lava"` | `"lava"`, `"viridis"`, or custom colormap |
|
|
127
|
+
| `waveformColor` | `[number, number, number]` | Auto | RGB color for waveform rendering |
|
|
128
|
+
| `device` | `GPUDevice` | Auto | WebGPU device (acquired automatically if omitted) |
|
|
129
|
+
| `signal` | `AbortSignal` | Internal | External abort signal for cancellation |
|
|
130
|
+
| `spectrogram` | `boolean` | `true` | Enable spectrogram GPU computation |
|
|
131
|
+
| `loudness` | `boolean` | `true` | Enable K-weighting and LUFS computation |
|
|
132
|
+
| `truePeak` | `boolean` | `true` | Enable BS.1770-4 true peak measurement |
|
|
133
|
+
|
|
134
|
+
#### ComputeResult
|
|
135
|
+
|
|
136
|
+
Discriminated union with `status` field:
|
|
137
|
+
|
|
138
|
+
- `{ status: "idle" }` — no computation started
|
|
139
|
+
- `{ status: "error", error: Error }` — pipeline failed
|
|
140
|
+
- `{ status: "ready", spectrogramTexture, waveformBuffer, waveformPointCount, loudnessData, options }` — results available
|
|
141
|
+
|
|
142
|
+
### Components
|
|
143
|
+
|
|
144
|
+
#### `<SpectrogramCanvas computeResult={computeResult} />`
|
|
145
|
+
|
|
146
|
+
Renders the spectrogram texture to a canvas via GPU blit.
|
|
147
|
+
|
|
148
|
+
#### `<WaveformCanvas computeResult={computeResult} color={[r, g, b]} />`
|
|
149
|
+
|
|
150
|
+
Renders the waveform envelope via GPU compute. `color` is optional RGB (0-255).
|
|
151
|
+
|
|
152
|
+
#### `<LoudnessCanvas computeResult={computeResult} />`
|
|
153
|
+
|
|
154
|
+
Renders loudness metrics on a 2D canvas. Optional boolean props to toggle each visualization:
|
|
155
|
+
|
|
156
|
+
| Prop | Default | Description |
|
|
157
|
+
| ------------- | -------- | --------------------------------- |
|
|
158
|
+
| `rmsEnvelope` | `true` | RMS amplitude envelope fill |
|
|
159
|
+
| `momentary` | `false` | 400ms momentary LUFS line |
|
|
160
|
+
| `shortTerm` | `false` | 3s short-term LUFS line |
|
|
161
|
+
| `integrated` | `true` | Integrated LUFS horizontal line |
|
|
162
|
+
| `truePeak` | `false` | True peak amplitude line |
|
|
163
|
+
| `colors` | Built-in | Override colors per visualization |
|
|
164
|
+
|
|
165
|
+
All components accept a `ref` prop for canvas element access.
|
|
166
|
+
|
|
167
|
+
## Browser Requirements
|
|
168
|
+
|
|
169
|
+
- **WebGPU** — required for spectrogram and waveform rendering. Check `navigator.gpu` for support.
|
|
170
|
+
- **`scheduler.yield()`** — optional. Used for cooperative yielding during processing. Falls back to `setTimeout` if unavailable.
|
|
171
|
+
|
|
172
|
+
## License
|
|
173
|
+
|
|
174
|
+
ISC
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
type FrequencyScale = "linear" | "log" | "mel" | "erb";
|
|
2
|
+
|
|
3
|
+
interface ColormapDefinition {
|
|
4
|
+
colors: ReadonlyArray<{
|
|
5
|
+
position: number;
|
|
6
|
+
color: readonly [number, number, number];
|
|
7
|
+
}>;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
type RequiredProperties<D extends object, K extends keyof D> = Pick<D, K> & Partial<Omit<D, K>>;
|
|
11
|
+
|
|
12
|
+
interface Dimensions {
|
|
13
|
+
width: number;
|
|
14
|
+
height: number;
|
|
15
|
+
}
|
|
16
|
+
interface SpectralConfig {
|
|
17
|
+
fftSize: number;
|
|
18
|
+
frequencyScale: FrequencyScale;
|
|
19
|
+
dbRange: [number, number];
|
|
20
|
+
colormap: "lava" | "viridis" | ColormapDefinition;
|
|
21
|
+
waveformColor: [number, number, number];
|
|
22
|
+
device: GPUDevice;
|
|
23
|
+
signal: AbortSignal;
|
|
24
|
+
spectrogram: boolean;
|
|
25
|
+
loudness: boolean;
|
|
26
|
+
truePeak: boolean;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
interface SpectralMetadata {
|
|
30
|
+
sampleRate: number;
|
|
31
|
+
sampleCount: number;
|
|
32
|
+
channelCount: number;
|
|
33
|
+
channelWeights?: ReadonlyArray<number>;
|
|
34
|
+
}
|
|
35
|
+
interface SampleQuery extends Dimensions {
|
|
36
|
+
startSample: number;
|
|
37
|
+
endSample: number;
|
|
38
|
+
}
|
|
39
|
+
interface PipelineOptions {
|
|
40
|
+
metadata: SpectralMetadata;
|
|
41
|
+
sampleQuery: SampleQuery;
|
|
42
|
+
readSamples: (channel: number, sampleOffset: number, sampleCount: number) => Promise<Float32Array>;
|
|
43
|
+
config: RequiredProperties<SpectralConfig, "device" | "signal">;
|
|
44
|
+
}
|
|
45
|
+
interface ResolvedPipelineOptions extends PipelineOptions {
|
|
46
|
+
config: SpectralConfig;
|
|
47
|
+
}
|
|
48
|
+
interface PipelineResult {
|
|
49
|
+
waveformBuffer: Float32Array;
|
|
50
|
+
waveformPointCount: number;
|
|
51
|
+
loudnessData: LoudnessData | null;
|
|
52
|
+
spectrogramTexture: GPUTexture | null;
|
|
53
|
+
options: ResolvedPipelineOptions;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
interface LoudnessData {
|
|
57
|
+
rmsEnvelope: Float32Array;
|
|
58
|
+
peakEnvelope: Float32Array;
|
|
59
|
+
momentaryLufs: Float32Array;
|
|
60
|
+
shortTermLufs: Float32Array;
|
|
61
|
+
integratedLufs: number;
|
|
62
|
+
peakDb: number;
|
|
63
|
+
truePeak?: number;
|
|
64
|
+
truePeakDb?: number;
|
|
65
|
+
rmsDb: number;
|
|
66
|
+
crestFactor: number;
|
|
67
|
+
pointCount: number;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
interface SpectralQuery extends Dimensions {
|
|
71
|
+
startMs: number;
|
|
72
|
+
endMs: number;
|
|
73
|
+
}
|
|
74
|
+
interface SpectralOptions {
|
|
75
|
+
metadata: SpectralMetadata;
|
|
76
|
+
query: SpectralQuery;
|
|
77
|
+
readSamples: (channel: number, sampleOffset: number, sampleCount: number) => Promise<Float32Array>;
|
|
78
|
+
config?: Partial<SpectralConfig>;
|
|
79
|
+
}
|
|
80
|
+
type ComputeResult = {
|
|
81
|
+
status: "idle";
|
|
82
|
+
} | {
|
|
83
|
+
status: "error";
|
|
84
|
+
error: Error;
|
|
85
|
+
} | {
|
|
86
|
+
status: "ready";
|
|
87
|
+
spectrogramTexture: GPUTexture | null;
|
|
88
|
+
waveformBuffer: Float32Array | null;
|
|
89
|
+
waveformPointCount: number;
|
|
90
|
+
loudnessData: LoudnessData | null;
|
|
91
|
+
options: ResolvedPipelineOptions;
|
|
92
|
+
};
|
|
93
|
+
declare function useSpectralCompute(options: SpectralOptions): ComputeResult;
|
|
94
|
+
|
|
95
|
+
interface LoudnessCanvasProps {
|
|
96
|
+
computeResult: ComputeResult;
|
|
97
|
+
rmsEnvelope?: boolean;
|
|
98
|
+
momentary?: boolean;
|
|
99
|
+
shortTerm?: boolean;
|
|
100
|
+
integrated?: boolean;
|
|
101
|
+
truePeak?: boolean;
|
|
102
|
+
colors?: {
|
|
103
|
+
rms?: string;
|
|
104
|
+
momentary?: string;
|
|
105
|
+
shortTerm?: string;
|
|
106
|
+
integrated?: string;
|
|
107
|
+
truePeak?: string;
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
declare const LoudnessCanvas: React.FC<LoudnessCanvasProps>;
|
|
111
|
+
|
|
112
|
+
interface SpectrogramCanvasProps {
|
|
113
|
+
computeResult: ComputeResult;
|
|
114
|
+
ref?: React.Ref<HTMLCanvasElement>;
|
|
115
|
+
}
|
|
116
|
+
declare const SpectrogramCanvas: React.FC<SpectrogramCanvasProps>;
|
|
117
|
+
|
|
118
|
+
declare const lavaColormap: ColormapDefinition;
|
|
119
|
+
|
|
120
|
+
declare const viridisColormap: ColormapDefinition;
|
|
121
|
+
|
|
122
|
+
interface WaveformCanvasProps {
|
|
123
|
+
computeResult: ComputeResult;
|
|
124
|
+
ref?: React.Ref<HTMLCanvasElement>;
|
|
125
|
+
color?: [number, number, number];
|
|
126
|
+
}
|
|
127
|
+
declare const WaveformCanvas: React.FC<WaveformCanvasProps>;
|
|
128
|
+
|
|
129
|
+
export { type ColormapDefinition, type ComputeResult, type Dimensions, type FrequencyScale, LoudnessCanvas, type LoudnessCanvasProps, type LoudnessData, type PipelineOptions, type PipelineResult, type ResolvedPipelineOptions, type SampleQuery, type SpectralConfig, type SpectralMetadata, type SpectralOptions, type SpectralQuery, SpectrogramCanvas, WaveformCanvas, lavaColormap, useSpectralCompute, viridisColormap };
|