react-native-local-audio
v1.0.3
Published
A React Native module to fetch local audio files with metadata (Android support, iOS coming soon).
Maintainers
Readme
📖 README.md
# react-native-local-audio
A lightweight React Native native module to fetch **local audio files** (with metadata like title, artist, album, and artwork) directly from the device storage.
✅ Works on **Android 6+**
⚠️ iOS support not yet implemented (coming soon).
---
## ✨ Features
- Fetch all audio files from device storage
- Optional parameters:
- `sortBy` → `TITLE | ARTIST | ALBUM | DATE_ADDED`
- `orderBy` → `ASC | DESC`
- `limit` → number of items
- `offset` → pagination offset
- `artworkQuality` → album artwork quality (0–100)
- Fetch songs by album
- Search songs by title
- Returns metadata: `id`, `url`, `title`, `artist`, `album`, `artwork`
---
## 📦 Installation
```sh
# install via npm
npm install react-native-local-audio
# or via yarn
yarn add react-native-local-audio
```// add in the android/settings.gradle
include ':react-native-local-audio'
project(':react-native-local-audio').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-local-audio/android')
// dependencies add in the android/app/build.gradle
implementation project(':react-native-local-audio')🔗 Linking
If you’re using React Native 0.60+, autolinking works automatically. For React Native <0.60, manually link:
react-native link react-native-local-audio⚙️ Android Setup
- Open
android/build.gradleand make sureminSdkVersionis 23 or higher:
ext {
minSdkVersion = 23
targetSdkVersion = 34
compileSdkVersion = 34
}- Add storage permissions in your
AndroidManifest.xml:
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29"/>- For Android 11+ (API 30+), add scoped storage permission:
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" tools:ignore="ScopedStorage"/>⚠️ You must request permissions at runtime using PermissionsAndroid.
🚀 Usage
import AudioModule from "react-native-local-audio";
// Example: get all audio
const songs = await AudioModule.getAllAudio({
sortBy: "TITLE",
orderBy: "ASC",
limit: 20,
offset: 0,
artworkQuality: 50, // Album artwork quality
});
console.log(songs);
// [
// {
// "id": 55,
// "title": "Hangouts Call",
// "artist": "<unknown>",
// "album": "Ringtones",
// "url": "/storage/emulated/0/Android/media/com.google.android.talk/Ringtones/hangouts_incoming_call.ogg",
// "artwork": "content://media/external/audio/albumart/2",
// "category": "ringtone",
// "artworkQuality": 50
// }
]
// Example: get songs by album
const albums = await AudioModule.getSongsByAlbum();
console.log(albums);
// Example: search songs by title
const searchResult = await AudioModule.searchSongsByTitle({ title: "ale" });
console.log(searchResult);🛠 Development (for contributors)
Clone the repo and install dependencies:
git clone https://github.com/nepolionchakma/react-native-local-audio.git
cd react-native-local-audio
yarn installBuild TypeScript:
yarn buildRun example project:
cd example
yarn install
yarn android📤 Publishing to NPM
- Build the package:
yarn build- Login to npm:
npm login- Publish:
npm publish --access public- Install in any app:
yarn add react-native-local-audio
# or
npm install react-native-local-audio📌 Roadmap
- [x] Android support
- [ ] iOS support
- [ ] Playlist management
- [ ] Audio player integration
📄 License
MIT © 2025 License
