🚀 Cross-platform audio playback for React Native — Play sound clips on iOS and Android with full TypeScript support and modern React Native architecture compatibility.

• 🎯 Cross-platform: Works on iOS and Android
• 📱 Modern Architecture: Full support for React Native's New Architecture (TurboModules)
• 🔤 TypeScript: Complete TypeScript definitions included
• 🎛️ Rich Controls: Play, pause, stop, seek, volume, pan, and looping
• 📁 Flexible Loading: Load from app bundle, local files, or network URLs
• 🔄 Multiple Players: Play multiple sounds simultaneously
• ⚡ Optimized: Minimal latency with preloading support
• 🛡️ Reliable: Battle-tested in production apps

📝 Note: This library focuses on audio clips playback, not streaming. For streaming audio, consider react-native-video or other dedicated streaming solutions.

iOS Implementation: Uses AVAudioPlayer for optimal performance and compatibility.

Android Implementation: Uses MediaPlayer with proper audio focus handling.

npm install react-native-sound

yarn add react-native-sound

This library supports both the old and new React Native architecture:

• ✅ Old Architecture: Uses traditional NativeModules
• ✅ New Architecture: Uses TurboModules for better performance
• ✅ Expo: Compatible with custom development builds (not Expo Go)

This usually indicates a linking issue. Try:

1. Clear build cache:

   cd android && ./gradlew cleanBuildCache

2. Reset Metro cache:

   npx react-native start --reset-cache

3. Clean and rebuild:

   # iOS cd ios && rm -rf build && cd .. && npx react-native run-ios # Android cd android && ./gradlew clean && cd .. && npx react-native run-android

• Ensure audio files are added to Xcode project bundle
• Check that AVFoundation framework is linked (automatically handled by CocoaPods)

• Place audio files in android/app/src/main/res/raw/
• Use lowercase filenames without spaces or special characters
• Clear build cache if encountering linking issues

• 📚 Wiki Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Check out our enhanced example app with both remote and local audio playback:

• 📁 /example - Full-featured demo application
• 🎯 Remote URL audio playback
• 📱 Local bundled audio files
• 🎨 Modern UI with TypeScript

• 🎵 react-native-sound-playerview - Advanced audio player UI component

Save audio files in android/app/src/main/res/raw/:

android/app/src/main/res/raw/ ├── whoosh.mp3 ✅ Correct ├── button_click.wav ✅ Correct └── my-sound.mp3 ❌ Use underscores: my_sound.mp3 

Note: Use lowercase, underscored filenames. No subdirectories allowed.

1. Open your project in Xcode
2. Right-click your project → "Add Files to [PROJECT]"
3. Select your audio files and ensure they're added to the app target

import Sound from "react-native-sound"; // Enable playback in silence mode (important for iOS) Sound.setCategory("Playback"); // Load a sound file from the app bundle const whoosh = new Sound("whoosh.mp3", Sound.MAIN_BUNDLE, (error) => { if (error) { console.log("Failed to load the sound", error); return; } // Sound loaded successfully console.log("Duration:", whoosh.getDuration(), "seconds"); console.log("Channels:", whoosh.getNumberOfChannels()); // Play the sound whoosh.play((success) => { if (success) { console.log("Successfully finished playing"); } else { console.log("Playback failed due to audio decoding errors"); } }); }); // Audio controls whoosh.setVolume(0.5); // 50% volume whoosh.setPan(1); // Full right stereo whoosh.setNumberOfLoops(-1); // Loop indefinitely // Get current properties console.log("Volume:", whoosh.getVolume()); console.log("Pan:", whoosh.getPan()); console.log("Loops:", whoosh.getNumberOfLoops()); // Seek to specific time whoosh.setCurrentTime(2.5); // Get current playback position whoosh.getCurrentTime((seconds) => { console.log("Current time:", seconds); }); // Control playback whoosh.pause(); // Pause playback whoosh.stop(() => { // Stop and rewind whoosh.play(); // Play from beginning }); // Always release resources when done whoosh.release();

// From app bundle (most common) const bundleSound = new Sound("sound.mp3", Sound.MAIN_BUNDLE, callback); // From documents directory const docSound = new Sound("sound.mp3", Sound.DOCUMENT, callback); // From library directory const libSound = new Sound("sound.mp3", Sound.LIBRARY, callback); // From absolute path const pathSound = new Sound("/path/to/sound.mp3", "", callback); // From remote URL (iOS/Android only) const urlSound = new Sound("https://example.com/sound.mp3", "", callback);

import { useEffect, useRef, useState } from "react"; import Sound from "react-native-sound"; const useSound = (filename: string) => { const sound = useRef<Sound | null>(null); const [isLoaded, setIsLoaded] = useState(false); const [isPlaying, setIsPlaying] = useState(false); useEffect(() => { sound.current = new Sound(filename, Sound.MAIN_BUNDLE, (error) => { if (error) { console.log("Error loading sound:", error); return; } setIsLoaded(true); }); return () => { sound.current?.release(); }; }, [filename]); const play = () => { if (sound.current && isLoaded) { sound.current.play((success) => { setIsPlaying(false); }); setIsPlaying(true); } }; const stop = () => { if (sound.current) { sound.current.stop(); setIsPlaying(false); } }; return { play, stop, isLoaded, isPlaying }; };

• Preload sounds during app initialization to minimize playback delay
• Reuse Sound instances for multiple playbacks of the same file
• Avoid race conditions by ensuring sounds are loaded before calling play()

• iOS: Uses AVAudioSessionCategoryAmbient to mix multiple sounds
• Multiple playback: You can play several sound files simultaneously
• Background audio: Configure audio categories for background playback

Supports: AAC, AIFF, CAF, MP3, WAV, and more

• 📚 Complete format list

Supports: 3GPP, MP4, MP3, AAC, OGG, FLAC, WAV, and more

• 📚 Complete format list

• Android absolute paths: Use /sdcard/ prefix (e.g., /sdcard/Downloads/sound.mp3)
• Method chaining: Supported for setters (e.g., sound.setVolume(0.5).setPan(0.5).play())

• ✅ Playing sound effects and short audio clips
• ✅ Background music with simple controls
• ✅ Audio feedback for user interactions
• ✅ Cross-platform compatibility requirements
• ✅ TypeScript projects requiring type safety

• ❌ Audio streaming or long-form content
• ❌ Advanced audio processing or effects
• ❌ Audio recording capabilities
• ❌ Complex playlist management

We welcome contributions! Here's how you can help:

• 🐛 Bug fixes and stability improvements
• 📚 Documentation improvements and examples
• 🧪 Test coverage expansion
• 🚀 Performance optimizations
• 🆕 New platform support

1. Fork and clone the repository
2. Install dependencies: npm install
3. Run the example app: cd example && npm install && npm run android
4. Make your changes and test thoroughly
5. Add tests for new features
6. Update documentation as needed

• 🔍 Open an issue first for major changes to discuss the approach
• ✅ Include tests for new functionality
• 📝 Update documentation including TypeScript definitions
• 🧪 Test on multiple platforms (iOS and Android)
• 📱 Test with both architectures (old and new React Native architecture)

• Follow existing TypeScript/JavaScript patterns

• Use meaningful commit messages

• Keep changes focused and atomic

• To minimize playback delay, you may want to preload a sound file without calling play() (e.g. var s = new Sound(...);) during app initialization. This also helps avoid a race condition where play() may be called before loading of the sound is complete, which results in no sound but no error because loading is still being processed.

• You can play multiple sound files at the same time. Under the hood, this module uses AVAudioSessionCategoryAmbient to mix sounds on iOS.

• You may reuse a Sound instance for multiple playbacks.

• On iOS, the module wraps AVAudioPlayer that supports aac, aiff, mp3, wav etc. The full list of supported formats can be found at https://developer.apple.com/library/content/documentation/MusicAudio/Conceptual/CoreAudioOverview/SupportedAudioFormatsMacOSX/SupportedAudioFormatsMacOSX.html

• On Android, the module wraps android.media.MediaPlayer. The full list of supported formats can be found at https://developer.android.com/guide/topics/media/media-formats.html

• On Android, the absolute path can start with '/sdcard/'. So, if you want to access a sound called "my_sound.mp3" on Downloads folder, the absolute path will be: '/sdcard/Downloads/my_sound.mp3'.

• You may chain non-getter calls, for example, sound.setVolume(.5).setPan(.5).play().

MIT License - see LICENSE file for details.

If this library helps your project, consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and issues
• 📝 Contributing improvements
• 💬 Helping others in discussions
• 📢 Sharing with the community

Made with ❤️ by the React Native community