Awesome

Sponsors

Maintainers

Installation

npm install @capacitor-community/media

This plugin is currently for Capacitor 6. Add an @5 at the end to install for Capacitor 5.

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

Migrating to Capacitor 6

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.

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

Returns: <code>Promise<<a href="#mediaresponse">MediaResponse</a>></code>

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

Returns: <code>Promise<<a href="#mediapath">MediaPath</a>></code>

getAlbums()

getAlbums() => Promise<MediaAlbumResponse>

Get list of albums.

Code Examples

Returns: <code>Promise<<a href="#mediaalbumresponse">MediaAlbumResponse</a>></code>

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

Returns: <code>Promise<<a href="#photoresponse">PhotoResponse</a>></code>

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

Returns: <code>Promise<<a href="#photoresponse">PhotoResponse</a>></code>

createAlbum(...)

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

Creates an album.

Code Examples

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: <code>Promise<<a href="#albumspathresponse">AlbumsPathResponse</a>></code>

Interfaces

MediaResponse

MediaAsset

MediaLocation

MediaFetchOptions

MediaSort

MediaPath

MediaAlbumResponse

MediaAlbum

PhotoResponse

MediaSaveOptions

MediaAlbumCreate

AlbumsPathResponse

Type Aliases

MediaField

Attributes to sort media by.

iOS Source

<code>'mediaType' | 'mediaSubtypes' | 'sourceType' | 'pixelWidth' | 'pixelHeight' | 'creationDate' | 'modificationDate' | 'isFavorite' | 'burstIdentifier'</code>

Enums

MediaAlbumType

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

You'll need to add the following to your app's AndroidManifest.xml file:

<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" />
  ...
</manifest>

Note the READ_MEDIA permissions -- these are new in Android 13!

Demo

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!