@umituz/react-native-sound 1.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Ümit UZ
+
+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,282 @@
+# @umituz/react-native-sound
+
+Universal sound playback and caching library for React Native apps. Supports local assets, remote URLs, and automatic caching with a simple, clean API.
+
+## Features
+
+- 🎵 **Universal Sound Playback** - Play sounds from local assets or remote URLs
+- 💾 **Automatic Caching** - Cache remote sounds locally for offline playback
+- 🔄 **Streaming Support** - Stream sounds while downloading in background
+- 🎛️ **Playback Controls** - Play, pause, stop, volume, and rate control
+- 🎯 **Singleton Pattern** - Only one sound plays at a time across the app
+- 🔌 **Storage Abstraction** - Works with any storage provider (Firebase, AWS S3, etc.)
+- 📦 **Zero Dependencies** - Only requires `expo-av` and `expo-file-system`
+
+## Installation
+
+```bash
+npm install @umituz/react-native-sound
+```
+
+## Peer Dependencies
+
+```bash
+npm install expo-av expo-file-system
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { useSoundPlayback, Sound } from '@umituz/react-native-sound';
+
+function MyComponent() {
+  const { playSound, stopSound, isPlaying } = useSoundPlayback();
+
+  const sound: Sound = {
+    id: 'ocean-waves',
+    name: 'Ocean Waves',
+    filename: 'ocean-waves.mp3',
+    storageUrl: 'sounds/ocean-waves.mp3', // Or full URL
+  };
+
+  return (
+    <Button
+      onPress={() => {
+        if (isPlaying(sound.id)) {
+          stopSound();
+        } else {
+          playSound(sound);
+        }
+      }}
+    >
+      {isPlaying(sound.id) ? 'Stop' : 'Play'}
+    </Button>
+  );
+}
+```
+
+### With Storage Service (Firebase, AWS S3, etc.)
+
+```typescript
+import { useSoundPlayback, IStorageService } from '@umituz/react-native-sound';
+import { getStorage } from 'firebase/storage';
+import { ref, getDownloadURL } from 'firebase/storage';
+
+// Implement storage service
+class FirebaseStorageService implements IStorageService {
+  async getDownloadUrl(storagePath: string): Promise<string> {
+    const storage = getStorage();
+    const storageRef = ref(storage, storagePath);
+    return getDownloadURL(storageRef);
+  }
+}
+
+function MyComponent() {
+  const storageService = new FirebaseStorageService();
+  const { playSound, stopSound } = useSoundPlayback({
+    storageService,
+  });
+
+  // ... rest of component
+}
+```
+
+### Local Assets
+
+```typescript
+import { useSoundPlayback, Sound } from '@umituz/react-native-sound';
+import oceanWavesSound from './assets/sounds/ocean-waves.mp3';
+
+function MyComponent() {
+  const { playSound } = useSoundPlayback();
+
+  const sound: Sound = {
+    id: 'ocean-waves',
+    name: 'Ocean Waves',
+    localAsset: oceanWavesSound, // Bundled asset
+  };
+
+  return <Button onPress={() => playSound(sound)}>Play</Button>;
+}
+```
+
+### Cache Management
+
+```typescript
+import { useSoundCache } from '@umituz/react-native-sound';
+
+function CacheSettings() {
+  const {
+    cacheSize,
+    clearCache,
+    isCached,
+    deleteCachedSound,
+  } = useSoundCache();
+
+  return (
+    <View>
+      <Text>Cache Size: {cacheSize.toFixed(2)} MB</Text>
+      <Button onPress={clearCache}>Clear Cache</Button>
+    </View>
+  );
+}
+```
+
+## API Reference
+
+### `useSoundPlayback(options?)`
+
+Main hook for sound playback.
+
+#### Options
+
+- `storageService?: IStorageService` - Storage service for remote URLs
+- `autoConfigureAudioSession?: boolean` - Auto-configure audio session (default: true)
+- `audioSessionOptions?: {...}` - Audio session configuration
+
+#### Returns
+
+- `playSound(sound, options?, onProgress?)` - Play a sound
+- `stopSound()` - Stop current sound
+- `pauseSound()` - Pause current sound
+- `resumeSound()` - Resume paused sound
+- `isPlaying(soundId)` - Check if sound is playing
+- `playingSoundId` - Currently playing sound ID
+- `downloadingSoundId` - Currently downloading sound ID
+- `downloadProgress` - Download progress (0-100)
+- `isStreaming` - Whether sound is streaming
+
+### `useSoundCache()`
+
+Hook for cache management.
+
+#### Returns
+
+- `isCached(sound)` - Check if sound is cached
+- `getCachedUri(sound)` - Get cached file URI
+- `clearCache()` - Clear all cache
+- `getCacheSize()` - Get cache size in MB
+- `deleteCachedSound(sound)` - Delete specific cached sound
+- `cacheSize` - Current cache size in MB
+- `isLoadingCacheSize` - Whether cache size is loading
+- `refreshCacheSize()` - Refresh cache size
+
+### `Sound` Entity
+
+```typescript
+interface Sound {
+  id: string;                    // Required: Unique identifier
+  name: string;                  // Required: Display name
+  description?: string;          // Optional: Description
+  filename?: string;             // Optional: Filename for caching
+  storageUrl?: string;           // Optional: Remote storage path or URL
+  localAsset?: number;           // Optional: Local asset reference
+  durationSeconds?: number;      // Optional: Duration in seconds
+  isPremium?: boolean;           // Optional: Premium flag
+  category?: string;             // Optional: Category
+  tags?: string[];               // Optional: Tags
+  metadata?: Record<string, unknown>; // Optional: App-specific metadata
+}
+```
+
+### `IStorageService` Interface
+
+```typescript
+interface IStorageService {
+  getDownloadUrl(storagePath: string): Promise<string>;
+}
+```
+
+Implement this interface for your storage provider (Firebase Storage, AWS S3, etc.).
+
+## Architecture
+
+This package follows Domain-Driven Design (DDD) principles:
+
+- **Domain Layer**: Entities and interfaces
+- **Infrastructure Layer**: Services and storage implementations
+- **Presentation Layer**: React hooks
+
+### SOLID Principles
+
+- **Single Responsibility**: Each service has one clear purpose
+- **Open/Closed**: Extensible through interfaces
+- **Liskov Substitution**: Storage services are interchangeable
+- **Interface Segregation**: Small, focused interfaces
+- **Dependency Inversion**: Depends on abstractions, not concretions
+
+## Examples
+
+### Multiple Sounds
+
+```typescript
+const sounds: Sound[] = [
+  {
+    id: 'ocean',
+    name: 'Ocean Waves',
+    filename: 'ocean.mp3',
+    storageUrl: 'sounds/ocean.mp3',
+  },
+  {
+    id: 'rain',
+    name: 'Rain',
+    filename: 'rain.mp3',
+    storageUrl: 'sounds/rain.mp3',
+  },
+];
+
+function SoundList() {
+  const { playSound, isPlaying } = useSoundPlayback();
+
+  return (
+    <View>
+      {sounds.map(sound => (
+        <Button
+          key={sound.id}
+          onPress={() => playSound(sound)}
+          disabled={isPlaying(sound.id)}
+        >
+          {sound.name}
+        </Button>
+      ))}
+    </View>
+  );
+}
+```
+
+### Download Progress
+
+```typescript
+function SoundPlayer() {
+  const { playSound, downloadProgress, downloadingSoundId } = useSoundPlayback();
+
+  const handlePlay = (sound: Sound) => {
+    playSound(
+      sound,
+      { isLooping: true },
+      (progress) => {
+        console.log(`Download: ${Math.round(progress * 100)}%`);
+      }
+    );
+  };
+
+  return (
+    <View>
+      {downloadingSoundId && (
+        <ProgressBar value={downloadProgress} />
+      )}
+    </View>
+  );
+}
+```
+
+## License
+
+MIT
+
+## Author
+
+Ümit UZ <umit@umituz.com>
+

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@umituz/react-native-sound",
+  "version": "1.1.0",
+  "description": "Universal sound playback and caching library for React Native apps",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "react-native",
+    "sound",
+    "audio",
+    "playback",
+    "caching",
+    "expo-av"
+  ],
+  "author": "Ümit UZ <umit@umituz.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/react-native-sound"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0",
+    "expo-av": ">=16.0.0"
+  },
+  "dependencies": {
+    "expo-file-system": "~18.0.0",
+    "zustand": "^5.0.2"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.45",
+    "@types/react-native": "^0.73.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.3.3",
+    "expo-av": "^16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/domain/entities/Sound.entity.ts

@@ -0,0 +1,78 @@
+/**
+ * Sound Entity
+ *
+ * Generic sound entity that can represent any audio file.
+ * SOLID: Single Responsibility - Only defines sound data structure
+ * KISS: Simple interface with essential properties
+ */
+
+export interface Sound {
+  /** Unique identifier for the sound */
+  id: string;
+
+  /** Display name of the sound */
+  name: string;
+
+  /** Optional description */
+  description?: string;
+
+  /** Filename for local caching (e.g., "ocean-waves.mp3") */
+  filename?: string;
+
+  /** Remote storage path or URL (e.g., "sounds/ocean-waves.mp3" or "https://...") */
+  storageUrl?: string;
+
+  /** Local asset reference (for bundled sounds) */
+  localAsset?: number;
+
+  /** Duration in seconds (optional) */
+  durationSeconds?: number;
+
+  /** Whether sound is premium/paid */
+  isPremium?: boolean;
+
+  /** Category or tags for organization */
+  category?: string;
+  tags?: string[];
+
+  /** Metadata for app-specific use */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Audio Source Type
+ * Can be a local asset (number) or remote URI (string)
+ */
+export type AudioSource = number | { uri: string };
+
+/**
+ * Sound Playback Options
+ */
+export interface SoundPlaybackOptions {
+  /** Whether to loop the sound */
+  isLooping?: boolean;
+
+  /** Initial volume (0.0 to 1.0) */
+  volume?: number;
+
+  /** Whether to play immediately */
+  shouldPlay?: boolean;
+
+  /** Playback rate (1.0 = normal speed) */
+  rate?: number;
+}
+
+/**
+ * Sound Cache Info
+ */
+export interface SoundCacheInfo {
+  /** Local file URI if cached */
+  cachedUri: string | null;
+
+  /** Whether sound is currently cached */
+  isCached: boolean;
+
+  /** Cache size in bytes */
+  cacheSize?: number;
+}
+

package/src/domain/repositories/IStorageService.ts

@@ -0,0 +1,19 @@
+/**
+ * Storage Service Interface
+ *
+ * Abstraction for remote storage providers (Firebase Storage, AWS S3, etc.)
+ * SOLID: Interface Segregation - Only storage-related methods
+ * DRY: Single interface for all storage providers
+ *
+ * Apps can implement this interface for their specific storage provider
+ */
+
+export interface IStorageService {
+  /**
+   * Get download URL for a storage path
+   * @param storagePath - Path in storage (e.g., "sounds/ocean-waves.mp3")
+   * @returns Promise resolving to download URL
+   */
+  getDownloadUrl(storagePath: string): Promise<string>;
+}
+

package/src/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @umituz/react-native-sound - Public API
+ *
+ * Universal sound playback and caching library for React Native apps.
+ * Supports local assets, remote URLs, and automatic caching.
+ *
+ * Usage:
+ *   import { useSoundPlayback, useSoundCache, Sound } from '@umituz/react-native-sound';
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Entities
+// =============================================================================
+
+export type {
+  Sound,
+  AudioSource,
+  SoundPlaybackOptions,
+  SoundCacheInfo,
+} from './domain/entities/Sound.entity';
+
+// =============================================================================
+// DOMAIN LAYER - Repository Interface
+// =============================================================================
+
+export type { IStorageService } from './domain/repositories/IStorageService';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Services
+// =============================================================================
+
+export {
+  SoundCacheService,
+  soundCacheService,
+} from './infrastructure/services/SoundCacheService';
+
+export {
+  AudioPlaybackService,
+  audioPlaybackService,
+} from './infrastructure/services/AudioPlaybackService';
+
+export {
+  SoundSourceResolver,
+} from './infrastructure/services/SoundSourceResolver';
+
+export type { ResolvedAudioSource } from './infrastructure/services/SoundSourceResolver';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Storage
+// =============================================================================
+
+export {
+  useSoundPlaybackStore,
+} from './infrastructure/storage/SoundPlaybackStore';
+
+export type { SoundPlaybackState } from './infrastructure/storage/SoundPlaybackStore';
+
+// =============================================================================
+// PRESENTATION LAYER - Hooks
+// =============================================================================
+
+export {
+  useSoundPlayback,
+} from './presentation/hooks/useSoundPlayback';
+
+export type { UseSoundPlaybackOptions } from './presentation/hooks/useSoundPlayback';
+
+export {
+  useSoundCache,
+} from './presentation/hooks/useSoundCache';
+
+export type { UseSoundCacheResult } from './presentation/hooks/useSoundCache';
+

package/src/infrastructure/services/AudioPlaybackService.ts

@@ -0,0 +1,105 @@
+/**
+ * Audio Playback Service
+ *
+ * Handles audio playback using expo-av.
+ * SOLID: Single Responsibility - Only handles audio playback
+ * KISS: Simple wrapper around expo-av
+ */
+
+import { Audio } from 'expo-av';
+import type { AudioSource, SoundPlaybackOptions } from '../../domain/entities/Sound.entity';
+
+export interface AudioPlaybackResult {
+  sound: Audio.Sound;
+  isStreaming: boolean;
+}
+
+export class AudioPlaybackService {
+  /**
+   * Configure audio session for playback
+   * KISS: Simple configuration wrapper
+   *
+   * @param options - Audio session options
+   */
+  async configureAudioSession(options?: {
+    playsInSilentModeIOS?: boolean;
+    allowsRecordingIOS?: boolean;
+    staysActiveInBackground?: boolean;
+  }): Promise<void> {
+    await Audio.setAudioModeAsync({
+      playsInSilentModeIOS: options?.playsInSilentModeIOS ?? true,
+      allowsRecordingIOS: options?.allowsRecordingIOS ?? false,
+      interruptionModeIOS: 2, // DuckOthers
+      interruptionModeAndroid: 1, // DuckOthers
+      shouldDuckAndroid: true,
+      playThroughEarpieceAndroid: false,
+      staysActiveInBackground: options?.staysActiveInBackground ?? false,
+    });
+  }
+
+  /**
+   * Create and load audio sound
+   * @param source - Audio source (local asset or URI)
+   * @param options - Playback options
+   * @returns Audio sound instance
+   */
+  async loadSound(
+    source: AudioSource,
+    options: SoundPlaybackOptions = {}
+  ): Promise<Audio.Sound> {
+    const { sound } = await Audio.Sound.createAsync(source, {
+      shouldPlay: options.shouldPlay ?? false,
+      isLooping: options.isLooping ?? false,
+      volume: options.volume ?? 1.0,
+      rate: options.rate ?? 1.0,
+    });
+
+    return sound;
+  }
+
+  /**
+   * Play audio sound
+   * @param sound - Audio sound instance
+   */
+  async playSound(sound: Audio.Sound): Promise<void> {
+    await sound.playAsync();
+  }
+
+  /**
+   * Pause audio sound
+   * @param sound - Audio sound instance
+   */
+  async pauseSound(sound: Audio.Sound): Promise<void> {
+    await sound.pauseAsync();
+  }
+
+  /**
+   * Stop and unload audio sound
+   * @param sound - Audio sound instance
+   */
+  async stopSound(sound: Audio.Sound): Promise<void> {
+    await sound.unloadAsync();
+  }
+
+  /**
+   * Set volume
+   * @param sound - Audio sound instance
+   * @param volume - Volume (0.0 to 1.0)
+   */
+  async setVolume(sound: Audio.Sound, volume: number): Promise<void> {
+    await sound.setVolumeAsync(volume);
+  }
+
+  /**
+   * Set playback rate
+   * @param sound - Audio sound instance
+   * @param rate - Playback rate (1.0 = normal speed)
+   */
+  async setRate(sound: Audio.Sound, rate: number): Promise<void> {
+    await sound.setRateAsync(rate, true);
+  }
+}
+
+// Export singleton instance
+export const audioPlaybackService = new AudioPlaybackService();
+

package/src/infrastructure/services/SoundCacheService.ts

@@ -0,0 +1,146 @@
+/**
+ * Sound Cache Service
+ *
+ * Handles local file caching for remote sounds.
+ * SOLID: Single Responsibility - Only handles file caching
+ * DRY: Centralized caching logic
+ * KISS: Simple file operations
+ */
+
+import * as FileSystem from 'expo-file-system/legacy';
+
+const CACHE_DIR = `${FileSystem.cacheDirectory}sounds/`;
+
+export class SoundCacheService {
+  /**
+   * Ensure cache directory exists
+   * KISS: Simple directory creation
+   */
+  async ensureCacheDir(): Promise<void> {
+    const dirInfo = await FileSystem.getInfoAsync(CACHE_DIR);
+    if (!dirInfo.exists) {
+      await FileSystem.makeDirectoryAsync(CACHE_DIR, { intermediates: true });
+    }
+  }
+
+  /**
+   * Get cached sound file URI
+   * @param filename - Sound filename (e.g., "ocean-waves.mp3")
+   * @returns Local file URI if cached, null otherwise
+   */
+  async getCachedSound(filename: string): Promise<string | null> {
+    await this.ensureCacheDir();
+
+    const localUri = `${CACHE_DIR}${filename}`;
+    const fileInfo = await FileSystem.getInfoAsync(localUri);
+
+    if (fileInfo.exists) {
+      return localUri;
+    }
+
+    return null;
+  }
+
+  /**
+   * Download and cache sound from remote URL
+   * @param remoteUrl - Remote download URL
+   * @param filename - Local filename for caching
+   * @param onProgress - Optional progress callback (0-1)
+   * @returns Local file URI of cached sound
+   */
+  async downloadAndCache(
+    remoteUrl: string,
+    filename: string,
+    onProgress?: (progress: number) => void
+  ): Promise<string> {
+    await this.ensureCacheDir();
+
+    // Check cache first (DRY: Reuse existing function)
+    const cached = await this.getCachedSound(filename);
+    if (cached) {
+      return cached;
+    }
+
+    const localUri = `${CACHE_DIR}${filename}`;
+
+    // Download with progress tracking
+    const downloadResumable = FileSystem.createDownloadResumable(
+      remoteUrl,
+      localUri,
+      {},
+      downloadProgress => {
+        const progress =
+          downloadProgress.totalBytesWritten /
+          downloadProgress.totalBytesExpectedToWrite;
+
+        onProgress?.(progress);
+      }
+    );
+
+    const result = await downloadResumable.downloadAsync();
+
+    if (!result) {
+      throw new Error('Download failed');
+    }
+
+    return result.uri;
+  }
+
+  /**
+   * Clear all cached sounds
+   * Useful for cleanup or cache management
+   */
+  async clearCache(): Promise<void> {
+    try {
+      await FileSystem.deleteAsync(CACHE_DIR, { idempotent: true });
+      await this.ensureCacheDir();
+    } catch {
+      // Silently fail - cache clearing is non-critical
+    }
+  }
+
+  /**
+   * Get cache size in MB
+   * @returns Cache size in megabytes
+   */
+  async getCacheSize(): Promise<number> {
+    try {
+      const dirInfo = await FileSystem.getInfoAsync(CACHE_DIR);
+      if (!dirInfo.exists) {
+        return 0;
+      }
+
+      const files = await FileSystem.readDirectoryAsync(CACHE_DIR);
+      let totalSize = 0;
+
+      for (const file of files) {
+        const fileInfo = await FileSystem.getInfoAsync(`${CACHE_DIR}${file}`);
+        if (fileInfo.exists && 'size' in fileInfo) {
+          totalSize += fileInfo.size || 0;
+        }
+      }
+
+      // Convert to MB
+      return totalSize / (1024 * 1024);
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Delete specific cached sound
+   * @param filename - Filename to delete
+   */
+  async deleteCachedSound(filename: string): Promise<void> {
+    try {
+      const localUri = `${CACHE_DIR}${filename}`;
+      await FileSystem.deleteAsync(localUri, { idempotent: true });
+    } catch {
+      // Silently fail
+    }
+  }
+}
+
+// Export singleton instance
+export const soundCacheService = new SoundCacheService();
+

package/src/infrastructure/services/SoundSourceResolver.ts

@@ -0,0 +1,97 @@
+/**
+ * Sound Source Resolver
+ *
+ * Resolves sound source from Sound entity to AudioSource.
+ * Handles local assets, cached files, and remote URLs.
+ * SOLID: Single Responsibility - Only resolves audio sources
+ * DRY: Centralized source resolution logic
+ */
+
+import type { Sound, AudioSource } from '../../domain/entities/Sound.entity';
+import type { IStorageService } from '../../domain/repositories/IStorageService';
+import { soundCacheService } from './SoundCacheService';
+
+export interface ResolvedAudioSource {
+  source: AudioSource;
+  isStreaming: boolean;
+}
+
+export class SoundSourceResolver {
+  constructor(private storageService?: IStorageService) {}
+
+  /**
+   * Resolve sound to audio source
+   * Handles: local assets, cached files, remote URLs
+   *
+   * @param sound - Sound entity
+   * @param onDownloadProgress - Optional download progress callback
+   * @returns Resolved audio source or null if cannot resolve
+   */
+  async resolve(
+    sound: Sound,
+    onDownloadProgress?: (progress: number) => void
+  ): Promise<ResolvedAudioSource | null> {
+    // 1. Local asset (bundled in app)
+    if (sound.localAsset !== undefined) {
+      return {
+        source: sound.localAsset,
+        isStreaming: false,
+      };
+    }
+
+    // 2. Remote storage URL
+    if (sound.storageUrl && sound.filename) {
+      // Check cache first
+      const cachedUri = await soundCacheService.getCachedSound(sound.filename);
+      if (cachedUri) {
+        return {
+          source: { uri: cachedUri },
+          isStreaming: false,
+        };
+      }
+
+      // Get download URL from storage service
+      if (this.storageService) {
+        try {
+          const downloadUrl = await this.storageService.getDownloadUrl(
+            sound.storageUrl
+          );
+
+          // Start background download
+          soundCacheService
+            .downloadAndCache(downloadUrl, sound.filename, onDownloadProgress)
+            .catch(() => {
+              // Silent fail - background download
+            });
+
+          // Return streaming URL immediately
+          return {
+            source: { uri: downloadUrl },
+            isStreaming: true,
+          };
+        } catch {
+          // Storage service error - return null
+          return null;
+        }
+      }
+
+      // No storage service - assume storageUrl is direct URL
+      return {
+        source: { uri: sound.storageUrl },
+        isStreaming: true,
+      };
+    }
+
+    // 3. Direct URI (if storageUrl is already a full URL)
+    if (sound.storageUrl && sound.storageUrl.startsWith('http')) {
+      return {
+        source: { uri: sound.storageUrl },
+        isStreaming: true,
+      };
+    }
+
+    // Cannot resolve
+    return null;
+  }
+}
+

package/src/infrastructure/storage/SoundPlaybackStore.ts

@@ -0,0 +1,241 @@
+/**
+ * Sound Playback Store
+ *
+ * Global state management for sound playback.
+ * Ensures only one sound plays at a time (singleton pattern).
+ * SOLID: Single Responsibility - Only manages playback state
+ * KISS: Simple Zustand store
+ */
+
+import { create } from 'zustand';
+import { Audio } from 'expo-av';
+import type {
+  Sound,
+  SoundPlaybackOptions,
+  AudioSource,
+} from '../../domain/entities/Sound.entity';
+
+export interface SoundPlaybackState {
+  /** Currently playing sound ID */
+  playingSoundId: string | null;
+
+  /** Currently downloading sound ID */
+  downloadingSoundId: string | null;
+
+  /** Download progress (0-100) */
+  downloadProgress: number;
+
+  /** Whether sound is streaming */
+  isStreaming: boolean;
+
+  /** Internal Audio.Sound instance */
+  _sound: Audio.Sound | null;
+
+  /** Play a sound */
+  playSound: (
+    sound: Sound,
+    options?: SoundPlaybackOptions,
+    onDownloadProgress?: (progress: number) => void
+  ) => Promise<void>;
+
+  /** Stop current sound */
+  stopSound: () => Promise<void>;
+
+  /** Pause current sound */
+  pauseSound: () => Promise<void>;
+
+  /** Resume paused sound */
+  resumeSound: () => Promise<void>;
+
+  /** Check if specific sound is playing */
+  isPlaying: (soundId: string) => boolean;
+
+  /** Cleanup all resources */
+  cleanup: () => Promise<void>;
+}
+
+export const useSoundPlaybackStore = create<SoundPlaybackState>((set, get) => ({
+  // Initial state
+  playingSoundId: null,
+  downloadingSoundId: null,
+  downloadProgress: 0,
+  isStreaming: false,
+  _sound: null,
+
+  // Play sound
+  playSound: async (
+    sound: Sound,
+    options: SoundPlaybackOptions = {},
+    onDownloadProgress?: (progress: number) => void
+  ) => {
+    const state = get();
+
+    // Toggle: If same sound is playing, stop it
+    if (state.playingSoundId === sound.id && state._sound) {
+      await get().stopSound();
+      return;
+    }
+
+    try {
+      // Stop any existing sound
+      if (state._sound) {
+        await state._sound.unloadAsync();
+        set({ _sound: null });
+      }
+
+      // Optimistic update
+      set({ playingSoundId: sound.id });
+
+      // Check if source is pre-resolved (from hook)
+      let resolvedSource: { source: AudioSource; isStreaming: boolean } | null =
+        null;
+
+      if (
+        sound.metadata &&
+        '_resolvedSource' in sound.metadata &&
+        '_isStreaming' in sound.metadata
+      ) {
+        // Use pre-resolved source from hook
+        resolvedSource = {
+          source: sound.metadata._resolvedSource as AudioSource,
+          isStreaming: sound.metadata._isStreaming as boolean,
+        };
+      } else {
+        // Import services dynamically to avoid circular dependencies
+        const { SoundSourceResolver } = await import(
+          '../services/SoundSourceResolver'
+        );
+
+        // Create resolver (no storage service in store - app should use hook)
+        const resolver = new SoundSourceResolver();
+
+        // Resolve audio source
+        resolvedSource = await resolver.resolve(sound, progress => {
+          set({
+            downloadingSoundId: sound.id,
+            downloadProgress: Math.round(progress * 100),
+          });
+          onDownloadProgress?.(progress);
+        });
+      }
+
+      if (!resolvedSource) {
+        throw new Error(`Cannot resolve audio source for sound: ${sound.id}`);
+      }
+
+      set({
+        isStreaming: resolvedSource.isStreaming,
+        downloadingSoundId: null,
+        downloadProgress: 0,
+      });
+
+      // Import audio service
+      const { audioPlaybackService } = await import(
+        '../services/AudioPlaybackService'
+      );
+
+      // Load and play sound
+      const audioSound = await audioPlaybackService.loadSound(
+        resolvedSource.source,
+        {
+          ...options,
+          shouldPlay: true,
+        }
+      );
+
+      set({ _sound: audioSound });
+    } catch (error) {
+      // Rollback on error
+      set({
+        playingSoundId: null,
+        _sound: null,
+        downloadingSoundId: null,
+        downloadProgress: 0,
+        isStreaming: false,
+      });
+      throw error;
+    }
+  },
+
+  // Stop sound
+  stopSound: async () => {
+    const state = get();
+
+    if (!state._sound && !state.playingSoundId) {
+      return;
+    }
+
+    set({
+      playingSoundId: null,
+      downloadingSoundId: null,
+      downloadProgress: 0,
+      isStreaming: false,
+    });
+
+    if (state._sound) {
+      try {
+        await state._sound.unloadAsync();
+      } catch {
+        // Silently fail
+      }
+      set({ _sound: null });
+    }
+  },
+
+  // Pause sound
+  pauseSound: async () => {
+    const state = get();
+
+    if (!state._sound) {
+      return;
+    }
+
+    try {
+      await state._sound.pauseAsync();
+    } catch {
+      // Silently fail
+    }
+  },
+
+  // Resume sound
+  resumeSound: async () => {
+    const state = get();
+
+    if (!state._sound) {
+      return;
+    }
+
+    try {
+      await state._sound.playAsync();
+    } catch {
+      // Silently fail
+    }
+  },
+
+  // Check if playing
+  isPlaying: (soundId: string) => {
+    return get().playingSoundId === soundId;
+  },
+
+  // Cleanup
+  cleanup: async () => {
+    const state = get();
+
+    try {
+      if (state._sound) {
+        await state._sound.unloadAsync();
+      }
+
+      set({
+        playingSoundId: null,
+        downloadingSoundId: null,
+        downloadProgress: 0,
+        isStreaming: false,
+        _sound: null,
+      });
+    } catch {
+      // Silently fail
+    }
+  },
+}));
+

package/src/presentation/hooks/useSoundCache.ts

@@ -0,0 +1,109 @@
+/**
+ * useSoundCache Hook
+ *
+ * React hook for sound cache management.
+ * Provides cache operations and statistics.
+ * SOLID: Single Responsibility - Only handles cache operations
+ * KISS: Simple hook wrapper around cache service
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { soundCacheService } from '../../infrastructure/services/SoundCacheService';
+import type { Sound } from '../../domain/entities/Sound.entity';
+
+export interface UseSoundCacheResult {
+  /** Check if sound is cached */
+  isCached: (sound: Sound) => Promise<boolean>;
+
+  /** Get cached sound URI */
+  getCachedUri: (sound: Sound) => Promise<string | null>;
+
+  /** Clear all cache */
+  clearCache: () => Promise<void>;
+
+  /** Get cache size in MB */
+  getCacheSize: () => Promise<number>;
+
+  /** Delete specific cached sound */
+  deleteCachedSound: (sound: Sound) => Promise<void>;
+
+  /** Current cache size in MB */
+  cacheSize: number;
+
+  /** Whether cache size is loading */
+  isLoadingCacheSize: boolean;
+
+  /** Refresh cache size */
+  refreshCacheSize: () => Promise<void>;
+}
+
+export function useSoundCache(): UseSoundCacheResult {
+  const [cacheSize, setCacheSize] = useState<number>(0);
+  const [isLoadingCacheSize, setIsLoadingCacheSize] = useState(false);
+
+  // Load cache size on mount
+  useEffect(() => {
+    refreshCacheSize();
+  }, []);
+
+  const refreshCacheSize = useCallback(async () => {
+    setIsLoadingCacheSize(true);
+    try {
+      const size = await soundCacheService.getCacheSize();
+      setCacheSize(size);
+    } catch {
+      // Silently fail
+    } finally {
+      setIsLoadingCacheSize(false);
+    }
+  }, []);
+
+  const isCached = useCallback(
+    async (sound: Sound): Promise<boolean> => {
+      if (!sound.filename) {
+        return false;
+      }
+      const cachedUri = await soundCacheService.getCachedSound(sound.filename);
+      return cachedUri !== null;
+    },
+    []
+  );
+
+  const getCachedUri = useCallback(
+    async (sound: Sound): Promise<string | null> => {
+      if (!sound.filename) {
+        return null;
+      }
+      return soundCacheService.getCachedSound(sound.filename);
+    },
+    []
+  );
+
+  const clearCache = useCallback(async () => {
+    await soundCacheService.clearCache();
+    await refreshCacheSize();
+  }, [refreshCacheSize]);
+
+  const deleteCachedSound = useCallback(
+    async (sound: Sound) => {
+      if (!sound.filename) {
+        return;
+      }
+      await soundCacheService.deleteCachedSound(sound.filename);
+      await refreshCacheSize();
+    },
+    [refreshCacheSize]
+  );
+
+  return {
+    isCached,
+    getCachedUri,
+    clearCache,
+    getCacheSize: refreshCacheSize,
+    deleteCachedSound,
+    cacheSize,
+    isLoadingCacheSize,
+    refreshCacheSize,
+  };
+}
+

package/src/presentation/hooks/useSoundPlayback.ts

@@ -0,0 +1,121 @@
+/**
+ * useSoundPlayback Hook
+ *
+ * React hook for sound playback.
+ * Provides easy access to sound playback functionality.
+ * SOLID: Single Responsibility - Only provides playback interface
+ * KISS: Simple hook wrapper around store
+ */
+
+import { useEffect } from 'react';
+import { useSoundPlaybackStore } from '../../infrastructure/storage/SoundPlaybackStore';
+import { audioPlaybackService } from '../../infrastructure/services/AudioPlaybackService';
+import type { Sound, SoundPlaybackOptions } from '../../domain/entities/Sound.entity';
+import type { IStorageService } from '../../domain/repositories/IStorageService';
+import { SoundSourceResolver } from '../../infrastructure/services/SoundSourceResolver';
+
+export interface UseSoundPlaybackOptions {
+  /** Storage service for remote sound URLs (optional) */
+  storageService?: IStorageService;
+
+  /** Auto-configure audio session on mount */
+  autoConfigureAudioSession?: boolean;
+
+  /** Audio session configuration options */
+  audioSessionOptions?: {
+    playsInSilentModeIOS?: boolean;
+    allowsRecordingIOS?: boolean;
+    staysActiveInBackground?: boolean;
+  };
+}
+
+export function useSoundPlayback(options: UseSoundPlaybackOptions = {}) {
+  const store = useSoundPlaybackStore();
+
+  // Auto-configure audio session
+  useEffect(() => {
+    if (options.autoConfigureAudioSession !== false) {
+      audioPlaybackService.configureAudioSession(
+        options.audioSessionOptions
+      );
+    }
+  }, [options.autoConfigureAudioSession, options.audioSessionOptions]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      store.cleanup();
+    };
+  }, [store]);
+
+  /**
+   * Play a sound
+   */
+  const playSound = async (
+    sound: Sound,
+    playbackOptions?: SoundPlaybackOptions,
+    onDownloadProgress?: (progress: number) => void
+  ) => {
+    // Create resolver with storage service
+    const resolver = new SoundSourceResolver(options.storageService);
+
+    // Progress callback wrapper
+    const progressCallback = onDownloadProgress
+      ? (progress: number) => {
+          useSoundPlaybackStore.setState({
+            downloadingSoundId: sound.id,
+            downloadProgress: Math.round(progress * 100),
+          });
+          onDownloadProgress(progress);
+        }
+      : undefined;
+
+    // Resolve source
+    const resolved = await resolver.resolve(sound, progressCallback);
+    if (!resolved) {
+      throw new Error(`Cannot resolve audio source for sound: ${sound.id}`);
+    }
+
+    // Pass resolved source to store via metadata
+    const soundWithSource: Sound = {
+      ...sound,
+      metadata: {
+        ...sound.metadata,
+        _resolvedSource: resolved.source,
+        _isStreaming: resolved.isStreaming,
+      },
+    };
+
+    await store.playSound(soundWithSource, playbackOptions, onDownloadProgress);
+  };
+
+  return {
+    /** Play a sound */
+    playSound,
+
+    /** Stop current sound */
+    stopSound: store.stopSound,
+
+    /** Pause current sound */
+    pauseSound: store.pauseSound,
+
+    /** Resume paused sound */
+    resumeSound: store.resumeSound,
+
+    /** Check if specific sound is playing */
+    isPlaying: store.isPlaying,
+
+    /** Currently playing sound ID */
+    playingSoundId: store.playingSoundId,
+
+    /** Currently downloading sound ID */
+    downloadingSoundId: store.downloadingSoundId,
+
+    /** Download progress (0-100) */
+    downloadProgress: store.downloadProgress,
+
+    /** Whether sound is streaming */
+    isStreaming: store.isStreaming,
+  };
+}
+