Sample View

sample-viewViewers

A take's waveform and spectrogram on one seconds axis.

$ pnpm dlx shadcn@latest add @pluginui/core-sample-view
Loading interactive preview…

Install

Copies the source into your project. Anything it depends on comes with it. Run this in your React project with shadcn initialized; no registry configuration is needed.

Pulls in

sample-view-geometrysample-view-contextspectrogramprepared-spectrogramsegmented-controluse-surface-pointercontrol-theme
Install using the registry URL
$ pnpm dlx shadcn@latest add https://pluginui.com/r/core-sample-view.json

Usage

Connect the documented props to your application or host.

example.tsx
import { SampleView } from "@/components/ui/sample-view"
import { sampleViewAxisSeconds } from "maruaudio/ui/shared/sample-view-geometry"

<SampleView peaks={take.peaks} spectrogram={take.spectrogram}
  durationSeconds={take.seconds}
  axisSeconds={sampleViewAxisSeconds(take.seconds, envelopeEnd)}
  mode={mode} onModeChange={setMode}
  region={{ start, end, loopStart, loopEnd }} loop={loopOn}
  onRegionChange={writeRegion} playheads={voices}
  overlay={<EnvelopeOverlay value={env} onChange={setEnv} />} />
About Sample View

Draws one take from host-prepared data only: min/max peaks and a prepared spectrogram, as wave, spectrum or both. Start/end and loop handles drag and step in take-normalized units; playheads; a dimmed extension past the take's end; a seconds ruler; and an overlay slot whose children share the time axis, such as the envelope overlay. The view never decodes audio or runs an FFT, and the waveform canvas repaints only when its data or size changes.

Props

PropTypeDefaultDescription
peaks{ min: Float32Array; max: Float32Array; columns: number }—Host-prepared peaks across the take, -1..1.
spectrogramPreparedSpectrogramData—Bounded host-prepared magnitudes with explicit frame times. Without it the spectrum modes are disabled.
durationSeconds / axisSecondsnumber—Take length and the axis length (at least the take). The difference is the dimmed extension.
mode / onModeChange"waveform" | "spectrogram" | "combined"—Controlled view mode; omit for uncontrolled (defaultMode).
region / onRegionChange / loop{ start, end, loopStart?, loopEnd? } / callback / boolean—Take-normalized handles; pairs stay ordered. loop shows the loop handles.
playheads{ id, position, color? }[]—Take-normalized cursors for sounding voices.
overlayReactNode—Drawn over the audio; reads the axis with useSampleViewGeometry. The axis latches during overlay drags.

Interaction

  • Handles Drag start, end and loop lines, or focus one and use arrows (0.5%), Shift (2.5%), PageUp/PageDown (5%), Home/End.
  • Mode Wave, Spectrum or Both; the host remembers the choice per viewer.
All controlsStart building