react-native-music-library

中文

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

✨ Features

• 🎵 Rich Metadata - Access local music with full metadata including lyrics, bitrate, sample rate, and more
• 🚀 TurboModules - Built with React Native's New Architecture for maximum performance
• 📄 Pagination - Cursor-based pagination for efficiently handling large music collections
• 🔍 Flexible Sorting - Multiple sorting options for tracks, albums, and artists
• 📁 Directory Filtering - Filter tracks by specific directories (Android)
• 🔄 TypeScript - Full type definitions and type safety
• 🎨 Album Artwork - Support for album artwork and cover images
• 🤖 Android - Full native Android implementation
• 🍎 iOS - Full native iOS implementation via MediaPlayer framework

🚀 Quick Start

Installation

npm install @nodefinity/react-native-music-library
# or
yarn add @nodefinity/react-native-music-library

Permissions

Android — add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

iOS — add to Info.plist:

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

Basic Usage

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

// Get first 20 tracks sorted by title
const result = await getTracksAsync({ sortBy: ['title', true] });
console.log(result.items); // Track[]
console.log(result.hasNextPage); // boolean
console.log(result.endCursor); // string | undefined

// Get next page
const nextPage = await getTracksAsync({
  sortBy: ['title', true],
  first: 20,
  after: result.endCursor,
});

📖 API

getTracksAsync(options?)

Returns a paginated list of tracks from the music library.

getTracksAsync(options?: TrackOptions): Promise<PaginatedResult<Track>>

TrackOptions

| Property | Type | Default | Description | | ----------- | -------------------------------------------------------- | ----------- | --------------------------------------- | | first | number | 20 | Max number of items to return | | after | string | — | Cursor from previous page's endCursor | | sortBy | TrackSortByKey \| [TrackSortByKey, boolean] \| (...)[] | 'default' | Sort key, or tuple [key, ascending] | | directory | string | — | Filter by directory path (Android only) |

TrackSortByKey: 'default' \| 'title' \| 'artist' \| 'album' \| 'duration' \| 'createdAt' \| 'modifiedAt' \| 'fileSize'

getTrackMetadataAsync(trackId)

Returns detailed audio metadata for a single track.

getTrackMetadataAsync(trackId: string): Promise<TrackMetadata>

getTracksByAlbumAsync(albumId)

Returns all tracks in an album (no pagination).

getTracksByAlbumAsync(albumId: string): Promise<Track[]>

getTracksByArtistAsync(artistId, options?)

Returns a paginated list of tracks by an artist.

getTracksByArtistAsync(artistId: string, options?: TrackOptions): Promise<PaginatedResult<Track>>

getAlbumsAsync(options?)

Returns a paginated list of albums.

getAlbumsAsync(options?: AlbumOptions): Promise<PaginatedResult<Album>>

AlbumOptions

| Property | Type | Default | Description | | -------- | -------------------------------------------------------- | ----------- | --------------------------------------- | | first | number | 20 | Max number of items to return | | after | string | — | Cursor from previous page's endCursor | | sortBy | AlbumSortByKey \| [AlbumSortByKey, boolean] \| (...)[] | 'default' | Sort key, or tuple [key, ascending] |

AlbumSortByKey: 'default' \| 'title' \| 'artist' \| 'trackCount' \| 'year'

getAlbumsByArtistAsync(artistId)

Returns all albums by an artist (no pagination).

getAlbumsByArtistAsync(artistId: string): Promise<Album[]>

getArtistsAsync(options?)

Returns a paginated list of artists.

getArtistsAsync(options?: ArtistOptions): Promise<PaginatedResult<Artist>>

ArtistOptions

| Property | Type | Default | Description | | -------- | ---------------------------------------------------------- | ----------- | --------------------------------------- | | first | number | 20 | Max number of items to return | | after | string | — | Cursor from previous page's endCursor | | sortBy | ArtistSortByKey \| [ArtistSortByKey, boolean] \| (...)[] | 'default' | Sort key, or tuple [key, ascending] |

ArtistSortByKey: 'default' \| 'title' \| 'trackCount' \| 'albumCount'

📦 Types

Track

| Field | Type | Description | | ------------ | --------- | ----------------------------------- | | id | string | Unique identifier | | title | string | Track title | | artist | string | Artist name | | artwork | string? | Artwork file URI (may be undefined) | | album | string | Album name | | duration | number | Duration in seconds | | url | string | File URI | | createdAt | number | Unix timestamp (seconds) | | modifiedAt | number | Unix timestamp (seconds) | | fileSize | number | File size in bytes |

TrackMetadata

| Field | Type | Description | | ------------- | -------- | ------------------------------------ | | id | string | Track ID | | duration | number | Duration in seconds | | bitrate | number | Bitrate in kbps | | sampleRate | number | Sample rate in Hz | | channels | string | Number of audio channels | | format | string | Audio format (e.g. "AAC", "MP3") | | title | string | Title tag | | artist | string | Artist tag | | album | string | Album tag | | year | number | Release year | | genre | string | Genre tag | | track | number | Track number | | disc | number | Disc number | | composer | string | Composer tag | | lyricist | string | Lyricist tag | | lyrics | string | Embedded lyrics | | albumArtist | string | Album artist tag | | comment | string | Comment tag |

Album

| Field | Type | Description | | ------------ | --------- | ------------------------------ | | id | string | Unique identifier | | title | string | Album name | | artist | string | Primary artist | | artwork | string? | Artwork URI (may be undefined) | | trackCount | number | Number of tracks | | year | number? | Release year |

Artist

| Field | Type | Description | | ------------ | -------- | ---------------------- | | id | string | Unique identifier | | title | string | Artist name | | albumCount | number | Number of albums | | trackCount | number | Total number of tracks |

PaginatedResult<T>

| Field | Type | Description | | ------------- | --------- | ----------------------------------------- | | items | T[] | Array of results | | hasNextPage | boolean | Whether more items are available | | endCursor | string? | Pass to after to fetch next page | | totalCount | number? | Total count (may be expensive to compute) |

🔄 Pagination Example

async function fetchAllTracks() {
  const allTracks = [];
  let cursor: string | undefined;

  do {
    const result = await getTracksAsync({ first: 50, after: cursor });
    allTracks.push(...result.items);
    cursor = result.hasNextPage ? result.endCursor : undefined;
  } while (cursor);

  return allTracks;
}

🤝 Contributing

See CONTRIBUTING.md for details.

📄 License

MIT License - see LICENSE for details.