https://github.com/stephan-fischer/capacitor-gallery-plus
Capacitor Gallery Plus – A Capacitor plugin to access and manage media files from the device gallery with filtering, sorting, and metadata extraction.
https://github.com/stephan-fischer/capacitor-gallery-plus
android capacitor capacitor-plugin file-access gallery image-processing ios media photo photos plugins videos web
Last synced: about 1 year ago
JSON representation
Capacitor Gallery Plus – A Capacitor plugin to access and manage media files from the device gallery with filtering, sorting, and metadata extraction.
- Host: GitHub
- URL: https://github.com/stephan-fischer/capacitor-gallery-plus
- Owner: stephan-fischer
- License: other
- Created: 2025-01-29T23:33:54.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-19T15:31:38.000Z (over 1 year ago)
- Last Synced: 2025-04-12T01:07:49.752Z (about 1 year ago)
- Topics: android, capacitor, capacitor-plugin, file-access, gallery, image-processing, ios, media, photo, photos, plugins, videos, web
- Language: TypeScript
- Homepage:
- Size: 604 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Capacitor Gallery Plus
A Capacitor plugin for accessing and managing media files (photos & videos) on iOS and Android. This plugin provides an easy way to retrieve media from the device's gallery, including metadata such as filenames, paths, and types.
## Features
- 📸 Retrieve **photos** & **videos** from the device gallery
- 🏷️ Get metadata like filenames, paths, and MIME types
- 🚀 Works with Capacitor 5, 6, and 7
- 🔧 Simple API for easy integration
## Install
```bash
npm install capacitor-gallery-plus
npx cap sync
```
## iOS Setup
To ensure the plugin works correctly on iOS, you need to add the following permissions to your `Info.plist` file.
### **Required Permissions**
Open your `ios/App/App/Info.plist` file and add the following keys inside the `` tag:
```xml
NSPhotoLibraryUsageDescription
This app requires access to your photo library to display media files.
```
This permission is required for accessing media files in the user's gallery.
If this is missing, the app might crash or fail to fetch media.
### **Requesting Permissions in Code**
If you need to explicitly request permissions, you can call:
```typescript
const permission = await GalleryPlus.checkPermissions();
if (permission.status !== "granted") {
const request = await GalleryPlus.requestPermissions();
if (request.status !== "granted") {
console.error("Permission denied.");
}
}
```
This ensures the app prompts the user for access when needed.
---
💡 **Tip:** If you experience crashes on iOS, check your Xcode logs to confirm missing permissions.
## Usage
```typescript
import { GalleryPlus } from 'capacitor-gallery-plus';
async function getMedia() {
try {
const result = await GalleryPlus.getMediaList({});
console.log('Media files:', result.media);
} catch (error) {
console.error('Error retrieving media:', error);
}
}
```
## API
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [`getMediaList(...)`](#getmedialist)
* [`getMedia(...)`](#getmedia)
* [Interfaces](#interfaces)
* [Enums](#enums)
### checkPermissions()
```typescript
checkPermissions() => Promise<{ status: string; }>
```
Checks the current permissions for accessing media.
**Returns:** Promise<{ status: string; }>
--------------------
### requestPermissions()
```typescript
requestPermissions() => Promise<{ status: string; }>
```
Requests the necessary permissions to access media.
**Returns:** Promise<{ status: string; }>
--------------------
### getMediaList(...)
```typescript
getMediaList(options: GetMediaListOptions) => Promise<{ media: MediaItem[]; }>
```
Retrieves media items from the device gallery.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------------- | ----------------------------------- |
| **`options`** | GetMediaListOptions | - The options for retrieving media. |
**Returns:** Promise<{ media: MediaItem[]; }>
--------------------
### getMedia(...)
```typescript
getMedia(options: GetMediaOptions) => Promise
```
Retrieves details of a specific media item by its ID.
| Param | Type |
| ------------- | ----------------------------------------------------------- |
| **`options`** | GetMediaOptions |
**Returns:** Promise<FullMediaItem>
--------------------
### Interfaces
#### MediaItem
| Prop | Type | Description |
| ---------------- | ----------------------------------------------------- | -------------------------------------------------------------------- |
| **`id`** | string | Unique identifier of the media item. |
| **`type`** | 'image' \| 'video' | The type of media (image or video). |
| **`createdAt`** | number | The Unix timestamp in milliseconds when the media was created. |
| **`thumbnail`** | string | Base64-encoded thumbnail image (only in `getMediaList`). |
| **`baseColor`** | string | Dominant color of the image (requires `includeBaseColor`). |
| **`name`** | string | Original file name of the media (only applicable for web platforms). |
| **`width`** | number | Width of the media in pixels (requires `includeDetails`). |
| **`height`** | number | Height of the media in pixels (requires `includeDetails`). |
| **`fileSize`** | number | Size of the file in bytes. |
| **`mimeType`** | string | The MIME type of the media item (e.g., "image/jpeg", "video/mp4"). |
| **`isFavorite`** | boolean | Indicates whether the media item is marked as a favorite. (iOS-only) |
| **`isHidden`** | boolean | Indicates whether the media item is hidden. (iOS-only) |
| **`subtype`** | MediaSubtype | The subtype of the media, indicating special properties |
#### GetMediaListOptions
| Prop | Type | Description | Default |
| ---------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **`type`** | 'image' \| 'video' \| 'all' | The type of media to retrieve. Default is `"all"`. - `"image"`: Only images - `"video"`: Only videos - `"all"`: Both images and videos | "all" |
| **`limit`** | number | The maximum number of media items to return. | |
| **`startAt`** | number | The starting index for pagination. | |
| **`thumbnailSize`** | number | The size of the thumbnail in pixels. Example: `200` for 200x200px. | |
| **`sort`** | 'oldest' \| 'newest' | Sort order of the media items. - `"oldest"`: Oldest first - `"newest"`: Newest first | "newest" |
| **`includeDetails`** | boolean | Whether to include additional details like width, height. | |
| **`includeBaseColor`** | boolean | Whether to extract and return the dominant color of the image. | |
| **`filter`** | MediaFilter | Filter applied to the media selection | |
#### FullMediaItem
An extended version of `MediaItem` returned by `getMedia`.
| Prop | Type | Description |
| ---------- | ------------------- | ---------------------------------------------- |
| **`path`** | string | File path or accessible URI of the media item. |
#### GetMediaOptions
| Prop | Type | Description | Default |
| ---------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **`id`** | string | The unique identifier of the media item. | |
| **`includeDetails`** | boolean | Whether to include additional metadata such as width, height, and file size. | false |
| **`includeBaseColor`** | boolean | Whether to extract and return the dominant color of the image. | false |
| **`includePath`** | boolean | Whether to generate a temporary path to access the media. Available on iOS, Android, and Web. - On **iOS & Android**, the file path is only available if enabled. - On **Web**, the browser automatically provides a temporary URL. | false (iOS & Android), always available on Web |
### Enums
#### MediaSubtype
| Members | Value | Description |
| ----------------- | --------------------------- | -------------------------------------------- |
| **`MotionPhoto`** | "motion_photo" | A Live Photo (iOS) or Motion Photo (Android) |
| **`Panorama`** | "panorama" | A panorama image |
| **`HDR`** | "hdr" | A high dynamic range (HDR) image |
| **`Screenshot`** | "screenshot" | A screenshot |
| **`Portrait`** | "portrait" | A photo with depth effect (bokeh) |
| **`SlowMotion`** | "slow_motion" | A high frame rate slow-motion video |
| **`Timelapse`** | "timelapse" | A time-lapse video |
#### MediaFilter
| Members | Value | Description |
| ---------------- | ------------------------- | ------------------------------- |
| **`All`** | "all" | No filtering, returns all media |
| **`Panorama`** | "panorama" | Only return panoramic images |
| **`HDR`** | "hdr" | Only return HDR images |
| **`Screenshot`** | "screenshot" | Only return screenshots |
## License
This project is **dual-licensed** under:
1. **MIT License (Free & Open-Source)** – For personal, educational, and open-source use.
2. **Commercial License** – Required for closed-source, proprietary, or commercial use.
See the [LICENSE](LICENSE) file for more details.