Sonification

A sonifier plays the visible series as sound, so people who cannot see the chart can hear its shape, trend and outliers. It adds to the text summary and live regions described under screen readers.

Pitch follows the value: the lowest value in view sounds at the low end of the pitch range and the highest at the high end. Up and down bars also differ in timbre (a pure tone for up, a softer buzz for down) and stereo side (right for up, left for down), so the direction is heard without judging the pitch. Short cues mark bar markers, crossed alert lines and the first bar of a new trading day.

import { createChart, createSonifier } from '@chart-on/core';

const chart = createChart(container);
const sonifier = createSonifier(chart, { durationMs: 5000 });

playButton.addEventListener('click', () => sonifier.toggle());

The sonifier is a separate module: the chart never imports it, so apps that do not call createSonifier do not bundle it. It uses the Web Audio API and needs no assets or network. Importing it is safe on a server: nothing touches the browser until the first play or step.

Starting the sound

Nothing sounds until play() or step() runs, and browsers only allow sound after a user gesture, so call them from a click or key handler. The audio context is made on that first call. Where there is no Web Audio, both return false.

Keys

With the plot focused (and keyboard on):

Key	Does
P	Play the visible range, or pause
Escape	Stop, while playing or paused
Ctrl+← / →	The chart moves the crosshair one bar; the sonifier sounds that bar and reads its values

Any other key, a pointer press or a wheel turn on the chart pauses the sound. Modifier keys pressed on their own (as screen readers do) do not.

The stepped bar's time, open, high, low, close and change are read in a polite live region, for example:

2024-05-09 11:00. Open 158.00, high 159.50, low 157.80, close 159.00, up 1.00 (0.63%).

While the chart's own accessibility.crosshairReadout is on, the sonifier leaves the reading to it.

The words come from the chart's localization messages (sonifyBar, sonifyPoint, sonifyValue, the sonifyCue* keys and describeUp / describeDown / describeUnchanged), so they follow the chart's language.

Options

Option	Default	Meaning
series	main series	The candle, line or histogram series to play
durationMs	4000	Time to play the whole visible range; each bar gets an equal share, held between 10 and 500 ms
pitchRange	{ low: 220, high: 880 }	Frequencies (Hz) for the lowest and highest value in view
mode	'close'	'close': one steady tone at the close. 'range': a glide across the bar's low and high, rising on up bars and falling on down bars
volume	0.2	Loudness, 0 to 1
cues	all true	{ markers, alerts, sessions }: which events get a cue
followCrosshair	true	Move the crosshair along with the sound
keyboard	true	The keys above
announce	true	Read the stepped bar's values
createAudioContext	browser AudioContext	Makes the audio context on first use; tests pass a fake

sonifier.applyOptions(patch) merges into the current options. Equal value steps give equal musical intervals; on a log price scale, equal ratios of value do instead.

valueToPitch(value, { min, max, low, high, log? }) is the mapping on its own, for apps that make their own sound.

Methods and state

Member	Does
play()	Play the visible range, oldest bar first, or go on from where pause stopped
pause()	Stop the sound and keep the position
stop()	Stop the sound and forget the position
toggle()	Pause while playing, else play
step(1) / step(-1)	Sound the next or previous bar on its own, move the crosshair there and announce it. The first step starts on the newest bar in view
state	'idle', 'playing' or 'paused'
position	Data index of the bar played last, or null
on('state:change', fn)	Subscribe to state changes; returns an unsubscribe function
destroy()	Stop, close the audio context and detach

The sonifier registers itself as a chart plugin (named sonifier-<n>), so chart.destroy() destroys it too.

sonifier.on('state:change', ({ state }) => {
  playButton.setAttribute('aria-pressed', String(state === 'playing'));
});