plinq

Programmatic UI sounds — pure Web Audio API synthesis, zero dependencies. Inspired by Sounds on the Web by Raphael Salaja.

Install

npm install plinq

pnpm add plinq

yarn add plinq

Quick Start

import { pop } from 'plinq'

pop()

Presets

Preset	Description
`click()`	Short, percussive click
`pop()`	Downward pitch glide
`toggle()`	Two-note switch sound
`tick()`	High-pitched tick
`drop()`	Descending pitch drop
`success()`	Ascending three-note chord (C5–E5–G5)
`error()`	Dissonant two-note buzz
`warning()`	Single-note warning tone

Options

Every preset accepts an optional PresetOptions object:

import { success } from 'plinq'

success({ volume: 0.5, pitch: 'high' })

Option	Type	Default	Description
`volume`	`number`	`1`	Volume from 0 to 1
`pitch`	`'low' \| 'mid' \| 'high' \| number`	`'mid'`	Pitch multiplier — `'low'` = 0.8x, `'mid'` = 1x, `'high'` = 1.3x, or pass a custom number

Custom Sounds

Use play() to define your own sounds:

import { play } from 'plinq'

play({
  layers: [
    {
      source: { type: 'oscillator', waveform: 'sine', frequency: 440, frequencyEnd: 220 },
      envelope: { attack: 0.001, decay: 0.15 },
      gain: 0.3,
    },
  ],
})

Each layer supports oscillator or noise sources, an optional biquad filter, an envelope with attack/decay, gain, and an optional delay (in seconds) to stagger layers.

API

`play(config: SoundConfig, options?: PresetOptions): void`

Play an arbitrary sound configuration.

`getContext(): AudioContext`

Returns the shared AudioContext, lazily creating one if needed.

`setContext(userCtx: AudioContext): void`

Provide your own AudioContext to share with other audio in your app.

Type Exports

SoundConfig, LayerConfig, Source, OscillatorSource, NoiseSource, WaveformType, FilterConfig, EnvelopeConfig, PresetOptions

License

MIT