Flet-media-library — Media Library Access for Flet

[fazi-gondal]

Hi @FeodorFitsner @ndonkoHenri @xzripper

I would like to share a new open-source Flet service extension for working with the device media library from Python:

flet-media-library

GitHub: https://github.com/fazi-gondal/Flet-media-library
PyPI: https://pypi.org/project/flet-media-library/
Latest version: 1.1.2
License: MIT
Platforms: Android & iOS
Requires: Flet >= 1.0.0

What is it?

flet-media-library provides a Flet-native Python API for accessing and managing photos, videos, and audio in the device media library.

It is designed for applications such as:

• Gallery applications
• Photo/video browsers
• Media managers
• Video editors
• Video downloaders
• Camera applications
• Audio recorders
• File/media organizers
• Backup applications
• Social/media applications
• Any Flet application that needs access to device media

The package uses Flutter's photo_manager for cross-platform media-library functionality and adds custom native Android Kotlin functionality where the upstream package does not provide the required APIs.

Main Features

• Browse photos, videos, and audio
• Query albums and folders
• Per-media-type permissions
• Android 13+ granular media permissions
• Android 14+ selected/limited media access
• iOS limited Photo Library access
• Paginated media queries
• Sorting and filtering
• Date-range filtering
• MIME-type filtering on Android
• Fast thumbnails
• File-path thumbnails for large galleries
• Save images directly to Pictures/ or DCIM/
• Save videos directly to Movies/ or DCIM/
• Save audio directly to Music/ on Android
• Rename media on Android
• Move media between public folders on Android
• Delete individual or multiple assets
• Copy assets where the platform permits it
• Real-time media-library change notifications
• Runtime platform capability detection
• Typed exceptions
• Thumbnail/file cache management

Android Permission Model

The package follows the least-privilege approach and does not require MANAGE_EXTERNAL_STORAGE.

It handles:

• Android 6–12: READ_EXTERNAL_STORAGE
• Android 13+: READ_MEDIA_IMAGES
• Android 13+: READ_MEDIA_VIDEO
• Android 13+: READ_MEDIA_AUDIO
• Android 14+: READ_MEDIA_VISUAL_USER_SELECTED

This allows applications to request only the media types they actually need.

iOS

The package integrates with PhotoKit and supports:

• Photo Library access
• Limited/partial access
• Saving photos and videos
• Album/media queries
• Media deletion
• Thumbnail generation
• Permission state handling

Android-only operations such as audio saving, renaming and moving are reported through the API as unsupported on iOS instead of silently failing.

Native Android Extensions

One of the goals of this package is to fill gaps that are not currently covered by photo_manager.

Custom Kotlin implementations provide:

• Audio saving through Android MediaStore.Audio
• Asset renaming
• Moving assets using MediaStore.RELATIVE_PATH
• Android write-consent handling

This means applications can work with the public media library without requiring unrestricted filesystem access.

Thumbnail Performance

Two thumbnail APIs are available:

await media.get_thumbnail(...)

for simple Base64-based usage, and:

await media.get_thumbnail_path(...)

for larger galleries.

get_thumbnail_path() writes the thumbnail to a local cache and returns its filesystem path, avoiding repeated Base64 transfers between Python and the Flutter/Dart layer.

This is particularly useful for scrolling gallery grids containing hundreds or thousands of assets.

Permissions API

Permissions can be queried and requested independently:

status = await media.request_permissions([
    "image",
    "video",
    "audio",
])

print(status.states)
print(status.all_granted)
print(status.any_limited)
print(status.can_request)

Applications can therefore build their UI around the actual permission state instead of assuming that all media access was granted.

Media Queries

Media can be queried with:

page = await media.get_assets(
    media_type="video",
    limit=30,
    offset=0,
    sort_by="date_added",
    sort_order="desc",
)

Supported filtering/sorting includes:

• Image/video/audio/all
• Album
• MIME type
• Date added
• Date modified
• Display name
• Size
• Duration
• Ascending/descending order
• Pagination

The returned MediaAssetPage provides:

• items
• total
• offset
• limit
• has_more

Saving Media

Images:

await media.save_image(
    path,
    file_name="photo.jpg",
    relative_path="Pictures/MyApp",
)

Videos:

await media.save_video(
    path,
    file_name="video.mp4",
    relative_path="Movies/MyApp",
)

Android audio:

await media.save_audio(
    path,
    file_name="recording.m4a",
    relative_path="Music/Recordings",
)

relative_path is the preferred destination argument, while album remains available as a backward-compatible alias.

Media Management

The package also provides:

await media.delete_asset(asset_id)
await media.delete_assets(asset_ids)
await media.rename_asset(asset_id, new_name)
await media.move_asset(asset_id, target_relative_path)
await media.copy_asset(asset_id, target_album)

Platform differences are exposed through UnsupportedError and capability detection.

Change Notifications

Applications can monitor the device media library:

media.on_change = on_media_changed
await media.start_change_notify()

This allows applications to react when media is added, removed, or modified instead of constantly polling the library.

Capability Detection

Applications can inspect the current platform:

capabilities = await media.get_capabilities()

Capabilities include:

• supports_audio_save
• supports_move
• supports_rename
• supports_copy
• supports_mime_filter
• supports_limited_access
• supports_thumbnail_path
• supports_change_notify
• Android SDK level
• Current platform

This makes it possible to write platform-aware applications without hard-coding assumptions.

Quick Start

pip install flet-media-library

Then:

import flet as ft
from flet_media_library import MediaLibrary

async def main(page: ft.Page):
    media = MediaLibrary()

    page.services.append(media)
    page.update()

    status = await media.request_permissions(["image", "video"])

    if not status.all_granted and not status.any_limited:
        page.add(ft.Text("Media permission denied"))
        return

    assets = await media.get_assets(
        media_type="image",
        limit=20,
    )

    for asset in assets.items:
        thumbnail = await media.get_thumbnail_path(
            asset.id,
            width=120,
            height=120,
        )

        page.add(
            ft.Image(
                src=thumbnail,
                width=120,
                height=120,
            )
        )

ft.run(main)

Demo Application

The repository also includes a full demo application with:

• Media gallery
• Photo/video thumbnails
• Video playback
• Audio playback
• Camera capture
• Audio recording
• Saving captured media
• File moving
• File renaming
• Batch deletion
• Permission handling
• Capability detection
• Automated API smoke testing

A pre-built Android demo APK is available from GitHub Releases:

https://github.com/fazi-gondal/Flet-media-library/releases

Why I am sharing this here

Flet makes it possible to build mobile applications primarily with Python, but mobile applications often need platform-specific capabilities that are outside the normal UI layer.

Media-library access is one of those areas.

This package is intended to provide a reusable Flet service instead of every Flet application having to implement its own Android/iOS media-library integration.

I would love to get feedback from the Flet community about:

• API design
• Android/iOS parity
• Performance with very large media libraries
• Permission handling
• Thumbnail performance
• Additional media-library capabilities that would be useful for Flet applications
• Real-world applications using the package

Repository: https://github.com/fazi-gondal/Flet-media-library

[xzripper]

Nice! Seems like a pretty powerful library! 😃👍 I wish I had a project where I could fully test and use it. Also if you want some feedback make sure to repost this to Discord server or anything related, they'll close the issue and this message will be pretty much hidden in closed issues tab.

[fazi-gondal]

Nice! Seems like a pretty powerful library! 😃👍 I wish I had a project where I could fully test and use it. Also if you want some feedback make sure to repost this to Discord server or anything related, they'll close the issue and this message will be pretty much hidden in closed issues tab.

Thanks! 😃 Really appreciate the feedback and the suggestion.

I’ll share it with the Flet Discord/community as well so it can reach more people who are building mobile apps with Flet and hopefully get some real-world feedback.

Thanks again for taking the time to check it out! 👍