@missingcore/react-native-metadata-retriever

React Native wrapper for Android's unstable MetadataRetriever API, which fallback to the old MediaMetadataRetriever API if no metadata was found (ie: ID3v1 tags aren't detected).

Supported Files

Unlike @missingcore/audio-metadata which this is a successor to, this uses Android's native metadata reader via AndroidX's MetadataRetriever API. With that in mind, we can support a wider range of formats which would have costed a lot of time and energy to develop with pure TypeScript.

View the full list of supported audio formats on Android's documentation on Supported media formats.

Installation

npm install @missingcore/react-native-metadata-retriever

Usage

import {
  MetadataPresets,
  getArtwork,
  getMetadata,
} from '@missingcore/react-native-metadata-retriever';

const uri = 'file:///storage/emulated/0/Music/Silence.mp3';

// Of course with `await`, use this inside an async function or use `Promise.then()`.
const metadata = await getMetadata(uri, MetadataPresets.standard);
const base64Artwork = await getArtwork(uri);

API Reference

Constants

MetadataPresets

const MetadataPresets: Record<string, MediaMetadataPublicFields>;

An object containing several metadata presets we can use to retrieve metadata.

SaveFormat

const SaveFormat = {
  JPEG: 'jpeg',
  PNG: 'png',
  WEBP: 'webp',
};

Formats that we can save the image as.

Functions

getArtwork

function getArtwork(uri: string): Promise<string | null>;

Returns a base64 string representing the embedded artwork.

Note: Defaults to returning up to 5 MB of data. Can be configured with updateConfigs.

getBulkMetadata

function getBulkMetadata<TOptions extends MediaMetadataPublicFields>(
  uris: string[],
  options: TOptions
): Promise<BulkMetadata<TOptions>>;

Get the metadata of multiple uris.

getMetadata

function getMetadata<TOptions extends MediaMetadataPublicFields>(
  uri: string,
  options: TOptions
): Promise<MediaMetadataExcerpt<TOptions>>;

Returns the specified metadata of the provided uri based on the options argument. Throws error if something went wrong.

Note: The "complicated" typing is to make the resulting promise type-safe and be based off the provided options.

saveArtwork

function saveArtwork(
  uri: string,
  options?: ArtworkOptions
): Promise<string | null>;

Returns the uri of the saved artwork.

Note: Ignores the hard-limit of the max size of the image that can be saved.

updateConfigs

function updateConfigs(options: ConfigOptions): Promise<void>;

Update internal configuration options such as the max size of the returned base64 image.

Types

ArtworkOptions

type ArtworkOptions = {
  /**
   * A value in the range `0.0` - `1.0` specifying the quality of the resulting image.
   * - Defaults to `1`.
   */
  compress?: number;
  /**
   * Specifies the format the image will be saved in.
   * - Defaults to `SaveFormat.JPEG`.
   */
  format?: SaveFormat;
  /** Uri we want to save the artwork to instead of the cache directory. */
  saveUri?: string;
};

Options to change the behavior of saveArtwork.

BulkMetadata

type BulkMetadata<TKeys extends MediaMetadataPublicFields> = {
  results: Array<{
    uri: string;
    data: MediaMetadataExcerpt<TKeys>;
  }>;
  errors: Array<{
    uri: string;
    data: { name: string; message: string };
  }>;
};

Structure returned when using getBulkMetadata.

ConfigOptions

type ConfigOptions = {
  /**
   * Size of the returned base64 image in MB.
   * - Defaults to `5`.
   */
  maxImageSizeMB?: number | null;
};

Configuration options we can set to modify the behavior of the package.

MediaMetadata

type MediaMetadata = {
  /* List of fields available on `Format`. */
  bitrate: number | null;
  channelCount: number | null;
  codecs: string | null;
  sampleMimeType: string | null;
  sampleRate: number | null; // in `Hz`
  /* List of fields available on `MediaMetadata`. */
  albumArtist: string | null;
  albumTitle: string | null;
  artist: string | null;
  artworkData: string | null;
  artworkDataType: string | null;
  artworkUri: string | null;
  compilation: string | null;
  composer: string | null;
  conductor: string | null;
  description: string | null;
  discNumber: number | null;
  displayTitle: string | null;
  // extras: unknown
  genre: string | null;
  isBrowsable: boolean | null;
  isPlayable: boolean | null;
  mediaType: string | null;
  overallRating: number | null;
  recordingDay: number | null;
  recordingMonth: number | null;
  recordingYear: number | null;
  releaseDay: number | null;
  releaseMonth: number | null;
  releaseYear: number | null;
  station: string | null;
  subtitle: string | null;
  title: string | null;
  totalDiscCount: number | null;
  totalTrackCount: number | null;
  trackNumber: number | null;
  userRating: number | null;
  writer: string | null;
  /* List of custom fields derived from other fields. */
  year: number | null;
};

The types of all the possible metadata we can return.

MediaMetadataExcerpt

type MediaMetadataExcerpt<TKeys extends MediaMetadataPublicFields> = Prettify<
  Pick<MediaMetadata, TKeys[number]>
>;

Narrow down the returned types in MediaMetadata based on the MediaMetadataPublicFields provided.

References

• Android Support Library vs AndroidX
• AndroidX Media3 GitHub Repository
• Retrieving metadata
• MetadataRetriever API

License

MIT