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).
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.
npm install @missingcore/react-native-metadata-retrieverimport {
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);const MetadataPresets: Record<string, MediaMetadataPublicFields>;An object containing several metadata presets we can use to retrieve metadata.
const SaveFormat = {
JPEG: 'jpeg',
PNG: 'png',
WEBP: 'webp',
};Formats that we can save the image as.
function getArtwork(uri: string): Promise<string | null>;Returns a base64 string (worth up to 5 MB of data) representing the embedded artwork.
function getBulkMetadata<TOptions extends MediaMetadataPublicFields>(
uris: string[],
options: TOptions
): Promise<BulkMetadata<TOptions>>;Get the metadata of multiple uris.
function getLyric(uri: string): Promise<string | null>;Attempts to return the embedded lyrics for a track.
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.
function getR128Gain(uri: string): Promise<number | null>;Attempts to return the track replay gain.
function saveArtwork(
uri: string,
options?: ArtworkOptions
): Promise<string | null>;Returns the uri of the saved artwork.
function saveHashedArtwork(
uri: string,
options?: HashedArtworkOptions
): Promise<{ hash: string; uri: string } | null>;Returns the hash of the embedded image & uri of the saved artwork.
Note: It will work as "expected" given that everything follows the same "social contract", as in
knownHashescontain hashes based on the same configuration passed to this function call.
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.
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.
type HashedArtworkOptions = {
/**
* 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;
/** Directory where we want to save the hashed image. The file name will be the hash. */
saveDirectory: string;
/**
* An array of known MD5 hashes formatted as a 32-character hexadecimal string
* which are stored in `saveDirectory` and is of the same format as what we
* pass for the `format` option.
*/
knownHashes: string[];
};Options to change the behavior of saveHashedArtwork.
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.
type MediaMetadataExcerpt<TKeys extends MediaMetadataPublicFields> = Prettify<
Pick<MediaMetadata, TKeys[number]>
>;Narrow down the returned types in MediaMetadata based on the MediaMetadataPublicFields provided.