Peal

Curated UI sounds for web apps — clicks, success chimes, errors, and the rest — copied into your repo and played through a small generated helper.

What you get

1. CLI — pick sounds from the built-in set and copy .wav files into your project
2. Generated peal.js — a tiny Howler-based player that knows where those files live
3. Library (Peal class) — optional lower-level API if you want to wire up your own paths

No sound hosting, no accounts. Files sit in your repo; you call peal.click() when something happens in the UI.

Quick start

npm install @peal-sounds/peal

peal add \
  click \
  success \
  error

That writes something like:

your-project/
├── peal.js          # generated — import this in your app
└── peal/
    ├── click.wav
    ├── success.wav
    └── error.wav

Then in your app:

import { peal } from './peal.js'

button.addEventListener('click', () => {
  peal.click()
})

async function save() {
  try {
    await api.save()
    peal.success()
  } catch {
    peal.error()
  }
}

./peal.js is created by the CLI in your project root. You are not importing the npm package for playback — only the generated helper (which wraps Howler and points at ./peal/*.wav).

Prefer a one-off without installing?

npx @peal-sounds/peal add click

Also published as @arach/peal (same package, older namespace).

Requires Node.js 20+.

Install

npm install @peal-sounds/peal
# pnpm add @peal-sounds/peal
# yarn add @peal-sounds/peal

The peal binary is on your PATH after install.

Available sounds

| Group | Names | | --- | --- | | UI feedback | success, error, notification, click, tap | | Transitions | transition, swoosh | | Loading | loading, complete | | Alerts | alert, warning | | Messages | message, mention | | Interactive | hover, select, toggle | | System | startup, shutdown, unlock |

19 sounds total. Run peal list for the full list in the terminal.

CLI

peal add                         # interactive picker
peal add click                   # one sound
peal add \                       # several sounds
  click \
  success \
  error
peal add --dir ./sounds          # custom folder for WAV files
peal add --typescript            # generate peal.ts instead of peal.js

peal list                   # show available sounds
peal play click             # preview a sound
peal demo                   # play through the set
peal remove click           # remove from your project

Using the library directly

If you already have audio files and do not need the generated helper:

import { Peal } from '@peal-sounds/peal'

const audio = new Peal()
audio.load('click', '/sounds/click.wav')
audio.play('click', { volume: 0.5, loop: false })
audio.volume(0.8)  // global volume (0–1)
audio.mute(true)

The generated peal.js is the usual path for CLI-added sounds. The Peal class is for custom loading and paths.

Optional TTS (OPENAI_API_KEY or GROQ_API_KEY):

const audio = new Peal({ openaiApiKey: process.env.OPENAI_API_KEY })
await audio.speak('Saved successfully')

API (generated helper)

• peal.play(name, options?) — play by name; options: volume (0–1), loop
• peal.click(), peal.success(), … — shortcuts for sounds you added (no options)
• peal.stop(name?), peal.pause(name?), peal.resume(name?)
• peal.setVolume(0.5), peal.mute(true)

peal.play('success', { volume: 0.5, loop: false })
// not: peal.success({ volume: 0.5 }) — shortcuts take no arguments

TypeScript

peal add --typescript

import { peal } from './peal'

peal.success()
peal.play('success', { volume: 0.8 })

Library types:

import { Peal, type PealOptions } from '@peal-sounds/peal'

Web app

The npm package is the CLI + library. Peal also runs in the browser — browse presets, generate sounds, or design in the studio — then copy what you need into a project with peal add.

Open the app · GitHub Pages mirror · GitHub

Links

• peal.app
• GitHub
• Issues

MIT — see LICENSE