DOCSEARCHbyAlgolia
Submit Docs

React Native Audio Pro

repository·main·Indexed 41 days ago

https://github.com/evergrace-co/react-native-audio-pro

A React Native module for professional-grade audio playback from remote URLs, optimized for long-form content like podcasts and audiobooks. Version 11.0.0-beta.2 features background playback, lock screen notification controls for Android (Media3) and iOS (AVFoundation), and web support. It includes an imperative API for playback control, a `useAudioPro` React hook for state management, and a dedicated Ambient Audio API for background sounds.

Tokens
15K
Snippets
45
Records
71
Agent score
49%

What's inside React Native Audio Pro

  1. Overview of react-native-audio-pro features

    main

    React Native Audio Pro is a modern audio playback library designed for long-form media like podcasts and audiobooks.

    Core Features

    • Remote Audio Playback: Play MP3 and other files via HTTP(S).
    • Background Playback: Audio continues when the screen is locked or the app is backgrounded.
    • Lock Screen Controls: Native media controls on Android and iOS.
    • Artwork Support: Display JPEG/PNG album art on media controls.
    • Notification Center Integration: Android media session support.
    • Progress Tracking: Configurable position/duration updates.
    • Imperative API: Methods for play, pause, resume, stop, etc.
    • Volume Control: Real-time volume adjustments.
    • Start Time Support: Begin playback from a specific timestamp.
    • HTTP Headers: Custom headers for audio and artwork URLs.

    Add-On Features

    • Ambient Audio API: A secondary player for layered/background audio.
    • Local Files: Support for file:// paths.
    • Autoplay + Timers: Support for autoPlay and startTimeMs.

  2. Core capabilities of React Native Audio Pro

    main

    React Native Audio Pro is a high-performance audio playback library designed for playing remote audio files (HTTPS) on iOS and Android. It focuses on reliable playback, background support, and lock screen integration.

    Supported Core Features

    • HTTPS Audio Playback: Play MP3 and other formats over HTTP(S).
    • Background Playback: Audio continues playing when the screen is locked or the app is backgrounded.
    • Lock Screen Controls: Media controls and artwork (JPEG, PNG) support on Android and iOS.
    • Notification Center Integration: Android media session support.
    • Imperative API: Direct control via methods like play, pause, resume, and stop.
    • Progress Tracking: Configurable interval updates for position and duration.
    • Volume & Speed Control: Real-time control of audio volume and playback speed.
    • Custom HTTP Headers: Ability to pass headers for both audio and artwork URLs.
    • Native Foundations: Uses Media3 on Android and AVFoundation on iOS.

  3. Playback and Control Features

    main

    The library provides comprehensive control over audio playback, including:

    • Playback Controls: play, pause, resume, seek, stop, and clear.
    • Audio Routing: Supports background playback and audio routing.
    • Media Integration: Integration with Lock screen and media sessions on both Android and iOS.
    • Volume Control: Native volume control using a range of 0.0 to 1.0 (this controls the player volume and does not affect the system-wide volume).
    • Playback Speed: Control playback speed from 0.25x to 2.0x.
    • State Updates: Reactive state and position updates are available via the useAudioPro hook and event listeners.
    • Progress Updates: Fine-grained progress update intervals can be configured between 100ms and 10,000ms (default is 1000ms).
    • Global Configuration: Supports setting content types, such as MUSIC vs SPEECH.

  4. What is out of scope in React Native Audio Pro

    main

    The following features are not supported and are not on the current roadmap. If your application requires these, you may need to implement them manually or use a different library:

    • Local Files via require(): Static asset imports are not supported. Use file paths (e.g., via react-native-fs) if you need to play local files.
    • Web Support: This is a native-only library (iOS and Android).
    • Playlist System: No built-in support for shuffling, repeating, or skipping tracks (though playlist support is a roadmap consideration).
    • Car Integration: No support for Android Auto or Apple CarPlay.
    • Custom 'End At' Timers: Logic for stopping audio after a certain time must be implemented in your app using progress events.
    • Offline Caching/Downloads: No built-in support for downloading or caching audio files.

  5. Understand Ambient Audio Logic

    main

    Ambient audio in react-native-audio-pro provides a minimal, isolated layer for playing ambient or looping audio tracks independently of the main playback system. It is architecturally separated from the main player to ensure no cross-interference.

    Key Characteristics

    • Isolation: Ambient audio has no shared variables, player instances, or event emitters with the main playback logic. Commands like play(), pause(), or stop() on the main player do not affect ambient audio.
    • Looping: Tracks loop by default unless loop: false is explicitly provided.
    • No State Tracking: The system does not track volume, progress, or playback state. There are no getters for volume or progress.
    • Automatic Cleanup: Calling stopAmbient() or allowing a non-looping track to finish will automatically tear down the player and release resources. Errors also trigger automatic cleanup.
    • Prefixing: All ambient-related functions and events are prefixed with ambient to prevent namespace collisions.

  6. Supported Audio Sources in react-native-audio-pro

    main

    The library supports two primary types of audio sources:

    1. Static remote URLs: Standard web URLs (e.g., https://example.com/audio.mp3).
    2. Locally downloaded file paths: Local filesystem paths (e.g., /data/user/0/com.app/files/foo.mp3).

    Note on Local Paths: The TypeScript layer automatically prefixes local paths with file:// if the prefix is not already present, ensuring compatibility with native modules.

  7. Understand AudioProState values

    main

    The player moves through several states:

    • IDLE: Default state; no track loaded.
    • STOPPED: Playback stopped, position at 0, track remains loaded.
    • LOADING: Track is buffering or loading.
    • PLAYING: Audio is currently playing.
    • PAUSED: Playback is paused at the current position.
    • ERROR: An error occurred. Use AudioPro.getError() to inspect.

  8. Understand the Playback State Flow

    main

    The playback state is managed exclusively by native code (Swift/Kotlin). The TypeScript layer must never attempt to infer or emit state; it should only listen for state changes emitted by the native side. This ensures the native media session remains the single source of truth.

    Method to State Transitions

    MethodDescriptionState TransitionsEmits
    configure()Set playback behavior (e.g., speech/music mode, debug)NoneNone
    play(track, opts)Load & start track→ LOADING → PLAYING or → LOADING → PAUSEDSTATE_CHANGED: LOADING, then PLAYING or PAUSED
    pause()Pause playback→ PAUSEDSTATE_CHANGED: PAUSED
    resume()Resume playback→ PLAYINGSTATE_CHANGED: PLAYING
    stop()Stop playback, reset position→ STOPPEDSTATE_CHANGED: STOPPED
    clear()Full teardown→ IDLESTATE_CHANGED: IDLE
    onError()Critical error→ ERRORSTATE_CHANGED: ERROR, PLAYBACK_ERROR
    seekTo() / seekForward() / seekBack()Seek to new position (via TypeScript)No state changeSEEK_COMPLETE
    setPlaybackSpeed()Adjust speedNo state changePLAYBACK_SPEED_CHANGED

  12. Reload the application

    main

    If you need to perform a full reload to reset the app state, use the following platform-specific shortcuts:

    • Android: Press the <kbd>R</kbd> key twice, or open the Dev Menu via <kbd>Ctrl</kbd> + <kbd>M</kbd> (Windows/Linux) or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> (macOS) and select "Reload".
    • iOS: Press <kbd>R</kbd> in the iOS Simulator.