Audio (Sonification)

The sonification module turns chart data into sound via the Web Audio API — an accessibility win and a novel way to spot patterns. Configure instruments and schedules declaratively, then play imperatively or on events.

Module setup. Registers the sonification engine. Playback needs a user gesture in most browsers — trigger it from a button or point click.

import "highcharts/modules/sonification";

Usage

Create a chart atom with standard Highcharts options, then render Chart(chart) anywhere in a mates template. Every later chart.set(…) or chart.update(…) re-renders the chart — no imperative Highcharts code.

Quick start

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "line"
    },
    title: {
        text: "Monthly revenue"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    xAxis: {
        categories: [
            "Jan",
            "Feb",
            "Mar",
            "Apr",
            "May",
            "Jun"
        ]
    },
    yAxis: {
        min: 0,
        title: {
            text: "$k"
        }
    },
    sonification: {
        enabled: true,
        defaultInstrument: "sine1",
        globalTracks: [
            {
                type: "series",
                instrument: "sine1"
            }
        ]
    },
    series: [
        {
            type: "line",
            name: "Revenue",
            data: [
                12,
                19,
                15,
                25,
                22,
                30
            ]
        }
    ]
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Live examples

Sonified line chart Highcharts demo ↗

Declare a global instrument track and a schedule; play it with chart.sonification.play(). Here the default instrument sweeps pitch across the series.

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";
import "highcharts/modules/sonification";

const chart = chartAtom({
    chart: { type: "line" },
    title: { text: "Monthly revenue — press the button to hear it" },
    xAxis: { categories: ["Jan", "Feb", "Mar", "Apr", "May", "Jun"] },
    yAxis: { min: 0 },
    sonification: {
        enabled: true,
        defaultInstrument: "sine1",
        globalTracks: [{ type: "series", instrument: "sine1" }],
    },
    series: [{ type: "line", name: "Revenue", data: [12, 19, 15, 25, 22, 30] }],
});

// play from any button — needs a user gesture:
export const PlayButton = () =>
    html`<button @click=${() => chart.sonification?.play()}>Play data</button>`;

export const MyChart = () => html`<div style="height: 22rem">${Chart(chart)}</div>`;

Speak the points (speech tracks)

Speech tracks announce each point aloud — the strongest accessibility story for users who can't see the chart.

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "column"
    },
    title: {
        text: "Weekly signups"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    xAxis: {
        categories: [
            "Mon",
            "Tue",
            "Wed",
            "Thu",
            "Fri"
        ]
    },
    yAxis: {
        min: 0,
        title: {
            text: "signups"
        }
    },
    sonification: {
        enabled: true,
        globalTracks: [
            {
                type: "series",
                instrument: "sine1",
                activeWhen: {
                    min: 1
                }
            },
            {
                type: "speech",
                mapping: {
                    text: "{point.category}: {point.y} signups"
                }
            }
        ]
    },
    series: [
        {
            type: "column",
            name: "Signups",
            data: [
                14,
                22,
                18,
                27,
                31
            ]
        }
    ]
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Options reference

mates-charts passes options straight through to Highcharts — these are the keys that matter for audio (sonification) charts. See the full Highcharts API for everything else.

Option	Type	Default	Description
`sonification.enabled`	boolean	false	Registers the engine on the chart (highcharts/modules/sonification).
`sonification.defaultInstrument`	string	—	Built-in instruments: sine1, sine2, … piano, pluck.
`sonification.globalTracks[]`	Track[]	—	series tracks map data to pitch; speech tracks announce points.
`chart.sonification.play()`	Function	—	Start playback — call from a user gesture.
`chart.sonification.setTimelineCursor / pause`	Function	—	Control playback programmatically.
`accessibility.enabled`	boolean	true	Pair sonification with screen-reader support.