star-audio 0.1.0

package/LICENSE-3RD-PARTY.md

@@ -0,0 +1,31 @@
+# Third-Party Software Notices and Information
+
+This package contains third-party software components governed by the licenses indicated below.
+
+---
+
+## howler.js
+
+- **Website:** [https://howlerjs.com/](https://howlerjs.com/)
+- **License:** MIT License
+
+Copyright (c) 2013-2020 James Simpson and GoldFire Studios, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# Star Audio
+
+A simple sound manager for web games that "just works" on mobile.
+
+`star-audio` solves the 90% use case for game audio: SFX playback and BGM crossfades, with a mobile-first design that handles browser audio unlocking automatically. It's designed to be predictable, easy to use, and LLM-friendly.
+
+**Powered by the battle-tested [Howler.js](https://howlerjs.com/) core.**
+
+This package is part of the **Star SDK**.
+
+## Features
+
+- **Bulletproof:** Missing audio files won't crash your game - errors are logged but never thrown.
+- **Mobile-Safe by Default:** Automatically handles audio context unlocking on user interaction. Plays sound even when the device's silent/ringer switch is on.
+- **Tiny API Surface:** A small, guessable API (`play`, `music.crossfadeTo`, `setMute`). No try/catch needed.
+- **Two-Bus Mixer:** Simple `music` and `sfx` groups for easy volume control.
+- **Seamless Music Crossfades:** Built-in helpers for smooth background music transitions.
+- **SSR-Safe:** Can be imported in server-side environments without errors.
+- **Single Dependency:** Powered by Howler.js for maximum reliability.
+
+## Install
+
+```bash
+yarn add star-audio
+# or
+npm install star-audio
+```
+
+## Quick Starts
+
+### 1. Vanilla JS (60 seconds)
+
+This is the fastest way to get started. Serve an `index.html` file and add the following.
+
+```html
+<div id="root" style="height:100vh; display: grid; place-items: center;">Tap anywhere</div>
+<script type="module">
+  import createAudio from 'star-audio';
+
+  // Create an audio manager. 
+  // 'auto' unlocks audio on the first user interaction.
+  // 'autostart' will play 'music.theme' once unlocked.
+  const audio = createAudio({
+    unlockWith: 'auto',
+    autostart: { id: 'music.theme', crossfadeSec: 1 }
+  });
+
+  // Preload your audio assets.
+  await audio.preload({
+    'music.theme': ['/audio/theme.m4a', '/audio/theme.mp3'],
+    'sfx.tap':     ['/audio/tap.mp3']
+  });
+
+  // Play a sound effect on user interaction.
+  document.getElementById('root').addEventListener('pointerdown', () => {
+    audio.play('sfx.tap', { volume: 0.9 }); // alias: audio.playSound('sfx.tap')
+  });
+</script>
+```
+
+### 2. Next.js / React (Client Component)
+
+In a React component, it's best to create the audio instance once with `useMemo`.
+
+```tsx
+/* app/game/page.tsx */
+"use client";
+import { useEffect, useMemo } from 'react';
+import { createStarAudio } from 'star-audio';
+
+export default function Game() {
+  const audio = useMemo(() => createStarAudio({
+    unlockWith: 'auto',
+    autostart: { id: 'music.theme', crossfadeSec: 1 },
+    suspendOnHidden: true, // Pauses audio when tab is not visible
+  }), []);
+
+  useEffect(() => {
+    // Preload assets when the component mounts.
+    (async () => {
+      await audio.preload({
+        'music.theme': ['/audio/theme.m4a', '/audio/theme.mp3'],
+        'sfx.tap':     ['/audio/tap.mp3']
+      });
+    })();
+
+    // Clean up the audio instance when the component unmounts.
+    return () => audio.destroy();
+  }, [audio]);
+
+  return (
+    <div 
+      className="h-screen w-screen" 
+      onPointerDown={() => audio.play('sfx.tap', { volume: 0.9 })}
+    >
+      Tap to play
+    </div>
+  );
+}
+```
+
+## Common Recipes
+
+### Crossfade Background Music
+
+```ts
+await audio.preload({ 'bgm.title': ['/music/title.m4a'] });
+
+// Fade from the current track (or silence) to the title music over 1.5 seconds.
+await audio.music.crossfadeTo('bgm.title', { duration: 1.5 });
+```
+
+### Volumes & Mute
+
+The volume and mute state are automatically persisted to `localStorage`.
+
+```ts
+// Set music volume to 60% with a 300ms fade.
+audio.setMusicVolume(0.6, { durationMs: 300 });
+
+// Set SFX volume to 80% instantly.
+audio.setSfxVolume(0.8);
+
+// Toggle mute for all audio.
+audio.toggleMute();
+```
+
+### Pause/Resume (e.g., for a pause menu)
+
+```ts
+// Suspend the audio context.
+await audio.pause();
+
+// Resume the audio context.
+await audio.resume();
+```
+
+### Limit SFX Overlap
+
+To prevent audio clipping from too many overlapping sounds, you can limit the number of concurrent SFX voices.
+
+```ts
+// Only allow a maximum of 16 sound effects to play at once.
+const audio = createAudio({ maxSfxVoices: 16 });
+```
+
+## Error Handling Philosophy
+
+Star Audio is designed to **never crash your game**. All loading methods (`preload()`, `load()`) gracefully handle missing or corrupt audio files:
+
+```ts
+// ✅ This never throws - even if the file doesn't exist!
+await audio.preload({
+  'sfx.coin': '/missing.mp3',      // ⚠️  Logs warning, continues
+  'sfx.jump': '/audio/jump.mp3'    // ✅ Loads successfully
+});
+
+// Game continues working with the sounds that did load
+audio.play('sfx.jump');  // ✅ Works
+audio.play('sfx.coin');  // ⚠️  Silently fails (already warned during preload)
+```
+
+**No try/catch needed.** Failed audio loads are logged to the console with clear warnings, but your game keeps running.
+
+If you need programmatic error handling, listen to the `'error'` event:
+
+```ts
+audio.on('error', () => {
+  console.log('An audio file failed to load, but the game is still running!');
+});
+```
+
+## Known Limitations
+
+`star-audio` is designed to solve the 90% use case for web game audio. The current implementation (v1.x) has the following limitations:
+
+- **No SFX voice limiting**: The `maxSfxVoices` option is accepted but not enforced. In practice, browsers limit concurrent audio to ~30-50 voices.
+- **No micro-ducking**: Background music does not automatically reduce volume when sound effects play.
+- **No volume ramping**: The `durationMs` parameter in `setMusicVolume()` and `setSfxVolume()` is accepted but ignored. Volume changes are instant.
+- **No scheduled playback**: The `when`, `offset`, and `duration` parameters in `PlayOptions` are not currently implemented.
+- **Pause/Resume behavior**: Only music is automatically resumed when calling `resume()` after `pause()`. Sound effects that were playing will not resume.
+
+These limitations reflect the current Howler.js wrapper implementation. If you need any of these features, please open an issue on GitHub to help us prioritize future development.
+
+## Acknowledgements
+
+The reliability and robustness of `star-audio`, especially on mobile devices, is made possible by the fantastic work of the developers behind [Howler.js](https://howlerjs.com/). We use the Howler core to handle the complexities of cross-browser audio, allowing us to provide a simpler, game-focused API on top of a battle-tested foundation.

package/dist/index.d.cts

@@ -0,0 +1,144 @@
+/**
+ * Star Audio SDK version
+ */
+declare const VERSION = "0.1.0";
+/**
+ * The possible states of the audio context.
+ * - `locked`: The audio context is waiting for a user gesture to start.
+ * - `running`: The audio context is active and playing sound.
+ * - `suspended`: The audio context is paused.
+ */
+type AudioState = 'locked' | 'running' | 'suspended';
+/**
+ * Predefined procedural sound presets.
+ */
+type SynthPreset = 'beep' | 'coin' | 'pickup' | 'jump' | 'hurt' | 'explosion' | 'powerup' | 'shoot' | 'laser' | 'error' | 'click' | 'success' | 'bonus' | 'select' | 'unlock' | 'swoosh' | 'hit';
+/**
+ * Custom procedural sound definition using Web Audio API oscillators.
+ */
+interface SynthDefinition {
+    waveform?: 'sine' | 'square' | 'sawtooth' | 'triangle';
+    frequency?: number | number[];
+    duration?: number;
+    volume?: number;
+    envelope?: 'percussive' | 'sustained';
+}
+/**
+ * A manifest of audio assets to load.
+ * The key is the asset ID, and the value can be:
+ * - A URL string (file-based audio)
+ * - An array of URLs (multiple formats)
+ * - A SynthPreset string (procedural preset sound)
+ * - A SynthDefinition object (custom procedural sound)
+ * - An object with `src`/`url`/`synth` and optional `group` properties
+ */
+type Manifest = Record<string, string | string[] | SynthPreset | SynthDefinition | {
+    src?: string | string[];
+    url?: string | string[];
+    synth?: SynthPreset | SynthDefinition;
+    group?: 'music' | 'sfx';
+    volume?: number;
+}>;
+/**
+ * Options for playing a sound.
+ */
+interface PlayOptions {
+    src?: string | string[];
+    url?: string | string[];
+    volume?: number;
+    loop?: boolean;
+    rate?: number;
+    detune?: number;
+    when?: number;
+    offset?: number;
+    duration?: number;
+    group?: 'music' | 'sfx';
+}
+/**
+ * A handle to a playing sound, allowing for control over its playback.
+ */
+interface SoundHandle {
+    id: string;
+    stop(at?: number): void;
+    setVolume(v: number, nowPlusSec?: number): void;
+    readonly playing: boolean;
+}
+/**
+ * Options for creating a StarAudio instance.
+ */
+interface StarAudioOptions {
+    unlockWith?: 'auto' | HTMLElement | Document | Window | false;
+    autostart?: string | {
+        id: string;
+        crossfadeSec?: number;
+        loop?: boolean;
+    };
+    autoplay?: StarAudioOptions['autostart'];
+    maxSfxVoices?: number;
+    initialMute?: boolean;
+    initialVolumes?: {
+        music?: number;
+        sfx?: number;
+    };
+    suspendOnHidden?: boolean;
+    persistKey?: string;
+    ducking?: boolean | {
+        amount?: number;
+        holdMs?: number;
+        releaseMs?: number;
+    };
+    latencyHint?: 'interactive' | 'balanced' | 'playback';
+}
+/**
+ * The main interface for the Star Audio manager.
+ */
+interface StarAudio {
+    readonly state: AudioState;
+    readonly ready: Promise<void>;
+    preload(m: Manifest): Promise<void>;
+    load(o: {
+        id: string;
+        src?: string | string[];
+        url?: string | string[];
+        group?: 'music' | 'sfx';
+    }): Promise<void>;
+    play(id: string, opts?: PlayOptions): SoundHandle | null;
+    playSound: StarAudio['play'];
+    music: {
+        crossfadeTo(id: string, o?: {
+            duration?: number;
+            loop?: boolean;
+        }): Promise<void>;
+        stop(fadeSec?: number): void;
+        fadeTo: StarAudio['music']['crossfadeTo'];
+        switchTo: StarAudio['music']['crossfadeTo'];
+    };
+    musicFadeTo: StarAudio['music']['crossfadeTo'];
+    setMusicVolume(v: number, o?: {
+        durationMs?: number;
+    }): void;
+    setSfxVolume(v: number, o?: {
+        durationMs?: number;
+    }): void;
+    setMusic: StarAudio['setMusicVolume'];
+    setSfx: StarAudio['setSfxVolume'];
+    setMute(muted: boolean): void;
+    mute: StarAudio['setMute'];
+    toggleMute(): void;
+    isMuted(): boolean;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    unlock(): Promise<void>;
+    attachUnlock(target?: HTMLElement | Document | Window): void;
+    on(evt: 'unlocked' | 'suspended' | 'resumed' | 'error', cb: () => void): void;
+    off(evt: 'unlocked' | 'suspended' | 'resumed' | 'error', cb: () => void): void;
+    destroy(): void;
+}
+/**
+ * Creates a new StarAudio instance.
+ * @param opts - A set of options for configuring the audio manager.
+ * @returns A new `StarAudio` instance.
+ */
+declare function createStarAudio(opts?: StarAudioOptions): StarAudio;
+
+export { type AudioState, type Manifest, type PlayOptions, type SoundHandle, type StarAudio, type StarAudioOptions, type SynthDefinition, type SynthPreset, VERSION, createStarAudio, createStarAudio as default };

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Star Audio SDK version
+ */
+declare const VERSION = "0.1.0";
+/**
+ * The possible states of the audio context.
+ * - `locked`: The audio context is waiting for a user gesture to start.
+ * - `running`: The audio context is active and playing sound.
+ * - `suspended`: The audio context is paused.
+ */
+type AudioState = 'locked' | 'running' | 'suspended';
+/**
+ * Predefined procedural sound presets.
+ */
+type SynthPreset = 'beep' | 'coin' | 'pickup' | 'jump' | 'hurt' | 'explosion' | 'powerup' | 'shoot' | 'laser' | 'error' | 'click' | 'success' | 'bonus' | 'select' | 'unlock' | 'swoosh' | 'hit';
+/**
+ * Custom procedural sound definition using Web Audio API oscillators.
+ */
+interface SynthDefinition {
+    waveform?: 'sine' | 'square' | 'sawtooth' | 'triangle';
+    frequency?: number | number[];
+    duration?: number;
+    volume?: number;
+    envelope?: 'percussive' | 'sustained';
+}
+/**
+ * A manifest of audio assets to load.
+ * The key is the asset ID, and the value can be:
+ * - A URL string (file-based audio)
+ * - An array of URLs (multiple formats)
+ * - A SynthPreset string (procedural preset sound)
+ * - A SynthDefinition object (custom procedural sound)
+ * - An object with `src`/`url`/`synth` and optional `group` properties
+ */
+type Manifest = Record<string, string | string[] | SynthPreset | SynthDefinition | {
+    src?: string | string[];
+    url?: string | string[];
+    synth?: SynthPreset | SynthDefinition;
+    group?: 'music' | 'sfx';
+    volume?: number;
+}>;
+/**
+ * Options for playing a sound.
+ */
+interface PlayOptions {
+    src?: string | string[];
+    url?: string | string[];
+    volume?: number;
+    loop?: boolean;
+    rate?: number;
+    detune?: number;
+    when?: number;
+    offset?: number;
+    duration?: number;
+    group?: 'music' | 'sfx';
+}
+/**
+ * A handle to a playing sound, allowing for control over its playback.
+ */
+interface SoundHandle {
+    id: string;
+    stop(at?: number): void;
+    setVolume(v: number, nowPlusSec?: number): void;
+    readonly playing: boolean;
+}
+/**
+ * Options for creating a StarAudio instance.
+ */
+interface StarAudioOptions {
+    unlockWith?: 'auto' | HTMLElement | Document | Window | false;
+    autostart?: string | {
+        id: string;
+        crossfadeSec?: number;
+        loop?: boolean;
+    };
+    autoplay?: StarAudioOptions['autostart'];
+    maxSfxVoices?: number;
+    initialMute?: boolean;
+    initialVolumes?: {
+        music?: number;
+        sfx?: number;
+    };
+    suspendOnHidden?: boolean;
+    persistKey?: string;
+    ducking?: boolean | {
+        amount?: number;
+        holdMs?: number;
+        releaseMs?: number;
+    };
+    latencyHint?: 'interactive' | 'balanced' | 'playback';
+}
+/**
+ * The main interface for the Star Audio manager.
+ */
+interface StarAudio {
+    readonly state: AudioState;
+    readonly ready: Promise<void>;
+    preload(m: Manifest): Promise<void>;
+    load(o: {
+        id: string;
+        src?: string | string[];
+        url?: string | string[];
+        group?: 'music' | 'sfx';
+    }): Promise<void>;
+    play(id: string, opts?: PlayOptions): SoundHandle | null;
+    playSound: StarAudio['play'];
+    music: {
+        crossfadeTo(id: string, o?: {
+            duration?: number;
+            loop?: boolean;
+        }): Promise<void>;
+        stop(fadeSec?: number): void;
+        fadeTo: StarAudio['music']['crossfadeTo'];
+        switchTo: StarAudio['music']['crossfadeTo'];
+    };
+    musicFadeTo: StarAudio['music']['crossfadeTo'];
+    setMusicVolume(v: number, o?: {
+        durationMs?: number;
+    }): void;
+    setSfxVolume(v: number, o?: {
+        durationMs?: number;
+    }): void;
+    setMusic: StarAudio['setMusicVolume'];
+    setSfx: StarAudio['setSfxVolume'];
+    setMute(muted: boolean): void;
+    mute: StarAudio['setMute'];
+    toggleMute(): void;
+    isMuted(): boolean;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    unlock(): Promise<void>;
+    attachUnlock(target?: HTMLElement | Document | Window): void;
+    on(evt: 'unlocked' | 'suspended' | 'resumed' | 'error', cb: () => void): void;
+    off(evt: 'unlocked' | 'suspended' | 'resumed' | 'error', cb: () => void): void;
+    destroy(): void;
+}
+/**
+ * Creates a new StarAudio instance.
+ * @param opts - A set of options for configuring the audio manager.
+ * @returns A new `StarAudio` instance.
+ */
+declare function createStarAudio(opts?: StarAudioOptions): StarAudio;
+
+export { type AudioState, type Manifest, type PlayOptions, type SoundHandle, type StarAudio, type StarAudioOptions, type SynthDefinition, type SynthPreset, VERSION, createStarAudio, createStarAudio as default };