Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stephan-fischer/capacitor-gallery-plus
📸 A Capacitor plugin for accessing and managing media files (photos & videos) on iOS and Android. Supports retrieving media metadata, paths, and thumbnails.
https://github.com/stephan-fischer/capacitor-gallery-plus
android capacitor capacitor-plugin gallery ios media photos typescript videos
Last synced: 9 days ago
JSON representation
📸 A Capacitor plugin for accessing and managing media files (photos & videos) on iOS and Android. Supports retrieving media metadata, paths, and thumbnails.
- Host: GitHub
- URL: https://github.com/stephan-fischer/capacitor-gallery-plus
- Owner: stephan-fischer
- License: other
- Created: 2025-01-28T19:21:11.000Z (11 days ago)
- Default Branch: main
- Last Pushed: 2025-01-28T19:56:40.000Z (11 days ago)
- Last Synced: 2025-01-28T20:29:05.536Z (11 days ago)
- Topics: android, capacitor, capacitor-plugin, gallery, ios, media, photos, typescript, videos
- Language: JavaScript
- Homepage:
- Size: 128 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
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.getMediaFiles();
console.log('Media files:', result);
} catch (error) {
console.error('Error retrieving media:', error);
}
}
```
## API
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [`getMedias(...)`](#getmedias)
* [`getMedia(...)`](#getmedia)
* [Interfaces](#interfaces)
### checkPermissions()
```typescript
checkPermissions() => Promise<{ status: string; }>
```
**Returns:** Promise<{ status: string; }>
--------------------
### requestPermissions()
```typescript
requestPermissions() => Promise<{ status: string; }>
```
**Returns:** Promise<{ status: string; }>
--------------------
### getMedias(...)
```typescript
getMedias(options: {
type?: "image" | "video" | "all";
limit?: number;
startAt?: number;
thumbnailSize?: number;
sort?: "oldest" | "newest";
includeDetails?: boolean;
includeBaseColor?: boolean;
generatePath?: boolean;
filter?: "all" | "panorama" | "hdr" | "screenshot";
}) => Promise<{ media: MediaItem[]; }>
```
| Param | Type | Description |
|--------------|------------------------------------------------------------------------------------------------------------------------|-------------|
| **`type`** | "image" \| "video" \| "all" | The type of media to retrieve. Default is `"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 (e.g., `200` for 200x200px). |
| **`sort`** | "oldest" \| "newest" | Sort order of the media items. Default is `"newest"`. |
| **`includeDetails`** | boolean | Whether to include additional details like width, height, and file size. |
| **`includeBaseColor`** | boolean | Whether to extract and return the dominant color of the image. |
| **`generatePath`** | boolean | Whether to generate a temporary path to access the media. |
| **`filter`** | "all" \| "panorama" \| "hdr" \| "screenshot" | Filters the media based on specific types (e.g., panorama, HDR, or screenshots). Default is `"all"`. |
**Returns:**
A **Promise** resolving to an object containing a list of media items:
```typescript
Promise<{ media: MediaItem[] }>
```
--------------------
### getMedia(...)
```typescript
getMedia(options: { id: string; includeBaseColor?: boolean; }) => Promise
```
| Param | Type |
| ------------- | -------------------------------------------------------- |
| **`options`** | { id: string; includeBaseColor?: boolean; } |
**Returns:** Promise<MediaItem>
--------------------
### 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 thumbnail image (if available). |
| **baseColor** | string | Dominant color of the image (if requested). |
| **name** | string | Original file name of the media. |
| **width** | number | Width of the media in pixels. |
| **height** | number | Height of the media in pixels. |
| **fileSize** | number | Size of the file in bytes. |
| **path** | string | File path or accessible URI of the media item. |
## 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.