react-native-android-media-fetcher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rakesh Prasad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,398 @@
+# react-native-android-media-fetcher
+
+[![npm version](https://img.shields.io/npm/v/react-native-android-media-fetcher.svg)](https://www.npmjs.com/package/react-native-android-media-fetcher)
+[![license](https://img.shields.io/npm/l/react-native-android-media-fetcher.svg)](https://github.com/rakeshprasad28/react-native-android-media-fetcher/blob/main/LICENSE)
+[![Android](https://img.shields.io/badge/Platform-Android-green.svg)](https://developer.android.com/)
+
+A React Native package for fetching audio files with complete metadata from Android devices. Built with TypeScript, supports pagination, and provides progress events for large music libraries.
+
+## Features
+
+- 🎵 **Fetch all audio files** from device storage
+- 📊 **Rich metadata**: title, artist, album, duration, size, bitrate, genre, and more
+- 🎨 **Album art extraction** as base64 for easy display
+- 📑 **Efficient pagination** for large libraries
+- 📡 **Progress events** for real-time loading feedback
+- ⚡ **New Architecture ready** (TurboModules support)
+- 📱 **Expo compatible** (with config plugin)
+
+## Requirements
+
+- React Native >= 0.60.0
+- Android API 29+ (Android 10+)
+- Expo SDK 47+ (for Expo projects, requires development builds)
+
+## Installation
+
+### React Native CLI
+
+```bash
+npm install react-native-android-media-fetcher
+# or
+yarn add react-native-android-media-fetcher
+```
+
+The package uses auto-linking, so no manual linking is required for React Native 0.60+.
+
+### Expo
+
+```bash
+npx expo install react-native-android-media-fetcher
+```
+
+Add the plugin to your `app.json` or `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": ["react-native-android-media-fetcher"]
+  }
+}
+```
+
+> **Note:** This package requires a development build. It will not work with Expo Go.
+
+```bash
+npx expo prebuild
+npx expo run:android
+```
+
+## Setup
+
+### Add Permissions (React Native CLI)
+
+Add the following permissions to your `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- For Android 13+ (API 33+) -->
+    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
+    
+    <!-- For Android 10-12 (API 29-32) -->
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
+        android:maxSdkVersion="32" />
+
+    <application>
+        ...
+    </application>
+</manifest>
+```
+
+### Request Runtime Permissions
+
+You must request runtime permissions before using the library. Here's an example using React Native's built-in `PermissionsAndroid`:
+
+```typescript
+import { PermissionsAndroid, Platform } from 'react-native';
+
+async function requestAudioPermission(): Promise<boolean> {
+  if (Platform.OS !== 'android') return false;
+
+  try {
+    if (Platform.Version >= 33) {
+      const granted = await PermissionsAndroid.request(
+        PermissionsAndroid.PERMISSIONS.READ_MEDIA_AUDIO,
+        {
+          title: 'Audio Library Permission',
+          message: 'This app needs access to your audio library.',
+          buttonNeutral: 'Ask Me Later',
+          buttonNegative: 'Cancel',
+          buttonPositive: 'OK',
+        }
+      );
+      return granted === PermissionsAndroid.RESULTS.GRANTED;
+    } else {
+      const granted = await PermissionsAndroid.request(
+        PermissionsAndroid.PERMISSIONS.READ_EXTERNAL_STORAGE,
+        {
+          title: 'Storage Permission',
+          message: 'This app needs access to your storage to read audio files.',
+          buttonNeutral: 'Ask Me Later',
+          buttonNegative: 'Cancel',
+          buttonPositive: 'OK',
+        }
+      );
+      return granted === PermissionsAndroid.RESULTS.GRANTED;
+    }
+  } catch (err) {
+    console.warn(err);
+    return false;
+  }
+}
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { AudioFetcher } from 'react-native-android-media-fetcher';
+
+// Fetch first 20 audio files
+const result = await AudioFetcher.getAudioFiles({ pageSize: 20, offset: 0 });
+
+console.log(`Total files: ${result.totalCount}`);
+console.log(`Has more: ${result.hasMore}`);
+
+result.files.forEach((file) => {
+  console.log(`${file.title} - ${file.artist}`);
+});
+```
+
+### Pagination
+
+```typescript
+import { AudioFetcher } from 'react-native-android-media-fetcher';
+
+async function loadAudioFiles() {
+  const allFiles = [];
+  let offset = 0;
+  const pageSize = 50;
+  let hasMore = true;
+
+  while (hasMore) {
+    const result = await AudioFetcher.getAudioFiles({ pageSize, offset });
+    allFiles.push(...result.files);
+    offset = result.nextOffset;
+    hasMore = result.hasMore;
+  }
+
+  return allFiles;
+}
+```
+
+### Fetch All with Progress
+
+```typescript
+import { 
+  AudioFetcher, 
+  addProgressListener 
+} from 'react-native-android-media-fetcher';
+
+// Subscribe to progress updates
+const unsubscribe = addProgressListener((progress) => {
+  console.log(`Loading: ${progress.percentage}% (${progress.current}/${progress.total})`);
+});
+
+// Fetch all files
+const allFiles = await AudioFetcher.getAllAudioFiles();
+
+// Clean up listener
+unsubscribe();
+
+console.log(`Loaded ${allFiles.length} audio files`);
+```
+
+### Get Single File by ID
+
+```typescript
+import { AudioFetcher } from 'react-native-android-media-fetcher';
+
+const file = await AudioFetcher.getAudioFileById('12345');
+
+if (file) {
+  console.log(`Title: ${file.title}`);
+  console.log(`Artist: ${file.artist}`);
+  console.log(`Duration: ${file.duration}ms`);
+}
+```
+
+### Get Total Count
+
+```typescript
+import { AudioFetcher } from 'react-native-android-media-fetcher';
+
+const count = await AudioFetcher.getTotalAudioCount();
+console.log(`Device has ${count} audio files`);
+```
+
+### Display Album Art
+
+```typescript
+import { Image } from 'react-native';
+
+// file.albumArt is a base64 string
+{file.albumArt && (
+  <Image
+    source={{ uri: `data:image/jpeg;base64,${file.albumArt}` }}
+    style={{ width: 100, height: 100 }}
+  />
+)}
+```
+
+### React Hook Example
+
+```typescript
+import { useState, useEffect, useCallback } from 'react';
+import { 
+  AudioFetcher, 
+  addProgressListener,
+  type AudioFile,
+  type FetchProgress 
+} from 'react-native-android-media-fetcher';
+
+function useAudioLibrary() {
+  const [files, setFiles] = useState<AudioFile[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [progress, setProgress] = useState<FetchProgress | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const loadFiles = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+
+    const unsubscribe = addProgressListener(setProgress);
+
+    try {
+      const allFiles = await AudioFetcher.getAllAudioFiles();
+      setFiles(allFiles);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load files');
+    } finally {
+      setLoading(false);
+      setProgress(null);
+      unsubscribe();
+    }
+  }, []);
+
+  return { files, loading, progress, error, loadFiles };
+}
+```
+
+## API Reference
+
+### AudioFetcher
+
+#### `getAudioFiles(options?: FetchOptions): Promise<FetchResult>`
+
+Fetches audio files with pagination.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pageSize` | `number` | 50 | Number of files per page (max: 500) |
+| `offset` | `number` | 0 | Starting position |
+
+Returns `FetchResult`:
+
+```typescript
+interface FetchResult {
+  files: AudioFile[];      // Array of audio files
+  totalCount: number;      // Total files on device
+  hasMore: boolean;        // Whether more files exist
+  nextOffset: number;      // Offset for next page
+}
+```
+
+#### `getAllAudioFiles(): Promise<AudioFile[]>`
+
+Fetches all audio files. Use with `addProgressListener` for progress updates.
+
+#### `getAudioFileById(id: string): Promise<AudioFile | null>`
+
+Fetches a single audio file by its ID.
+
+#### `getTotalAudioCount(): Promise<number>`
+
+Returns the total count of audio files on the device.
+
+### Event Functions
+
+#### `addProgressListener(listener: ProgressListener): Unsubscribe`
+
+Subscribes to progress updates during `getAllAudioFiles()`.
+
+```typescript
+type ProgressListener = (progress: FetchProgress) => void;
+
+interface FetchProgress {
+  current: number;     // Files processed
+  total: number;       // Total files
+  percentage: number;  // Progress 0-100
+}
+```
+
+#### `addErrorListener(listener: ErrorListener): Unsubscribe`
+
+Subscribes to error events.
+
+#### `removeAllListeners(): void`
+
+Removes all event listeners.
+
+### AudioFile Interface
+
+```typescript
+interface AudioFile {
+  id: string;              // Unique identifier
+  uri: string;             // Content URI
+  displayName: string;     // Filename with extension
+  title: string;           // Track title
+  artist: string;          // Artist name
+  album: string;           // Album name
+  duration: number;        // Duration in milliseconds
+  size: number;            // File size in bytes
+  mimeType: string;        // MIME type (e.g., "audio/mpeg")
+  dateAdded: number;       // Unix timestamp (seconds)
+  dateModified: number;    // Unix timestamp (seconds)
+  albumArt: string | null; // Base64 encoded album art
+  path: string;            // Absolute file path
+  bitrate: number;         // Bitrate in bps
+  sampleRate: number;      // Sample rate in Hz
+  albumArtist: string;     // Album artist
+  composer: string;        // Composer
+  genre: string;           // Genre
+  year: number;            // Release year
+  trackNumber: number;     // Track number
+}
+```
+
+### Supported Audio Formats
+
+All audio formats recognized by Android MediaStore:
+
+- MP3, M4A, AAC, FLAC, WAV
+- OGG, OPUS, WMA, AMR
+- MIDI, and more
+
+## Troubleshooting
+
+### "The package doesn't seem to be linked"
+
+1. Make sure you've rebuilt the app after installing:
+   ```bash
+   cd android && ./gradlew clean && cd ..
+   npx react-native run-android
+   ```
+
+2. For Expo, ensure you're using a development build, not Expo Go.
+
+### No audio files returned
+
+1. Verify permissions are granted:
+   ```typescript
+   const granted = await PermissionsAndroid.check(
+     Platform.Version >= 33 
+       ? PermissionsAndroid.PERMISSIONS.READ_MEDIA_AUDIO
+       : PermissionsAndroid.PERMISSIONS.READ_EXTERNAL_STORAGE
+   );
+   console.log('Permission granted:', granted);
+   ```
+
+2. Check if audio files exist on the device/emulator.
+
+### Album art not showing
+
+Album art extraction depends on:
+- Having embedded artwork in the audio file
+- Sufficient permissions
+
+Some files may not have embedded album art. In those cases, `albumArt` will be `null`.
+
+## License
+
+MIT © [Rakesh Prasad](https://github.com/rakeshprasad28)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

package/android/build.gradle

@@ -0,0 +1,111 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath "com.android.tools.build:gradle:8.1.0"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0"
+    }
+}
+
+def isNewArchitectureEnabled() {
+    return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+if (isNewArchitectureEnabled()) {
+    apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["AndroidMediaFetcher_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["AndroidMediaFetcher_" + name]).toInteger()
+}
+
+def supportsNamespace() {
+    def parsed = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')
+    def major = parsed[0].toInteger()
+    def minor = parsed[1].toInteger()
+    return (major == 7 && minor >= 3) || major >= 8
+}
+
+android {
+    if (supportsNamespace()) {
+        namespace "com.androidmediafetcher"
+
+        sourceSets {
+            main {
+                manifest.srcFile "src/main/AndroidManifestNew.xml"
+            }
+        }
+    }
+
+    compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+    defaultConfig {
+        minSdkVersion 29
+        targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+    }
+
+    buildFeatures {
+        buildConfig true
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+
+    lintOptions {
+        disable "GradleCompatible"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+
+    sourceSets {
+        main {
+            if (isNewArchitectureEnabled()) {
+                java.srcDirs += ["src/newarch"]
+            } else {
+                java.srcDirs += ["src/oldarch"]
+            }
+        }
+    }
+}
+
+repositories {
+    mavenCentral()
+    google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+    implementation "com.facebook.react:react-native:+"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
+}
+
+if (isNewArchitectureEnabled()) {
+    react {
+        jsRootDir = file("../src/")
+        libraryName = "AndroidMediaFetcher"
+        codegenJavaPackageName = "com.androidmediafetcher"
+    }
+}

package/android/gradle.properties

@@ -0,0 +1,3 @@
+AndroidMediaFetcher_kotlinVersion=1.9.0
+AndroidMediaFetcher_compileSdkVersion=34
+AndroidMediaFetcher_targetSdkVersion=34

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.androidmediafetcher">
+</manifest>

package/android/src/main/AndroidManifestNew.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/androidmediafetcher/AndroidMediaFetcherPackage.kt

@@ -0,0 +1,21 @@
+package com.androidmediafetcher
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * React Native Package registration for AndroidMediaFetcher
+ * This registers the native module with React Native
+ */
+class AndroidMediaFetcherPackage : ReactPackage {
+    
+    override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+        return listOf(AndroidMediaFetcherModule(reactContext))
+    }
+
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}

package/android/src/main/java/com/androidmediafetcher/models/AudioFile.kt

@@ -0,0 +1,57 @@
+package com.androidmediafetcher.models
+
+import org.json.JSONObject
+
+/**
+ * Data class representing an audio file with all its metadata
+ */
+data class AudioFile(
+    val id: String,
+    val uri: String,
+    val displayName: String,
+    val title: String,
+    val artist: String,
+    val album: String,
+    val duration: Long,
+    val size: Long,
+    val mimeType: String,
+    val dateAdded: Long,
+    val dateModified: Long,
+    val albumArt: String?,
+    val path: String,
+    val bitrate: Int,
+    val sampleRate: Int,
+    val albumArtist: String,
+    val composer: String,
+    val genre: String,
+    val year: Int,
+    val trackNumber: Int
+) {
+    /**
+     * Convert AudioFile to JSON object for passing to JavaScript
+     */
+    fun toJson(): JSONObject {
+        return JSONObject().apply {
+            put("id", id)
+            put("uri", uri)
+            put("displayName", displayName)
+            put("title", title)
+            put("artist", artist)
+            put("album", album)
+            put("duration", duration)
+            put("size", size)
+            put("mimeType", mimeType)
+            put("dateAdded", dateAdded)
+            put("dateModified", dateModified)
+            put("albumArt", albumArt ?: JSONObject.NULL)
+            put("path", path)
+            put("bitrate", bitrate)
+            put("sampleRate", sampleRate)
+            put("albumArtist", albumArtist)
+            put("composer", composer)
+            put("genre", genre)
+            put("year", year)
+            put("trackNumber", trackNumber)
+        }
+    }
+}