react-native-music-library

中文版

A powerful React Native library for accessing local music files with full metadata support. Built with React Native's New Architecture (TurboModules) for optimal performance.

Note: Currently only Android is implemented. iOS support is coming soon.

Features & Roadmap

• [x] 🎵 Access local music library with rich metadata(including lyrics)
• [x] 🚀 Built with TurboModules for maximum performance
• [x] 📄 Pagination support for large music collections
• [x] 🔍 Flexible sorting and filtering options
• [x] 📁 Directory-based filtering
• [x] 🔄 TypeScript support with full type definitions
• [x] 🎨 Base64 album artwork support
• [x] 🤖 Android support
• [ ] 📱 iOS support
• [ ] 📀 Album queries (getAlbumsAsync)
• [ ] 👨‍🎤 Artist queries (getArtistsAsync)
• [ ] 🎼 Genre queries (getGenresAsync)
• [ ] 🎵 Playlist support
• [ ] 🔍 Search functionality
• [ ] 📡 Real-time library change notifications

Installation

npm install @nodefinity/react-native-music-library

or

yarn add @nodefinity/react-native-music-library

Platform Support

This library supports multiple platforms with automatic platform detection:

• Android: Full native music library access
• iOS: Full native music library access (coming soon)
• Web: Fallback implementation with warnings (for React Native Web projects)

The library automatically provides the appropriate implementation based on your platform. On web, all methods will return empty results and show development warnings to help with development and testing.

Android Setup

For Android, add the following permission to your android/app/src/main/AndroidManifest.xml:

<!-- Android 13+ granular permission -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<!-- Android 12 and below traditional storage permission -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

iOS Setup (Coming Soon)

iOS implementation is not yet available. For now, you can add the permission to your Info.plist for future compatibility:

<key>NSAppleMusicUsageDescription</key>
<string>This app needs access to your music library to play songs</string>

Permissions

You need to request permission to access the music library before using this library. We recommend using one of these libraries:

• react-native-permissions
• expo-media-library (for Expo projects)

API Reference

getTracksAsync(options?)

Retrieves music tracks from the device's music library.

Parameters

• options (optional): AssetsOptions - Configuration options for the query

Returns

Promise that resolves to TrackResult containing:

• items: Array of Track objects
• hasNextPage: Boolean indicating if more tracks are available
• endCursor: String cursor for pagination
• totalCount: Total number of tracks (optional)

getTrackMetadataAsync(trackId)

Retrieves detailed metadata for a specific track, including lyrics and additional metadata from JAudioTagger.

Parameters

• trackId: string - The ID of the track to get metadata for

Returns

Promise that resolves to TrackMetadata containing:

interface TrackMetadata {
  id: string;              // Track ID

  // audio header
  duration: number;       // Duration in seconds
  bitrate: number;        // Bitrate in kbps
  sampleRate: number;     // Sample rate in Hz
  channels: number;       // Number of channels
  format: string;         // Audio format

  // tag info
  title: string;          // Track title
  artist: string;         // Artist name
  album: string;          // Album name
  year: number;           // Release year
  genre: string;          // Music genre
  track: number;          // Track number
  disc: number;           // Disc number
  composer: string;       // Composer
  lyricist: string;       // Lyricist
  lyrics: string;         // Lyrics content
  albumArtist: string;    // Album artist
  comment: string;        // Comment
}

Example

import { getTrackMetadataAsync } from '@nodefinity/react-native-music-library';

// Get metadata for a specific track
const metadata = await getTrackMetadataAsync('track-id-123');
console.log('Lyrics:', metadata.lyrics);
console.log('Additional metadata:', metadata.additionalMetadata);

Type Definitions

Track

interface Track {
  id: string;
  title: string;          // Track title
  artist: string;         // Artist name
  artwork: string;        // Artwork file URI
  album: string;          // Album name
  duration: number;       // Duration in seconds
  url: string;            // File URL or path
  createdAt: number;      // Date added (Unix timestamp)
  modifiedAt: number;     // Date modified (Unix timestamp)
  fileSize: number;       // File size in bytes
}

AssetsOptions

interface AssetsOptions {
  after?: string;          // Cursor for pagination
  first?: number;          // Max items to return (default: 20)
  sortBy?: SortByValue | SortByValue[];  // Sorting configuration
  directory?: string;      // Directory path to search
}

SortByValue

type SortByValue = SortByKey | [SortByKey, boolean];

type SortByKey = 
  | 'default'
  | 'artist' 
  | 'album'
  | 'duration'
  | 'createdAt'
  | 'modifiedAt'
  | 'trackCount';

TrackResult

interface TrackResult {
  items: Track[];          // Array of tracks
  hasNextPage: boolean;    // More items available?
  endCursor?: string;      // Cursor for next page
  totalCount?: number;     // Total count (optional)
}

Usage Examples

Basic Usage

import { getTracksAsync } from '@nodefinity/react-native-music-library';

const loadMusicLibrary = async () => {
  try {
    const result = await getTracksAsync();
    
    result.items.forEach(track => {
      console.log(`${track.title} by ${track.artist}`);
      console.log(`Duration: ${Math.floor(track.duration / 60)}:${track.duration % 60}`);
      console.log(`File: ${track.url}`);
    });
  } catch (error) {
    console.error('Failed to load music library:', error);
  }
};

Pagination

import { getTracksAsync } from '@nodefinity/react-native-music-library';

const loadAllTracks = async () => {
  let allTracks = [];
  let hasMore = true;
  let cursor;
  
  while (hasMore) {
    const result = await getTracksAsync({
      first: 100,
      after: cursor
    });
    
    allTracks = [...allTracks, ...result.items];
    hasMore = result.hasNextPage;
    cursor = result.endCursor;
  }
  
  console.log(`Loaded ${allTracks.length} tracks total`);
  return allTracks;
};

Sorting

import { getTracksAsync } from '@nodefinity/react-native-music-library';

// Sort by artist name (descending - default)
const tracksByArtist = await getTracksAsync({
  sortBy: 'artist'
});

// Sort by artist name ascending
const tracksByArtistAsc = await getTracksAsync({
  sortBy: ['artist', true]
});

// Multiple sort criteria
const tracksMultiSort = await getTracksAsync({
  sortBy: [
    ['artist', true],
    ['album', true],
    'duration'
  ]
});

Directory Filtering

import { getTracksAsync } from '@nodefinity/react-native-music-library';

// Get tracks from specific directory
const playlistTracks = await getTracksAsync({
  directory: '/Music/Playlists/Favorites'
});

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library