61:I[707087,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/1bpgyrs5qflhu.js","/_next/static/immutable/chunks/0-6vu2ul1h6ld.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"RegistryDependencies"] 62:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/1bpgyrs5qflhu.js","/_next/static/immutable/chunks/0-6vu2ul1h6ld.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 63:T9d03,/** * Source: https://maru.audio/ui-kit/spectrogram * Copyright © [Maru](https://maru.audio) * * Maru UI Kit — https://maru.audio/ui-kit * * Installed from the Maru UI registry. This file is yours now: edit it * freely, it will not be overwritten unless you re-run the add command. * * Keep this item’s companion files and CSS imports together. Dependencies * declared by the registry are installed with the source. */ /** * Spectrogram — a time × frequency heatmap, realtime or static. * * Three modes share one component and one set of pure cores (see `mode`): * * - **realtime** (default): where `Spectrum` shows one instant of the FFT, * this keeps the history — each frame paints a single one-pixel column at * the right edge and shifts the whole image one pixel left, so the display * reads right-to-left as "now" back to a few seconds ago. * - **static**: given a finished buffer (`samples`), the entire signal is * analysed with an offline STFT (`lib/stft`) up front and the complete * picture is painted in one pass, time running left→right. No analyser and * no animation loop — the right tool for a whole clip or an offline render. * - **prepared**: a host supplies bounded magnitudes and exact window-center * timestamps. Rendering never analyzes PCM, and shares a timeline's time * domain and logarithmic MIDI-row bounds. * * Frequency runs up the vertical axis, magnitude is colour, in both modes. * * The scroll is done by blitting the canvas onto itself at a one-pixel offset * rather than by keeping a ring buffer of frames and repainting all of them. * That is O(1) per frame regardless of how much history is on screen, which is * what makes a full-width spectrogram affordable at animation rate — and it is * the trick the Vue original used too. The cost is that history lives only in * the pixels: a resize necessarily loses it (see `useAudioCanvas`, which * re-sizes the backing store on layout changes). * * Two pure, canvas-free cores are exported: `sampleSpectrogramColumn`, which * turns one FFT frame into the column of normalised magnitudes to paint, and * the `SPECTROGRAM_COLOR_SCALES` maps that turn a magnitude into RGB. Both are * unit-testable in Node and reusable by a WebGL or offline renderer. * * Ported from the osc1 Vue `Spectrogram.vue` / `SpectrogramPanel.vue` / * `FrequencyBandsOverTime.vue` trio. Deliberate deviations, matching the * policy the Lissajous port set: * * - No FPS-based auto-degradation. `FrequencyBandsOverTime.vue` throttled * itself to 30 fps by silently skipping frames; a component must not * quietly rewrite the behaviour its caller asked for. Feed it a slower * source, or pause it, if you want fewer frames. * - No analyser construction or connection. The Vue component created its * own `AnalyserNode` and connected the caller's node into it. Here the * analyser comes in through the shared `use-audio-source` contract and is * only ever read — the same bargain every other display in the kit makes. * - The dB→unit normalisation is explicit (`minDecibels`/`maxDecibels`) * rather than riding on `getByteFrequencyData`'s hidden 0..255 mapping, so * the same component works from a `getData` callback with no analyser. * * Styling comes from CSS custom properties — see `lib/theme.ts`. */ import { useCallback, useEffect, useRef } from "react" import type { CSSProperties } from "react" import { COLOR_SCALES, type ColorScale, type ColorScaleName, type RGB, } from "maruaudio/ui/shared/color-scale" import { token } from "maruaudio/ui/shared/theme" import { useAudioCanvas, type AudioSourceProps, } from "maruaudio/ui/shared/use-audio-source" import { computeSpectrogram, toMono, } from "maruaudio/ui/shared/stft" import type { StftSpectrogram } from "maruaudio/ui/shared/stft" import { preparedSpectrogramToRaster, type PreparedSpectrogramData, } from "maruaudio/ui/shared/prepared-spectrogram" export type { PreparedSpectrogramData } from "maruaudio/ui/shared/prepared-spectrogram" /** RGB in 0..255, the form a canvas fill style is built from. */ export type SpectrogramRGB = RGB /** Maps a 0..1 magnitude to a colour. */ export type SpectrogramColorScale = ColorScale export type SpectrogramColorScaleName = ColorScaleName const clampUnit = (value: number): number => value < 0 ? 0 : value > 1 ? 1 : value /** * The colour ramps: the kit's shared `COLOR_SCALES` (`lib/color-scale`), the * real multi-stop scientific colormaps from `d3-scale-chromatic` tabulated * once. Re-exported under the spectrogram's historical name so existing * callers and the WebGL renderer keep the identical ramp the canvas uses. */ export const SPECTROGRAM_COLOR_SCALES: Record< SpectrogramColorScaleName, SpectrogramColorScale > = COLOR_SCALES /** * Frequency in Hz to an FFT bin index, clamped into the buffer. * * Pure. `binCount` bins span 0..nyquist linearly, which is what an FFT gives * you regardless of how the display chooses to lay them out. */ export function frequencyToBin( frequency: number, sampleRate: number, binCount: number ): number { if (binCount <= 0) return 0 const nyquist = sampleRate / 2 const index = Math.floor((frequency / nyquist) * binCount) return Math.max(0, Math.min(binCount - 1, index)) } export interface SpectrogramColumnParams { /** How many pixel rows the column has. */ rows: number /** Sample rate of the analysed signal, for the frequency axis. */ sampleRate: number /** Lowest frequency at the bottom of the column, in Hz. */ minFrequency?: number /** Highest frequency at the top of the column, in Hz. */ maxFrequency?: number /** Bottom of the magnitude range, in dB. */ minDecibels?: number /** Top of the magnitude range, in dB. */ maxDecibels?: number /** Multiplier applied after normalisation, before clamping. */ gain?: number /** Peak preserves narrow partials; mean power estimates energy per Hz. */ reduction?: "peak" | "mean-power" /** * Frequency axis mapping. Log spreads the musically dense low end over * usable height; linear is what the raw bins give you. */ scale?: "log" | "linear" } /** * One frame of dB magnitudes → one column of 0..1 values, bottom row first. * * Pure: no canvas, no DOM, no React. This is the whole of the spectrogram's * data path — everything the component adds on top is colour and blitting — * so the mapping from bins to pixels can be asserted on directly. * * Index 0 is the **bottom** row (lowest frequency). The renderer flips it when * it paints, because canvas y grows downward while frequency should grow up. */ export function sampleSpectrogramColumn( data: Float32Array, { rows, sampleRate, minFrequency = 20, maxFrequency, minDecibels = -90, maxDecibels = -10, gain = 1, scale = "log", reduction = "peak", }: SpectrogramColumnParams ): Float32Array { const rowCount = Math.max(0, Math.floor(rows)) const column = new Float32Array(rowCount) if (rowCount === 0 || data.length === 0) return column const nyquist = sampleRate / 2 const top = Math.min(maxFrequency ?? nyquist, nyquist) // A degenerate range would divide by zero below; a flat column is the honest // answer for "no frequencies requested". const low = Math.max(1, minFrequency) if (top <= low) return column const range = maxDecibels - minDecibels const logLow = Math.log10(low) const logTop = Math.log10(top) // An FFT's bins are evenly spaced in Hz, but a log display axis is not, so // the two disagree at both ends and a single bin per row is wrong in // opposite ways: // // - Low end, rows narrower than a bin. At 48 kHz / 2048 a bin is ~23 Hz, // so 20–100 Hz is about four bins spread over a quarter of the height. // Point sampling snaps whole runs of rows onto the same bin and paints // them identically — the flat horizontal slabs in the bass. // - High end, rows wider than a bin. 10–20 kHz is hundreds of bins folded // into a few dozen rows, so point sampling reads one bin per row and // silently discards the rest — a hi-hat's energy thins to a sparse line // because the bins carrying it were never visited. // // Both are fixed by giving each row the frequency *band* it actually covers // and reducing over it: interpolate when the band is narrower than a bin, // take the peak when it is wider. Peak rather than mean because a // spectrogram is read for partials and transients, and averaging buries a // narrow one in its quiet neighbours. const binWidth = nyquist / Math.max(1, data.length - 1) /** Fractional bin index of a frequency — the un-rounded `frequencyToBin`. */ const exactBin = (frequency: number): number => frequency / binWidth /** Lower edge of row `i`, in Hz, for i in 0..rowCount (edges, not centres). */ const rowEdge = (i: number): number => { const t = i / rowCount return scale === "linear" ? low + (top - low) * t : 10 ** (logLow + (logTop - logLow) * t) } const lastBin = data.length - 1 /** dB at a fractional bin, linearly interpolated between its neighbours. */ const dbAt = (position: number): number => { const clamped = position < 0 ? 0 : position > lastBin ? lastBin : position const lower = Math.floor(clamped) const upper = lower >= lastBin ? lastBin : lower + 1 const a = data[lower] const b = data[upper] // -Infinity is what an analyser reports for silence. Interpolating it // yields NaN, so fall back to whichever neighbour is finite. if (!Number.isFinite(a)) return Number.isFinite(b) ? b : -Infinity if (!Number.isFinite(b)) return a const fraction = clamped - lower return a + (b - a) * fraction } for (let row = 0; row < rowCount; row += 1) { const bandLow = exactBin(rowEdge(row)) const bandHigh = exactBin(rowEdge(row + 1)) let db: number const firstWhole = Math.ceil(bandLow) const lastWhole = Math.floor(bandHigh) if (lastWhole < firstWhole) { // The row falls strictly between two bin centres: no bin to peak over, // so read the interpolated value at the band's centre. This is what // replaces the bass banding with a smooth ramp. db = dbAt((bandLow + bandHigh) / 2) } else if (reduction === "mean-power") { // Average linear power, then return to dB. A wider high band must not // gain level merely because it contains more FFT bins. const from = Math.max(0, firstWhole) const to = Math.min(lastBin, lastWhole) let power = 0 let count = 0 for (let bin = from; bin <= to; bin += 1) { const value = data[bin] if (Number.isFinite(value)) { power += 10 ** (value / 10) count += 1 } } db = count > 0 && power > 0 ? 10 * Math.log10(power / count) : -Infinity } else { // At least one whole bin lands inside. Take the loudest of them, and of // the interpolated band edges so a peak just outside the whole-bin span // is not lost. db = Math.max(dbAt(bandLow), dbAt(bandHigh)) const from = Math.max(0, firstWhole) const to = Math.min(lastBin, lastWhole) for (let bin = from; bin <= to; bin += 1) { const value = data[bin] if (value > db) db = value } } const unit = Number.isFinite(db) && range !== 0 ? (db - minDecibels) / range : 0 column[row] = clampUnit(unit * gain) } return column } /** * How the display is driven. * * - `"realtime"` (default): a live analyser or `getData` callback feeds one * FFT frame per animation tick, and the image scrolls right-to-left so it * reads "now" back to a few seconds ago. This is the historical behaviour. * - `"static"`: a finished buffer (`samples`) is analysed in full up front * and the whole time × frequency picture is painted once — no analyser, no * animation loop. Time runs left→right across the width. Use this to show * an entire clip, an offline render, or a decoded file. * - `"prepared"`: already analyzed display data with explicit timestamps, * suitable for isolated module faces and exact time/pitch overlays. */ export type SpectrogramMode = "realtime" | "static" | "prepared" /** A mono `Float32Array`, or an `AudioBuffer` (down-mixed to mono internally). */ export type SpectrogramSamples = Float32Array | AudioBuffer /** * A lightweight original-versus-modified overlay for a static spectrogram. * * The selected source-time range stays in the same horizontal coordinates as * the original. `frequencyScale` moves the selected spectral image vertically * to preview playback-rate pitch changes without resampling audio or touching * the realtime engine. The expensive STFT raster is cached independently from * these values, so dragging a trim guide only recomposites existing pixels. */ export interface StaticSpectrogramComparison { /** Normalized source-time position of the retained range start. */ start: number /** Normalized source-time position of the retained range end. */ end: number /** Frequency multiplier for the modified layer. Default 1. */ frequencyScale?: number /** Opacity of the complete original raster. Default 0.34. */ originalOpacity?: number /** Opacity of the selected modified layer. Default 1. */ modifiedOpacity?: number } export interface SpectrogramProps extends AudioSourceProps { /** Realtime analyser, static PCM analysis, or prepared display data. Default "realtime". */ mode?: SpectrogramMode /** Prepared mode: bounded host/worker-produced spectral data; no PCM analysis in the face. */ prepared?: PreparedSpectrogramData /** Prepared mode: timeline domain; defaults to the source's duration. */ durationSeconds?: number /** * Static mode only: the audio to analyse. A mono `Float32Array` or an * `AudioBuffer` (down-mixed to mono). Ignored in realtime mode. */ samples?: SpectrogramSamples /** * Static mode only: FFT / analysis window size in samples (rounded up to a * power of two). Larger means finer frequency, coarser time. Default 2048. */ fftSize?: number /** Static mode only: hop between analysis frames, in samples. Default fftSize/4. */ hop?: number width?: number | string height?: number | string /** Colour ramp name, or your own magnitude → RGB function. */ colorScale?: SpectrogramColorScaleName | SpectrogramColorScale /** Lowest frequency shown, in Hz. */ minFrequency?: number /** Highest frequency shown, in Hz. Defaults to the Nyquist limit. */ maxFrequency?: number /** Bottom of the magnitude range, in dB. */ minDecibels?: number /** Top of the magnitude range, in dB. */ maxDecibels?: number /** Magnitude multiplier applied after normalisation. */ gain?: number /** Frequency axis mapping. */ scale?: "log" | "linear" /** Realtime mode only: pixels the image scrolls per frame. Higher is faster, coarser history. */ scrollSpeed?: number /** * Sample rate for the frequency axis. Required in static mode when `samples` * is a bare `Float32Array` (an `AudioBuffer` carries its own); in realtime * mode it defaults from the analyser, and is only needed with `getData`. */ sampleRate?: number /** * Draw the frequency axis labels down the left edge. * * In the Vue panel this was effectively fullscreen-only chrome. Here it is an * unconditional prop, on by default: the caller decides, not the layout. */ showAxis?: boolean /** Static mode only: compare the full source with a trimmed/pitched layer. */ comparison?: StaticSpectrogramComparison className?: string style?: CSSProperties "aria-label"?: string } /** Decade labels a listener actually reads a frequency axis by. */ const AXIS_FREQUENCIES = [100, 1000, 10000] const AXIS_RAIL_X = 5.5 const AXIS_TICK_END_X = 9.5 const AXIS_LABEL_X = 15 const AXIS_INK = "rgba(248, 250, 252, 0.96)" const AXIS_SHADOW = "rgba(2, 6, 23, 0.9)" const formatAxisLabel = (frequency: number): string => frequency >= 1000 ? `${frequency / 1000}k` : `${frequency}` export interface SpectrogramFrequencyTransformParams { height: number sampleRate: number minFrequency: number maxFrequency?: number frequencyScale: number scale: "log" | "linear" } /** * Canvas destination geometry for multiplying every visible frequency. * Exported as a pure core so the visual transform can be pinned in Node tests. */ export function spectrogramFrequencyTransform({ height, sampleRate, minFrequency, maxFrequency, frequencyScale, scale, }: SpectrogramFrequencyTransformParams): { y: number; height: number } { const canvasHeight = Math.max(0, height) const multiplier = Number.isFinite(frequencyScale) && frequencyScale > 0 ? frequencyScale : 1 const nyquist = sampleRate / 2 const top = Math.min(maxFrequency ?? nyquist, nyquist) const low = Math.max(1, minFrequency) if (canvasHeight === 0 || top <= low || multiplier === 1) { return { y: 0, height: canvasHeight } } if (scale === "log") { return { y: (-Math.log(multiplier) / (Math.log(top) - Math.log(low))) * canvasHeight, height: canvasHeight, } } return { y: (canvasHeight * top * (1 - multiplier)) / (top - low), height: canvasHeight * multiplier, } } function sameRasterKey( left: readonly unknown[], right: readonly unknown[] ): boolean { return ( left.length === right.length && left.every((value, index) => Object.is(value, right[index])) ) } interface DrawFrequencyAxisOptions { ctx: CanvasRenderingContext2D width: number height: number sampleRate: number minFrequency: number maxFrequency?: number scale: "log" | "linear" } /** * Draw the frequency scale as a compact rail instead of opaque label plates. * * Bright outlined text gives the scale stronger contrast than the old muted * labels, while the rail and short ticks locate it without covering detail. */ function drawFrequencyAxis({ ctx, width, height, sampleRate, minFrequency, maxFrequency, scale, }: DrawFrequencyAxisOptions): void { const nyquist = sampleRate / 2 const top = Math.min(maxFrequency ?? nyquist, nyquist) const low = Math.max(1, minFrequency) if (top <= low || width <= 0 || height <= 0) return const ticks: Array<{ label: string; y: number }> = [] for (const frequency of AXIS_FREQUENCIES) { if (frequency <= low || frequency >= top) continue const t = scale === "linear" ? (frequency - low) / (top - low) : (Math.log10(frequency) - Math.log10(low)) / (Math.log10(top) - Math.log10(low)) ticks.push({ label: formatAxisLabel(frequency), y: height - t * height }) } if (ticks.length === 0) return ctx.save() ctx.font = "11px ui-monospace, SFMono-Regular, Menlo, monospace" ctx.textAlign = "left" ctx.textBaseline = "middle" ctx.lineCap = "round" ctx.lineJoin = "round" const drawRail = (strokeStyle: string, lineWidth: number) => { ctx.strokeStyle = strokeStyle ctx.lineWidth = lineWidth ctx.beginPath() ctx.moveTo(AXIS_RAIL_X, 1) ctx.lineTo(AXIS_RAIL_X, height - 1) for (const { y } of ticks) { const crispY = Math.round(y) + 0.5 ctx.moveTo(AXIS_RAIL_X, crispY) ctx.lineTo(AXIS_TICK_END_X, crispY) } ctx.stroke() } drawRail(AXIS_SHADOW, 3) drawRail(AXIS_INK, 1) ctx.strokeStyle = AXIS_INK ctx.lineWidth = 1.25 ctx.shadowColor = AXIS_SHADOW ctx.shadowBlur = 2 for (const { label, y } of ticks) { ctx.strokeText(label, AXIS_LABEL_X, y) } ctx.restore() } /** * The historical scrolling spectrogram: one analyser/`getData` frame per * animation tick, blitted right-to-left. Behaviour is unchanged from before * the `mode` prop existed — the dispatcher below routes realtime callers here. */ function RealtimeSpectrogram({ analyser, getData, dataSize = 1024, paused = false, width = "100%", height = 200, colorScale = "viridis", minFrequency = 20, maxFrequency, minDecibels = -90, maxDecibels = -10, gain = 1, scale = "log", scrollSpeed = 1, sampleRate, showAxis = true, className, style, "aria-label": ariaLabel, }: SpectrogramProps) { const canvasRef = useRef(null) const draw = useCallback( ({ ctx, width: w, height: h, data, }: { ctx: CanvasRenderingContext2D width: number height: number data: Float32Array | null }) => { const styles = getComputedStyle(ctx.canvas) const surface = styles.getPropertyValue("--uikit-surface").trim() || "#14161d" const mapper = typeof colorScale === "function" ? colorScale : (SPECTROGRAM_COLOR_SCALES[colorScale] ?? SPECTROGRAM_COLOR_SCALES.viridis) const rate = sampleRate ?? analyser?.context.sampleRate ?? 48000 /** * Axis labels, repainted every frame because the scroll blit drags the * previous frame's labels leftward with the image. */ const drawAxis = () => { drawFrequencyAxis({ ctx, width: w, height: h, sampleRate: rate, minFrequency, maxFrequency, scale, }) } // Resting state: no source attached yet, or paused before the first // frame. Paint the surface so the component is a display rather than a // transparent hole, and stop. if (!data || data.length === 0) { ctx.fillStyle = surface ctx.fillRect(0, 0, w, h) if (showAxis) drawAxis() return } const step = Math.max(1, Math.round(scrollSpeed)) // Scroll: blit the canvas onto itself shifted left by `step`. Copying a // canvas onto itself is well-defined (the source is snapshotted first), // so this needs no scratch canvas — the Vue original kept one only // because it also wanted a separate compositing target. // // The source rect is in the backing store's intrinsic pixels — it does // NOT pass through the current transform; only the destination rect // does. So the source must be the full device-pixel store while the // destination is the full CSS-pixel rect (shifted): mixing the two // frames of reference rescales the image by devicePixelRatio on every // blit, which on a HiDPI screen zooms the whole history exponentially. ctx.drawImage( ctx.canvas, 0, 0, ctx.canvas.width, ctx.canvas.height, -step, 0, w, h ) // One value per device-independent pixel row. Sub-pixel rows would be // averaged away by the canvas anyway. const rows = Math.max(1, Math.round(h)) const column = sampleSpectrogramColumn(data, { rows, sampleRate: rate, minFrequency, maxFrequency, minDecibels, maxDecibels, gain, scale, }) const rowHeight = h / rows for (let row = 0; row < rows; row += 1) { const [r, g, b] = mapper(column[row]) ctx.fillStyle = `rgb(${r}, ${g}, ${b})` // Column index 0 is the lowest frequency, which belongs at the bottom. const y = h - (row + 1) * rowHeight // Overdraw by a hair so rounding never leaves hairline gaps between // adjacent rows on fractional-pixel heights. ctx.fillRect(w - step, y, step, rowHeight + 1) } if (showAxis) drawAxis() }, [ colorScale, minFrequency, maxFrequency, minDecibels, maxDecibels, gain, scale, scrollSpeed, sampleRate, showAxis, analyser, ] ) useAudioCanvas(canvasRef, { analyser, getData, dataSize, paused, kind: "frequency", draw, }) return (