React Native Anything Player (RNAP)

react-native-anything-player is a native-first audio player for React Native and the web — files, streams and internet radio, with opt-in video — that keeps playing correctly in the background, through network loss, interruptions and JavaScript freezes. One API on iOS, Android, Expo web, React Native Web, React (Vite, Next.js) and plain web pages, with AirPlay, Google Cast and the voice assistants.

import { Player } from 'react-native-anything-player';

const player = new Player();
await player.load('https://radio.example.com/stream');
await player.play();

That is the whole integration for a radio that reconnects on its own, survives Wi-Fi ↔ cellular handoffs, respects phone calls and other apps, shows the station and the current song (from ICY metadata) on the lock screen, and releases its connection when paused.

Why

Playback logic that lives in JavaScript breaks in exactly the situations a player must handle: React Native suspends JS timers in the background, the JS thread can be frozen or reloaded, and native events race JS commands. RNAP keeps the whole player — state machine, recovery, audio focus, interruptions, media session, clocks — in native code. On iOS and Android, JavaScript sends commands and mirrors native state, and a frozen JS thread does not stop playback. Only what you ask JavaScript for needs it (refresh, getLicense, sideloaded subtitles); on the web the engine itself is JavaScript.

RNAP was built by @rmotafreitas, developer of the Rádio Animu mobile app and part of the animu.moe team, when React Native Track Player went commercial (v5 needs a paid licence even for a free app from a non-profit) and staying on air through a dropped network, a phone call or a switch to Instagram still took a pile of app code with every available player. docs/why.md has the full story with sources; docs/recovery.md lists every recovery rule and the failure behind it.

Read from each library's published source; sizes, methodology and the gaps RNAP still has are in Comparison & benchmarks and the roadmap.

Features

• Sources: local files, bundled assets (require('./a.mp3')), content:// URIs, HTTP(S) files, progressive streams, HLS, ICY (Shoutcast/Icecast) radio.
• Internet radio: ICY metadata (title/artist/station, charset repair, StreamUrl artwork), live-edge recovery, gapless reconnects when a station drops the connection, exactly one connection per stream (verified against a connection-counting server), paused-stream connection release.
• Recovery: stall and silent-stall detection, dead-socket re-open, jittered exponential backoff, offline-aware probing, network-handoff awareness, a give-up limit, circuit breakers against connection storms.
• System integration: background playback, lock screen / Control Center / notification, headset, Bluetooth, car and Wear controls, Android audio focus (incl. Android 15 rules), iOS interruptions, output disconnects, media-services reset.
• Correctness: per-open generations reject stale native events; commands are applied in call order; status snapshots are sequence-numbered; events are ordered after the status they imply.
• Video (opt-in): a Player with a picture. HLS, DASH, MP4, and MKV, WebM and MPEG-TS through a remux; renditions, subtitles, DRM, fullscreen, Picture in Picture, AirPlay and Cast. See Video.
• Visualizer: decoded-audio windows (audioSample) on iOS, Android and the web — including live HTTP streams on iOS, where AVPlayer's audio tap never runs.
• Outputs and casting: where the audio goes (status.route), the system output picker (<RoutePicker />: AirPlay, Android's Output Switcher), and Google Cast as a build option (<CastButton />), with radio titles kept while casting.
• Voice assistants: a catalog stored on the device answers "Hey Siri / Hey Google, play X on MyApp", even with the app closed; Siri shortcuts on iOS 16+; the same search on the web (playFromSearch).
• Cars & watches: one browse tree from the catalog (group, favorites, recently played) in Android Auto, Android Automotive OS, Wear OS and CarPlay; opt-in with car. See Cars & watches.
• Song progress for radio: give the current song's duration and the lock screen shows its progress, advanced natively.

Install

npm install react-native-anything-player
# or: yarn add react-native-anything-player / pnpm add react-native-anything-player

This is the beginning of the README. Read the rest at the original. Read the full README ↗