EasyMediaPicker

2.2.0indexed

Unified coroutine-based API for picking images, videos and files with Compose integration, camera capture, permission handling, multi-select support, and platform-specific result metadata.

AndroidJSJVMNative·BasemNasr/EasyMediaPicker

Stars

—

Used by

dependents

—

Health

/ 100

EasyMediaPicker KMP

A Kotlin Multiplatform library for picking images, videos, and files across Android, iOS, Desktop, and Web platforms.

Demo

Screenshot

Overview

EasyMediaPicker KMP is the multiplatform evolution of EasyMediaPicker. It provides a unified, coroutine-based API for media picking operations across all supported platforms.

Features

*Camera capture on web uses the browser's built-in camera interface via capture attribute.

Installation

Option 1: Maven Central (Recommended - Supports Android, iOS, Desktop, Web)

Add the dependency to your shared module's build.gradle.kts:

// In your shared module (e.g., composeApp or shared)
kotlin {
    sourceSets {
        commonMain.dependencies {
            // Core logic
            implementation("io.github.basemnasr-labs:easy-media-picker-core:2.2.0")
            
            // Compose Multiplatform UI integration
            implementation("io.github.basemnasr-labs:easy-media-picker-compose:2.2.0")
        }
    }
}

Option 2: JitPack (Android & Desktop Only)

⚠️ Note: JitPack cannot build iOS artifacts. Use this only for Android/Desktop projects.

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
        maven(url = "https://jitpack.io") {
            // Exclude module metadata to avoid iOS resolution errors
            metadataSources {
                mavenPom()
                artifact()
            }
        }
    }
}

// In your androidMain or desktopMain (NOT commonMain)
androidMain.dependencies {
    implementation("com.github.BasemNasr.EasyMediaPicker:easy-media-picker-core:v2.2.0")
    implementation("com.github.BasemNasr.EasyMediaPicker:easy-media-picker-compose:v2.2.0")
}

For Android-only projects

If you only need Android support and do not need KMP, you have two options:

1. XML / View-based Android apps (legacy API)

Use the original Android-only API (EasyPicker / FragmentEasyPicker) from JitPack:

// settings.gradle / settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

// build.gradle (app)
dependencies {
    implementation "com.github.BasemNasr:EasyMediaPicker:v2.2.0"
}

This version is designed primarily for XML / View-based UIs.
You use it from Activity / Fragment as shown in the legacy examples below.
There is no direct Compose API; in a Compose screen you would call it via interop (e.g. using AndroidView or triggering the picker from an Activity/Fragment method).

2. Android apps using Jetpack Compose

If your Android-only app is already using Jetpack Compose, it is recommended to use the new KMP version even if you only target Android:

dependencies {
    // Core API (Android implementation included)
    implementation("com.github.BasemNasr.EasyMediaPicker:easy-media-picker-core:v2.2.0")

    // Compose integration (for rememberMediaPickerState)
    implementation("com.github.BasemNasr.EasyMediaPicker:easy-media-picker-compose:v2.2.0")
}

This gives you a first-class Compose API via rememberMediaPickerState().
You can still stay Android-only, but your code is ready for iOS/Desktop later.

Quick Start

With Compose Multiplatform (Recommended)

@Composable
fun MediaPickerDemo() {
    val pickerState = rememberMediaPickerState()
    var selectedImage by remember { mutableStateOf<MediaResult?>(null) }
    
    Column {
        Button(onClick = {
            pickerState.pickImage { result ->
                selectedImage = result
            }
        }) {
            Text("Pick Image")
        }
        
        selectedImage?.let { image ->
            Text("Selected: ${image.name}")
            Text("Size: ")
        }
    }
}

Without Compose (Coroutines)

// Create picker instance
val picker = MediaPickerFactory.create()

// Pick an image
lifecycleScope.launch {
    val image = picker.pickImage()
    image?.let {
        println("Selected: ${it.uri}")
        println("Name: ${it.name}")
        println("Size: ${it.size} bytes")
    }
}

Platform Setup

Android

The library handles permissions internally. Just make sure your Activity extends ComponentActivity:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // If NOT using Compose, initialize the factory
        MediaPickerFactory.initialize(this)
        
        // For Compose, the initialization is automatic when using rememberMediaPickerState()
    }
}

Note: The required permissions are already declared in the library's manifest and will be merged automatically.

iOS

Initialize the picker from your UIViewController:

Swift:

import EasyMediaPickerCore

class MyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        MediaPickerFactory.shared.initialize(viewController: self)
    }
}

Kotlin (in shared code):

// Called from iOS native code
fun initializePicker(viewController: UIViewController) {
    MediaPickerFactory.initialize(viewController)
}

Add required keys to your Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photos to let you pick images.</string>
<key>NSCameraUsageDescription</key>
<string>We need camera access to take photos.</string>

Desktop

No special setup required. Optionally, initialize with a window for proper dialog positioning:

fun main() = application {
    Window(onCloseRequest = ::exitApplication) {
        LaunchedEffect(Unit) {
            MediaPickerFactory.initialize(window)
        }
        
        App()
    }
}

Web (JavaScript)

No special setup required. The library uses the HTML5 File API which is supported in all modern browsers.

// In your Compose for Web app
@Composable
fun App() {
    val pickerState = rememberMediaPickerState()
    
    Button(onClick = {
        pickerState.pickImage { result ->
            result?.let {
                console.log("Selected: ${it.name}")
            }
        }
    }) {
        Text("Pick Image")
    }
}

Browser Compatibility:

Chrome/Edge: Full support
Firefox: Full support
Safari: Full support (iOS 13+)

Limitations:

Camera capture uses browser's native camera UI (via capture attribute)
File access is sandboxed by browser security
No direct file system access (files are accessed via Blob URLs)
Video duration metadata may not be available on all browsers

API Reference

MediaResult

data class MediaResult(
    val uri: String,           // Platform-specific URI as string
    val name: String?,         // File name
    val size: ?,           
     mimeType: String?,     
     type: MediaType,       
     duration: ?,       
     platformData: Any?     
)

MediaPicker Interface

MediaPickerConfig

data class MediaPickerConfig(
    val maxSelection: Int = 1,
    val allowedMimeTypes: List<String> = emptyList(),
    val copyToCache: Boolean = ,
     imageQuality:  = ,
     compressImages:  = ,
     maxImageDimension:  = 
)


MediaPickerConfig.Default
MediaPickerConfig.Images
MediaPickerConfig.Videos
MediaPickerConfig.Documents

Usage Examples

Pick Multiple Images

val pickerState = rememberMediaPickerState()

Button(onClick = {
    pickerState.pickImages(maxSelection = 5) { images ->
        images.forEach { image ->
            println("${image.name}: ${image.formattedSize()}")
        }
    }
}) {
    Text("Select up to 5 images")
}

Pick PDF Documents

val config = MediaPickerConfig(
    allowedMimeTypes = listOf("application/pdf")
)

pickerState.pickFile(config) { file ->
    file?.let {
        println("PDF selected: ${it.name}")
    }
}

Capture Photo with Camera

pickerState.captureImage { photo ->
    photo?.let {
        println("Photo captured: ${it.uri}")
    }
}

Access Platform-Specific Data

// On Android
val androidUri = result.platformData as? android.net.Uri
androidUri?.let { uri ->
    val inputStream = context.contentResolver.openInputStream(uri)
    // Process the stream
}

// On iOS
val nsUrl = result.platformData as? platform.Foundation.NSURL
nsUrl?.let { url ->
    val data = NSData.dataWithContentsOfURL(url)
    // Process the data
}


 file = result.platformData ? java.io.File
file?.let {
     bytes = it.readBytes()
    
}

Migration from Android-only Version

If you're currently using the Android-only EasyMediaPicker, here's how to migrate:

Before (Android-only)

val easyPicker = EasyPicker.Builder(this)
    .setListener(object : OnCaptureMedia {
        override fun onCaptureMedia(request: Int, files: ArrayList<FileResource>?) {
            files?.forEach { file ->
                println("Selected: ${file.uri}")
            }
        }
    })
    .build()

easyPicker.chooseImage()

After (KMP)

// With Compose
val pickerState = rememberMediaPickerState()

pickerState.pickImage { result ->
    result?.let {
        println("Selected: ${it.uri}")
    }
}

// Without Compose
val picker = MediaPickerFactory.create(activity)
lifecycleScope.launch {
    val result = picker.pickImage()
    result?.let {
        println("Selected: ${it.uri}")
    }
}

Key Differences

Project Structure

EasyMediaPicker/
├── easy-media-picker-core/          # Core KMP module
│   └── src/
│       ├── commonMain/              # Common API
│       ├── androidMain/             # Android implementation
│       ├── iosMain/                 # iOS implementation
│       ├── desktopMain/             # Desktop implementation
│       └── jsMain/                  # Web (JS) implementation
├── easy-media-picker-compose/       
│   └── src/
│       ├── commonMain/              
│       ├── androidMain/             
│       ├── iosMain/                 
│       ├── desktopMain/             
│       └── jsMain/                  
├── EasyMediaPicker/                 
└── app/

License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you find this library helpful, please consider giving it a ⭐ on GitHub!

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

SaltAudioTag★ 161

MoriaflyCross-platform audio tag editor in early development, leveraging Compose for UI and kotlinx-io for IO operations, supporting FLAC format metadata reading and writing.Shared: image, file, compose-multiplatform

krop★ 178

tamimattafiFacilitates image cropping with support for shapes, aspect ratios, transformations, and large images. Offers out-of-the-box or custom UI options and easy integration with image sources.Shared: image, compose-multiplatform

ParticleEmitter★ 91

PiotrPrusPhysics-driven particle effects with two renderers: layout-based custom particle content and high-performance canvas; directional gravity, edge behaviors (bounce/stick/wrap), blend modes, multi-emitter orchestration.Shared: image, compose-multiplatform

Emoji.kt★ 75

kosi-libsDisplay and parse emoji in strings, extract and list emoji, replace short-codes/emoticons; render using Noto images or animations with system-font fallback and customizable download handling.Shared: image, compose-multiplatform

MapComposeMP★ 125

p-lrFacilitates efficient display of tiled maps with support for markers, paths, and gestures like flinging, dragging, scaling, and rotating. Features marker clustering and multi-layer capabilities, ensuring responsive and smooth map interactions.Shared: image, compose-multiplatform

kflite★ 62

ShadAdmanFresh and improved version of moko tensorflow, facilitating machine learning model integration with enhanced functionality and ongoing development for evolving needs.Shared: image, compose-multiplatform

Pick Image	✅	✅	✅	✅
Pick Multiple Images	✅	✅	✅	✅
Pick Video	✅	✅	✅	✅
Pick Multiple Videos	✅	✅	✅	✅
Pick File	✅	✅	✅	✅
Pick Multiple Files	✅	✅	✅	✅
Camera Capture (Photo)	✅	✅	❌	✅*
Camera Capture (Video)	✅	✅	❌	✅*
Permission Handling	✅	✅	N/A	N/A
Compose Integration	✅	✅	✅	✅

Callback style	Listener interface	Suspend functions / callbacks
Result type	`FileResource`	`MediaResult`
URI type	`android.net.Uri`	`String` (with `platformData` for native type)
Multi-platform	Android only	Android, iOS, Desktop
Compose support	Manual integration	`rememberMediaPickerState()`