@odion-cloud/capacitor-mediastore/README.md

A Capacitor plugin that provides comprehensive access to Android MediaStore API for media file access and metadata retrieval. This plugin is specifically designed to overcome the limitations of Capacitor's filesystem API, particularly for accessing SD car

# Capacitor MediaStore Plugin

A simple and powerful Capacitor plugin that lets you access media files (music, photos, videos) on Android devices, including SD card storage.

## 🚀 Quick Start

```bash
npm install @odion-cloud/capacitor-mediastore
npx cap sync
```

## 📱 What This Plugin Does

- ✅ Get all your music files with details (title, artist, album, duration)
- ✅ Access photos and videos from device storage
- ✅ Read files from both internal storage and SD card
- ✅ Get music albums and playlists
- ✅ Save new media files to device
- ✅ Works on all Android versions (6.0+)

## 🛠️ Setup

### Android Permissions

Add these permissions to `android/app/src/main/AndroidManifest.xml`:

```xml
<!-- For Android 6-12 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" 
                 android:maxSdkVersion="32" />

<!-- For Android 13+ -->
<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" />
```

### iOS Setup (Optional)

Add to `ios/App/App/Info.plist`:

```xml
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to your photos and media</string>
```

## 📖 Basic Usage

### 1. Import the Plugin

```typescript
import { CapacitorMediaStore } from '@odion-cloud/capacitor-mediastore';
```

### 2. Request Permissions

```typescript
// Request all media permissions
const permissions = await CapacitorMediaStore.requestPermissions();

// Or request specific types
const audioOnly = await CapacitorMediaStore.requestPermissions({ 
  types: ['audio'] 
});
```

### 3. Get Media Files

```typescript
// Get all media files (photos, music, videos)
const allMedia = await CapacitorMediaStore.getMedias({
  limit: 50,
  includeExternal: true // Include SD card files
});

console.log(`Found ${allMedia.totalCount} files`);
```

### 4. Get Specific Media Types

```typescript
// Get all music files
const music = await CapacitorMediaStore.getMediasByType({
  mediaType: 'audio',
  sortBy: 'TITLE',
  includeExternal: true
});

// Get all photos
const photos = await CapacitorMediaStore.getMediasByType({
  mediaType: 'image',
  limit: 100
});

// Get all videos
const videos = await CapacitorMediaStore.getMediasByType({
  mediaType: 'video'
});

// Get documents (PDF, DOC, TXT, etc.)
const documents = await CapacitorMediaStore.getMediasByType({
  mediaType: 'document'
});
```

## 🎵 Music App Example

```typescript
async function buildMusicLibrary() {
  // Ask for permission to read music files
  await CapacitorMediaStore.requestPermissions({ types: ['audio'] });
  
  // Get all songs from device (including SD card)
  const result = await CapacitorMediaStore.getMediasByType({
    mediaType: 'audio',
    sortBy: 'TITLE',
    includeExternal: true
  });
  
  // Display songs with details
  result.media.forEach(song => {
    console.log(`${song.title} by ${song.artist}`);
    console.log(`Album: ${song.album}, Duration: ${song.duration}ms`);
    console.log(`Location: ${song.isExternal ? 'SD Card' : 'Internal'}`);
  });
  
  return result.media;
}
```

## 📸 Photo Gallery Example

```typescript
async function buildPhotoGallery() {
  // Ask for permission to read photos
  await CapacitorMediaStore.requestPermissions({ types: ['images'] });
  
  // Get recent photos
  const photos = await CapacitorMediaStore.getMediasByType({
    mediaType: 'image',
    sortBy: 'DATE_ADDED',
    sortOrder: 'DESC',
    limit: 50
  });
  
  return photos.media;
}
```

## 📋 API Reference

### Get All Media Files

```typescript
getMedias(options?: {
  limit?: number;           // How many files to get
  offset?: number;          // Skip first N files  
  sortBy?: string;          // Sort by: 'DATE_ADDED', 'TITLE', 'SIZE'
  sortOrder?: 'ASC' | 'DESC'; // Sort direction
  includeExternal?: boolean; // Include SD card (default: true)
})
```

### Get Media by Type

```typescript
getMediasByType(options: {
  mediaType: 'audio' | 'image' | 'video' | 'document';
  limit?: number;
  offset?: number;
  sortBy?: string;
  sortOrder?: 'ASC' | 'DESC';
  includeExternal?: boolean;
  albumName?: string;       // Filter by album (audio only)
  artistName?: string;      // Filter by artist (audio only)
})
```

### Get Music Albums

```typescript
getAlbums(): Promise<{
  albums: Array<{
    id: string;
    name: string;
    artist: string;
    trackCount: number;
    albumArtUri?: string;
  }>;
  totalCount: number;
}>
```

### Save Media File

```typescript
saveMedia(options: {
  data: string;             // Base64 data or file URI
  fileName: string;         // Name for the file
  mediaType: 'audio' | 'image' | 'video';
  albumName?: string;       // Album to save in (optional)
  relativePath?: string;    // Custom folder path (optional)
}): Promise<{
  success: boolean;
  uri?: string;            // URI of saved file
  error?: string;          // Error message if failed
}>
```

### Get Media Metadata

```typescript
getMediaMetadata(options: {
  filePath: string;        // URI of the media file
}): Promise<{
  media: MediaFile;        // File with complete metadata
}>
```

### Check/Request Permissions

```typescript
// Check current permissions
checkPermissions(): Promise<PermissionStatus>

// Request permissions
requestPermissions(options?: {
  types?: ('audio' | 'images' | 'video')[];
}): Promise<PermissionStatus>
```

## 📝 Media File Properties

When you get media files, each file includes:

```typescript
interface MediaFile {
  id: string;               // Unique ID
  uri: string;              // File path
  displayName: string;      // File name
  size: number;             // File size in bytes
  mimeType: string;         // File type (e.g., 'audio/mp3')
  dateAdded: number;        // When added to device
  mediaType: string;        // 'audio', 'image', 'video'
  
  // For music files
  title?: string;           // Song title
  artist?: string;          // Artist name
  album?: string;           // Album name
  albumArtist?: string;     // Album artist
  composer?: string;        // Song composer
  duration?: number;        // Length in milliseconds
  genre?: string;           // Music genre
  year?: number;            // Release year
  track?: number;           // Track number
  bitrate?: number;         // Audio bitrate (kbps)
  sampleRate?: number;      // Sample rate (Hz)
  channels?: number;        // Audio channels (1=mono, 2=stereo)
  albumArtUri?: string;     // Album cover image URI
  
  // For images/videos
  width?: number;           // Image/video width
  height?: number;          // Image/video height
  
  // Storage info
  isExternal?: boolean;     // true if on SD card
}
```

## 🔧 Permission Types

| Type | What It Accesses | Android Version |
|------|------------------|-----------------|
| `audio` | Music, podcasts, sound files | All versions |
| `images` | Photos, pictures, images | All versions |
| `video` | Videos, movies | All versions |
| `document` | PDF, DOC, TXT, and other documents | All versions |

## ❓ Common Questions

### How do I access SD card files?

Set `includeExternal: true` in your options:

```typescript
const result = await CapacitorMediaStore.getMediasByType({
  mediaType: 'audio',
  includeExternal: true  // This includes SD card
});
```

### Why am I not getting any files?

1. Make sure you requested permissions first
2. Check that permissions were granted
3. Try running on a real device (not simulator)

```typescript
// Debug permissions
const permissions = await CapacitorMediaStore.checkPermissions();
console.log('Current permissions:', permissions);
```

### How do I filter music by artist or album?

```typescript
// Get songs by specific artist
const artistSongs = await CapacitorMediaStore.getMediasByType({
  mediaType: 'audio',
  artistName: 'Taylor Swift'
});

// Get songs from specific album
const albumSongs = await CapacitorMediaStore.getMediasByType({
  mediaType: 'audio',
  albumName: 'Abbey Road'
});
```

### How do I save a new media file?

```typescript
// Save an audio file
const result = await CapacitorMediaStore.saveMedia({
  data: 'base64-encoded-audio-data',
  fileName: 'my-song.mp3',
  mediaType: 'audio',
  albumName: 'My Custom Album'
});

if (result.success) {
  console.log('File saved at:', result.uri);
}
```

### How do I get detailed metadata for a file?

```typescript
// Get complete metadata for a specific song
const metadata = await CapacitorMediaStore.getMediaMetadata({
  filePath: 'content://media/external/audio/media/123'
});

console.log('Song:', metadata.media.title);
console.log('Bitrate:', metadata.media.bitrate);
console.log('Sample Rate:', metadata.media.sampleRate);
```

## 🤝 Platform Support

### 📱 Supported Devices

| Platform | Support Level | Features | Notes |
|----------|---------------|----------|-------|
| **Android 6.0+** | ✅ **Full Support** | All media types, SD card, rich metadata | Production ready |
| **iOS 12+** | 🚧 **Coming Soon** | Photos, videos, music library | Expected Q2 2025 |
| **Web** | ⚠️ **Development Only** | Mock data for testing | Not for production |

### 🏆 Android Compatibility

- **Android 14+** (API 34+): Visual media permissions, latest features
- **Android 13** (API 33): Granular media permissions 
- **Android 10-12** (API 29-32): Scoped storage, external volumes
- **Android 6-9** (API 23-28): Runtime permissions, full SD card access
- **Android 5** (API 21-22): Basic support, limited external storage

### 📱 iOS Support Coming Soon!

We're actively working on iOS support with full Photos framework integration. Expected features:
- Access to Photos and Videos
- Music library integration
- Album and artist metadata

## 💝 Support This Project

Help me improve this plugin and build better tools for the community!

### 🤝 GitHub Sponsors
- **GitHub Sponsors**: [github.com/sponsors/odion-cloud](https://github.com/sponsors/odion-cloud)

### ₿ Cryptocurrency Support
- **Bitcoin (BTC)**: `bc1q2k0ftm2fgst22kzj683e8gpau3spfa23ttkg26`
- **USDT (Ethereum)**: `0xd6f4d8733c8C23e7bEC8Aeba37F4b3D2e93172d1`
- **USDT (BNB Chain)**: `0xd6f4d8733c8C23e7bEC8Aeba37F4b3D2e93172d1`
- **USDT (TRON/TRC20)**: `TXVy781mQ2tCuQ1BrattXWueUHp1wB5fwt`
- **USDT (Solana)**: `GZ8jmSUUzc4dQF7Cthj2atomvpBZWqccR81N9DL4o1Be`
- **USDT (TON)**: `UQAthXSNIlauj3SrzpDAU4VYxgEVV3niOSmeTPCtMBKGfEAE`

### 💻 Why Support?
Your contributions help me:
- Upgrade to better development hardware
- Improve my workspace and productivity  
- Dedicate more time to open source projects
- Add iOS support and new features faster
- Provide better documentation and examples

### 🤝 Other Ways to Help
- ⭐ **Star the project** on GitHub
- 🐛 **Report issues** and suggest features
- 📖 **Improve documentation** 
- 💬 **Share with other developers**

## 📄 License

MIT License - feel free to use in your projects!

---

**Need help?** Check the examples above or create an issue on GitHub.