@tempest/sounds

Storm-themed sound effects and audio utilities for the Tempest Audio ecosystem. Provides a simple API for playing UI sound effects across all Tempest applications.

Installation

# Using npm
npm install @tempest/sounds

# Using pnpm
pnpm add @tempest/sounds

Quick Start

import { TempestAudio } from '@tempest/sounds';

// Preload sounds on app initialization
await TempestAudio.preload('success', 'thunder-rumble.mp3');
await TempestAudio.preload('error', 'thunder-crack.mp3');
await TempestAudio.preload('click', 'water-drop.mp3');

// Play sounds
TempestAudio.play('success'); // Thunder rumble
TempestAudio.play('error'); // Thunder crack
TempestAudio.play('click'); // Water drop

// Configure
TempestAudio.setVolume(0.7); // 70% volume
TempestAudio.setEnabled(false); // Disable sounds

Sound Types

The Tempest ecosystem uses five core sound types:

| Type | Sound | Use Case | Example | |------|-------|----------|---------| | success | Thunder rumble | Successful operations | Recording completed, export finished | | error | Thunder crack | Errors and failures | File not found, operation failed | | processing | Wind whoosh | AI/background processing | Noise profile analysis, mastering | | complete | Rain patter | Task completion | Project saved, render complete | | click | Water drop | UI interactions | Button clicks, menu navigation |

Usage

Basic Implementation

import { TempestAudio } from '@tempest/sounds';

// In your app's initialization
async function initializeAudio() {
  await TempestAudio.preload('success', 'thunder-rumble.mp3');
  await TempestAudio.preload('error', 'thunder-crack.mp3');
  await TempestAudio.preload('processing', 'wind-whoosh.mp3');
  await TempestAudio.preload('complete', 'rain-success.mp3');
  await TempestAudio.preload('click', 'water-drop.mp3');
}

// Play sounds in your UI
function handleSaveProject() {
  saveToDatabase()
    .then(() => {
      TempestAudio.play('success');
      showNotification('Project saved!');
    })
    .catch(() => {
      TempestAudio.play('error');
      showNotification('Save failed');
    });
}

With React

import { useEffect } from 'react';
import { TempestAudio } from '@tempest/sounds';

function App() {
  useEffect(() => {
    // Preload sounds
    const sounds = [
      ['success', 'thunder-rumble.mp3'],
      ['error', 'thunder-crack.mp3'],
      ['click', 'water-drop.mp3'],
    ] as const;

    Promise.all(
      sounds.map(([type, file]) => TempestAudio.preload(type, file))
    );
  }, []);

  return (
    <button onClick={() => {
      TempestAudio.play('click');
      handleAction();
    }}>
      Click Me
    </button>
  );
}

Custom Instance

import { TempestAudioManager } from '@tempest/sounds';

// Create a custom instance with specific settings
const customAudio = new TempestAudioManager({
  volume: 0.3,
  enabled: true,
  soundsPath: '/assets/audio'
});

await customAudio.preload('success', 'my-sound.mp3');
customAudio.play('success');

Settings Management

// Get current settings
const { volume, enabled } = TempestAudio.getSettings();

// Update volume (0-1)
TempestAudio.setVolume(0.8);

// Toggle sounds
TempestAudio.setEnabled(userPreferences.soundsEnabled);

Creating Sound Files

Requirements

• Format: MP3 or OGG (MP3 recommended for broad compatibility)
• Duration: 0.2-1.0 seconds (keep UI responsive)
• File Size: < 50KB per file (optimize for web)
• Sample Rate: 44.1kHz or 48kHz
• Bit Rate: 128-192 kbps

Sound Design Guidelines

1. Thunder Rumble (success)

   • Deep, satisfying thunder sound
   • 0.5-0.8 seconds
   • Positive emotional tone

2. Thunder Crack (error)

   • Sharp, brief lightning crack
   • 0.2-0.4 seconds
   • Not too harsh/startling

3. Wind Whoosh (processing)

   • Gentle wind/air movement
   • 0.3-0.6 seconds
   • Subtle, non-intrusive

4. Rain Patter (complete)

   • Light rain drops
   • 0.4-0.7 seconds
   • Calming, conclusive

5. Water Drop (click)

   • Single water droplet
   • 0.1-0.2 seconds
   • Clean, crisp

Recommended Tools

• Audacity (Free) - Edit and optimize audio files
• Freesound.org - Free sound effects library
• Adobe Audition - Professional audio editing
• Logic Pro / Ableton Live - Create custom sounds

File Structure

Place your sound files in your app's public directory:

public/
  sounds/
    thunder-rumble.mp3    # success
    thunder-crack.mp3     # error
    wind-whoosh.mp3       # processing
    rain-success.mp3      # complete
    water-drop.mp3        # click

Browser Support

Uses the Web Audio API, supported by:

• Chrome/Edge 14+
• Firefox 25+
• Safari 14.1+
• Opera 15+

Performance

• Sounds are preloaded for instant playback
• No audio lag during UI interactions
• Minimal memory footprint (<250KB total)
• Efficient Web Audio API implementation

Part of the Tempest Ecosystem

This sound library is used by:

• Tempest Record - Vinyl digitization app
• Tempest DJ - DJ performance platform
• Tempest Create - Digital audio workstation
• Tempest Radio - Online streaming platform

License

MIT

Version

Current version: 0.1.0

Tempest Audio - The Storm of Sound