soundeffect-player/src/soundeffect-player.d.ts

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

/**
 * TypeScript definitions for SoundEffect Player
 * Integration with SoundEffect.app - 300K+ sound effects library
 */

export interface SoundEffectPlayerConfig {
  /** SoundEffect.app API base URL */
  apiBase?: string;
  /** Optional API key for higher rate limits from SoundEffect.app */
  apiKey?: string;
  /** Default volume (0.0 - 1.0) */
  volume?: number;
  /** Enable debug logging */
  debug?: boolean;
}

export interface PlayOptions {
  /** Volume for this specific playback (0.0 - 1.0) */
  volume?: number;
  /** Whether to loop the audio */
  loop?: boolean;
}

export interface SearchResult {
  /** Unique sound ID from SoundEffect.app */
  id: string;
  /** Sound title */
  title: string;
  /** Sound description */
  description?: string;
  /** Duration in seconds */
  duration: number;
  /** Category (e.g., 'game', 'meme', 'notification') */
  category: string;
  /** Tags array */
  tags: string[];
  /** Download URL */
  url: string;
  /** Streaming URL */
  streamUrl: string;
  /** Thumbnail image URL */
  thumbnail?: string;
  /** Popularity score */
  popularity: number;
  /** Upload date */
  createdAt: string;
}

export interface PlayerState {
  /** Whether audio is currently playing */
  isPlaying: boolean;
  /** Current volume level (0.0 - 1.0) */
  volume: number;
  /** Current playback time in seconds */
  currentTime: number;
  /** Total duration in seconds */
  duration: number;
  /** Whether there's an audio element loaded */
  hasAudio: boolean;
}

export interface SoundCategory {
  /** Category ID */
  id: string;
  /** Category name */
  name: string;
  /** Category description */
  description: string;
  /** Number of sounds in category */
  soundCount: number;
  /** Category thumbnail */
  thumbnail?: string;
}

export interface Soundboard {
  /** Map of sound keys to IDs */
  sounds: Map<string, string>;
  /** Reference to the player instance */
  player: SoundEffectPlayer;
  /** Play a specific sound by key */
  play(key: string): Promise<HTMLAudioElement>;
  /** Play a random sound from the soundboard */
  playRandom(): Promise<HTMLAudioElement>;
  /** List all available sound keys */
  list(): string[];
}

/**
 * SoundEffect Player - Lightweight audio player with SoundEffect.app integration
 * 
 * Access 300,000+ high-quality sound effects with AI-powered search
 * Perfect for games, web apps, streaming, and content creation
 * 
 * @example
 * ```typescript
 * import SoundEffectPlayer from 'soundeffect-player';
 * 
 * const player = new SoundEffectPlayer({
 *   apiKey: 'your-key', // Get free API key at https://soundeffect.app/api
 *   volume: 0.8
 * });
 * 
 * // Play a sound effect
 * await player.play('epic-win-sound');
 * 
 * // AI-powered search
 * const sounds = await player.search('explosion');
 * console.log(`Found ${sounds.length} explosion sounds on SoundEffect.app`);
 * ```
 */
export default class SoundEffectPlayer {
  /** Current API base URL */
  public readonly apiBase: string;
  /** API key for SoundEffect.app */
  public readonly apiKey: string;
  /** Current volume level */
  public volume: number;
  /** Currently playing audio element */
  public currentAudio: HTMLAudioElement | null;
  /** Whether audio is currently playing */
  public isPlaying: boolean;
  /** Internal cache for API responses */
  public readonly cache: Map<string, any>;
  /** Debug mode flag */
  public readonly debug: boolean;

  /**
   * Create a new SoundEffect Player instance
   * @param config Configuration options
   */
  constructor(config?: SoundEffectPlayerConfig);

  /**
   * Play a sound by ID from SoundEffect.app
   * @param soundId Sound ID from SoundEffect.app library
   * @param options Playback options
   * @returns Promise resolving to the audio element
   */
  play(soundId: string, options?: PlayOptions): Promise<HTMLAudioElement>;

  /**
   * Search for sounds using SoundEffect.app's AI-powered search
   * @param query Search query (e.g., "explosion", "victory fanfare")
   * @param limit Maximum number of results (default: 10, max: 50)
   * @returns Promise resolving to search results
   */
  search(query: string, limit?: number): Promise<SearchResult[]>;

  /**
   * Get a random sound from SoundEffect.app by category
   * @param category Sound category (e.g., 'game', 'meme', 'notification')
   * @returns Promise resolving to a random sound
   */
  getRandomSound(category: string): Promise<SearchResult>;

  /**
   * Get currently trending sounds from SoundEffect.app
   * @param limit Number of trending sounds to fetch (default: 10)
   * @returns Promise resolving to trending sounds array
   */
  getTrending(limit?: number): Promise<SearchResult[]>;

  /**
   * Get available sound categories from SoundEffect.app
   * @returns Promise resolving to categories array
   */
  getCategories(): Promise<SoundCategory[]>;

  /**
   * Stop current audio playback
   */
  stop(): void;

  /**
   * Pause current audio playback
   */
  pause(): void;

  /**
   * Resume paused audio playback
   */
  resume(): void;

  /**
   * Set volume for current and future playback
   * @param volume Volume level (0.0 - 1.0)
   */
  setVolume(volume: number): void;

  /**
   * Get current playback state
   * @returns Current state information
   */
  getState(): PlayerState;

  /**
   * Clear the internal cache
   */
  clearCache(): void;

  /**
   * Create a soundboard with multiple sounds from SoundEffect.app
   * @param soundIds Array of sound IDs or search queries
   * @returns Promise resolving to a soundboard object
   */
  createSoundboard(soundIds: string[]): Promise<Soundboard>;
}

/**
 * CommonJS export
 */
export = SoundEffectPlayer;