Skip to content

Latest commit

 

History

History
382 lines (261 loc) · 21.9 KB

README.md

File metadata and controls

382 lines (261 loc) · 21.9 KB
Raw


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

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).
fileName string File name to save the image as in the album. Do not include extension. Android only.

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
Stew
💻 📖 🚧		 Zachary Keeton
Zachary Keeton
💻		 Pierre Grimaud
Pierre Grimaud
📖		 Talles Alves
Talles Alves
🚧		 Zyad Yasser
Zyad Yasser
🚧
Manuel Rodríguez
Manuel Rodríguez
💻 🚧		 Michael
Michael
💻		 Matheus Davidson
Matheus Davidson
💻 📖		 Nisala Kalupahana
Nisala Kalupahana
💻 📖 💡 🚧		 Masahiko Sakakibara
Masahiko Sakakibara
🚧

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