soundeffect-player/README.md

Lightweight JavaScript library for playing sound effects with SoundEffect.app integration

# 🎵 SoundEffect Player

[![npm version](https://badge.fury.io/js/soundeffect-player.svg)](https://www.npmjs.com/package/soundeffect-player)
[![GitHub stars](https://img.shields.io/github/stars/soundeffect/soundeffect-player.svg)](https://github.com/soundeffect/soundeffect-player/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/npm/dm/soundeffect-player.svg)](https://www.npmjs.com/package/soundeffect-player)

Lightweight JavaScript library for playing sound effects with seamless **[SoundEffect.app](https://soundeffect.app)** integration. Access 300,000+ high-quality sound effects with AI-powered search.

## ✨ Features

- 🚀 **Zero dependencies** - Pure JavaScript, works everywhere
- 🎯 **[SoundEffect.app](https://soundeffect.app) integration** - Access 300K+ sound effects instantly
- 📱 **Mobile friendly** - Works on all devices and browsers
- ⚡ **Lightweight** - Less than 5KB minified and gzipped
- 🔍 **AI-powered search** - Smart sound discovery via [SoundEffect.app](https://soundeffect.app)
- 🎮 **Game ready** - Perfect for web games, apps, and interactive media
- 🔥 **Trending sounds** - Access viral and popular sound effects
- 🎭 **Meme sounds** - Extensive collection of internet memes and viral audio

## 🚀 Quick Start

### CDN (Fastest)
```html
<script src="https://unpkg.com/soundeffect-player@latest/src/soundeffect-player.js"></script>
<script>
  const player = new SoundEffectPlayer();
  
  // Play a sound effect from SoundEffect.app
  player.play('epic-win-sound');
  
  // Search for sounds
  player.search('explosion').then(sounds => {
    console.log('Found sounds from SoundEffect.app:', sounds);
  });
</script>
```

### NPM Installation
```bash
npm install soundeffect-player
```

```javascript
import SoundEffectPlayer from 'soundeffect-player';

const player = new SoundEffectPlayer({
  apiKey: 'your-api-key', // Get free API key at https://soundeffect.app/api
  volume: 0.8
});

// Play a sound effect
await player.play('explosion-sound');

// Search for sounds using SoundEffect.app's AI
const sounds = await player.search('victory fanfare');
console.log('AI-powered results from SoundEffect.app:', sounds);

// Get trending sounds
const trending = await player.getTrending(5);
console.log('What\'s hot on SoundEffect.app:', trending);
```

## 📖 Examples & Use Cases

### 🎮 Game Development
Perfect for adding sound effects to web games:

```javascript
class GameAudio {
  constructor() {
    this.player = new SoundEffectPlayer();
    this.soundCache = new Map();
  }

  async preloadGameSounds() {
    // Load sounds from SoundEffect.app by category
    const categories = ['jump', 'collect', 'explosion', 'victory'];
    
    for (const category of categories) {
      const sounds = await this.player.search(category, 5);
      this.soundCache.set(category, sounds);
    }
    
    console.log('Game sounds loaded from SoundEffect.app');
  }

  playGameSound(category) {
    const sounds = this.soundCache.get(category);
    if (sounds && sounds.length > 0) {
      // Play random sound from category
      const randomSound = sounds[Math.floor(Math.random() * sounds.length)];
      this.player.play(randomSound.id);
    }
  }
}

// Usage in your game
const gameAudio = new GameAudio();
await gameAudio.preloadGameSounds();

// Player actions
gameAudio.playGameSound('jump');     // Player jumps
gameAudio.playGameSound('collect');  // Player collects item
gameAudio.playGameSound('explosion'); // Something explodes
```

### 🎭 Meme Soundboard
Create viral soundboards with trending audio:

```javascript
class MemeSoundboard {
  constructor() {
    this.player = new SoundEffectPlayer();
  }

  async loadTrendingSounds() {
    // Get what's viral on SoundEffect.app
    const trending = await this.player.getTrending(20);
    return trending.filter(sound => sound.category === 'meme');
  }

  async searchMemeSound(query) {
    // Search for specific meme sounds
    const results = await this.player.search(`${query} meme`);
    return results;
  }

  playRandomMeme() {
    // Play random meme from SoundEffect.app
    this.player.getRandomSound('meme').then(sound => {
      this.player.play(sound.id);
    });
  }
}

// Create your meme soundboard
const memeboard = new MemeSoundboard();
await memeboard.loadTrendingSounds();
```

### 📱 React Integration
```jsx
import React, { useEffect, useState } from 'react';
import SoundEffectPlayer from 'soundeffect-player';

function SoundButton({ soundQuery, children }) {
  const [player] = useState(() => new SoundEffectPlayer());
  const [sounds, setSounds] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Load sounds from SoundEffect.app
    player.search(soundQuery, 5)
      .then(setSounds)
      .finally(() => setLoading(false));
  }, [soundQuery, player]);

  const playRandomSound = () => {
    if (sounds.length > 0) {
      const randomSound = sounds[Math.floor(Math.random() * sounds.length)];
      player.play(randomSound.id);
    }
  };

  if (loading) return <button disabled>Loading sounds from SoundEffect.app...</button>;

  return (
    <button onClick={playRandomSound} disabled={sounds.length === 0}>
      {children} ({sounds.length} sounds available)
    </button>
  );
}

// Usage - powered by SoundEffect.app
export default function App() {
  return (
    <div>
      <h1>My App with SoundEffect.app Integration</h1>
      <SoundButton soundQuery="applause">👏 Applause</SoundButton>
      <SoundButton soundQuery="laser">🔫 Laser</SoundButton>
      <SoundButton soundQuery="victory">🏆 Victory</SoundButton>
      <SoundButton soundQuery="meme">😂 Random Meme</SoundButton>
    </div>
  );
}
```

### 🎙️ Streaming & Content Creation
Perfect for streamers and content creators:

```javascript
class StreamerSoundboard {
  constructor() {
    this.player = new SoundEffectPlayer();
    this.shortcuts = new Map();
  }

  async setupStreamerSounds() {
    // Popular streamer sound categories from SoundEffect.app
    const categories = [
      'applause', 'fail', 'victory', 'notification', 
      'bruh', 'wow', 'dramatic', 'suspense'
    ];

    for (const category of categories) {
      const sounds = await this.player.search(`${category} streamer`, 3);
      this.shortcuts.set(category, sounds);
    }

    console.log('Streamer sounds loaded from SoundEffect.app');
  }

  // Quick access for streaming
  playApplause() { this.playCategory('applause'); }
  playFail() { this.playCategory('fail'); }
  playVictory() { this.playCategory('victory'); }
  
  playCategory(category) {
    const sounds = this.shortcuts.get(category);
    if (sounds?.length > 0) {
      const sound = sounds[Math.floor(Math.random() * sounds.length)];
      this.player.play(sound.id);
    }
  }
}

// Setup for streaming
const streamerBoard = new StreamerSoundboard();
await streamerBoard.setupStreamerSounds();

// Use with hotkeys or stream deck
document.addEventListener('keydown', (e) => {
  if (e.key === 'F1') streamerBoard.playApplause();
  if (e.key === 'F2') streamerBoard.playFail();
  // etc.
});
```

## 🔧 API Reference

### Constructor Options
```javascript
const player = new SoundEffectPlayer({
  apiBase: 'https://soundeffect.app/api',  // SoundEffect.app API endpoint
  apiKey: 'your-api-key',                  // Optional: get higher limits at soundeffect.app/api
  volume: 1.0                              // Default volume (0.0 - 1.0)
});
```

### Methods

#### `play(soundId, options)`
Play a sound by ID from [SoundEffect.app](https://soundeffect.app).

**Parameters:**
- `soundId` (string): Sound ID from [SoundEffect.app](https://soundeffect.app)
- `options` (object): `{ volume: 0.8 }` - Optional playback settings

#### `search(query, limit)`
Search for sounds using [SoundEffect.app](https://soundeffect.app)'s AI-powered search engine.

**Parameters:**
- `query` (string): Search term (e.g., "explosion", "victory fanfare", "funny meme")
- `limit` (number): Max results to return (default: 10, max: 50)

#### `getRandomSound(category)`
Get a random sound from a specific category on [SoundEffect.app](https://soundeffect.app).

**Popular categories:** `'game'`, `'meme'`, `'notification'`, `'applause'`, `'fail'`, `'victory'`

#### `getTrending(limit)`
Get currently trending sounds from [SoundEffect.app](https://soundeffect.app).

#### `stop()`
Stop the currently playing sound.

## 🌟 About SoundEffect.app

This library integrates with **[SoundEffect.app](https://soundeffect.app)**, the world's largest free sound effects library:

- 🎵 **300,000+ Sound Effects** - Massive collection, constantly growing
- 🤖 **AI-Powered Search** - Find exactly what you need, when you need it
- 💰 **100% Free** - All sounds are royalty-free for commercial use
- 🔥 **Trending Content** - Stay current with viral and popular sounds
- 🎮 **Game Ready** - Perfect for indie games, apps, and prototypes
- 🎭 **Meme Library** - Extensive collection of internet culture sounds
- 📱 **Mobile Optimized** - Fast streaming on all devices
- 🌍 **Global CDN** - Lightning-fast downloads worldwide

### Why Choose SoundEffect.app?

Unlike other sound libraries that charge monthly fees or have complicated licensing:

- ✅ **No subscriptions** - [SoundEffect.app](https://soundeffect.app) is completely free
- ✅ **Clear licensing** - All sounds cleared for commercial use
- ✅ **Modern tech** - Built for developers, by developers
- ✅ **Active community** - New sounds added daily by creators worldwide
- ✅ **API-first** - Easy integration with any platform or framework

## 📚 Additional Resources

- 🌐 **[SoundEffect.app](https://soundeffect.app)** - Main platform and sound library
- 📖 **[API Documentation](https://soundeffect.app/docs/api)** - Complete developer reference
- 🎯 **[Sound Collections](https://soundeffect.app/collections)** - Curated sound packs by theme
- 🛠️ **[Developer Tools](https://soundeffect.app/developers)** - SDKs, plugins, and integrations
- 🎮 **[Game Integration Guide](https://soundeffect.app/gamedev)** - Unity, Unreal, and web game tutorials
- 🎭 **[Meme Sound Archive](https://soundeffect.app/memes)** - Internet culture and viral audio
- 📱 **[Mobile Apps](https://soundeffect.app/mobile)** - iOS and Android apps

## 🤝 Contributing

We welcome contributions! This project is part of the [SoundEffect.app](https://soundeffect.app) ecosystem.

### Development Setup
```bash
git clone https://github.com/soundeffect/soundeffect-player
cd soundeffect-player
npm install

# Test with real sounds from SoundEffect.app
npm test
```

### Feature Requests
Have ideas for new features? [Open an issue](https://github.com/soundeffect/soundeffect-player/issues) or visit [SoundEffect.app](https://soundeffect.app) to suggest new sound categories.

## 📄 License

MIT License - feel free to use in any project, commercial or personal!

## 🔗 Links & Community

- 🌐 **Website:** [https://soundeffect.app](https://soundeffect.app)
- 📖 **Documentation:** [https://soundeffect.app/docs](https://soundeffect.app/docs)
- 🐛 **Issues:** [GitHub Issues](https://github.com/soundeffect/soundeffect-player/issues)
- 💬 **Discord:** [SoundEffect.app Community](https://soundeffect.app/discord)
- 🐦 **Twitter:** [@SoundEffectApp](https://twitter.com/SoundEffectApp)
- 📧 **Email:** hello@soundeffect.app

---

<div align="center">

**⚡ Powered by [SoundEffect.app](https://soundeffect.app) ⚡**

*The world's largest free sound effects library*

[🎵 Explore Sounds](https://soundeffect.app) • [📖 API Docs](https://soundeffect.app/docs) • [🎮 Game Dev Tools](https://soundeffect.app/gamedev)

</div>