Rulers

Rulers render timeline timestamps and frequency axes that stay in sync with spectrogram and waveform viewports.

Tick intervals recalculate automatically as you zoom and pan. When connected to navigation, dragging directly on a ruler scrubs across time or adjusts visible frequency bounds.

The basics

Rulers attach to standard HTML <canvas> elements. Calling createTimeRuler or createFrequencyRuler without options applies standard tick marks, labels, and auto-resizing:

import { Sonoscope } from "@sonoscope/core";

const scope = await Sonoscope.fromUrl("/audio/sample.wav");

// Create a horizontal time ruler using default options
const timeRuler = scope.createTimeRuler(timeCanvas);

// Create a vertical frequency ruler using default options
const freqRuler = scope.createFrequencyRuler(freqCanvas);

// Synchronize drag and zoom interactions
scope.attachNavigation(timeCanvas, { axis: "time" });
scope.attachNavigation(freqCanvas, { axis: "frequency" });

Set visible time and frequency ranges on Sonoscope, not on a ruler:

const scope = await Sonoscope.fromUrl("/audio/sample.wav", {
  startTime: 5,
  endTime: 15,
  minDuration: 0.05,
  maxDuration: 30,
  minFrequency: 100,
  maxFrequency: 12_000,
});

---

Example configurations

1. Default time ruler

Draws top tick marks with dynamic major and minor subdivisions:

scope.createTimeRuler(timeCanvas);

2. Colored ruler

Applies custom theme colors:

scope.createTimeRuler(timeCanvas, {
  color: "#38bdf8",
});

3. Ticks on bottom

Positions tick marks below the numeric timestamp labels:

scope.createTimeRuler(timeCanvas, {
  tickPosition: "bottom",
});

4. Ticks on both sides

Draws tick marks along both the top and bottom borders:

scope.createTimeRuler(timeCanvas, {
  tickPosition: "both",
});

5. Segmented boxes style

Replaces standard tick lines with segmented blocks:

scope.createTimeRuler(timeCanvas, {
  renderer: "boxes",
});

6. Timecode formatting (mm:ss.ms)

Formats timestamps in standard media timecode notation:

scope.createTimeRuler(timeCanvas, {
  timeFormat: "timecode",
});

7. Frequency ruler (kHz format)

Displays vertical frequency values formatted in kilohertz:

scope.createFrequencyRuler(freqCanvas, {
  frequencyFormat: "khz",
});

---

Configuration options

Time ruler options

Options accepted by scope.createTimeRuler(canvas, options). Full reference: TimeRulerConfig.

Option	Type	Default	Description
autoRenderopt	boolean	true	Whether to automatically re-render when viewport or configuration changes.
coloropt	string	"#a0a0a0"	Primary color for axis lines, tick marks, and text labels.
backgroundColoropt	string	"transparent"	Canvas background fill color.
tickColoropt	string	color	Specific color override for tick lines.
labelColoropt	string	color	Specific color override for text labels.
fontopt	string	"10px monospace"	CSS font specification for time labels.
tickPositionopt	"top" | "bottom" | "both" | "inside"	"top"	Tick mark position relative to the ruler baseline.
timeFormatopt	TimeFormatMode	"auto"	Numeric timestamp formatting mode. - "auto": Adapts precision based on zoom level. - "seconds": Displays raw seconds (e.g., `12.5s`). - "timecode": Broadcast notation (`mm:ss.ms`). - "hhmmss": Clock time (`hh:mm:ss`). - Custom function `(sec: number) => string`.
minMajorPixelSpacingopt	number	75	Minimum pixel spacing between adjacent major tick labels.
rendereropt	TimeRulerRendererName | TimeRulerRenderer	"ticks"	Visual renderer: standard tick lines or segmented boxes.
autoResizeopt	boolean	true	Whether to automatically resize canvas pixel resolution when container dimensions change.
devicePixelRatioopt	boolean | number	window.devicePixelRatio	Device pixel ratio scaling factor for HiDPI/Retina displays.

Frequency ruler options

Options accepted by scope.createFrequencyRuler(canvas, options). Full reference: FrequencyRulerConfig.

Option	Type	Default	Description
autoRenderopt	boolean	true	Whether to automatically re-render when viewport or configuration changes.
frequencyScaleopt	FrequencyScale	inherits from Sonoscope viewport scale	Frequency scale mapping: linear, mel, or logarithmic.
coloropt	string	"#a0a0a0"	Primary color for axis lines, tick marks, and text labels.
backgroundColoropt	string	"transparent"	Canvas background fill color.
tickColoropt	string	color	Specific color override for tick lines.
labelColoropt	string	color	Specific color override for text labels.
fontopt	string	"10px monospace"	CSS font specification for frequency labels.
tickPositionopt	"left" | "right" | "both" | "inside"	"left"	Tick mark position relative to the vertical ruler axis.
frequencyFormatopt	FrequencyFormatMode	"auto"	Frequency label formatting mode. - "auto": Switches between Hz and kHz depending on magnitude. - "hz": Always formats in Hertz (e.g. `2000 Hz`). - "khz": Always formats in kilohertz (e.g. `2.0 kHz`). - Custom function `(hz: number) => string`.
minMajorPixelSpacingopt	number	45	Minimum pixel spacing between adjacent major frequency labels.
rendereropt	FrequencyRulerRendererName | FrequencyRulerRenderer	"ticks"	Visual renderer: standard tick lines or segmented boxes.
autoResizeopt	boolean	true	Whether to automatically resize canvas pixel resolution when container dimensions change.
devicePixelRatioopt	boolean | number	window.devicePixelRatio	Device pixel ratio scaling factor for HiDPI/Retina displays.

---

Navigation & interaction

Use scope.attachNavigation(canvas, options) to link panning and zooming between rulers and spectrograms:

• Axis constraints: Set { axis: 'time' } on horizontal rulers and { axis: 'frequency' } on vertical rulers so dragging only navigates along that ruler’s dimension.
• Drag & scroll: Dragging scrubs the timeline or frequency range; scrolling or pinching zooms in and out.
• Synchronized views: Navigating on any attached canvas immediately updates all connected rulers and spectrogram views.

---

Try it yourself!

Play around with the code in the live sandbox below:

• Drag the spectrogram or rulers to pan around.
• Scroll / Pinch over the rulers to zoom in and out.
• Edit the options in index.ts to see how different tick styles, positions, and formats look in real time.