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

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:

<!-- 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:

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

📖 Basic Usage

1. Import the Plugin

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

2. Request Permissions

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

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

3. Get Media Files

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

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

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

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

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

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

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

Save Media File

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

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

Check/Request Permissions

// 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:

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:

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)

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

How do I filter music by artist or album?

// 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?

// 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?

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

₿ 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.