# Class: Sonification

## Highcharts. Sonification

#### new Sonification(chart)

  The Sonification class. This class represents a chart's sonification capabilities. A chart automatically gets an instance of this class when applicable.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `chart` | Highcharts.Chart | The chart to tie the sonification to

  ##### Requires:

  - module:modules/sonification

  ##### Try it

  - Basic demo accessing some of the chart.sonification methods.
  - More advanced demo using more functionality.

### Requires

- module:modules/sonification

### Methods

#### cancel()

  Cancel current playing audio and reset the timeline.

#### downloadMIDI()

  Start download of a MIDI file export of the timeline.

#### getLastPlayedPoint()

  Get last played point

  ##### Returns:

  Highcharts.Point | null .

  The point, or null if none

  ##### Try it

  - Sonification keyboard navigation.

#### isPlaying()

  Check if sonification is playing currently

  ##### Returns:

  boolean .

  `true` if currently playing, `false` if not

#### playAdjacent(next [, onEnd] [, eventFilter])

  Play point(s)/event(s) adjacent to current timeline cursor location.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `next` | number |  | Pass `true` to play next point, `false` for previous
  `onEnd` | Highcharts.SonificationChartEventCallback | <optional> | Callback to call after play completed
  `eventFilter` | Highcharts.SonificationTimelineFilterCallback | <optional> | Filter to apply to the events before finding adjacent to play

  ##### Try it

  - Sonification keyboard navigation.

#### playAdjacentSeries(next [, prop] [, onEnd])

  Play next/previous series, picking the point closest to a prop value from last played point. By default picks the point in the adjacent series with the closest x value as the last played point.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `next` | number |  | Pass `true` to play next series, `false` for previous
  `prop` | string | <optional> | Prop to find closest value of, defaults to `x`.
  `onEnd` | Highcharts.SonificationChartEventCallback | <optional> | Callback to call after play completed

  ##### Returns:

  Highcharts.Series | null .

  The played series, or `null` if none found

  ##### Try it

  - Sonification keyboard navigation.

#### playClosestToProp(prop, targetValue [, targetFilter] [, onEnd])

  Play point(s)/event(s) closest to a prop relative to a reference value.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `prop` | string |  | Prop to compare.
  `targetValue` | number |  | Target value to find closest value of.
  `targetFilter` | Highcharts.SonificationTimelineFilterCallback | <optional> | Filter to apply to the events before finding closest point(s)
  `onEnd` | Highcharts.SonificationChartEventCallback | <optional> | Callback to call after play completed

#### playNote(instrument, options [, delayMs])

  Play a note with a specific instrument, and optionally a time offset.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `instrument` | Highcharts.SonificationSynthPreset | Highcharts.SynthPatchOptionsObject |  | The instrument to play. Can be either a string referencing the instrument presets, or an actual SynthPatch configuration.
  `options` | Highcharts.SonificationInstrumentScheduledEventOptionsObject |  | Configuration for the instrument event to play.
  `delayMs` | number | <optional> | Time offset from now, in milliseconds. Defaults to 0.

  ##### Try it

  - Custom notifications.

#### playSegment(segment [, onEnd])

  Divide timeline into 100 parts of equal time, and play one of them. Can be used for scrubbing navigation.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `segment` | number |  | The segment to play, from 0 to 100
  `onEnd` | Highcharts.SonificationChartEventCallback | <optional> | Callback to call after play completed

  ##### Try it

  - Scrubbing with slider.

#### setAudioDestination(audioDestination)

  Set the audio destination node to something other than the default output. This allows for inserting custom WebAudio chains after the sonification.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `audioDestination` | AudioDestinationNode | The destination node

#### speak(text [, speakerOptions] [, delayMs])

  Speak a text string, optionally with a custom speaker configuration

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `text` | string |  | Text to announce
  `speakerOptions` | Highcharts.SonificationSpeakerOptionsObject | <optional> | Options for the announcement
  `delayMs` | number | <optional> | Time offset from now, in milliseconds. Defaults to 0.

  ##### Try it

  - Custom notifications.