highcharts 12.0.0 → 12.0.2

package/modules/sonification.d.ts

@@ -0,0 +1,663 @@
+/*!*
+ *
+ *  Copyright (c) Highsoft AS. All rights reserved.
+ *
+ *!*/
+import * as globals from "../globals";
+import * as _Highcharts from "../highcharts";
+/**
+ * Adds the module to the imported Highcharts namespace.
+ *
+ * @param highcharts
+ *        The imported Highcharts namespace to extend.
+ */
+export function factory(highcharts: typeof Highcharts): void;
+declare module "../highcharts" {
+    /**
+     * Callback function for sonification events on chart.
+     *
+     * @param e
+     *        Sonification chart event context
+     */
+    type SonificationChartEventCallback = (e: SonificationChartEventCallbackContext) => void;
+    /**
+     * Callback function for sonification events on series.
+     *
+     * @param e
+     *        Sonification series event context
+     */
+    type SonificationSeriesEventCallback = (e: SonificationSeriesEventCallbackContext) => void;
+    type SonificationSynthPreset = ("basic1"|"basic2"|"chop"|"chord"|"flute"|"kick"|"lead"|"noise"|"piano"|"plucked"|"sawsynth"|"sawtooth"|"saxophone"|"shaker"|"shortnote"|"sine"|"square"|"step"|
+"triangle"|"trumpet"|"vibraphone"|"wind"|"wobble"|"filteredNoise"|"sineGlide");
+    /**
+     * Filter callback for filtering timeline events on a SonificationTimeline.
+     *
+     * @param e
+     *        TimelineEvent being filtered
+     *
+     * @param ix
+     *        Index of TimelineEvent in current event array
+     *
+     * @param arr
+     *        The current event array
+     *
+     * @return The function should return true if the TimelineEvent should be
+     *         included, false otherwise.
+     */
+    type SonificationTimelineFilterCallback = (e: SonificationTimelineEvent, ix: number, arr: Array<SonificationTimelineEvent>) => boolean;
+    interface Chart {
+        /**
+         * Sonification capabilities for the chart.
+         */
+        sonification?: Sonification;
+        /**
+         * Play a sonification of a chart.
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         */
+        sonify(onEnd?: SonificationChartEventCallback): void;
+        /**
+         * Play/pause sonification of a chart.
+         *
+         * @param reset
+         *        Reset the playing cursor after play completed. Defaults to
+         *        `true`.
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         */
+        toggleSonify(reset?: boolean, onEnd?: SonificationChartEventCallback): void;
+    }
+    interface Point {
+        /**
+         * Play a sonification of a point.
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         */
+        sonify(onEnd?: SonificationChartEventCallback): void;
+    }
+    interface Series {
+        /**
+         * Play a sonification of a series.
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         */
+        sonify(onEnd?: SonificationChartEventCallback): void;
+    }
+    /**
+     * Event context object sent to sonification chart events.
+     */
+    interface SonificationChartEventCallbackContext {
+        /**
+         * The relevant chart
+         */
+        chart?: Chart;
+        /**
+         * The points that were played, if any
+         */
+        pointsPlayed?: Array<Point>;
+        /**
+         * The playing timeline object with advanced and internal content
+         */
+        timeline?: object;
+    }
+    /**
+     * Collection of Sonification classes and objects.
+     */
+    interface SonificationGlobalObject {
+        /**
+         * SynthPatch presets
+         */
+        InstrumentPresets?: Record<SonificationSynthPreset, SynthPatchOptionsObject>;
+        /**
+         * Musical scale presets
+         */
+        Scales?: SonificationScalePresetsObject;
+        /**
+         * SonificationInstrument class
+         */
+        SonificationInstrument?: SonificationInstrument;
+        /**
+         * SonificationSpeaker class
+         */
+        SonificationSpeaker?: SonificationSpeaker;
+        /**
+         * SynthPatch class
+         */
+        SynthPatch?: SynthPatch;
+    }
+    /**
+     * Capabilities configuration for a SonificationInstrument.
+     */
+    interface SonificationInstrumentCapabilitiesOptionsObject {
+        /**
+         * Whether or not instrument should be able to use filter effects.
+         * Defaults to `false`.
+         */
+        filters?: boolean;
+        /**
+         * Whether or not instrument should be able to pan. Defaults to `true`.
+         */
+        pan?: boolean;
+        /**
+         * Whether or not instrument should be able to use tremolo effects.
+         * Defaults to `false`.
+         */
+        tremolo?: boolean;
+    }
+    /**
+     * Configuration for a SonificationInstrument.
+     */
+    interface SonificationInstrumentOptionsObject {
+        /**
+         * Define additional capabilities for the instrument, such as panning,
+         * filters, and tremolo effects.
+         */
+        capabilities?: SonificationInstrumentCapabilitiesOptionsObject;
+        /**
+         * A track name to use for this instrument in MIDI export.
+         */
+        midiTrackName?: string;
+        /**
+         * The synth configuration for the instrument. Can be either a string,
+         * referencing the instrument presets, or an actual SynthPatch
+         * configuration.
+         */
+        synthPatch: (SonificationSynthPreset|SynthPatchOptionsObject);
+    }
+    /**
+     * Options for a scheduled event for a SonificationInstrument
+     */
+    interface SonificationInstrumentScheduledEventOptionsObject {
+        /**
+         * Note frequency in Hertz. Overrides note, if both are given.
+         */
+        frequency?: number;
+        /**
+         * Frequency of the highpass filter, in Hertz.
+         */
+        highpassFreq?: number;
+        /**
+         * Resonance of the highpass filter, in dB. Can be negative for a dip,
+         * or positive for a bump.
+         */
+        highpassResonance?: number;
+        /**
+         * Frequency of the lowpass filter, in Hertz.
+         */
+        lowpassFreq?: number;
+        /**
+         * Resonance of the lowpass filter, in dB. Can be negative for a dip, or
+         * positive for a bump.
+         */
+        lowpassResonance?: number;
+        /**
+         * Number of semitones from c0, or a note string - such as "c4" or
+         * "F#6".
+         */
+        note?: (number|string);
+        /**
+         * Duration to play the note in milliseconds. If not given, the note
+         * keeps playing indefinitely
+         */
+        noteDuration?: number;
+        /**
+         * Stereo panning value, from -1 (left) to 1 (right).
+         */
+        pan?: number;
+        /**
+         * Depth/intensity of the tremolo effect - which is a periodic change in
+         * volume. From 0 to 1.
+         */
+        tremoloDepth?: number;
+        /**
+         * Speed of the tremolo effect, from 0 to 1.
+         */
+        tremoloSpeed?: number;
+        /**
+         * Volume of the instrument, from 0 to 1. Can be set independent of the
+         * master/overall volume.
+         */
+        volume?: number;
+    }
+    /**
+     * Preset scales for pitch mapping.
+     */
+    interface SonificationScalePresetsObject {
+        /**
+         * Dorian scale
+         */
+        dorian: Array<number>;
+        /**
+         * Harmonic minor scale
+         */
+        harmonicMinor: Array<number>;
+        /**
+         * Lydian scale
+         */
+        lydian: Array<number>;
+        /**
+         * Major (ionian) scale
+         */
+        major: Array<number>;
+        /**
+         * Major pentatonic scale
+         */
+        majorPentatonic: Array<number>;
+        /**
+         * Minor scale (aeolian)
+         */
+        minor: Array<number>;
+        /**
+         * Minor pentatonic scale
+         */
+        minorPentatonic: Array<number>;
+        /**
+         * Mixolydian scale
+         */
+        mixolydian: Array<number>;
+        /**
+         * Phrygian scale
+         */
+        phrygian: Array<number>;
+    }
+    /**
+     * Event context object sent to sonification series events.
+     */
+    interface SonificationSeriesEventCallbackContext {
+        /**
+         * The relevant series
+         */
+        series?: Series;
+        /**
+         * The playing timeline object with advanced and internal content
+         */
+        timeline?: object;
+    }
+    /**
+     * Configuration for a SonificationSpeaker.
+     */
+    interface SonificationSpeakerOptionsObject {
+        /**
+         * The language of the voice synthesis. Defaults to `"en-US"`.
+         */
+        language?: string;
+        /**
+         * Name of the voice synthesis to use. If not found, reverts to the
+         * default voice for the language chosen.
+         */
+        name?: string;
+        /**
+         * The pitch modifier of the voice. Defaults to `1`. Set higher for a
+         * higher voice pitch.
+         */
+        pitch?: number;
+        /**
+         * The speech rate modifier. Defaults to `1`.
+         */
+        rate?: number;
+        /**
+         * The speech volume, from 0 to 1. Defaults to `1`.
+         */
+        volume?: number;
+    }
+    /**
+     * A TimelineEvent object represents a scheduled audio event to play for a
+     * SonificationTimeline.
+     */
+    interface SonificationTimelineEvent {
+        /**
+         * Callback to call when playing the event.
+         */
+        callback?: Function;
+        /**
+         * Options for an instrument event to be played.
+         */
+        instrumentEventOptions?: SonificationInstrumentScheduledEventOptionsObject;
+        /**
+         * The message to speak for speech events.
+         */
+        message?: string;
+        /**
+         * A reference to a data point related to the TimelineEvent. Populated
+         * when sonifying points.
+         */
+        relatedPoint?: Point;
+        /**
+         * Options for a speech event to be played.
+         */
+        speechOptions?: SonificationSpeakerOptionsObject;
+        /**
+         * Time is given in milliseconds, where 0 is now.
+         */
+        time: number;
+    }
+    /**
+     * The Sonification class. This class represents a chart's sonification
+     * capabilities. A chart automatically gets an instance of this class when
+     * applicable.
+     */
+    class Sonification {
+        /**
+         * The Sonification class. This class represents a chart's sonification
+         * capabilities. A chart automatically gets an instance of this class
+         * when applicable.
+         *
+         * @param chart
+         *        The chart to tie the sonification to
+         */
+        constructor(chart: Chart);
+        /**
+         * Cancel current playing audio and reset the timeline.
+         */
+        cancel(): void;
+        /**
+         * Start download of a MIDI file export of the timeline.
+         */
+        downloadMIDI(): void;
+        /**
+         * Get last played point
+         *
+         * @return The point, or null if none
+         */
+        getLastPlayedPoint(): (Point|null);
+        /**
+         * Check if sonification is playing currently
+         *
+         * @return `true` if currently playing, `false` if not
+         */
+        isPlaying(): boolean;
+        /**
+         * Play point(s)/event(s) adjacent to current timeline cursor location.
+         *
+         * @param next
+         *        Pass `true` to play next point, `false` for previous
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         *
+         * @param eventFilter
+         *        Filter to apply to the events before finding adjacent to play
+         */
+        playAdjacent(next: number, onEnd?: SonificationChartEventCallback, eventFilter?: SonificationTimelineFilterCallback): void;
+        /**
+         * 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.
+         *
+         * @param next
+         *        Pass `true` to play next series, `false` for previous
+         *
+         * @param prop
+         *        Prop to find closest value of, defaults to `x`.
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         *
+         * @return The played series, or `null` if none found
+         */
+        playAdjacentSeries(next: number, prop?: string, onEnd?: SonificationChartEventCallback): (Series|null);
+        /**
+         * Play point(s)/event(s) closest to a prop relative to a reference
+         * value.
+         *
+         * @param prop
+         *        Prop to compare.
+         *
+         * @param targetValue
+         *        Target value to find closest value of.
+         *
+         * @param targetFilter
+         *        Filter to apply to the events before finding closest point(s)
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         */
+        playClosestToProp(prop: string, targetValue: number, targetFilter?: SonificationTimelineFilterCallback, onEnd?: SonificationChartEventCallback): void;
+        /**
+         * Play a note with a specific instrument, and optionally a time offset.
+         *
+         * @param instrument
+         *        The instrument to play. Can be either a string referencing the
+         *        instrument presets, or an actual SynthPatch configuration.
+         *
+         * @param options
+         *        Configuration for the instrument event to play.
+         *
+         * @param delayMs
+         *        Time offset from now, in milliseconds. Defaults to 0.
+         */
+        playNote(instrument: (SonificationSynthPreset|SynthPatchOptionsObject), options: SonificationInstrumentScheduledEventOptionsObject, delayMs?: number): void;
+        /**
+         * Divide timeline into 100 parts of equal time, and play one of them.
+         * Can be used for scrubbing navigation.
+         *
+         * @param segment
+         *        The segment to play, from 0 to 100
+         *
+         * @param onEnd
+         *        Callback to call after play completed
+         */
+        playSegment(segment: number, onEnd?: SonificationChartEventCallback): void;
+        /**
+         * Set the audio destination node to something other than the default
+         * output. This allows for inserting custom WebAudio chains after the
+         * sonification.
+         *
+         * @param audioDestination
+         *        The destination node
+         */
+        setAudioDestination(audioDestination: AudioDestinationNode): void;
+        /**
+         * Speak a text string, optionally with a custom speaker configuration
+         *
+         * @param text
+         *        Text to announce
+         *
+         * @param speakerOptions
+         *        Options for the announcement
+         *
+         * @param delayMs
+         *        Time offset from now, in milliseconds. Defaults to 0.
+         */
+        speak(text: string, speakerOptions?: SonificationSpeakerOptionsObject, delayMs?: number): void;
+    }
+    /**
+     * The SonificationInstrument class. This class represents an instrument
+     * with mapping capabilities. The instrument wraps a SynthPatch object, and
+     * extends it with functionality such as panning, tremolo, and global
+     * low/highpass filters.
+     */
+    class SonificationInstrument {
+        /**
+         * The SonificationInstrument class. This class represents an instrument
+         * with mapping capabilities. The instrument wraps a SynthPatch object,
+         * and extends it with functionality such as panning, tremolo, and
+         * global low/highpass filters.
+         *
+         * @param audioContext
+         *        The AudioContext to use.
+         *
+         * @param outputNode
+         *        The destination node to connect to.
+         *
+         * @param options
+         *        Configuration for the instrument.
+         */
+        constructor(audioContext: AudioContext, outputNode: AudioNode, options: SonificationInstrumentOptionsObject);
+        /**
+         * Cancel currently playing sounds and any scheduled actions.
+         */
+        cancel(): void;
+        /**
+         * Stop instrument and destroy it, cleaning up used resources.
+         */
+        destroy(): void;
+        /**
+         * Convert a note value to a frequency.
+         *
+         * @param note
+         *        Note to convert. Can be a string 'c0' to 'b8' or a number of
+         *        semitones from c0.
+         *
+         * @return The converted frequency
+         */
+        musicalNoteToFrequency(note: (number|string)): number;
+        /**
+         * Schedule an instrument event at a given time offset, whether it is
+         * playing a note or changing the parameters of the instrument.
+         *
+         * @param time
+         *        Time is given in seconds, where 0 is now.
+         *
+         * @param params
+         *        Parameters for the instrument event.
+         */
+        scheduleEventAtTime(time: number, params: SonificationInstrumentScheduledEventOptionsObject): void;
+        /**
+         * Set the overall volume.
+         *
+         * @param volume
+         *        The volume to set, from 0 to 1.
+         */
+        setMasterVolume(volume: number): void;
+        /**
+         * Schedule silencing the instrument at a given time offset.
+         *
+         * @param time
+         *        Time is given in seconds, where 0 is now.
+         */
+        silenceAtTime(time: number): void;
+    }
+    /**
+     * The SonificationSpeaker class. This class represents an announcer using
+     * speech synthesis. It allows for scheduling speech announcements, as well
+     * as speech parameter changes - including rate, volume and pitch.
+     */
+    class SonificationSpeaker {
+        /**
+         * The SonificationSpeaker class. This class represents an announcer
+         * using speech synthesis. It allows for scheduling speech
+         * announcements, as well as speech parameter changes - including rate,
+         * volume and pitch.
+         *
+         * @param options
+         *        Configuration for the speaker
+         */
+        constructor(options: SonificationSpeakerOptionsObject);
+        /**
+         * Clear scheduled announcements, and stop current speech.
+         */
+        cancel(): void;
+        /**
+         * Say a message using the speaker voice. Interrupts other currently
+         * speaking announcements from this speaker.
+         *
+         * @param message
+         *        The message to speak.
+         *
+         * @param options
+         *        Optionally override speaker configuration.
+         */
+        say(message: string, options?: SonificationSpeakerOptionsObject): void;
+        /**
+         * Schedule a message using the speaker voice.
+         *
+         * @param time
+         *        The time offset to speak at, in milliseconds from now.
+         *
+         * @param message
+         *        The message to speak.
+         *
+         * @param options
+         *        Optionally override speaker configuration.
+         */
+        sayAtTime(time: number, message: string, options?: SonificationSpeakerOptionsObject): void;
+        /**
+         * Set speaker overall/master volume modifier. This affects all
+         * announcements, and applies in addition to the individual announcement
+         * volume.
+         *
+         * @param vol
+         *        Volume from 0 to 1.
+         */
+        setMasterVolume(vol: number): void;
+    }
+    /**
+     * The SynthPatch class. This class represents an instance and configuration
+     * of the built-in Highcharts synthesizer. It can be used to play various
+     * generated sounds.
+     */
+    class SynthPatch {
+        /**
+         * The SynthPatch class. This class represents an instance and
+         * configuration of the built-in Highcharts synthesizer. It can be used
+         * to play various generated sounds.
+         *
+         * @param audioContext
+         *        The AudioContext to use.
+         *
+         * @param options
+         *        Configuration for the synth.
+         */
+        constructor(audioContext: AudioContext, options: SynthPatchOptionsObject);
+        /**
+         * Cancel any scheduled actions
+         */
+        cancelScheduled(): void;
+        /**
+         * Connect the SynthPatch output to an audio node / destination.
+         *
+         * @param destinationNode
+         *        The node to connect to.
+         *
+         * @return The destination node, to allow chaining.
+         */
+        connect(destinationNode: AudioNode): AudioNode;
+        /**
+         * Mute sound immediately.
+         */
+        mute(): void;
+        /**
+         * Mute sound at time (in seconds). Will still run release envelope.
+         * Note: If scheduled multiple times in succession, the release envelope
+         * will run, and that could make sound.
+         *
+         * @param time
+         *        Time offset from now, in seconds
+         */
+        silenceAtTime(time: number): void;
+        /**
+         * Play a frequency at time (in seconds). Time denotes when the attack
+         * ramp starts. Note duration is given in milliseconds. If note duration
+         * is not given, the note plays indefinitely.
+         *
+         * @param time
+         *        Time offset from now, in seconds
+         *
+         * @param frequency
+         *        The frequency to play at
+         *
+         * @param noteDuration
+         *        Duration to play, in milliseconds
+         */
+        silenceAtTime(time: number, frequency: number, noteDuration: (number|undefined)): void;
+        /**
+         * Start the oscillators, but don't output sound.
+         */
+        startSilently(): void;
+        /**
+         * Stop the synth. It can't be started again.
+         */
+        stop(): void;
+    }
+    /**
+     * Global Sonification classes and objects.
+     */
+    let sonification: SonificationGlobalObject;
+}
+export default factory;
+export let Highcharts: typeof _Highcharts;