@umituz/react-native-sound 1.2.12 → 1.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-sound",
-  "version": "1.2.12",
+  "version": "1.2.13",
   "description": "Universal sound playback and caching library for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/AudioManager.ts

@@ -1,10 +1,26 @@
 import { Audio, AVPlaybackStatus, InterruptionModeIOS, InterruptionModeAndroid } from 'expo-av';
 import { useSoundStore } from './store';
-import { PlaybackOptions, SoundSource, isPlaybackStatusSuccess, isSoundSourceValid } from './types';
+import {
+    PlaybackOptions,
+    SoundSource,
+    isPlaybackStatusSuccess,
+    isSoundSourceValid,
+    clampVolume,
+    clampRate,
+} from './types';
+
+interface CachedSound {
+    sound: Audio.Sound;
+    source: SoundSource;
+    loadedAt: number;
+}
 
 class AudioManager {
     private sound: Audio.Sound | null = null;
     private currentId: string | null = null;
+    private cache: Map<string, CachedSound> = new Map();
+    private readonly maxCacheSize = 3;
+    private readonly cacheExpireMs = 5 * 60 * 1000;
 
     constructor() {
         this.configureAudio();
@@ -46,6 +62,66 @@ class AudioManager {
         }
     };
 
+    private cleanExpiredCache() {
+        const now = Date.now();
+        for (const [id, cached] of this.cache) {
+            if (now - cached.loadedAt > this.cacheExpireMs) {
+                cached.sound.unloadAsync().catch(() => {});
+                this.cache.delete(id);
+                if (__DEV__) console.log('[AudioManager] Expired cache removed:', id);
+            }
+        }
+    }
+
+    private enforceCacheLimit() {
+        if (this.cache.size >= this.maxCacheSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                const cached = this.cache.get(firstKey);
+                cached?.sound.unloadAsync().catch(() => {});
+                this.cache.delete(firstKey);
+                if (__DEV__) console.log('[AudioManager] Cache limit enforced, removed:', firstKey);
+            }
+        }
+    }
+
+    async preload(id: string, source: SoundSource, options?: PlaybackOptions) {
+        if (!isSoundSourceValid(source)) {
+            throw new Error('Invalid sound source: source is null or undefined');
+        }
+
+        if (this.cache.has(id)) {
+            if (__DEV__) console.log('[AudioManager] Already cached:', id);
+            return;
+        }
+
+        try {
+            this.cleanExpiredCache();
+            this.enforceCacheLimit();
+
+            const volume = options?.volume !== undefined ? clampVolume(options.volume) : 1.0;
+            const rate = options?.rate !== undefined ? clampRate(options.rate) : 1.0;
+
+            const { sound } = await Audio.Sound.createAsync(
+                source,
+                {
+                    shouldPlay: false,
+                    isLooping: options?.isLooping ?? false,
+                    volume,
+                    rate,
+                },
+                this.onPlaybackStatusUpdate
+            );
+
+            this.cache.set(id, { sound, source, loadedAt: Date.now() });
+            if (__DEV__) console.log('[AudioManager] Preloaded:', id);
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            if (__DEV__) console.error('[AudioManager] Error preloading sound:', error);
+            throw new Error(errorMessage);
+        }
+    }
+
     async play(id: string, source: SoundSource, options?: PlaybackOptions) {
         const store = useSoundStore.getState();
 
@@ -73,26 +149,41 @@ class AudioManager {
         try {
             await this.unload();
 
+            const volume = options?.volume !== undefined ? clampVolume(options.volume) : 1.0;
+            const rate = options?.rate !== undefined ? clampRate(options.rate) : 1.0;
+
+            const cached = this.cache.get(id);
+            if (cached) {
+                this.sound = cached.sound;
+                this.cache.delete(id);
+                if (__DEV__) console.log('[AudioManager] Using cached sound:', id);
+            } else {
+                const { sound } = await Audio.Sound.createAsync(
+                    source,
+                    {
+                        shouldPlay: true,
+                        isLooping: options?.isLooping ?? false,
+                        volume,
+                        rate,
+                        positionMillis: options?.positionMillis ?? 0,
+                    },
+                    this.onPlaybackStatusUpdate
+                );
+                this.sound = sound;
+                if (__DEV__) console.log('[AudioManager] Sound created and playing');
+            }
+
             this.currentId = id;
             store.setCurrent(id, source);
             store.setError(null);
 
-            if (__DEV__) console.log('[AudioManager] Creating sound from source:', source);
-
-            const { sound } = await Audio.Sound.createAsync(
-                source,
-                {
-                    shouldPlay: true,
-                    isLooping: options?.isLooping ?? false,
-                    volume: options?.volume ?? 1.0,
-                    rate: options?.rate ?? 1.0,
-                    positionMillis: options?.positionMillis ?? 0,
-                },
-                this.onPlaybackStatusUpdate
-            );
-
-            this.sound = sound;
-            if (__DEV__) console.log('[AudioManager] Sound created and playing');
+            if (!cached) {
+                await this.sound?.playAsync();
+            } else {
+                await this.sound?.setVolumeAsync(volume);
+                await this.sound?.setRateAsync(rate, false);
+                await this.sound?.playAsync();
+            }
         } catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
             if (__DEV__) console.error('[AudioManager] Error playing sound:', error);
@@ -122,10 +213,34 @@ class AudioManager {
         }
     }
 
+    async seek(positionMillis: number) {
+        if (this.sound) {
+            const status = await this.sound.getStatusAsync();
+            if (status.isLoaded) {
+                await this.sound.setStatusAsync({ positionMillis: Math.max(0, positionMillis) });
+            }
+        }
+    }
+
     async setVolume(volume: number) {
         if (this.sound) {
-            await this.sound.setVolumeAsync(volume);
-            useSoundStore.getState().setVolumeState(volume);
+            const clampedVolume = clampVolume(volume);
+            await this.sound.setVolumeAsync(clampedVolume);
+            useSoundStore.getState().setVolumeState(clampedVolume);
+        }
+    }
+
+    async setRate(rate: number) {
+        if (this.sound) {
+            const clampedRate = clampRate(rate);
+            const status = await this.sound.getStatusAsync();
+            if (status.isLoaded) {
+                try {
+                    await this.sound.setRateAsync(clampedRate, false);
+                } catch (error) {
+                    if (__DEV__) console.warn('[AudioManager] Could not set rate:', error);
+                }
+            }
         }
     }
 
@@ -134,7 +249,7 @@ class AudioManager {
             try {
                 await this.sound.unloadAsync();
             } catch (e) {
-                // Ignore unload errors
+                if (__DEV__) console.warn('[AudioManager] Error unloading sound:', e);
             }
             this.sound = null;
         }
@@ -142,9 +257,21 @@ class AudioManager {
         useSoundStore.getState().reset();
     }
 
+    clearCache() {
+        for (const cached of this.cache.values()) {
+            cached.sound.unloadAsync().catch(() => {});
+        }
+        this.cache.clear();
+        if (__DEV__) console.log('[AudioManager] Cache cleared');
+    }
+
     getCurrentId() {
         return this.currentId;
     }
+
+    isCached(id: string): boolean {
+        return this.cache.has(id);
+    }
 }
 
 export const audioManager = new AudioManager();

package/src/index.ts

@@ -1,8 +1,9 @@
 /**
  * @umituz/react-native-sound
- * Universal sound playback library
+ * Universal sound playback library with caching
  */
 
 export * from './types';
 export * from './useSound';
 export { audioManager } from './AudioManager';
+export { useSoundStore } from './store';

package/src/types.ts

@@ -43,3 +43,19 @@ export function isPlaybackStatusSuccess(status: AVPlaybackStatus): status is Pla
 export function isSoundSourceValid(source: SoundSource): source is number | { uri: string; headers?: Record<string, string> } {
     return source !== null && source !== undefined;
 }
+
+export function validateVolume(volume: number): boolean {
+    return typeof volume === 'number' && volume >= 0 && volume <= 1;
+}
+
+export function validateRate(rate: number): boolean {
+    return typeof rate === 'number' && rate >= 0.5 && rate <= 2.0;
+}
+
+export function clampVolume(volume: number): number {
+    return Math.max(0, Math.min(1, volume));
+}
+
+export function clampRate(rate: number): number {
+    return Math.max(0.5, Math.min(2.0, rate));
+}

package/src/useSound.ts

@@ -1,4 +1,4 @@
-import { useCallback } from 'react';
+import { useCallback, useEffect } from 'react';
 import { useSoundStore } from './store';
 import { audioManager } from './AudioManager';
 import { PlaybackOptions, SoundSource } from './types';
@@ -12,9 +12,14 @@ export const useSound = () => {
     const error = useSoundStore((state) => state.error);
     const volume = useSoundStore((state) => state.volume);
 
+    useEffect(() => {
+        return () => {
+            if (__DEV__) console.log('[useSound] Cleanup on unmount');
+        };
+    }, []);
+
     const play = useCallback(
         async (id: string, source: SoundSource, options?: PlaybackOptions) => {
-            // Toggle logic: If same ID, toggle pause/resume
             if (currentId === id) {
                 if (isPlaying) {
                     await audioManager.pause();
@@ -32,24 +37,54 @@ export const useSound = () => {
         await audioManager.pause();
     }, []);
 
+    const resume = useCallback(async () => {
+        await audioManager.resume();
+    }, []);
+
     const stop = useCallback(async () => {
         await audioManager.stop();
     }, []);
 
+    const seek = useCallback(async (positionMillis: number) => {
+        await audioManager.seek(positionMillis);
+    }, []);
+
     const setVolume = useCallback(async (vol: number) => {
         await audioManager.setVolume(vol);
     }, []);
 
+    const setRate = useCallback(async (rate: number) => {
+        await audioManager.setRate(rate);
+    }, []);
+
+    const preload = useCallback(async (id: string, source: SoundSource, options?: PlaybackOptions) => {
+        await audioManager.preload(id, source, options);
+    }, []);
+
     const unload = useCallback(async () => {
         await audioManager.unload();
     }, []);
 
+    const clearCache = useCallback(() => {
+        audioManager.clearCache();
+    }, []);
+
+    const isCached = useCallback((id: string): boolean => {
+        return audioManager.isCached(id);
+    }, []);
+
     return {
         play,
         pause,
+        resume,
         stop,
-        unload,
+        seek,
         setVolume,
+        setRate,
+        preload,
+        unload,
+        clearCache,
+        isCached,
         isPlaying,
         isBuffering,
         position,