github.com/capacitor-community/media @v9.1.0

Capacitor Media

@capacitor-community/media

Capacitor plugin for saving and retrieving photos and videos, and managing photo albums.

Maintainers

Maintainer	GitHub	Social
Nisala Kalupahana	nkalupahana
Stewan Silva	stewones	@stewones

Installation

npm install @capacitor-community/media

This plugin is currently maintained for Capacitor 8 (plugin version 9). Add an @8 at the end to install for Capacitor 7, or @7 for Capacitor 6. There are currently no API changes between these three versions, so if you're migrating between plugin v7 - v9 (Capacitor 6 - 8), no code changes should be required. SPM is only supported for plugin v9.

After installing, be sure to sync by running npx cap sync.

Migrating from Plugin v6 to v7+

There has been a breaking change to the way permissions are handled on Android. - If your app is not a "gallery" app (does not need access to all photo albums on the device, just its own), you no longer need the READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE, READ_MEDIA_IMAGES, or READ_MEDIA_VIDEO permissions. You can remove them from your AndroidManifest.xml file. The plugin will no longer request any permissions to save images to your app's albums. - If your app is a gallery app and you need access to all albums on the device, you'll need to update your capacitor.config.ts file (and keep all of the above permissions) -- see the setup instructions below.

You will need to update to v7 to publish an app with this plugin on the Google Play Store.

Migrating from Plugin v5 to v6

There are a few breaking changes to take note of: - saveGif no longer exists. Use savePhoto for images and GIFs. - Error text has been changed. If you were checking for specific error messages, you should now use error.code, which will be accessDenied, argumentError, downloadError, or filesystemError.

Setup

iOS

You'll need to add the following to your app's Info.plist file:

<dict>
  ...
  <key>NSPhotoLibraryUsageDescription</key>
  <string>Describe why you need access to user's photos (getting albums and media)</string>
  <key>NSPhotoLibraryAddUsageDescription</key>
  <string>Describe why you need to add photos to user's photo library</string>
  ...
</dict>

Android

By default, this plugin only has access to the albums associated with the app it's installed in. This should be enough for most use cases. For this basic level of access, you only need to add the following permission:

<manifest>
  ...
  <uses-permission android:name="android.permission.INTERNET" />
  ...
</manifest>

If you're building an app that needs to access all photos and videos on the device (e.g. a photo gallery app), you'll need the following permissions:

<manifest>
  ...
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
  <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
  ...

You'll also need to add the following configuration to capacitor.config.ts:

plugins: {
  Media: {
    androidGalleryMode: true
  }
}

You can find an example of how this should look in the example/ folder.

Demo

Go the the example/ folder to play with an example app that should show all functionality of this plugin.

API

Unless otherwise noted, there should be full feature parity between iOS and Android. Web is not supported.

• getMedias(...)
• getMediaByIdentifier(...)
• getAlbums()
• savePhoto(...)
• saveVideo(...)
• createAlbum(...)
• getAlbumsPath()
• Interfaces
• Type Aliases
• Enums

getMedias(...)

getMedias(options?: MediaFetchOptions | undefined) => Promise<MediaResponse>

Get filtered thumbnails from camera roll. iOS only.

Code Examples

Param	Type
options	MediaFetchOptions

Returns: Promise<MediaResponse>

---

getMediaByIdentifier(...)

getMediaByIdentifier(options?: { identifier: string; } | undefined) => Promise<MediaPath>

Get a filesystem path to a full-quality media asset by its identifier. iOS only. This is not included for Android because on Android, a media asset's identifier IS its path! You can simply use the Filesystem plugin to work with it. On iOS, you have to turn the identifier into a path using this function. After that, you can use the Filesystem plugin, same as Android.

Code Examples

Param	Type
options	{ identifier: string; }

Returns: Promise<MediaPath>

---

getAlbums()

getAlbums() => Promise<MediaAlbumResponse>

Get list of albums.

Code Examples

Returns: Promise<MediaAlbumResponse>

---

savePhoto(...)

savePhoto(options?: MediaSaveOptions | undefined) => Promise<PhotoResponse>

Saves a still photo or GIF to the camera roll.

On Android and iOS, this supports web URLs, base64 encoded images (e.g. data:image/jpeg;base64,...), and local files. On Android, all image formats supported by the user's photo viewer are supported. On iOS, most common image formats are supported.

Code Examples

Param	Type
options	MediaSaveOptions

Returns: Promise<PhotoResponse>

---

saveVideo(...)

saveVideo(options?: MediaSaveOptions | undefined) => Promise<PhotoResponse>

Saves a video to the camera roll.

On Android and iOS, this supports web URLs, base64 encoded videos (e.g. data:image/mp4;base64,...), and local files. On Android, all video formats supported by the user's photo viewer are supported. On iOS, the supported formats are based on whatever iOS supports at the time.

Code Examples

Param	Type
options	MediaSaveOptions

Returns: Promise<PhotoResponse>

---

createAlbum(...)

createAlbum(options: MediaAlbumCreate) => Promise<void>

Creates an album.

Code Examples

Param	Type
options	MediaAlbumCreate

---

getAlbumsPath()

getAlbumsPath() => Promise<AlbumsPathResponse>

Gets the path where album folders and their corresponding photos are stored on the Android filesystem. This can be used to identify your album by more than just its name on Android, in case there are multiple albums with the same name, which is possible on Android. Just compare the albums path to the start of the album identifier when getting albums.

Only available on Android.

Code Examples: basic, when saving media

Returns: Promise<AlbumsPathResponse>

---

Interfaces

MediaResponse

Prop	Type
medias	MediaAsset[]

MediaAsset

Prop	Type	Description
identifier	string	Platform-specific identifier
data	string	Data for a photo asset as a base64 encoded string (JPEG only supported)
creationDate	string	ISO date string for creation date of asset
duration	number	Duration of asset in seconds, only returned for videos
fullWidth	number	Full width of original asset
fullHeight	number	Full height of original asset
thumbnailWidth	number	Width of thumbnail preview
thumbnailHeight	number	Height of thumbnail preview
location	MediaLocation	Location metadata for the asset

MediaLocation

Prop	Type	Description
latitude	number	GPS latitude image was taken at
longitude	number	GPS longitude image was taken at
heading	number	Heading of user at time image was taken
altitude	number	Altitude of user at time image was taken
speed	number	Speed of user at time image was taken

MediaFetchOptions

Prop	Type	Description
quantity	number	The number of photos to fetch, sorted by last created date descending. To paginate, just request a higher quantity -- OS caching should make this relatively performant.
**`thu