# React Native Audio Stream [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://coff.ee/mustafakarali) > 💔 **Personal Appeal from the Developer** > > Dear fellow developers, > > I'm facing a critical financial situation with $30,000 in debt that's weighing heavily on my life. I've poured my heart and soul into creating this audio streaming library to help the React Native community. If this package has saved you time, helped your project, or added value to your work, please consider supporting me. > > **Even a $10 donation from each user would make a life-changing difference.** > > Your support doesn't just help with code – it helps a fellow developer get back on their feet. Every contribution, no matter how small, brings hope and relief to my difficult situation. > > 🙏 Please click the **[Buy Me A Coffee](https://coff.ee/mustafakarali)** button above. Your kindness can truly change a life. > > Thank you for your compassion and support, > Mustafa A comprehensive React Native audio streaming library with real-time playback support for iOS and Android. Built with TypeScript and featuring advanced capabilities like buffering management, network resilience, equalizer support, and background playback. > ⚠️ **Important**: This is a comprehensive implementation but has not been fully tested in production. Please see [TESTING.md](TESTING.md) for testing requirements and known limitations. ## Features - 🎵 **Real-time Audio Streaming** - Start playback immediately upon receiving first chunk - 📱 **Cross-Platform** - Full iOS and Android support with platform-specific optimizations - 🔧 **TypeScript** - Complete type definitions for excellent developer experience - 🎛️ **Advanced Controls** - Play, pause, stop, seek, volume, and playback rate control - 📊 **Real-time Statistics** - Network speed, buffer health, latency monitoring - 🎚️ **Equalizer** - Built-in equalizer with presets - 💾 **Smart Caching** - Automatic caching with configurable size limits - 🔄 **Network Resilience** - Automatic reconnection and retry logic - 🎯 **Background Playback** - Continue playing when app is in background - 📡 **Multiple Protocols** - Support for HTTP, HTTPS, HLS, DASH, and WebSocket streaming - 🎨 **Multiple Formats** - MP3, AAC, WAV, OGG, FLAC, PCM support - 🎬 **HLS/DASH Support** - Native adaptive bitrate streaming support - ❌ **Cancel Stream** - Properly cancel ongoing streams - 🎙️ **iOS Features (Future)** - AirPods high-quality recording, input device picker, spatial audio - 🚀 **Enhanced Buffering** - AirPlay 2 enhanced buffering for better performance - 📍 **AVQueuePlayer Support** - Enhanced playback capabilities with queue management ## Compatibility | RN Audio Stream | React Native | iOS | Android | Expo SDK | |-----------------|--------------|-----|---------|----------| | 1.0.0+ | 0.64+ | 11+ | 21+ | 43+ | | 1.4.x | 0.71+ | 13+ | 23+ | 48+ | | 1.5.x - 1.6.x | 0.73+ | 13+ | 23+ | 49+ | ✅ Actively maintained 📱 React Native 0.76+ New Architecture support (default) 🏗️ React Native 0.80 supported ## Installation ```bash npm install @mustafakarali/react-native-audio-stream # or yarn add @mustafakarali/react-native-audio-stream ``` ### iOS Setup ```bash cd ios && pod install ``` Add the following to your `Info.plist`: ```xml UIBackgroundModes audio AVInitialRouteSharingPolicy LongFormAudio AVAudioSessionRouteSharingPolicy LongFormAudio ``` **[📖 View Detailed iOS Setup Guide](./docs/IOS_SETUP.md)** - Includes troubleshooting, performance tips, and common issues. ### Android Setup The library automatically handles Android configuration. However, ensure your `minSdkVersion` is at least 21 in `android/build.gradle`. ## Quick Start ```typescript import AudioStream from '@mustafakarali/react-native-audio-stream'; // Initialize the audio stream (optional but recommended) // If not called, default configuration will be used await AudioStream.initialize({ enableBackgroundMode: true, autoPlay: true, }); // Start streaming await AudioStream.startStream('https://your-audio-stream-url.mp3'); // Or start HLS/DASH streaming (automatically detected) await AudioStream.startStream('https://example.com/playlist.m3u8'); // Add event listeners AudioStream.addEventListener('onProgress', (progress) => { console.log(`Current time: ${progress.currentTime}s`); }); AudioStream.addEventListener('onError', (error) => { console.error('Stream error:', error); }); // Cancel stream if needed await AudioStream.cancelStream(); ``` ## API Reference ### Initialization #### `initialize(config?: AudioStreamConfig): Promise` Initialize the audio stream with optional configuration. ```typescript await AudioStream.initialize({ bufferSize: 64, // Buffer size in KB (default: 64) prebufferThreshold: 16, // Start playback threshold in KB (default: 16) enableBackgroundMode: true, // Enable background playback (default: false) enableCache: true, // Enable caching (default: false) cacheSize: 100, // Cache size in MB (default: 100) logLevel: LogLevel.DEBUG, // Logging level (default: WARNING) }); ``` ### Streaming Control #### `startStream(url: string, config?: AudioStreamConfig): Promise` Start streaming from the specified URL. ```typescript await AudioStream.startStream('https://example.com/audio.mp3', { headers: { 'Authorization': 'Bearer token', }, autoPlay: true, }); ``` #### `stopStream(): Promise` Stop the current stream and clean up resources. #### `cancelStream(): Promise` Cancel the current stream immediately and set state to IDLE. Unlike `stopStream()`, this doesn't wait for cleanup. #### `playFromData(base64Data: string, config?: AudioStreamConfig): Promise` Play audio from base64 encoded binary data. Useful for TTS services that return audio data directly. ```typescript // Example with ElevenLabs TTS const response = await fetch('https://api.elevenlabs.io/v1/text-to-speech/voice-id', { method: 'POST', headers: { 'xi-api-key': 'your-api-key', 'Content-Type': 'application/json' }, body: JSON.stringify({ text: 'Hello world' }) }); // Convert response to base64 const audioBlob = await response.blob(); const reader = new FileReader(); reader.readAsDataURL(audioBlob); reader.onloadend = () => { const base64Data = reader.result.split(',')[1]; // Remove data:audio/mpeg;base64, prefix AudioStream.playFromData(base64Data, { autoPlay: true }); }; ``` ### Playback Control #### `play(): Promise` Resume playback. #### `pause(): Promise` Pause playback. #### `stop(): Promise` Stop playback and reset position. #### `seek(position: number): Promise` Seek to position in seconds. ```typescript await AudioStream.seek(30.5); // Seek to 30.5 seconds ``` ### Volume and Rate #### `setVolume(volume: number): Promise` Set volume (0.0 to 1.0). #### `setPlaybackRate(rate: number): Promise` Set playback rate (0.5 to 2.0). ```typescript await AudioStream.setVolume(0.8); // 80% volume await AudioStream.setPlaybackRate(1.5); // 1.5x speed ``` ### State and Information #### `getState(): Promise` Get current playback state. #### `getCurrentTime(): Promise` Get current playback position in seconds. #### `getDuration(): Promise` Get total duration in seconds. #### `getBufferedPercentage(): Promise` Get buffered percentage (0-100). #### `getStats(): Promise` Get detailed playback statistics. ```typescript const stats = await AudioStream.getStats(); console.log(`Buffer health: ${stats.bufferHealth}%`); console.log(`Network speed: ${stats.networkSpeed} KB/s`); ``` ### Equalizer #### `setEqualizer(bands: EqualizerBand[]): Promise` Set custom equalizer bands. #### `applyEqualizerPreset(preset: EqualizerPreset): Promise` Apply a preset equalizer configuration. ```typescript // Available presets const presets = [ { name: 'Flat', bands: [/* ... */] }, // Index 0 { name: 'Bass Boost', bands: [/* ... */] }, // Index 1 { name: 'Treble Boost', bands: [/* ... */] }, // Index 2 { name: 'Vocal', bands: [/* ... */] }, // Index 3 { name: 'Rock', bands: [/* ... */] }, // Index 4 { name: 'Pop', bands: [/* ... */] }, // Index 5 { name: 'Jazz', bands: [/* ... */] }, // Index 6 { name: 'Dance', bands: [/* ... */] }, // Index 7 { name: 'Classical', bands: [/* ... */] }, // Index 8 ]; // Apply bass boost preset await AudioStream.applyEqualizerPreset(1); // Custom equalizer (5 bands: 60Hz, 230Hz, 910Hz, 3600Hz, 14000Hz) await AudioStream.setEqualizer([ { frequency: 60, gain: 6 }, // Bass { frequency: 230, gain: 4 }, // Low-mid { frequency: 910, gain: 0 }, // Mid { frequency: 3600, gain: 2 }, // High-mid { frequency: 14000, gain: 4 }, // Treble ]); ``` ### Event Handling #### `addEventListener(event: string, callback: Function): void` Available events: - `onStart` - Stream started - `onBuffer` - Buffer state changed - `onProgress` - Playback progress update - `onError` - Error occurred - `onEnd` - Stream ended - `onStateChange` - Playback state changed - `onMetadata` - Metadata received (title, artist, album) - `onStats` - Statistics update - `onNetworkStateChange` - Network connectivity changed ```typescript // Progress tracking AudioStream.addEventListener('onProgress', (progress) => { console.log(`${progress.currentTime}s / ${progress.duration}s`); console.log(`Buffered: ${progress.percentage}%`); }); // Error handling with recovery AudioStream.addEventListener('onError', (error) => { console.error(`Error Code: ${error.code}`); console.error(`Error Message: ${error.message}`); if (error.recoverable) { // Implement retry logic setTimeout(() => { AudioStream.startStream(currentUrl); }, 3000); } }); // Metadata display AudioStream.addEventListener('onMetadata', (metadata) => { console.log(`Now playing: ${metadata.title} by ${metadata.artist}`); console.log(`Album: ${metadata.album}`); }); // Network monitoring AudioStream.addEventListener('onNetworkStateChange', (state) => { console.log(`Network connected: ${state.isConnected}`); console.log(`Connection type: ${state.type}`); }); ``` ### Cache Management #### `clearCache(): Promise` Clear all cached data. #### `getCacheSize(): Promise` Get current cache size in bytes. #### `preloadStream(url: string, duration?: number): Promise` Preload a stream for faster playback. ```typescript // Preload first 30 seconds await AudioStream.preloadStream(url, 30); ``` ### Platform Specific #### iOS ```typescript // Set audio session category await AudioStream.setAudioSessionCategory('playback'); ``` #### Android ```typescript // Request audio focus const granted = await AudioStream.requestAudioFocus(); ``` ## Types ### AudioStreamConfig ```typescript interface AudioStreamConfig { bufferSize?: number; prebufferThreshold?: number; maxBufferSize?: number; chunkSize?: number; protocol?: StreamingProtocol; reconnectAttempts?: number; reconnectDelay?: number; timeout?: number; format?: AudioFormat; sampleRate?: number; channels?: number; bitRate?: number; autoPlay?: boolean; enableBackgroundMode?: boolean; maintainAudioFocus?: boolean; enableCache?: boolean; cacheSize?: number; cachePath?: string; logLevel?: LogLevel; headers?: Record; } ``` ### PlaybackState ```typescript enum PlaybackState { IDLE = 'idle', LOADING = 'loading', BUFFERING = 'buffering', PLAYING = 'playing', PAUSED = 'paused', STOPPED = 'stopped', ERROR = 'error', COMPLETED = 'completed', } ``` ### PlaybackStats ```typescript interface PlaybackStats { bufferedDuration: number; // Seconds of buffered content playedDuration: number; // Seconds played totalDuration: number; // Total duration if known networkSpeed: number; // KB/s latency: number; // Network latency in ms bufferHealth: number; // 0-100 percentage droppedFrames: number; // Dropped audio frames bitRate: number; // Actual bitrate in kbps bufferedPosition: number; // End position of buffer in seconds currentPosition: number; // Current playback position bufferedPercentage: number; // Percentage of total duration buffered isBuffering: boolean; // Currently buffering playWhenReady: boolean; // Will play when buffer is ready } ``` ## Complete Example ```typescript import React, { useEffect, useState } from 'react'; import { View, Button, Text } from 'react-native'; import AudioStream, { PlaybackState, LogLevel } from '@mustafakarali/react-native-audio-stream'; export default function AudioPlayer() { const [state, setState] = useState(PlaybackState.IDLE); const [progress, setProgress] = useState({ current: 0, total: 0 }); const [metadata, setMetadata] = useState({ title: '', artist: '' }); useEffect(() => { // Initialize audio stream (optional) AudioStream.initialize({ enableBackgroundMode: true, enableCache: true, logLevel: LogLevel.INFO, }); // Setup event listeners AudioStream.addEventListener('onStateChange', setState); AudioStream.addEventListener('onProgress', (data) => { setProgress({ current: data.currentTime, total: data.duration }); }); AudioStream.addEventListener('onMetadata', (data) => { setMetadata({ title: data.title || '', artist: data.artist || '' }); }); return () => { AudioStream.removeAllEventListeners(); AudioStream.destroy(); }; }, []); const handlePlay = async () => { if (state === PlaybackState.IDLE) { await AudioStream.startStream('https://example.com/stream.mp3'); } else { await AudioStream.play(); } }; return ( State: {state} Progress: {progress.current.toFixed(1)}s / {progress.total.toFixed(1)}s {metadata.title ? ( Now Playing: {metadata.title} - {metadata.artist} ) : null}