@react-text-game/core 0.4.0 → 0.5.0

package/dist/audio/audioTrack.d.ts

@@ -0,0 +1,407 @@
+import type { AudioOptions, AudioState } from "./types";
+/**
+ * Individual audio track with reactive state management.
+ *
+ * AudioTrack wraps the HTMLAudioElement API with Valtio reactive state,
+ * making it easy to integrate with React components and the game's save system.
+ *
+ * Features:
+ * - Reactive state updates via Valtio
+ * - Automatic persistence with save/load
+ * - Volume, loop, and playback rate controls
+ * - Fade in/out effects
+ * - Event-driven state synchronization
+ *
+ * @example
+ * ```typescript
+ * const music = new AudioTrack('assets/music.mp3', {
+ *   id: 'bg-music',
+ *   loop: true,
+ *   volume: 0.7,
+ * });
+ *
+ * await music.play();
+ * music.setVolume(0.5);
+ * ```
+ */
+export declare class AudioTrack {
+    readonly id: string;
+    readonly src: string;
+    private readonly audioElement;
+    private readonly state;
+    private readonly jsonPath;
+    private readonly unsubscribe?;
+    constructor(src: string, options?: AudioOptions);
+    /**
+     * Attaches event listeners to sync HTMLAudioElement state with reactive state.
+     * @private
+     */
+    private attachEventListeners;
+    /**
+     * Plays the audio track.
+     *
+     * @returns Promise that resolves when playback starts
+     * @throws Error if playback fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await audio.play();
+     * } catch (error) {
+     *   console.error('Playback failed:', error);
+     * }
+     * ```
+     */
+    play(): Promise<void>;
+    /**
+     * Pauses the audio track.
+     *
+     * @example
+     * ```typescript
+     * audio.pause();
+     * ```
+     */
+    pause(): void;
+    /**
+     * Resumes playback if the audio is paused.
+     *
+     * @example
+     * ```typescript
+     * audio.resume();
+     * ```
+     */
+    resume(): void;
+    /**
+     * Stops the audio track and resets to the beginning.
+     *
+     * @example
+     * ```typescript
+     * audio.stop();
+     * ```
+     */
+    stop(): void;
+    /**
+     * Sets the volume level.
+     *
+     * @param volume - Volume level (0.0 to 1.0), clamped to valid range
+     *
+     * @example
+     * ```typescript
+     * audio.setVolume(0.5); // 50% volume
+     * ```
+     */
+    setVolume(volume: number): void;
+    /**
+     * Applies the effective volume (track volume * master volume) to the audio element.
+     * Internal method used by AudioManager to apply master volume changes.
+     *
+     * @internal
+     */
+    _applyEffectiveVolume(): void;
+    /**
+     * Sets whether the audio should loop.
+     *
+     * @param loop - True to enable looping, false to disable
+     *
+     * @example
+     * ```typescript
+     * audio.setLoop(true);
+     * ```
+     */
+    setLoop(loop: boolean): void;
+    /**
+     * Sets the playback rate.
+     *
+     * @param rate - Playback rate multiplier (0.5 = half speed, 2.0 = double speed)
+     *
+     * @example
+     * ```typescript
+     * audio.setPlaybackRate(1.5); // 1.5x speed
+     * ```
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Sets whether the audio is muted.
+     *
+     * @param muted - True to mute, false to unmute
+     *
+     * @example
+     * ```typescript
+     * audio.setMuted(true);
+     * ```
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Seeks to a specific time in the audio.
+     *
+     * @param time - Time in seconds, clamped to [0, duration]
+     *
+     * @example
+     * ```typescript
+     * audio.seek(30); // Seek to 30 seconds
+     * ```
+     */
+    seek(time: number): void;
+    /**
+     * Fades in the audio over a specified duration.
+     *
+     * Starts at volume 0 and gradually increases to the target volume.
+     *
+     * @param duration - Fade duration in milliseconds
+     * @returns Promise that resolves when fade completes
+     *
+     * @example
+     * ```typescript
+     * await audio.fadeIn(2000); // Fade in over 2 seconds
+     * ```
+     */
+    fadeIn(duration?: number): Promise<void>;
+    /**
+     * Fades out the audio over a specified duration and stops.
+     *
+     * @param duration - Fade duration in milliseconds
+     * @returns Promise that resolves when fade completes
+     *
+     * @example
+     * ```typescript
+     * await audio.fadeOut(1500); // Fade out over 1.5 seconds
+     * ```
+     */
+    fadeOut(duration?: number): Promise<void>;
+    /**
+     * Fades to a target volume over a specified duration.
+     *
+     * @private
+     * @param targetVolume - Target volume level (0.0 to 1.0)
+     * @param duration - Fade duration in milliseconds
+     * @returns Promise that resolves when fade completes
+     */
+    private fadeTo;
+    /**
+     * Gets the reactive audio state.
+     *
+     * This state is a Valtio proxy and can be used with useSnapshot() in React.
+     *
+     * @returns The reactive audio state
+     *
+     * @example
+     * ```typescript
+     * const state = audio.getState();
+     * console.log(state.isPlaying); // true/false
+     * ```
+     */
+    getState(): AudioState;
+    /**
+     * Saves the current audio state to storage.
+     *
+     * Called automatically when auto-save is enabled.
+     *
+     * @example
+     * ```typescript
+     * audio.save();
+     * ```
+     */
+    save(): void;
+    /**
+     * Loads the audio state from storage.
+     *
+     * Restores volume, loop, playback rate, muted status, and playback position.
+     * Optionally resumes playback if the audio was playing when saved.
+     *
+     * @example
+     * ```typescript
+     * audio.load();
+     * ```
+     */
+    load(): void;
+    /**
+     * Cleans up the audio track and removes all listeners.
+     *
+     * Should be called when the audio track is no longer needed.
+     *
+     * @example
+     * ```typescript
+     * audio.dispose();
+     * ```
+     */
+    dispose(): void;
+}
+/**
+ * Global audio manager for controlling all audio tracks.
+ *
+ * AudioManager provides a singleton interface for game-wide audio operations
+ * like master volume control, muting all tracks, or pausing all audio.
+ *
+ * @example
+ * ```typescript
+ * // Global volume control
+ * AudioManager.setMasterVolume(0.5);
+ *
+ * // Mute all audio
+ * AudioManager.muteAll();
+ *
+ * // Pause all playing tracks
+ * AudioManager.pauseAll();
+ * ```
+ */
+declare class AudioManagerClass {
+    private tracks;
+    private state;
+    /**
+     * Internal method to register a track.
+     * Called automatically by AudioTrack constructor.
+     *
+     * @internal
+     * @param track - The audio track to register
+     */
+    _registerTrack(track: AudioTrack): void;
+    /**
+     * Internal method to unregister a track.
+     * Called automatically by AudioTrack.dispose().
+     *
+     * @internal
+     * @param track - The audio track to unregister
+     */
+    _unregisterTrack(track: AudioTrack): void;
+    /**
+     * Sets the master volume for all audio tracks.
+     *
+     * The master volume is multiplied with each track's individual volume.
+     * This does not modify individual track volumes - it applies a global multiplier.
+     *
+     * @param volume - Master volume level (0.0 to 1.0), clamped to valid range
+     *
+     * @example
+     * ```typescript
+     * AudioManager.setMasterVolume(0.5); // 50% master volume
+     * ```
+     */
+    setMasterVolume(volume: number): void;
+    /**
+     * Gets the current master volume.
+     *
+     * @returns The master volume level (0.0 to 1.0)
+     *
+     * @example
+     * ```typescript
+     * const volume = AudioManager.getMasterVolume();
+     * ```
+     */
+    getMasterVolume(): number;
+    /**
+     * Mutes all audio tracks.
+     *
+     * @example
+     * ```typescript
+     * AudioManager.muteAll();
+     * ```
+     */
+    muteAll(): void;
+    /**
+     * Unmutes all audio tracks.
+     *
+     * @example
+     * ```typescript
+     * AudioManager.unmuteAll();
+     * ```
+     */
+    unmuteAll(): void;
+    /**
+     * Pauses all currently playing audio tracks.
+     *
+     * @example
+     * ```typescript
+     * AudioManager.pauseAll();
+     * ```
+     */
+    pauseAll(): void;
+    /**
+     * Resumes all paused audio tracks.
+     *
+     * @example
+     * ```typescript
+     * AudioManager.resumeAll();
+     * ```
+     */
+    resumeAll(): void;
+    /**
+     * Stops all audio tracks.
+     *
+     * @example
+     * ```typescript
+     * AudioManager.stopAll();
+     * ```
+     */
+    stopAll(): void;
+    /**
+     * Gets all registered audio tracks.
+     *
+     * @returns Array of all audio tracks
+     *
+     * @example
+     * ```typescript
+     * const tracks = AudioManager.getAllTracks();
+     * console.log(`Total tracks: ${tracks.length}`);
+     * ```
+     */
+    getAllTracks(): Array<AudioTrack>;
+    /**
+     * Gets an audio track by its ID.
+     *
+     * @param id - The unique identifier of the audio track
+     * @returns The audio track, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const music = AudioManager.getTrackById('bg-music');
+     * if (music) {
+     *   music.play();
+     * }
+     * ```
+     */
+    getTrackById(id: string): AudioTrack | undefined;
+    /**
+     * Gets the reactive audio manager state.
+     *
+     * This state is a Valtio proxy and can be used with useSnapshot() in React.
+     *
+     * @returns The reactive audio manager state
+     *
+     * @example
+     * ```typescript
+     * const state = AudioManager.getState();
+     * console.log(state.masterVolume); // 1.0
+     * ```
+     */
+    getState(): {
+        masterVolume: number;
+        isMuted: boolean;
+    };
+    /**
+     * Disposes all audio tracks.
+     *
+     * Useful for cleanup when shutting down the game.
+     *
+     * @example
+     * ```typescript
+     * AudioManager.disposeAll();
+     * ```
+     */
+    disposeAll(): void;
+}
+/**
+ * Singleton instance of the AudioManager.
+ *
+ * Use this to control all audio tracks globally.
+ *
+ * @example
+ * ```typescript
+ * import { AudioManager } from '@react-text-game/core/audio';
+ *
+ * AudioManager.setMasterVolume(0.8);
+ * AudioManager.muteAll();
+ * ```
+ */
+export declare const AudioManager: AudioManagerClass;
+export {};
+//# sourceMappingURL=audioTrack.d.ts.map

package/dist/audio/audioTrack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioTrack.d.ts","sourceRoot":"","sources":["../../src/audio/audioTrack.ts"],"names":[],"mappings":"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"}