Sponsors

Maintainers

| Maintainer | GitHub | Social | | ----------------- | --------------------------------------------- | ----------------------------------------- | | Nisala Kalupahana | nkalupahana | | | Stewan Silva | stewones | @stewones |

Installation

Run one of the following commands, based on what you're using:

npm install @capacitor-community/media # NPM
yarn add @capacitor-community/media # Yarn

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

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

Migrating to Capacitor 5

A major breaking change has been made to this plugin: Saving media on Android now takes an album identifier instead of an album name. The album identifier, like on iOS, can be obtained using getAlbums(). (This call will now also return empty albums made by the plugin.) To ensure people notice this significant change, the property has been renamed from album to albumIdentifier, which will need to be updated in your code. It is still optional on iOS.

API

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

• getMedias(...)
• getAlbums()
• savePhoto(...)
• saveVideo(...)
• saveGif(...)
• createAlbum(...)
• getAlbumsPath()
• Interfaces
• 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>

getAlbums()

getAlbums() => Promise<MediaAlbumResponse>

Get list of albums.

Code Examples

Returns: Promise<MediaAlbumResponse>

savePhoto(...)

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

Saves a photo 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, all image formats supported by SDWebImage 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>

saveGif(...)

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

Saves an animated GIF to the camera roll.

On Android and iOS, this supports web URLs, base64 encoded GIFs (e.g. data:image/gif;base64,...), and local files. This only supports GIF files specifically.

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 | | 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. | | thumbnailWidth | number | The width of thumbnail to return | | thumbnailHeight | number | The height of thumbnail to return | | thumbnailQuality | number | The quality of thumbnail to return as JPEG (0-100) | | types | "photos" | "videos" | "all" | Which types of assets to return thumbnails for. | | albumIdentifier | string | Which album identifier to query in (get identifier with getAlbums()) | | sort | "mediaType" | "mediaSubtypes" | "sourceType" | "pixelWidth" | "pixelHeight" | "creationDate" | "modificationDate" | "isFavorite" | "burstIdentifier" | MediaSort[] | Sort order of returned assets by field and ascending/descending |

MediaSort

| Prop | Type | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | key | "mediaType" | "mediaSubtypes" | "sourceType" | "pixelWidth" | "pixelHeight" | "creationDate" | "modificationDate" | "isFavorite" | "burstIdentifier" | | ascending | boolean |

MediaAlbumResponse

| Prop | Type | | ------------ | ------------------------- | | albums | MediaAlbum[] |

MediaAlbum

| Prop | Type | | ---------------- | --------------------------------------------------------- | | identifier | string | | name | string | | type | MediaAlbumType |

PhotoResponse

| Prop | Type | Description | | -------------- | ------------------- | -------------------------- | | filePath | string | Available on Android only. |

MediaSaveOptions

| Prop | Type | Description | | --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | path | string | Web URL, base64 encoded URI, or local file path to save. | | albumIdentifier | string | Album identifier from getAlbums(). Since 5.0, identifier is used on both Android and iOS. Identifier is required on Android but not on iOS. On iOS 14+, if the identifier is not specified and no permissions have been requested yet, add-only permissions will be requested instead of full permissions (assuming NSPhotoLibraryAddUsageDescription is in Info.plist). | | fileName | string | File name to save the image as in the album. Do not include extension. Android only. |

MediaAlbumCreate

| Prop | Type | | ---------- | ------------------- | | name | string |

AlbumsPathResponse

| Prop | Type | | ---------- | ------------------- | | path | string |

Enums

MediaAlbumType

| Members | Value | Description | | ------------ | --------------------- | -------------------------------------------------------------- | | Smart | 'smart' | Album is a "smart" album (such as Favorites or Recently Added) | | Shared | 'shared' | Album is a cloud-shared album | | User | 'user' | Album is a user-created album |

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!