plinq

Dependency-free library for creating programmatic UI sounds. Inspired by Sounds on the Web by Raphael Salaja.

Docs & Playground

Install

npm install plinq

pnpm add plinq

yarn add plinq

bun 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

Browser Notes (Safari)

Safari requires audio playback to originate from a user interaction (e.g. click, pointerdown, keydown). plinq handles AudioContext creation, suspension, and resumption automatically — including after tab and app switches.

If you run into Safari-specific audio issues, please open an issue.

License

MIT