ISonoscope

Central coordinator managing audio playback, viewport state, and viewer creation.

Properties

Property	Modifier	Type	Description
source	readonly	AudioSource	Active audio source.
viewport	readonly	IViewportController	Viewport controller managing time and frequency axes.

Methods

attachAudio()

attachAudio(audio: HTMLAudioElement): void;

Connects an HTML audio element to synchronize playhead and time updates.

Parameters

Parameter	Type
audio	HTMLAudioElement

Returns

void

---

attachNavigation()

attachNavigation(container: HTMLElement, options?: NavigationOptions): () => void;

Attaches pan and zoom navigation handlers to a DOM element.

Parameters

Parameter	Type	Description
container	HTMLElement	DOM element to receive pointer and wheel events.
options?	NavigationOptions	Gesture configuration.

Returns

Unsubscribe function that removes event listeners.

() => void

---

attachPlayhead()

attachPlayhead(container: HTMLElement, options?: PlayheadOverlayOptions): () => void;

Attaches a synchronized playback playhead overlay to a DOM container.

Parameters

Parameter	Type	Description
container	HTMLElement	DOM element that will host the playhead line.
options?	PlayheadOverlayOptions	Visual styling options for the playhead overlay.

Returns

Cleanup function that removes the playhead element and unsubscribes event listeners.

() => void

---

destroy()

destroy(): void;

Disposes the coordinator, audio listeners, and animation loops.

Returns

void

---

detachAudio()

detachAudio(): void;

Disconnects the HTML audio element.

Returns

void

---

fork()

fork(options?: Partial<SonoscopeOptions>): ISonoscope;

Creates an independent coordinator sharing the same audio source.

Parameters

Parameter	Type
options?	Partial<SonoscopeOptions>

Returns

ISonoscope

---

getAudio()

getAudio(): HTMLAudioElement | undefined;

Returns attached HTML audio element if present.

Returns

HTMLAudioElement | undefined

---

getClipBounds()

getClipBounds(): object;

Returns active clip start and end boundaries in seconds.

Returns

object

clipEnd?

optional clipEnd?: number;

clipStart?

optional clipStart?: number;

---

getCurrentTime()

getCurrentTime(): number;

Returns current audio playback position in seconds.

Returns

number

---

getDuration()

getDuration(): number;

Returns total audio duration in seconds.

Returns

number

---

getFollowPlayback()

getFollowPlayback(): FollowPlaybackMode;

Returns active playback follow mode.

Returns

FollowPlaybackMode

---

getNyquist()

getNyquist(): number;

Returns Nyquist frequency (sampleRate / 2) in Hz.

Returns

number

---

getSampleRate()

getSampleRate(): number;

Returns audio sample rate in Hz.

Returns

number

---

getViewport()

getViewport(): ViewportState;

Returns the current viewport state.

Returns

ViewportState

---

getViewportController()

getViewportController(): IViewportController;

Returns the underlying viewport controller.

Returns

IViewportController

---

isPlaying()

isPlaying(): boolean;

Returns true if audio playback is currently active.

Returns

boolean

---

on()

on<K>(event: K, handler: (e: SonoscopeEvents[K]) => void): () => void;

Subscribes to coordinator events.

Type Parameters

Type Parameter
K extends keyof SonoscopeEvents

Parameters

Parameter	Type
event	K
handler	(e: SonoscopeEvents[K]) => void

Returns

() => void

---

pan()

pan(deltaSeconds: number, source?: string): void;

Shifts viewport time range by a delta in seconds.

Parameters

Parameter	Type
deltaSeconds	number
source?	string

Returns

void

---

panFrequency()

panFrequency(deltaHz: number, source?: string): void;

Shifts viewport frequency range by a delta in Hz.

Parameters

Parameter	Type
deltaHz	number
source?	string

Returns

void

---

panTo()

panTo(startTime: number, source?: string): void;

Moves viewport start to a specific timestamp in seconds.

Parameters

Parameter	Type
startTime	number
source?	string

Returns

void

---

seek()

seek(time: number): void;

Seeks audio and updates playhead timestamp in seconds.

Parameters

Parameter	Type
time	number

Returns

void

---

setClipBounds()

setClipBounds(bounds: object): void;

Updates audio clip boundaries in seconds without re-creating the source.

Parameters

Parameter	Type
bounds	{ clipEnd?: number; clipStart?: number; }
bounds.clipEnd?	number
bounds.clipStart?	number

Returns

void

---

setFollowPlayback()

setFollowPlayback(mode: FollowPlaybackMode): void;

Sets playback follow mode (page, smooth, or off).

Parameters

Parameter	Type
mode	FollowPlaybackMode

Returns

void

---

setSource()

setSource(source: AudioSource): void;

Replaces the audio source and updates all attached viewers.

Parameters

Parameter	Type
source	AudioSource

Returns

void

---

setViewport()

setViewport(vp: Partial<ViewportConfig>, source?: string): void;

Updates viewport coordinates.

Parameters

Parameter	Type
vp	Partial<ViewportConfig>
source?	string

Returns

void

---

updateViewport()

updateViewport(vp: Partial<ViewportConfig>, source?: string): void;

Alias for setViewport.

Parameters

Parameter	Type
vp	Partial<ViewportConfig>
source?	string

Returns

void

---

zoom()

zoom(
   factor: number,
   centerTime?: number,
   source?: string): void;

Zooms the time axis.

Parameters

Parameter	Type
factor	number
centerTime?	number
source?	string

Returns

void

---

zoomBoth()

zoomBoth(
   factor:
  | number
  | {
  frequency: number;
  time: number;
},
   center?: object,
   source?: string): void;

Zooms both time and frequency axes.

Parameters

Parameter	Type
factor	| number | { frequency: number; time: number; }
center?	{ frequency?: number; time?: number; }
center.frequency?	number
center.time?	number
source?	string

Returns

void

---

zoomFreq()

zoomFreq(
   factor: number,
   centerFrequency?: number,
   source?: string): void;

Alias for zoomFrequency.

Parameters

Parameter	Type
factor	number
centerFrequency?	number
source?	string

Returns

void

---

zoomFrequency()

zoomFrequency(
   factor: number,
   centerFrequency?: number,
   source?: string): void;

Zooms the frequency axis around an optional center in Hz.

Parameters

Parameter	Type
factor	number
centerFrequency?	number
source?	string

Returns

void

---

zoomTime()

zoomTime(
   factor: number,
   centerTime?: number,
   source?: string): void;

Zooms the time axis.

Parameters

Parameter	Type
factor	number
centerTime?	number
source?	string

Returns

void