1.3.2 • Published 2 months ago

expo-music-library

Licence

MIT

Version

1.3.2

Deps

Size

199 kB

Vulns

Weekly

Summary Dependency Versions

Expo Music Library

An Expo native module for querying audio-library metadata, availability, albums, artists, genres, playlists, and folders on Android and iOS.

The library deliberately distinguishes an item being visible in the music library from its audio being available to a third-party app. This matters on iOS, where Apple Music and iCloud items can have complete metadata but no local, unprotected audio URL.

Features

Paginated audio queries, search, filters, and sorting
Albums, artists, genres, and platform collections
Explicit local, cloud-only, DRM-protected, and unavailable states
Opt-in lazy artwork URIs while preserving existing artwork output by default
Android MediaStore and iOS MediaPlayer implementations
Coarse library-change notifications
TypeScript types and an Expo config plugin

Platform and Expo compatibility

Environment	Support
Android physical device/emulator	Supported when the media library contains audio
iOS physical device	Supported
iOS Simulator	Module compiles, but the simulator has no real Music library
Web	Native API unavailable; `isAvailableAsync()` safely returns `false`
Expo Go	Not supported; use a development build

Version 1.3.2 targets Expo SDK 55 through 57:

Expo SDK	React Native	React	Minimum Node.js	Expo host minimums
55	0.83	19.2	20.19	Android 7+, iOS 15.1+
56	0.85	19.2	20.19	Android 7+, iOS 16.4+
57	0.86	19.2	22.13	Android 7+, iOS 16.4+

See the Expo SDK version table for the authoritative host requirements. Expo SDK 55 and newer always use React Native's New Architecture.

Installation

npx expo install expo-music-library

Add the config plugin:

{
  "expo": {
    "plugins": [
      [
        "expo-music-library",
        {
          "musicLibraryPermission": "Allow $(PRODUCT_NAME) to access your music library."
        }
      ]
    ]
  }
}

Then regenerate or rebuild the native project:

npx expo prebuild
npx expo run:ios
# or
npx expo run:android

This package contains native code, so adding it requires a new native build. An over-the-air JavaScript update alone is not enough.

What the config plugin changes

Platform	Configuration
iOS	Adds `NSAppleMusicUsageDescription`
Android 13+	Adds `READ_MEDIA_AUDIO`
Android 12 and older	Adds `READ_EXTERNAL_STORAGE` with `maxSdkVersion="32"`

The module does not need Photos permission to read MPMediaItemArtwork.

For bare projects that do not run Expo prebuild, apply the equivalent settings manually:

<!-- ios/Info.plist -->
<key>NSAppleMusicUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to access your music library.</string>

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission
  android:name="android.permission.READ_EXTERNAL_STORAGE"
  android:maxSdkVersion="32" />

Basic usage

import * as MusicLibrary from "expo-music-library";

async function loadSongs() {
  if (!(await MusicLibrary.isAvailableAsync())) {
    return [];
  }

  const permission = await MusicLibrary.requestPermissionsAsync();
  if (!permission.granted) {
    return [];
  }

  const page = await MusicLibrary.getAssetsAsync({
    first: 50,
    sortBy: ["title", true],
    availability: "all",
    artwork: "uri",
  });

  return page.assets;
}

["title", true] means title ascending. Multiple sort values use an array:

sortBy: [["artist", true], ["album", true], "title"];

Page sizes must be integers from 1 through 1000.

Audio availability

Queries return metadata-only entries by default. Inspect availability before passing an item to AVFoundation, an audio player, an exporter, or a stem separator:

const page = await MusicLibrary.getAssetsAsync({
  availability: "all",
});

for (const track of page.assets) {
  if (!track.isLocallyAvailable || !track.canAccessWithAVFoundation) {
    console.log(track.title, track.availability, track.availabilityReason);
    continue;
  }

  const audioUri = track.assetUrl || track.contentUri || track.uri;
  // Use audioUri with an API that supports its URI kind.
}

Availability values are:

Value	Meaning
`local`	The platform exposes audio the app can access
`cloud`	The item is visible but is not downloaded locally
`protected`	The item is DRM-protected
`unavailable`	No usable native audio URL is currently exposed

Useful fields include:

type AssetAvailabilityStatus =
  | "local"
  | "cloud"
  | "protected"
  | "unavailable";

type Asset = {
  // Existing 1.x fields
  id: string;
  title: string;
  artist: string;
  uri: string;
  artwork?: string;
  duration: number;

  // Additive 1.3.1 fields
  assetUrl?: string | null;
  contentUri?: string | null;
  uriKind?: "ipod-library" | "content" | "file" | "none";
  artworkUri?: string | null;
  availability?: AssetAvailabilityStatus;
  availabilityReason?: "cloud" | "protected" | "missingAssetUrl" | null;
  isCloudItem?: boolean;
  hasProtectedAsset?: boolean;
  hasAssetUrl?: boolean;
  hasLocalAssetURL?: boolean;
  canAccessWithAVFoundation?: boolean;
  isLocallyAvailable?: boolean;
  isPlayable?: boolean;
  mimeType?: string | null;
  fileSize?: number | null;
  albumTitle?: string | null;
  trackNumber?: number | null;
  discNumber?: number | null;
};

uri remains a required string for 1.x compatibility, but it may be empty for an iOS metadata-only item. New code should prefer the explicit availability and URI fields.

Apple Music, purchased songs, and downloaded songs

iOS returns items known to the user's Music library, including some cloud and Apple Music subscription entries. Library visibility does not guarantee that MPMediaItem.assetURL exists.

A cloud-only purchased track generally needs to be downloaded in Apple's Music app before a local asset URL can become available.
Downloading does not remove DRM. Apple Music subscription tracks can remain protected and cannot be exported, decoded, or sent to a stem separator through a normal third-party file API.
A purchased item can still lack an accessible URL depending on its format, account state, sync state, or platform policy.
For reliable editing and separation, import an unprotected audio file the user is authorized to process.

The module cannot initiate an Apple Music download or bypass DRM.

To request only usable iOS AVFoundation items:

const localPage = await MusicLibrary.getAssetsAsync({
  availability: "avFoundationAccessible",
  artwork: "none",
});

Available filters are:

"all" — all matching metadata, including unavailable items
"hasAssetUrl" — items for which the platform exposes an asset URL
"avFoundationAccessible" — unprotected items expected to work with AVFoundation

Artwork

artwork: "legacy" is the default and preserves the 1.3.0 artwork field. On iOS that field remains raw JPEG base64; on Android it remains a URI. The additive artworkUri field is a lazy music-artwork://<persistentID> URI on iOS and a MediaStore content URI on Android.

Use artwork: "uri" to put the lazy URI in both artwork and artworkUri, or artwork: "none" for large metadata-only queries.

<Image source={{ uri: track.artworkUri || track.artwork }} />

When rendering the legacy iOS field directly, add a data:image/jpeg;base64, prefix. Do not add that prefix to artworkUri.

Pagination

Every asset page has this shape:

type PagedInfo<T> = {
  assets: T[];
  endCursor: string;
  hasNextPage: boolean;
  totalCount: number;
};

endCursor is opaque and platform-specific. Pass it back unchanged; do not parse it or assume it is an asset ID or numeric offset.

const firstPage = await MusicLibrary.getAssetsAsync({ first: 20 });

const nextPage = await MusicLibrary.getAssetsAsync({
  first: 20,
  after: firstPage.endCursor,
});

Search and filters

const matches = await MusicLibrary.searchAssetsAsync("Beatles", {
  first: 25,
  album: "album-id",
  createdAfter: new Date("2020-01-01T00:00:00Z"),
  sortBy: [["artist", true], ["album", true], ["title", true]],
  availability: "all",
});

createdAfter and createdBefore accept a valid Date or a finite Unix timestamp in milliseconds.

Albums, artists, genres, and collections

const albums = await MusicLibrary.getAlbumsAsync();
const artists = await MusicLibrary.getArtistsAsync();
const genres = await MusicLibrary.getGenresAsync();
const collections = await MusicLibrary.getFoldersAsync();

const albumTracks = await MusicLibrary.getAlbumAssetsAsync(albums[0].id, {
  first: 20,
  availability: "all",
});

The legacy Folder API has platform-specific semantics:

Android folders represent filesystem/MediaStore audio directories.
iOS folders represent Music playlists.

Use getCapabilitiesAsync() when the distinction matters:

const capabilities = await MusicLibrary.getCapabilitiesAsync();

type MusicLibraryCapabilities = {
  playlists: boolean;
  directories: boolean;
  cloudItems: boolean;
  protectedAssets: boolean;
  uriSchemes: Array<"ipod-library" | "content" | "file">;
};

Library changes

Change notifications are reload signals, not incremental diffs:

const subscription = MusicLibrary.addChangeListener((event) => {
  if (event.requiresFullReload) {
    void reloadCurrentQuery();
  }
});

subscription.remove();

The event payload is:

type ChangeEventPayload = {
  hasIncrementalChanges: boolean; // false at runtime since 1.3.1
  requiresFullReload?: boolean; // true at runtime since 1.3.1
  requiresReload?: boolean; // compatibility alias
};

API

isAvailableAsync(): Promise<boolean>
getPermissionsAsync(writeOnly?: boolean): Promise<PermissionResponse>
requestPermissionsAsync(writeOnly?: boolean): Promise<PermissionResponse>
getCapabilitiesAsync(): Promise<MusicLibraryCapabilities>

getAssetsAsync(options?: AssetsOptions): Promise<PagedInfo<Asset>>
searchAssetsAsync(query: string, options?: AssetsOptions): Promise<PagedInfo<Asset>>
getAssetByIdAsync(id: string): Promise<Asset>

getAlbumsAsync(): Promise<Album[]>
getAlbumAssetsAsync(id: string, options?: SubQueryOptions): Promise<PagedInfo<Asset>>
getArtistsAsync(): Promise<Artist[]>
getArtistAssetsAsync(id: string, options?: SubQueryOptions): Promise<PagedInfo<Asset>>
getGenresAsync(): Promise<Genre[]>
getGenreAssetsAsync(id: string, options?: SubQueryOptions): Promise<PagedInfo<Asset>>
getFoldersAsync(): Promise<Folder[]>
getFolderAssetsAsync(id: string, options?: SubQueryOptions): Promise<PagedInfo<Asset>>

addChangeListener(listener: (event: ChangeEventPayload) => void): {
  remove(): void;
}

writeOnly remains in the permission methods for backward compatibility. The module itself is read-only.

Troubleshooting

The package name is rejected as a config plugin

Version 1.3.1 and newer include the root app.plugin.js entry point expected by Expo. Upgrade the package, then rerun prebuild and rebuild the native app.

A song is listed but cannot play or separate

Check availability, availabilityReason, hasProtectedAsset, hasAssetUrl, and canAccessWithAVFoundation. On iOS, metadata-only cloud and protected items are expected. Downloading a purchased song may help; downloading an Apple Music subscription item does not remove DRM.