Sample View

sample-viewViewers

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.

Bone / Studio

Loading interactive preview…

Planar / Flat

Loading interactive preview…

Midnight / Minimal

Loading interactive preview…

Ember / Vintage

Loading interactive preview…

Ink / Studio

Loading interactive preview…

Mint / Flat

Loading interactive preview…

Install

Copies the source into your project. Anything it depends on comes with it.

$ pnpm dlx shadcn@latest add @pluginui/core-sample-view

Pulls in

sample-view-geometrysample-view-contextspectrogramprepared-spectrogramsegmented-controluse-surface-pointercontrol-theme

First time? Add the registry to your components.json once:

components.json

{
  "registries": {
    "@pluginui": "https://pluginui.com/r/{name}.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} />} />

Props

Prop	Type	Default	Description
peaks	{ min: Float32Array; max: Float32Array; columns: number }	—	Host-prepared peaks across the take, -1..1.
spectrogram	PreparedSpectrogramData	—	Bounded host-prepared magnitudes with explicit frame times. Without it the spectrum modes are disabled.
durationSeconds / axisSeconds	number	—	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.
overlay	ReactNode	—	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 controls Start building