react-native-media-metadata-picker

Pick images and videos and get metadata only — no file copy, no processing. Works on Android and iOS with all formats, including iOS HEVC.

Features

• Metadata only: Returns file information (dimensions, duration, size, type, dates) without copying or processing the file.
• No temp files: Does not write to a temp folder or convert the media.
• All formats: Supports all image and video formats the platform supports, including:
  • iOS: HEVC (.mov), H.264, JPEG, HEIC, PNG, etc.
  • Android: Common image and video MIME types.
• Cross-platform: Same API on Android and iOS.

Requirements

• React Native 0.83 or above
• Node.js 22 or above

Installation

npm install react-native-media-metadata-picker
# or
yarn add react-native-media-metadata-picker

iOS

cd ios && pod install && cd ..

Minimum iOS version: 14.0 (for PHPicker).

Android

No extra setup. Minimum SDK: 24.

Usage

import {
  pickMediaMetadata,
  pickMultipleMediaMetadata,
  type MediaMetadata,
} from 'react-native-media-metadata-picker';

// Pick a single image or video
const meta = await pickMediaMetadata({ mediaType: 'all' });
if (meta) {
  console.log(meta.uri, meta.width, meta.height, meta.type);
  if (meta.type === 'video') console.log(meta.duration);
}

// Pick multiple
const list = await pickMultipleMediaMetadata({ mediaType: 'video' });
list.forEach((m) => console.log(m.uri, m.duration));

Options

• mediaType: 'image' | 'video' | 'all' — filter by type (default 'all').
• multiple: Only via pickMultipleMediaMetadata() for multiple selection.

Returned metadata (MediaMetadata)

| Field | Type | Description | |--------------------|----------|--------------------------------------------------| | uri | string | Platform-specific reference to the file | | type | 'image' \| 'video' | Media type | | width | number | Width in pixels | | height | number | Height in pixels | | fileName | string? | Display name when available | | mimeType | string? | e.g. image/jpeg, video/hevc | | fileSize | number? | Size in bytes | | duration | number? | Duration in seconds (video only) | | creationDate | string? | ISO date string | | modificationDate | string? | ISO date string | | localIdentifier | string? | iOS PHAsset identifier | | codec | string? | Codec hint when available | | originalUrl | string? | Original file URL (file:// on iOS, same as uri on Android); use for upload | | originalDirPath | string? | Directory path without filename (e.g. /var/mobile/.../). iOS from file URL; Android when available |

• Android: uri and originalUrl are the same content:// URI; use for upload without copying.
• iOS: uri is a ph:// reference (persists after app reinstall). originalUrl is the original file:// URL when available. Store uri (ph://) and call getFileUrl(uri) when you need to preview or upload so it works after reinstall.

Resolving ph:// for preview and upload (iOS)

On iOS, originalUrl is a temporary file URL. Store meta.uri (ph://) in your app. When displaying or uploading, call:

import { getFileUrl } from 'react-native-media-metadata-picker';

const displayOrUploadUri = await getFileUrl(localfile.uri); // file:// on iOS, or same uri on Android

Use displayOrUploadUri for <Image source={{ uri }} />, <Video source={{ uri }} />, and RNBlobUtil.wrap(uri). This works after the app is reinstalled.

Behavior

• No copy: The library does not copy or process file data. It only reads metadata from the system (e.g. Android ContentResolver + MediaMetadataRetriever, iOS PHAsset).
• HEVC: On iOS, HEVC and other formats are supported without conversion; the system provides metadata for the selected asset.
• Permissions: Uses the system picker (Android ACTION_GET_CONTENT, iOS PHPicker), so no storage/photo library permission is required for picking.

License

MIT