Documentation Index
Fetch the complete documentation index at: https://mintlify.com/afkcodes/react-native-audio-pro/llms.txt
Use this file to discover all available pages before exploring further.
Ambient audio is a completely isolated secondary player built into React Native Audio Pro. It is designed for looping background sounds — rain, white noise, nature soundscapes, or any audio bed — that should play alongside your main content without interfering with playback state, events, or controls. The ambient player has its own event emitter key, no shared state with the main player, and a deliberately minimal API.
Key Design Principles
- Fully isolated from the main player — no shared variables, player instances, or event emitters. Stopping, pausing, or clearing the main player has no effect on ambient audio.
- Auto-plays immediately — calling
ambientPlay() starts playback right away; no separate play() call is needed.
- Loops by default — pass
loop: false to play through once.
- Stateless API — there is no volume getter, no position getter, and no playback state query. The ambient player is designed as a fire-and-forget system.
- Self-cleaning — when
ambientStop() is called, or when a non-looping track ends, or when a playback error occurs, the player fully tears down and releases all audio resources automatically.
Methods
ambientPlay(options)
Starts ambient playback immediately. If another ambient track is already playing, it is replaced.
| Parameter | Type | Required | Default | Description |
|---|
url | string | Yes | — | Remote https:// URL or local file:// path to the audio file |
loop | boolean | No | true | Loop the track indefinitely. Set to false to play through once |
import { AudioPro } from 'react-native-audio-pro';
AudioPro.ambientPlay({
url: 'https://example.com/rain.mp3',
loop: true,
});
Ambient audio supports both remote HTTPS URLs and local file:// paths. Use a library such as react-native-fs to resolve a local file path and prefix it with file:// before passing it here.
ambientStop()
Stops ambient playback, tears down the player, and releases all audio resources. This is the recommended way to fully clean up the ambient player.
ambientPause()
Pauses ambient playback. No-op if the ambient player is not currently playing.
ambientResume()
Resumes ambient playback after a pause. No-op if the ambient player is already playing or has no active track.
AudioPro.ambientResume();
ambientSeekTo(positionMs)
Seeks to a specific position in the ambient track, in milliseconds. Silently ignored if seeking is unsupported or if no ambient track is loaded.
| Parameter | Type | Description |
|---|
positionMs | number | Target position in milliseconds |
AudioPro.ambientSeekTo(30000); // Seek to 30 seconds
ambientSetVolume(volume)
Sets the playback volume of the ambient player. This is a direct setter — there is no corresponding getter.
| Parameter | Type | Description |
|---|
volume | number | Volume level from 0.0 (mute) to 1.0 (full) |
AudioPro.ambientSetVolume(0.4); // 40% volume
addAmbientListener(callback)
Subscribes to ambient audio events. Returns a subscription object with a .remove() method.
const subscription = AudioPro.addAmbientListener((event) => {
console.log(event.type); // 'AMBIENT_TRACK_ENDED' | 'AMBIENT_ERROR'
});
// Later, when you no longer need the listener:
subscription.remove();
Events
The ambient player emits two event types, both delivered through a separate event emitter key (AudioProAmbientEvent) that is completely independent from the main player’s AudioProEvent.
| Event | Payload | Description |
|---|
AMBIENT_TRACK_ENDED | {} | Fired when a non-looping track reaches the end. The player tears down automatically after emitting this event |
AMBIENT_ERROR | { error: string } | Fired when a playback error occurs. The player cleans up automatically — no manual ambientStop() call is needed |
Complete Example
The following example starts a rain soundscape alongside a podcast, adjusts its volume, pauses and resumes it based on app state, and listens for the track ending.
import { useEffect } from 'react';
import { AudioPro, AudioProAmbientEventType } from 'react-native-audio-pro';
export function AmbientRainPlayer() {
useEffect(() => {
// Start ambient rain loop at 40% volume
AudioPro.ambientPlay({
url: 'https://example.com/rain-loop.mp3',
loop: true,
});
AudioPro.ambientSetVolume(0.4);
// Listen for ambient events
const subscription = AudioPro.addAmbientListener((event) => {
if (event.type === AudioProAmbientEventType.AMBIENT_TRACK_ENDED) {
// Fired when loop: false and the track completes
console.log('Ambient track finished');
}
if (event.type === AudioProAmbientEventType.AMBIENT_ERROR) {
// Player has already cleaned up at this point
console.error('Ambient error:', event.payload?.error);
}
});
return () => {
// Clean up on unmount
AudioPro.ambientStop();
subscription.remove();
};
}, []);
// Pause when user navigates away, resume on return
function handleBackground() {
AudioPro.ambientPause();
}
function handleForeground() {
AudioPro.ambientResume();
}
// Seek back to the start
function handleRestart() {
AudioPro.ambientSeekTo(0);
}
return null; // This is a headless audio component
}
Using a One-Shot Sound
To play an ambient sound once and react when it finishes, set loop: false and handle AMBIENT_TRACK_ENDED:
AudioPro.ambientPlay({
url: 'https://example.com/notification-chime.mp3',
loop: false,
});
const subscription = AudioPro.addAmbientListener((event) => {
if (event.type === AudioProAmbientEventType.AMBIENT_TRACK_ENDED) {
console.log('Chime finished');
subscription.remove();
}
});
Ambient audio usually continues playing when the app is backgrounded, but this is not guaranteed across all devices and OS versions. For reliable background audio, keep a main track playing concurrently via AudioPro.play(). The main player’s background session keeps the audio session alive for both streams.