@whiteguru/capacitor-plugin-media

Capacitor plugin to handle media files

Install (Capacitor 6.x)

npm install @whiteguru/capacitor-plugin-media
npx cap sync

or for Capacitor 5.x

npm install @whiteguru/capacitor-plugin-media@^5.0.2
npx cap sync

or for Capacitor 4.x

npm install @whiteguru/capacitor-plugin-media@^4.1.1
npx cap sync

or for Capacitor 3.x

npm install @whiteguru/capacitor-plugin-media@^3.0.1
npx cap sync

Android

This API requires the following permissions be added to your AndroidManifest.xml:

<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_AUDIO" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

API

• getMedias(...)
• getAlbums()
• savePhoto(...)
• saveVideo(...)
• saveGif(...)
• saveDocument(...)
• saveAudio(...)
• createAlbum(...)
• Interfaces
• Enums

getMedias(...)

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

Get list of user medias. IOS only

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | MediaFetchOptions |

Returns: Promise<MediasResponse>

getAlbums()

getAlbums() => Promise<MediaAlbumResponse>

Get list of user albums. IOS and Android Api 29+

Returns: Promise<MediaAlbumResponse>

savePhoto(...)

savePhoto(options?: MediaSaveOptions | undefined) => Promise<MediaResponse>

Add image to gallery. Creates album if not exists.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | MediaSaveOptions |

Returns: Promise<MediaResponse>

saveVideo(...)

saveVideo(options?: MediaSaveOptions | undefined) => Promise<MediaResponse>

Add video to gallery. Creates album if not exists.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | MediaSaveOptions |

Returns: Promise<MediaResponse>

saveGif(...)

saveGif(options?: MediaSaveOptions | undefined) => Promise<MediaResponse>

Add gif to gallery. Creates album if not exists.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | MediaSaveOptions |

Returns: Promise<MediaResponse>

saveDocument(...)

saveDocument(options?: MediaSaveOptions | undefined) => Promise<MediaResponse>

Add document to gallery. Android only. Create album if not exists.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | MediaSaveOptions |

Returns: Promise<MediaResponse>

saveAudio(...)

saveAudio(options?: MediaSaveOptions | undefined) => Promise<MediaResponse>

Add audio to gallery. Android only. Creates album if not exists.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | MediaSaveOptions |

Returns: Promise<MediaResponse>

createAlbum(...)

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

Create album. IOS only

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | MediaAlbumCreate |

Returns: Promise<MediaAlbum>

Interfaces

MediasResponse

| 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 | string | Which types of assets to return (currently only supports "photos") | | albumIdentifier | string | Which album identifier to query in (get identifier with getAlbums()) |

MediaAlbumResponse

| Prop | Type | Description | | ------------ | ------------------------- | --------------------------------------------- | | albums | MediaAlbum[] | Array of MediaAlbum |

MediaAlbum

| Prop | Type | Description | | ---------------- | --------------------------------------------------------- | ---------------------------------- | | identifier | string | Platform-specific album identifier | | name | string | Album name | | type | MediaAlbumType | Album type |

MediaResponse

| Prop | Type | Description | | ---------- | ------------------- | ----------- | | path | string | Media path | | name | string | Media name |

MediaSaveOptions

| Prop | Type | Description | | ----------- | -------------------------------------------- | ----------------------------------------------------------------------------------- | | path | string | Path of file to add | | album | { id?: string; name?: string; } | Album to add media. If no 'id' and 'name' not exists, album 'name' will be created. |

MediaAlbumCreate

| Prop | Type | Description | | ---------- | ------------------- | ----------- | | name | string | Album name |

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 |