zusound

🔊 zusound

Hear your state changes. Debug faster.

zusound is a Zustand middleware that converts state changes into short Web Audio cues so you can hear update patterns while debugging.

Install

npm install zusound

Supported Zustand versions: >=4 <6.

Quick Usage

import { create } from 'zustand'
import { zusound } from 'zusound'

const useStore = create(
  zusound((set) => ({
    count: 0,
    inc: () => set((state) => ({ count: state.count + 1 })),
  }))
)

API

zusound(initializer, options?)

The middleware signature matches standard Zustand middleware usage.

createZusound(options?)

Create a configured, stateful instance that works in both middleware and subscriber mode:

import { create } from 'zustand'
import { createZusound } from 'zusound'

const useStore = create((set) => ({
  count: 0,
  inc: () => set((state) => ({ count: state.count + 1 })),
}))

const zs = createZusound({ enabled: true, volume: 0.5, debounceMs: 80 })
const unsubscribe = useStore.subscribe(zs)

// later
unsubscribe()
zs.cleanup()

Use a fresh createZusound(...) instance for each store.subscribe(...) attachment when you want explicit lifecycle control.

ZusoundOptions

Option	Type	Default	Description
enabled	boolean	true in dev-like envs, false otherwise	Enables/disables audio feedback
volume	number	0.3	Global playback volume (0..1)
debounceMs	number	0	Debounce state-change sound emission
soundMapping	Record<string, Partial<SoundParams>>	undefined	Path-level overrides for timbre/frequency/waveform
aesthetics	Partial<AestheticParams>	type-specific defaults	Base tuning for pleasantness/brightness/arousal/valence/simultaneity
mapChangeToAesthetics	(change) => Partial<AestheticParams>	undefined	Per-change dynamic aesthetic override hook
performanceMode	boolean	false	Uses static consonance ranking to reduce dissonance computation cost
onError	(error, context) => void	undefined	Optional hook for non-fatal middleware/audio errors

Aesthetic Parameters

Param	Range	Effect
pleasantness	0..1	Consonance selection, supports fractional semitone interpolation
brightness	0..1	Harmonic rolloff control for timbre brightness
arousal	0..1	Envelope speed (attack/decay/release)
valence	0..1	Envelope sustain character
simultaneity	0..1	Dyad onset spread (1 = together, 0 = spread over ~80% duration)
baseMidi	number	Base pitch center before interval mapping
duration	number	Optional note duration override (seconds)

Advanced Example

import { create } from 'zustand'
import { zusound } from 'zusound'

const useStore = create(
  zusound(
    (set) => ({
      count: 0,
      status: 'idle',
      inc: () => set((state) => ({ count: state.count + 1 })),
      setStatus: (status: string) => set({ status }),
    }),
    {
      enabled: true,
      volume: 0.28,
      debounceMs: 40,
      performanceMode: false,
      aesthetics: {
        pleasantness: 0.75,
        brightness: 0.65,
        arousal: 0.55,
        valence: 0.6,
        simultaneity: 1,
        baseMidi: 69,
      },
      mapChangeToAesthetics: (change) => {
        if (change.operation === 'add') return { pleasantness: 0.9, valence: 0.8 }
        if (change.operation === 'remove') return { pleasantness: 0.35, arousal: 0.7 }
        return {}
      },
    }
  )
)

Production Notes

• Defaults are production-safe: audio is off in production unless enabled: true is explicitly set.
• If the runtime environment cannot be classified, audio stays off unless enabled: true is set.
• Browsers may keep AudioContext suspended until user interaction.
• performanceMode is recommended for low-power or high-frequency update scenarios.
• Use onError if you need telemetry for non-fatal audio/debugging failures.

What You'll Hear

• Numbers: pitch-centric tones
• Booleans: short click-like cues
• Strings: brighter/longer character
• Objects/arrays: more layered motion

Related Docs

• Root project overview: README
• Quick start guide: QUICK_START
• Dev workflow: DEVELOPMENT
• Demo usage: demo/README
• React strict TypeScript demo: examples/README
• Operations runbook: docs/RUNBOOK

License

MIT © joe-byounghern-kim