@capacitor-community/media
Capacitor plugin for saving and retrieving photos and videos, and managing photo albums.
|
Chatness AI |
| Maintainer | GitHub | Social |
|---|---|---|
| Nisala Kalupahana | nkalupahana | |
| Stewan Silva | stewones | @stewones |
npm install @capacitor-community/mediaThis 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.
There are a few breaking changes to take note of:
-
saveGifno longer exists. UsesavePhotofor images and GIFs. - Error text has been changed. If you were checking for specific error messages, you should now use
error.code, which will beaccessDenied,argumentError,downloadError, orfilesystemError.
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
- Enums
getMedias(options?: MediaFetchOptions | undefined) => Promise<MediaResponse>Get filtered thumbnails from camera roll. iOS only.
| Param | Type |
|---|---|
options |
MediaFetchOptions |
Returns: Promise<MediaResponse>
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.
| Param | Type |
|---|---|
options |
{ identifier: string; } |
Returns: Promise<MediaPath>
getAlbums() => Promise<MediaAlbumResponse>Get list of albums.
Returns: Promise<MediaAlbumResponse>
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.
| Param | Type |
|---|---|
options |
MediaSaveOptions |
Returns: Promise<PhotoResponse>
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.
| Param | Type |
|---|---|
options |
MediaSaveOptions |
Returns: Promise<PhotoResponse>
createAlbum(options: MediaAlbumCreate) => Promise<void>Creates an album.
| Param | Type |
|---|---|
options |
MediaAlbumCreate |
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>
| 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 |
| 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 |
| 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 |
| Prop | Type |
|---|---|
key |
"mediaType" | "mediaSubtypes" | "sourceType" | "pixelWidth" | "pixelHeight" | "creationDate" | "modificationDate" | "isFavorite" | "burstIdentifier" |
ascending |
boolean |
| Prop | Type | Description |
|---|---|---|
path |
string |
Path to media asset |
identifier |
string |
Identifier for media asset |
| Prop | Type |
|---|---|
albums |
MediaAlbum[] |
| Prop | Type |
|---|---|
identifier |
string |
name |
string |
type |
MediaAlbumType |
| Prop | Type | Description |
|---|---|---|
filePath |
string |
Available on Android only. |
| 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. |
| Prop | Type |
|---|---|
name |
string |
| Prop | Type |
|---|---|
path |
string |
| 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 |
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>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!
Go the the example/ folder to play with an example app that should show all functionality of this plugin.
Thanks goes to these wonderful people (emoji key):
 stewones 💻 📖 🚧 |
 Zachary Keeton 💻 |
 Pierre Grimaud 📖 |
 Talles Alves 🚧 |
 Zyad Yasser 🚧 |
 Manuel Rodríguez 💻 🚧 |
 Michael 💻 |
 Nisala Kalupahana 💻 📖 💡 🚧 |
 Masahiko Sakakibara 🚧 |
 ha6-6ru 💻 |
 Stephan Fischer 💻 |
 Matheus Davidson 💻 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!