/audio

name: audio
description: "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 |