Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@capacitor-community/media

Package Overview
Dependencies
Maintainers
0
Versions
20
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@capacitor-community/media

Capacitor plugin for saving and retrieving photos and videos, and managing photo albums.

  • 7.0.1
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
7.4K
increased by62.54%
Maintainers
0
Weekly downloads
 
Created
Source


Capacitor Media

@capacitor-community/media

Capacitor plugin for saving and retrieving photos and videos, and managing photo albums.


Sponsors

Chatness AI

Maintainers

MaintainerGitHubSocial
Nisala Kalupahanankalupahana
Stewan Silvastewones@stewones

Installation

npm install @capacitor-community/media

This plugin is currently for Capacitor 6. Add an @5 at the end to install for Capacitor 5. Note that the Capacitor 5 version is no longer maintained, and cannot be published to the Google Play Store.

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

Migrating to v7

There has been a breaking change to the way permissions are handled on Android.

  • If your app is not a "gallery" app (does not need access to all photo albums on the device, just its own), you no longer need the READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE, READ_MEDIA_IMAGES, or READ_MEDIA_VIDEO permissions. You can remove them from your AndroidManifest.xml file. The plugin will no longer request any permissions to save images to your app's albums.
  • If your app is a gallery app and you need access to all albums on the device, you'll need to update your capacitor.config.ts file (and keep all of the above permissions) -- see the setup instructions below.

You will need to update to v7 to publish an app with this plugin on the Google Play Store.

Migrating to Capacitor 6

There are a few breaking changes to take note of:

  • saveGif no longer exists. Use savePhoto for images and GIFs.
  • Error text has been changed. If you were checking for specific error messages, you should now use error.code, which will be accessDenied, argumentError, downloadError, or filesystemError.

Setup

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

By default, this plugin only has access to the albums associated with the app it's installed in. This should be enough for most use cases. For this basic level of access, you only need to add the following permission:

<manifest>
  ...
  <uses-permission android:name="android.permission.INTERNET" />
  ...
</manifest>

If you're building an app that needs to access all photos and videos on the device (e.g. a photo gallery app), you'll need the following permissions:

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

You'll also need to add the following configuration to capacitor.config.ts:

plugins: {
  Media: {
    androidGalleryMode: true
  }
}

You can find an example of how this should look in the example/ folder.

Demo

Go the the example/ folder to play with an example app that should show all functionality of this plugin.

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 thumbnails from camera roll. iOS only.

Code Examples

ParamType
optionsMediaFetchOptions

Returns: Promise<MediaResponse>


getMediaByIdentifier(...)

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.

Code Examples

ParamType
options{ identifier: string; }

Returns: Promise<MediaPath>


getAlbums()

getAlbums() => Promise<MediaAlbumResponse>

Get list of albums.

Code Examples

Returns: Promise<MediaAlbumResponse>


savePhoto(...)

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.

Code Examples

ParamType
optionsMediaSaveOptions

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

ParamType
optionsMediaSaveOptions

Returns: Promise<PhotoResponse>


createAlbum(...)

createAlbum(options: MediaAlbumCreate) => Promise<void>

Creates an album.

Code Examples

ParamType
optionsMediaAlbumCreate

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
PropType
mediasMediaAsset[]
MediaAsset
PropTypeDescription
identifierstringPlatform-specific identifier
datastringData for a photo asset as a base64 encoded string (JPEG only supported)
creationDatestringISO date string for creation date of asset
durationnumberDuration of asset in seconds, only returned for videos
fullWidthnumberFull width of original asset
fullHeightnumberFull height of original asset
thumbnailWidthnumberWidth of thumbnail preview
thumbnailHeightnumberHeight of thumbnail preview
locationMediaLocationLocation metadata for the asset
MediaLocation
PropTypeDescription
latitudenumberGPS latitude image was taken at
longitudenumberGPS longitude image was taken at
headingnumberHeading of user at time image was taken
altitudenumberAltitude of user at time image was taken
speednumberSpeed of user at time image was taken
MediaFetchOptions
PropTypeDescription
quantitynumberThe 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.
thumbnailWidthnumberThe width of thumbnail to return
thumbnailHeightnumberThe height of thumbnail to return
thumbnailQualitynumberThe quality of thumbnail to return as JPEG (0-100)
types'photos' | 'videos' | 'all'Which types of assets to return thumbnails for.
albumIdentifierstringWhich album identifier to query in (get identifier with getAlbums())
sortMediaField | MediaSort[]Sort order of returned assets by field and ascending/descending
MediaSort
PropType
keyMediaField
ascendingboolean
MediaPath
PropTypeDescription
pathstringPath to media asset
identifierstringIdentifier for media asset
MediaAlbumResponse
PropType
albumsMediaAlbum[]
MediaAlbum
PropType
identifierstring
namestring
typeMediaAlbumType
PhotoResponse
PropTypeDescription
filePathstringAvailable on Android only.
identifierstringAvailable on iOS only. To get a file path for an image on iOS, pass this identifier to getMediaByIdentifier.
MediaSaveOptions
PropTypeDescription
pathstringWeb URL, base64 encoded URI, or local file path to save.
albumIdentifierstringAlbum 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).
fileNamestringFile name to save the image as in the album. Do not include extension. Android only.
MediaAlbumCreate
PropType
namestring
AlbumsPathResponse
PropType
pathstring

Type Aliases

MediaField

Attributes to sort media by.

iOS Source

'mediaType' | 'mediaSubtypes' | 'sourceType' | 'pixelWidth' | 'pixelHeight' | 'creationDate' | 'modificationDate' | 'isFavorite' | 'burstIdentifier'

Enums

MediaAlbumType
MembersValueDescription
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

Contributors ✨

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!

Keywords

FAQs

Package last updated on 18 Dec 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc