Registry / communication / react-native-audio-api

react-native-audio-api

JSON →
library0.11.7jsnpmunverified

react-native-audio-api is a high-performance audio engine for React Native that implements a significant portion of the Web Audio API specification, allowing developers to create and manipulate audio graphs in a cross-platform manner (iOS, Android, and Web). The library enables advanced audio functionalities such as sound synthesis, real-time effects processing using various audio nodes (e.g., OscillatorNode, GainNode, BiquadFilterNode), microphone input, audio recording to files, HLS streaming, and audio visualization. Currently at version 0.11.7, it receives frequent patch updates addressing bugs and adding minor features, demonstrating active development. Its core differentiator is the adherence to the Web Audio API, offering a familiar interface for web developers moving to React Native for complex audio tasks, unlike simpler audio playback libraries.

npm install react-native-audio-api
INSTALL
IMPORT
SIG · REACT-NATIVE-AUDIO
R
react-native-audio-api
communicationjavascriptv0.11.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AudioContext
import { AudioContext } from 'react-native-audio-api';
import AudioContext from 'react-native-audio-api';
AudioContext is a named export, essential for creating an audio graph. Instantiating it is the first step in most audio operations.
OscillatorNode
import { AudioContext, OscillatorNode, GainNode } from 'react-native-audio-api';
import { OscillatorNode } from 'react-native-audio-api/src/nodes/OscillatorNode';
Individual AudioNodes like OscillatorNode and GainNode are typically imported as named exports directly from the main package. Avoid deep imports as paths may change.
AudioManager
import { AudioManager } from 'react-native-audio-api';
import AudioManager from 'react-native-audio-api';
AudioManager provides system-specific audio control functions, such as managing audio session options and observing interruptions. It's a named export.

This quickstart code initializes an `AudioContext` and creates a simple audio graph to generate and play a 440 Hz sine wave, demonstrating basic sound synthesis and control. It also includes an example of requesting necessary microphone permissions using `react-native-permissions` for more advanced use cases like recording.

import React, { useEffect, useState } from 'react'; import { View, Button, Text, Alert } from 'react-native'; import { AudioContext, OscillatorNode, GainNode, AudioDestinationNode, AudioManager } from 'react-native-audio-api'; import { requestMultiple, PERMISSIONS, RESULTS } from 'react-native-permissions'; const AudioPlayer = () => { const [context, setContext] = useState<AudioContext | null>(null); const [oscillator, setOscillator] = useState<OscillatorNode | null>(null); const [isPlaying, setIsPlaying] = useState(false); const requestPermissions = async () => { const results = await requestMultiple([PERMISSIONS.IOS.MICROPHONE, PERMISSIONS.ANDROID.RECORD_AUDIO]); if (results[PERMISSIONS.IOS.MICROPHONE] === RESULTS.GRANTED || results[PERMISSIONS.ANDROID.RECORD_AUDIO] === RESULTS.GRANTED) { console.log('Microphone permission granted'); } else { Alert.alert('Permission Denied', 'Microphone permission is required for some audio features.'); } }; useEffect(() => { requestPermissions(); const initAudio = async () => { try { const newContext = new AudioContext(); await newContext.start(); const newOscillator = new OscillatorNode(newContext); newOscillator.frequency.value = 440; // A4 note newOscillator.type = 'sine'; const gainNode = new GainNode(newContext); gainNode.gain.value = 0.5; const destination = new AudioDestinationNode(newContext); newOscillator.connect(gainNode); gainNode.connect(destination); setContext(newContext); setOscillator(newOscillator); } catch (error) { console.error('Failed to initialize audio context:', error); } }; initAudio(); return () => { context?.close(); }; }, []); const togglePlayback = async () => { if (!context || !oscillator) return; if (isPlaying) { oscillator.stop(); setIsPlaying(false); } else { // Oscillators can only be started once, so create a new one each time const newOscillator = new OscillatorNode(context); newOscillator.frequency.value = 440; newOscillator.type = 'sine'; const gainNode = new GainNode(context); gainNode.gain.value = 0.5; const destination = new AudioDestinationNode(context); newOscillator.connect(gainNode); gainNode.connect(destination); newOscillator.start(); setOscillator(newOscillator); setIsPlaying(true); } }; if (!context) { return ( <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}> <Text>Loading Audio Engine...</Text> </View> ); } return ( <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}> <Text style={{ fontSize: 24, marginBottom: 20 }}>Simple Sine Wave Generator</Text> <Button title={isPlaying ? 'Stop Sine Wave' : 'Start Sine Wave'} onPress={togglePlayback} /> <Button title="Request Permissions" onPress={requestPermissions} /> </View> ); }; export default AudioPlayer;
Debug
Known issues
breakingVersion 0.11.0 introduced significant breaking changes, including a 'Refactor/context wise' and the removal of a custom metro-config wrapper. This likely affects how `AudioContext` is managed and how the library integrates with Metro bundler.
fix
Review the official migration guide or example applications on the GitHub repository. The removal of the metro-config wrapper suggests a simplified or standard Metro setup, but context refactoring may require changes to audio graph initialization and management logic.
affects: >=0.11.0
gotchaWhen using `OscillatorNode` or `AudioBufferSourceNode`, they can only be started once. To play the same sound again, you must create a new instance of the node, connect it to the graph, and then start it. Repeatedly calling `start()` on the same instance after it has stopped will result in an error or no sound. This is consistent with the Web Audio API specification.
fix
Always create a new `OscillatorNode` or `AudioBufferSourceNode` instance each time you intend to play a sound. Disconnect and dereference old nodes if they are no longer needed to prevent memory leaks.
affects: >=0.1.0
gotchaMicrophone and background audio playback features require specific native permissions to be configured in `AndroidManifest.xml` (Android) and `Info.plist` (iOS). Failing to declare these permissions will prevent audio recording or background playback from functioning correctly.
fix
For Android, add `<uses-permission android:name="android.permission.RECORD_AUDIO" />` and `FOREGROUND_SERVICE_MEDIA_PLAYBACK` (if applicable) to `AndroidManifest.xml`. For iOS, add `NSMicrophoneUsageDescription` to `Info.plist` and ensure background audio modes are enabled for background playback. Use a library like `react-native-permissions` for runtime permission requests.
affects: >=0.1.0
gotchaThe library is compatible with the Web Audio API, but for cross-platform consistency, it limits available interfaces to those implemented on both iOS and Android. Some advanced Web Audio API interfaces might be marked as 'not yet available' (e.g., `ChannelMergerNode`, `PannerNode`).
fix
Consult the 'Web Audio API coverage' documentation to verify if a specific node or interface is implemented and supported across all target platforms before relying on it. If a crucial interface is missing, consider alternative approaches or contributing to the library.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Tried to use 'require' to access 'react-native-audio-api' (did you mean 'import'?)
Attempting to use CommonJS `require()` syntax with `react-native-audio-api`, which is an ESM-first or modern module.
fix
Update your import statements to use ES module syntax: `import { SomeModule } from 'react-native-audio-api';`.
Invariant Violation: 'react-native-audio-api' has not been linked. Please run 'npx react-native autolink-ios' or 'cd ios && pod install'.
Native modules for `react-native-audio-api` are not correctly linked into the iOS or Android project. This typically happens after initial installation or when updating React Native versions.
fix
For iOS, navigate to the `ios` directory and run `pod install`, then rebuild your project. For Android, ensure `react-native autolink` runs correctly during your build process. Clear Metro bundler cache if issues persist.
AudioContext cannot be created. Native context is null or undefined.
The underlying native audio engine failed to initialize or the `AudioContext` was instantiated before the native module was fully ready. This can happen if the app isn't fully loaded or due to native module linking issues.
fix
Ensure the app has completely loaded before attempting to create an `AudioContext`. If using Expo, ensure you are using a development build. Verify `react-native-audio-api` is properly linked. Delay `AudioContext` creation until essential app components are mounted.
Upgrade
Version history
0.11.7latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React Native applications.
react-nativerequiredCore peer dependency for React Native applications.
Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources
react-native-audio-api — npm install react-native-audio-api · libregistry