![\"UI](\"https://raw.githubusercontent.com/romainsimon/uisfx/main/docs/assets/uisfx-banner.webp\")
\n \n\n \n \n \n
\n Preview all 936 sounds\n ·\n GitHub\n ·\n Browse cues\n
\n\n# UI SFX: open-source interface sound effects\n\nA zero-dependency semantic sound system for web apps, mobile apps, SaaS, education, media, and games. Call `success` once, then change the whole product's sonic personality without changing its logic.\n\n## Install\n\n```bash\nnpm install uisfx\n```\n\nWant a coding agent to implement it across an existing product? Use the [copy-ready implementation prompt](https://uisfx.com/agent-prompt.txt) or the complete [agent integration guide](https://uisfx.com/docs/agent-guide.md). Machine-readable cue and pack documentation starts at [`/llms.txt`](https://uisfx.com/llms.txt).\n\n## Try it in 30 seconds\n\n```ts\nimport { createUISFX } from 'uisfx'\n\nconst ui = createUISFX({\n pack: 'minimal',\n volume: 0.7,\n preferences: { key: 'my-product:sound' },\n})\n\n// Call from the first trusted pointer or keyboard action.\nawait ui.unlock()\n\nsaveButton.addEventListener('click', async () => {\n const processing = ui.play('processing')\n\n try {\n await saveChanges()\n processing?.stop()\n ui.play('success')\n } catch {\n processing?.stop()\n ui.play('error')\n }\n})\n```\n\nThe `AudioContext` is created lazily. Sounds are synthesized and cached locally from deterministic recipes, so the runtime fetches no audio files. The player bounds polyphony, deduplicates loops, rate-limits frequent cues, and restarts repeated outcomes instead of layering them.\n\n## What ships\n\n- 78 semantic cues across 13 interaction categories\n- 12 interchangeable sound packs\n- 936 portable sounds in both MP3 and Ogg\n- 72 brief one-shots and 6 seamless state loops\n- Dry, event-bound textures with clean silent tails\n- A 12.0 kB compressed Web Audio runtime\n- Zero runtime dependencies\n- MIT code and CC0 audio\n\n## One API, twelve sonic personalities\n\nEvery pack implements every cue. Product logic stays stable while the sound design changes instantly.\n\n```ts\nui.play('complete')\n\nui.setPack('arcade')\nui.play('complete') // Same meaning, entirely different feel.\n```\n\nAn active loop moves to the new pack automatically and keeps the same stoppable handle.\n\n| Pack | Character | Good fit |\n| --- | --- | --- |\n| `minimal` | Dry, precise, almost invisible | Productivity, SaaS, system UI |\n| `soft` | Rounded, warm, reassuring | Mobile, wellness, friendly SaaS |\n| `glass` | Bright, crystalline, premium | Media, finance, luxury products |\n| `arcade` | Chunky pixels and cheerful voltage | Games, streaks, gamified learning |\n| `mechanical` | Switches, relays, firm detents | Devtools, hardware, industrial UI |\n| `organic` | Wood, water, breath, small stones | Education, kids, calm games |\n| `dreamy` | Airy blooms and slow sparkle | Creative tools, wellness, ambient apps |\n| `scifi` | Clean holographic pings and restrained digital shimmer | AI tools, spatial UI, futuristic games |\n| `rubber` | Tactile elastic taps with a quick friendly rebound | Kids, playful mobile, casual games |\n| `cinematic` | Deep impacts and polished tails | Premium media and dramatic moments |\n| `studio` | Tactile precision with warm restraint | Film, audio, and AI creative tools |\n| `zen` | Paper folds, soft brush, warm wood, and quiet chimes | Calm tools, wellness, reading, and focus |\n\n[Hear every pack on the interactive website →](https://uisfx.com)\n\n## Common UI patterns\n\n### Discrete outcomes\n\nUse one-shots for meaningful state changes, not decoration.\n\n```ts\nui.play('toggle-on')\nui.play('add-to-cart')\nui.play('purchase')\nui.play('level-up')\n```\n\n### Long-running states\n\nLoop cues continue until the visible interface state resolves. Always stop them on success, failure, or cancellation.\n\n```ts\nconst recording = ui.play('recording')\n\n// When recording ends:\nrecording?.stop()\nui.play('complete')\n```\n\nThe six built-in loops are `loading`, `processing`, `recording`, `connecting`, `scanning`, and `streaming`.\n\n### Packs, volume, and mute preferences\n\n```ts\nui.setPack('studio')\nui.setVolume(0.5)\nui.setEnabled(userPreferences.soundEnabled)\n\nui.stopAll()\nawait ui.destroy()\n```\n\nPass `preferences: {}` to persist pack, volume, and enabled state in localStorage. Supply a `storage` adapter for React Native, Electron, tests, or another persistence layer.\n\n### Playback policy and preload\n\nThe default policy allows eight concurrent voices, reuses duplicate loops, restarts duplicate one-shots, and applies short cooldowns to high-frequency cues. Override deliberately when an interaction needs real overlap.\n\n```ts\nui.play('reaction', { retrigger: 'overlap' })\nui.play('hover', { cooldownMs: 0 })\n\nconst controller = new AbortController()\nawait ui.preload(['hover', 'select', 'success'], { signal: controller.signal })\ncontroller.abort()\n```\n\nPreload yields between cues so it does not synthesize an entire pack in one browser task.\n\n## Add sound with HTML\n\nUse declarative bindings when data attributes fit your app better than event handlers.\n\n```ts\nimport { bindUISFX } from 'uisfx'\n\nconst { player, unbind } = bindUISFX(document, { pack: 'soft' })\n\n// Later, when the view is destroyed:\nunbind()\nawait player.destroy()\n```\n\n```html\nDocumentation\n\n\n```\n\nTouch pointers automatically skip hover sounds.\n\n## Use the audio files anywhere\n\nThe package includes every sound as MP3 and Ogg for native apps, games, video, and environments without Web Audio.\n\n```ts\nimport successUrl from 'uisfx/sounds/soft/success.mp3?url'\n\nconst success = new Audio(successUrl)\nawait success.play()\n```\n\nAsset paths follow `sounds/{pack}/{cue}.{mp3|ogg}`. The `uisfx/manifest` export describes each path, size, rendered duration, channel count, loop flag, default volume, cue, category, and pack.\n\n## API at a glance\n\n| API | Purpose |\n| --- | --- |\n| `createUISFX(options)` | Create a player with preferences, a pack, volume, enabled state, voice limit, cooldown, or custom `AudioContext` |\n| `player.unlock()` | Resume Web Audio from a trusted pointer or keyboard action |\n| `player.play(cue, options)` | Play a typed semantic cue and receive `stop()` plus an `ended` promise |\n| `player.preload(cues?, options?)` | Cooperatively render selected cues with optional cancellation |\n| `player.setPack(pack)` | Change personality and migrate active loops without changing their handles |\n| `player.setVolume(value)` | Set master volume between `0` and `1` |\n| `player.setEnabled(value)` | Persist the sound preference and stop active audio when disabled |\n| `bindUISFX(root?, options?)` | Wire semantic cues to HTML data attributes |\n| `cueNames`, `packNames` | Build typed selectors, settings, and sound browsers |\n\nTypeScript exports `CueName`, `PackName`, `UISFXPlayer`, `PlayingSFX`, and the complete `CUES`, `PACKS`, and `CATEGORIES` catalogs.\n\n## Accessibility\n\nSound should reinforce visible feedback, never replace it.\n\n- Give people a persistent mute setting and respect device volume.\n- Never make audio the only distinction between success, warning, and error.\n- Keep hover feedback quiet or disable it in dense interfaces.\n- Start audio only after an explicit interaction.\n- Debounce frequent notifications and stop loops with their visible state.\n\n## Documentation and license\n\n- [Interactive sound library and examples](https://uisfx.com)\n- [Full cue taxonomy](https://github.com/romainsimon/uisfx/blob/main/docs/taxonomy.md)\n- [Listening conformance protocol](https://github.com/romainsimon/uisfx/blob/main/docs/listening-protocol.md)\n- [Source code and contribution guide](https://github.com/romainsimon/uisfx)\n- [Issues and feature requests](https://github.com/romainsimon/uisfx/issues)\n- [Sponsor ongoing maintenance](https://github.com/sponsors/romainsimon)\n\nThe TypeScript code is [MIT licensed](https://github.com/romainsimon/uisfx/blob/main/LICENSE). The generated audio library is dedicated to the public domain under [CC0 1.0](https://github.com/romainsimon/uisfx/blob/main/LICENSE-AUDIO).\n","readmeFilename":"README.md"}