Terminal Sound Alerts

Terminal Sound Alerts plays different sounds for important terminal events in real-time.

The extension listens to terminal output using vscode.window.onDidWriteTerminalData and classifies lines into:

• Build errors (build failed)
• Test failures (test failed, jest)
• Generic runtime errors (error)
• Warnings (warning)
• Optional success events (success, build succeeded, tests passed, completed successfully)

Features

• Real-time terminal monitoring with low overhead
• Different sound per alert type
• Built-in sound dropdown per alert type
• Custom .wav / .mp3 file path per alert type
• Per-type enable/disable toggles
• Global volume control (0-100)
• Debounce protection (default 3000ms) to prevent sound spam
• Command: Terminal Sound Alerts: Test Sound
• Safe fallback behavior if custom or built-in files are missing/invalid
• Auto-generated fallback tone per alert type when no valid media file is available

Default Sound Mapping

• Build error -> sound1.mp3
• Test failure -> sound2.mp3
• Generic error -> sound3.mp3
• Warning -> sound4.mp3
• Success -> sound5.mp3

Configuration

Search for Terminal Sound Alerts in VS Code Settings.

Global Settings

• terminalSoundAlerts.globalEnabled
• terminalSoundAlerts.mode (auto, terminalData, compat)
• terminalSoundAlerts.volume
• terminalSoundAlerts.debounceMs

Per-Type Settings

For each type (buildError, testFailure, genericError, warning, success):

• terminalSoundAlerts.<type>.enabled
• terminalSoundAlerts.<type>.builtinSound
• terminalSoundAlerts.<type>.customSoundPath

Resolution order:

1. Use customSoundPath if it exists and is valid.
2. Otherwise use selected builtinSound.
3. If missing/invalid, fall back to default built-in mapping.
4. If still missing, generate a valid fallback .wav tone and play it.

Compatibility Across Cursor/Windsurf/VS Code

• auto mode (default): tries real-time terminal text events first, then falls back to shell command completion events.
• terminalData mode: full keyword parsing from terminal output (build failed, jest, warning, error) when host allows onDidWriteTerminalData.
• compat mode: classifies by command and exit code using shell integration events; best option for editors that block terminal text APIs.

In compat mode, warning text detection is limited because raw terminal output is not exposed. Build/test/generic error and success alerts still work.

Project Structure

terminal-sound-alerts/
  media/
    sound1.mp3
    sound2.mp3
    sound3.mp3
    sound4.mp3
    sound5.mp3
  src/
    extension.ts
    types/
      sound-play.d.ts
  package.json
  tsconfig.json
  README.md
  LICENSE
  .vscodeignore

Run in Development (F5)

1. Install dependencies:

   npm install
   

2. Compile:

   npm run compile
   

3. Press F5 to launch the Extension Development Host.
4. In the host window terminal, run commands that emit matching keywords.
5. Optionally run the command palette action Terminal Sound Alerts: Test Sound.

Publish to VS Code Marketplace

1. Set publisher in package.json to your marketplace publisher ID.
2. Package:

   npx vsce package
   

3. Publish:

   npx vsce publish
   

Notes

• Built-in files are sample placeholders. Replace them with your preferred audio while keeping the same names, or choose different built-ins in settings.
• Supported formats: .wav, .mp3
• Custom paths support ~ and ${workspaceFolder}.