Software Mansion's best practices for audio in React Native using react-native-audio-api. Covers audio playback (buffer sources, oscillators, streaming), recording (file, callback, graph), audio effects (gain, filters, delay, convolver, panner, waveshaper), real-time analysis and visualization, audio worklets (custom synthesis, UIRuntime/AudioRuntime), system integration (sessions, interruptions, permissions), and testing. Trigger on: react-native-audio-api, AudioContext, AudioRecorder, AudioBuffer, AudioBufferSourceNode, AudioBufferQueueSourceNode, OscillatorNode, StreamerNode, GainNode, BiquadFilterNode, DelayNode, ConvolverNode, StereoPannerNode, WaveShaperNode, AnalyserNode, AudioParam, AudioManager, PlaybackNotificationManager, RecordingNotificationManager, WorkletNode, WorkletSourceNode, WorkletProcessingNode, audio playback, record audio, microphone, waveform, audio visualization, audio streaming, audio worklet, or any React Native feature that captures, processes, or emits sound.
Audio
Software Mansion's production audio patterns for React Native using react-native-audio-api.
Load at most one reference file per question. For API signatures and config options, webfetch the documentation pages linked in each reference file.
Critical Rules
Single AudioContext: Create one AudioContext instance per app. Multiple instances lead to conflicting states (one running, another suspended). Encapsulate it in a singleton class.
Single AudioRecorder: Create one AudioRecorder instance and reuse it. Switching between recorder instances has noticeable impact on performance, memory, and battery.
Suspend when idle: A running AudioContext plays silence even with no source nodes connected, draining battery. On iOS, it also prevents the lock screen from showing a paused state. Use suspend() when audio is temporarily not needed, close() when done permanently.
AudioBufferSourceNode is single-use: An AudioBufferSourceNode can be started only once. To replay the same sound, create a new node. Nodes are inexpensive to create; reuse the AudioBuffer.
Use AudioParam scheduling for smooth changes: Direct, immediate changes to gain, frequency, or other params cause audible clicks. Use linearRampToValueAtTime, exponentialRampToValueAtTime, or setTargetAtTime for smooth transitions.
Mutate typed arrays in place for visualizations: When passing audio data to Reanimated shared values, use .modify() to mutate the existing Float32Array rather than allocating a new one each frame. Allocating at 60fps+ causes GC jank.
References
File
When to read
audio.md
Decision tree for choosing an audio approach; AudioContext lifecycle and singleton pattern; audio graph concepts; decoding audio data; AudioBuffer state management
playback.md
Playing audio with AudioBufferSourceNode, OscillatorNode, StreamerNode, AudioBufferQueueSourceNode; looping and scheduling; AudioParam scheduling methods; playback rate and pitch; noise generation
recording.md
Recording audio with AudioRecorder; three recording modes (file, data callback, graph processing); file output configuration and formats; permissions; background recording setup
effects-and-analysis.md
Audio effects chain (GainNode, BiquadFilterNode, DelayNode, ConvolverNode, StereoPannerNode, WaveShaperNode); ADSR envelopes; AnalyserNode for time-domain and frequency-domain data; audio visualization patterns
worklets.md
Audio worklets with WorkletNode, WorkletSourceNode, WorkletProcessingNode; UIRuntime vs AudioRuntime; performance budgets and latency constraints; custom synthesis and real-time processing
system-and-notifications.md
AudioManager for session configuration and system events; PlaybackNotificationManager and RecordingNotificationManager for media controls; permissions; interruption handling; testing with mocks
