Interface AudioState

Stereo position, read by AudioService as interpolate(x, 0, cols - 1, -1, 1) and clamped to that range.

x and cols are usually a column index and a column count, which pans a trace left to right. They are not required to be: what the service needs is a position and the range to read it against. PieTrace supplies cols: 2 and a fractional x so the pan follows a slice around the dial rather than along a row — a circle sweeps out and back, which an index cannot express.

When a chord's tones sit at different x positions, x stays the single representative position every non-chord path reads (empty tone, zero tone, click, glide, smooth, position announcement) and the per-tone slots go in AudioState.panX.

Group index for multiclass plots. Used to determine which audio palette entry to use. If undefined, defaults to 0 (single group).

Indicates whether the audio is continuous. If true, the audio plays without interruption. If false or undefined, the audio may have discrete segments.

Candlestick trend information for audio palette selection. Used by AudioService to determine appropriate audio characteristics. Only applicable for candlestick traces.

When true, a raw value of exactly 0 plays a percussive click instead of the default low "null" tone. Used by the candlestick delta layer, where zero means "exactly on the reference line" — a meaningful data point, not missing data.

Pitch-glide direction for the tone. When set, the tone glides its pitch over the note duration to convey a direction while freq.raw still sets the base pitch: 'up' sweeps upward (a rising "whoosh"), 'down' sweeps downward (a falling drop). Used by the candlestick delta layer so above-line points rise and below-line points fall, independent of the base pitch that still encodes the delta magnitude. Ignored for the zero (zeroClick) path.

Volume multiplier for dynamic volume control. Used to scale audio volume based on data characteristics (e.g., violin plot width). If undefined, defaults to 1.0 (no volume scaling). Range should typically be between 0.0 and 1.0, but can exceed 1.0 for emphasis.

Volume scale for dynamic volume control (0-1 range). Used to scale audio volume based on density values (e.g., violin plot density). If undefined, defaults to 1.0 (no volume scaling). Range is 0.0 to 1.0, where 0.0 = quietest and 1.0 = loudest.

Normalized z-axis intensity (0-1) for a third-dimension sonification cue. Scalar for a single tone; array (index-aligned with freq.raw) for group playback. Currently set by 3D scatter plots and drives echo count in the audio service.

Per-tone stereo slots, index-aligned with freq.raw when that is an array and read against the same panning.cols. Present only when one navigation step emits a chord whose tones sit at different x positions — a 3D scatter ROW plays one note per point, and collapsing them onto panning.x would saturate the whole row into one ear.

Absent everywhere else, so no existing consumer has to narrow a union: panning.x remains a plain number for every reader that wants one position, which is all of them but the chord loop.