@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

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

Usage

`js
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

$3

`ts
const MetadataPresets: Record;
`

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

$3

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

Formats that we can save the image as.

Functions

$3

`ts
function getArtwork(uri: string): Promise;
`

Returns a base64 string representing the embedded artwork.

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

$3

`ts
function getBulkMetadata(
uris: string[],
options: TOptions
): Promise>;
`

Get the metadata of multiple uris.

$3

`ts
function getMetadata(
uri: string,
options: TOptions
): Promise>;
`

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.

$3

`ts
function saveArtwork(
uri: string,
options?: ArtworkOptions
): Promise;
`

Returns the uri of the saved artwork.

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

$3

`ts
function updateConfigs(options: ConfigOptions): Promise;
`

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

Types

$3

`ts
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.

$3

`ts
type BulkMetadata = {
results: Array<{
uri: string;
data: MediaMetadataExcerpt;
}>;
errors: Array<{
uri: string;
data: { name: string; message: string };
}>;
};
`

Structure returned when using getBulkMetadata.

$3

`ts
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.

$3

`ts
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.

$3

`ts
type MediaMetadataExcerpt = Prettify<
Pick
>;
`

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