@capacitor-community/media

Capacitor Media

@capacitor-community/media

Capacitor community plugin for enabling extra media capabilities

Sponsors

Intenseloop

Maintainers

Maintainer	GitHub	Social
Nisala Kalupahana	nkalupahana
Stewan Silva	stewones	@StewanSilva

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(...)
• Interfaces
• Enums

getMedias(...)

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

Get filtered media from camera roll (pictures only currently). 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. All images on iOS are converted to PNG for system compatability.

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

---

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
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"	Which types of assets to return. Only photos supported currently.
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
filePath	string

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).

MediaAlbumCreate

Prop	Type
name	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):

Stew 💻 📖 🚧	Zachary Keeton 💻	Pierre Grimaud 📖	Talles Alves 🚧	Zyad Yasser 🚧
Manuel Rodríguez 💻 🚧	Michael 💻	Matheus Davidson 💻 📖	Nisala Kalupahana 💻 📖 💡 🚧	Masahiko Sakakibara 🚧

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

Changelog

5.2.0 (2023-08-13)

• Allow add-only photo permissions on iOS 14+