Skip to main content

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.

This guide takes you from a freshly installed package to a working audio player in four steps. You will configure the player once at the app root, add tracks to the queue, start playback, and then wire up a React component that reads live state from the useAudioPro hook. By the end you will have a minimal but fully functional player with play/pause, a progress readout, and the currently playing track name.
1

Install the package

If you have not already installed React Native Audio Pro, follow the full Installation guide first. It covers the npm/yarn install, iOS pod install, Xcode Background Modes setup, and Android SDK version requirements.
2

Configure the player

Call AudioPro.configure() once, as early as possible in your app’s lifecycle — ideally in index.js or the root App component, outside any render function. Configuration is stored internally and applied when the first play() call is made.
index.js (or App.tsx)
import { AudioPro, AudioProContentType } from 'react-native-audio-pro';

AudioPro.configure({
  contentType: AudioProContentType.MUSIC, // or AudioProContentType.SPEECH
  progressIntervalMs: 1000,               // how often PROGRESS events fire (ms)
  cacheEnabled: true,                     // enable on-device caching
  maxCacheSize: 1024 * 1024 * 500,        // 500 MB cache limit
  debug: false,                           // set true to enable verbose logging
  debugIncludesProgress: false,           // set true to log every PROGRESS event
});
Call configure() exactly once, before any other AudioPro method. A good place is at the top level of index.js or inside a useEffect with an empty dependency array in your root App component. Re-calling it later is safe but configuration changes only take effect at the start of the next playback session.
3

Add tracks and start playback

Use addMediaItems() to populate the queue, then call play() to begin. Tracks are plain objects matching the AudioProTrack shape: a required id, url, title, and artwork, with optional artist and album fields plus any custom key/value pairs.
import { AudioPro } from 'react-native-audio-pro';
import type { AudioProTrack } from 'react-native-audio-pro';

const tracks: AudioProTrack[] = [
  {
    id: 'track-001',
    url: 'https://example.com/audio/episode-1.mp3',
    title: 'Episode 1: Getting Started',
    artist: 'My Podcast',
    artwork: 'https://example.com/artwork/episode-1.jpg',
  },
  {
    id: 'track-002',
    url: 'https://example.com/audio/episode-2.mp3',
    title: 'Episode 2: Going Deeper',
    artist: 'My Podcast',
    artwork: 'https://example.com/artwork/episode-2.jpg',
  },
];

// Add all tracks to the queue
AudioPro.addMediaItems(tracks);

// Start playback from the first track
AudioPro.play();
You can also seek to a specific track by index:
AudioPro.seekToMediaItem(1);  // jump to the second track
AudioPro.play();
Gapless playback between tracks in the queue is enabled by default — no extra configuration is needed.
4

Display state in a React component

The useAudioPro() hook subscribes to the player’s internal store and re-renders your component whenever state changes. It returns everything you need to build a player UI.
import { useAudioPro, AudioProState } from 'react-native-audio-pro';

const { 
  state,            // AudioProState enum: IDLE | LOADING | PLAYING | PAUSED | STOPPED | ERROR
  position,         // current playback position in milliseconds
  duration,         // total track duration in milliseconds
  bufferedPosition, // how much has been buffered, in milliseconds
  playingTrack,     // the currently active AudioProTrack object (or null)
  activeTrackIndex, // zero-based index of the current track in the queue
  playbackSpeed,    // current speed (0.25 – 2.0)
  volume,           // current volume (0.0 – 1.0)
  queueSize,        // total number of tracks in the queue
  error,            // last AudioProPlaybackErrorPayload, or null
} = useAudioPro();

​
Complete Minimal Example

The component below brings all four steps together into a self-contained player. Copy it into your project, adjust the track URLs, and it will play audio with play/pause controls, a live progress display, and track information pulled directly from the hook. 
import React, { useEffect } from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';

import {
  AudioPro,
  AudioProContentType,
  AudioProState,
  useAudioPro,
} from 'react-native-audio-pro';
import type { AudioProTrack } from 'react-native-audio-pro';

// Configure once at module level so it runs before any render
AudioPro.configure({
  contentType: AudioProContentType.MUSIC,
  progressIntervalMs: 1000,
});

const TRACKS: AudioProTrack[] = [
  {
    id: 'ep-1',
    url: 'https://example.com/audio/episode-1.mp3',
    title: 'Episode 1',
    artist: 'My Podcast',
    artwork: 'https://example.com/artwork/episode-1.jpg',
  },
  {
    id: 'ep-2',
    url: 'https://example.com/audio/episode-2.mp3',
    title: 'Episode 2',
    artist: 'My Podcast',
    artwork: 'https://example.com/artwork/episode-2.jpg',
  },
];

function formatMs(ms: number): string {
  const totalSeconds = Math.floor(ms / 1000);
  const minutes = Math.floor(totalSeconds / 60);
  const seconds = totalSeconds % 60;
  return `${minutes}:${seconds.toString().padStart(2, '0')}`;
}

export default function MiniPlayer() {
  const { state, position, duration, playingTrack } = useAudioPro();

  useEffect(() => {
    // Load the queue when the component mounts
    AudioPro.addMediaItems(TRACKS);
  }, []);

  const isPlaying = state === AudioProState.PLAYING;
  const isLoading = state === AudioProState.LOADING;

  const handlePlayPause = () => {
    if (isPlaying) {
      AudioPro.pause();
    } else {
      AudioPro.play();
    }
  };

  return (
    <View style={styles.container}>
      {/* Track info */}
      <Text style={styles.title} numberOfLines={1}>
        {playingTrack?.title ?? 'No track loaded'}
      </Text>
      <Text style={styles.artist} numberOfLines={1}>
        {playingTrack?.artist ?? ''}
      </Text>

      {/* Progress */}
      <Text style={styles.progress}>
        {formatMs(position)} / {formatMs(duration)}
      </Text>

      {/* Controls */}
      <View style={styles.controls}>
        <TouchableOpacity
          style={styles.btn}
          onPress={() => AudioPro.seekToPreviousMediaItem()}
        >
          <Text style={styles.btnText}>⏮</Text>
        </TouchableOpacity>

        <TouchableOpacity style={styles.playBtn} onPress={handlePlayPause}>
          <Text style={styles.playBtnText}>
            {isLoading ? '⏳' : isPlaying ? '⏸' : '▶'}
          </Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={styles.btn}
          onPress={() => AudioPro.seekToNextMediaItem()}
        >
          <Text style={styles.btnText}>⏭</Text>
        </TouchableOpacity>
      </View>

      {/* State label */}
      <Text style={styles.state}>{state}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    alignItems: 'center',
    padding: 24,
  },
  title: {
    fontSize: 18,
    fontWeight: '600',
    marginBottom: 4,
  },
  artist: {
    fontSize: 14,
    color: '#666',
    marginBottom: 16,
  },
  progress: {
    fontSize: 13,
    color: '#888',
    marginBottom: 20,
    fontVariant: ['tabular-nums'],
  },
  controls: {
    flexDirection: 'row',
    alignItems: 'center',
    gap: 16,
    marginBottom: 12,
  },
  btn: {
    padding: 12,
  },
  btnText: {
    fontSize: 24,
  },
  playBtn: {
    width: 64,
    height: 64,
    borderRadius: 32,
    backgroundColor: '#6366F1',
    alignItems: 'center',
    justifyContent: 'center',
  },
  playBtnText: {
    fontSize: 28,
    color: '#fff',
  },
  state: {
    fontSize: 12,
    color: '#aaa',
  },
});

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us