faaah-error-sound

Zero-config sound alert on every JavaScript error — browser & Node.js.

faaah-error-sound plays an audible FAAAH alert the instant your JavaScript app throws an uncaught error or unhandled promise rejection — in the browser and in Node.js — with absolutely zero configuration and zero runtime dependencies.

Stop staring at a silent screen. Hear your bugs the moment they happen.

Install

npm install faaah-error-sound

Usage

Add a single import to your entry file — that's it. No setup, no config, no callbacks.

// ESM
import "faaah-error-sound";

// CommonJS
require("faaah-error-sound");

Next.js / React

Add it to your root layout or _app.tsx:

import "faaah-error-sound";

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

Vite / Webpack

// main.js or index.ts
import "faaah-error-sound";

What it catches automatically

| Environment | Event | |---|---| | Browser | window.onerror (uncaught exceptions) | | Browser | window.unhandledrejection (unhandled promises) | | Browser | console.error(...) | | Node.js | process.uncaughtException | | Node.js | process.unhandledRejection | | Node.js | console.error(...) |

Platform support (Node.js)

| OS | Player used | |---|---| | macOS | afplay (built-in, no install needed) | | Windows | PowerShell System.Windows.Media.MediaPlayer | | Linux | mpg123 → mpg321 → mpv → ffplay (tries in order) |

Custom sound

Replace assets/faaah.mp3 with any MP3 file, then rebuild:

cp /path/to/your/sound.mp3 node_modules/faaah-error-sound/assets/faaah.mp3

Or for development (forked/cloned repo):

cp /path/to/your/faaah.mp3 assets/faaah.mp3
npm run build

Configuration

All settings are zero-config by default. To change them, edit src/cooldown.js inside the package:

| Setting | Default | Description | |---|---|---| | cooldownMs | 3000 ms | Minimum time between sound plays | | volume | 0.5 | Audio volume (0.0 – 1.0) |

How it works

import "faaah-error-sound"
        │
        ├─ Browser? ──► Attaches window.error + unhandledrejection listeners
        │                Overrides console.error
        │                Plays MP3 via Web Audio API (bundled base64, no HTTP request)
        │
        └─ Node.js? ──► Attaches process.uncaughtException + unhandledRejection
                         Overrides console.error
                         Plays MP3 via OS-native player (afplay / PowerShell / mpg123)

• No dependencies — uses only Node.js built-ins and native OS audio tools
• Cooldown system — prevents sound spam when multiple errors fire at once (3 s default)
• Safe — all sound errors are swallowed; the package never crashes your app
• Side-effect only — exports nothing, just import or require it

Requirements

• Node.js ≥ 14.0.0
• Browser: any modern browser with Web Audio API support

Author

Shivam Yadav — github.com/shivamyadav

License

MIT © Shivam Yadav