@yairza/capacitor-community-media NPM

FORK OF THIS PLUGIN https://github.com/capacitor-community/media/

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

getMedias(options?: MediaFetchOptions | undefined) => any

Get filtered thumbnails from camera roll. iOS only.

Code Examples

Param	Type
`options`	MediaFetchOptions

Returns: any

getAlbums()

getAlbums() => any

Get list of albums.

Code Examples

Returns: any

savePhoto(...)

savePhoto(options?: MediaSaveOptions | undefined) => any

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: any

saveVideo(...)

saveVideo(options?: MediaSaveOptions | undefined) => any

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: any

saveGif(...)

saveGif(options?: MediaSaveOptions | undefined) => any

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: any

createAlbum(...)

createAlbum(options: MediaAlbumCreate) => any

Creates an album.

Code Examples

Param	Type
`options`	MediaAlbumCreate

Returns: any

getAlbumsPath()

getAlbumsPath() => any

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: any

Interfaces

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"	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

MediaResponse

Prop	Type
`medias`	{}

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

MediaAlbumResponse

Prop	Type
`albums`	{}

MediaAlbum

Prop	Type
`identifier`	string
`name`	string
`type`	MediaAlbumType

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.

PhotoResponse

Prop	Type	Description
`filePath`	string	Available on 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!

capacitor plugin native

5.4.2

1 year ago

5.4.1

1 year ago

6.0.0

1 year ago

@yairza/capacitor-community-media v5.4.2

FORK OF THIS PLUGIN https://github.com/capacitor-community/media/

Sponsors

Maintainers

Installation

Migrating to Capacitor 5

API

getMedias(...)

getAlbums()

savePhoto(...)

saveVideo(...)

saveGif(...)

createAlbum(...)

getAlbumsPath()

Interfaces

MediaFetchOptions

MediaSort

MediaResponse

MediaAsset

MediaLocation

MediaAlbumResponse

MediaAlbum

MediaSaveOptions

PhotoResponse

MediaAlbumCreate

AlbumsPathResponse

Enums

MediaAlbumType

iOS

Android

Demo

Contributors ✨