Introducing flet-media-library — A Full Media Library Service Extension for Flet

[fazi-gondal]

Hi @FeodorFitsner @ndonkoHenri @xzripper

I have built and published flet-media-library, an open-source Flet service extension for accessing and managing the device media library from Python.

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 and iOS
Flet: >=1.0.0

The goal is simple: provide Flet applications with a reusable, production-oriented API for working with device photos, videos, audio, albums, permissions, thumbnails and media-management operations.

---

Why this package?

Flet applications can already build the UI and application logic in Python, but mobile applications frequently need native platform integrations.

Accessing the device media library is a good example.

A typical application may need to:

• Ask for photo/video/audio permissions
• Browse thousands of media items
• Display thumbnails efficiently
• Save captured/downloaded media to the public gallery
• Organize files into folders
• Rename files
• Delete files
• React when the gallery changes
• Handle Android's changing permission model
• Handle iOS limited Photo Library access
• Deal with platform-specific API differences

Instead of implementing these pieces separately in every Flet application, flet-media-library provides them through one Python service.

---

Architecture at a high level

The package is implemented as a Flet service extension.

The cross-platform media-library functionality is powered primarily by Flutter's photo_manager.

Where photo_manager does not provide the required functionality, the package adds native Android Kotlin implementations.

Cross-platform functionality

photo_manager is used for:

• Photos
• Videos
• Albums
• Asset queries
• Thumbnails
• Image saving
• Video saving
• Deletion
• Photo Library integration

Custom Android functionality

Native Kotlin handles:

• Audio saving
• MediaStore asset renaming
• MediaStore relative-path moving
• Android-specific write-consent handling

This hybrid approach allows the package to provide functionality that would otherwise require applications to implement their own native plugins.

---

Features

1. Photos, videos and audio

The API treats the device media library as a unified source while still allowing applications to work with specific media types:

image
video
audio
all

---

2. Per-type permissions

Applications can request only the media types they actually need:

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

Permission states are exposed independently:

status["image"]
status["video"]
status["audio"]

Possible states include:

granted
limited
denied
denied_forever
restricted
unknown

The permission model is particularly important on Android 13+, where image, video and audio permissions are granular.

---

Android permission support

The package supports the modern Android media permission model.

Android 6–12

READ_EXTERNAL_STORAGE

with the permission limited to API 32 and below.

Android 13+

READ_MEDIA_IMAGES
READ_MEDIA_VIDEO
READ_MEDIA_AUDIO

Android 14+

READ_MEDIA_VISUAL_USER_SELECTED

for selected/limited visual media access.

The package deliberately does not require:

MANAGE_EXTERNAL_STORAGE

The goal is to use the least amount of permission necessary for media operations.

---

iOS permission support

The package integrates with PhotoKit and supports:

• Full photo-library access
• Limited/partial access
• Permission status checking
• Permission requests
• Re-opening the limited picker
• Saving photos and videos
• Reading albums and assets
• Deleting media

Applications can call:

await media.present_limited(["image", "video"])

when additional selected-media access is required.

---

Album and folder browsing

Applications can retrieve albums:

albums = await media.get_albums(
    media_type="image"
)

Albums can represent collections such as:

• Camera
• Screenshots
• Download
• WhatsApp
• Movies
• Music
• Custom application folders
• System-managed media collections

Each MediaAlbum provides information such as:

id
name
asset_count
media_types
is_all
is_system_album
platform_identifier

---

Media queries

The package provides paginated media queries:

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

Supported filters include:

• Media type
• Album
• MIME type
• Minimum date added
• Maximum date added

Supported sorting includes:

• Date added
• Date modified
• Display name
• Size
• Duration

Pagination provides:

items
total
offset
limit
has_more

This makes the API suitable for gallery applications that cannot load the entire media library at once.

---

Media metadata

Each MediaAsset provides:

id
display_name
mime_type
media_type
size
width
height
duration_ms
date_added
date_modified
orientation
album_id
album_name
relative_path
source_uri

This gives applications enough information to build gallery, media-manager, downloader and editor interfaces without immediately opening the original files.

---

Thumbnail support

There are two thumbnail approaches.

Base64 thumbnail

thumbnail = await media.get_thumbnail(
    asset.id,
    width=200,
    height=200,
)

This is convenient for simple Flet UI usage:

ft.Image(src_base64=thumbnail)

File-path thumbnail

For larger galleries:

thumbnail_path = await media.get_thumbnail_path(
    asset.id,
    width=160,
    height=160,
)

The plugin stores the generated JPEG in its local cache and returns the filesystem path.

This avoids repeatedly transferring large Base64 strings across the Python/Flutter boundary.

For gallery grids and scrolling media browsers, this can significantly reduce unnecessary bridge traffic.

---

Saving images

Images can be saved directly into public media storage:

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

Supported public destinations include:

Pictures/
Pictures/<subfolder>

DCIM/
DCIM/<subfolder>

The implementation uses photo_manager.

---

Saving videos

Videos can be saved directly to public video storage:

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

Supported destinations include:

Movies/
Movies/<subfolder>

DCIM/
DCIM/<subfolder>

---

Saving audio

Audio saving is one of the areas where the package extends beyond the functionality provided by photo_manager.

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

On Android this uses the native:

MediaStore.Audio

API.

Audio can therefore be indexed directly into the public:

Music/

directory.

This feature is currently Android-only.

Calling it on unsupported platforms raises UnsupportedError.

---

Rename media

Android applications can rename assets:

await media.rename_asset(
    asset.id,
    "vacation_sunset.jpg",
)

This uses the Android MediaStore rather than requiring unrestricted filesystem access.

On newer Android versions, the system may require user confirmation when modifying media that the application does not own.

---

Move media

Android 10+ supports moving assets using MediaStore relative paths:

await media.move_asset(
    asset.id,
    "Pictures/Archive",
)

For example:

DCIM/Camera
        ↓
Pictures/Archive

This is implemented through:

MediaStore.RELATIVE_PATH

rather than unrestricted filesystem access.

---

Delete media

Single asset:

await media.delete_asset(asset.id)

Multiple assets:

await media.delete_assets([
    "id1",
    "id2",
    "id3",
])

The underlying platform confirmation behavior is respected.

---

Copy media

The package also exposes:

await media.copy_asset(
    asset.id,
    target_album,
)

However, platform support differs because modern Android scoped storage restricts arbitrary duplication.

The API therefore reports unsupported operations rather than pretending the operation is universally available.

---

Real-time media change notifications

Applications can subscribe to media-library changes:

media.on_change = on_media_changed

await media.start_change_notify()

Applications can use this for:

• Gallery refresh
• New camera photos
• Newly downloaded videos
• Deleted media
• Edited media
• Media synchronization

When finished:

await media.stop_change_notify()

---

Capability discovery

Instead of forcing applications to maintain their own Android/iOS feature matrix, the package exposes:

capabilities = await media.get_capabilities()

Capabilities include:

platform
supports_audio_save
supports_move
supports_rename
supports_copy
supports_mime_filter
supports_limited_access
supports_thumbnail_path
supports_change_notify
android_sdk

For example:

if capabilities["supports_audio_save"]:
    await media.save_audio(...)

This makes platform-specific UI and behavior easier to implement.

---

Typed exceptions

The package provides structured exceptions:

MediaLibraryError
├── PermissionRequiredError
├── PermissionDeniedError
├── UnsupportedError
├── AssetNotFoundError
├── AlbumNotFoundError
├── InvalidArgumentError
└── PlatformError

Applications can therefore handle expected platform and permission failures without relying on parsing error strings.

---

Cache management

Thumbnail/file caches can be cleared:

await media.clear_file_cache()

This is useful for applications that need to control temporary storage usage.

---

Installation

Install from PyPI:

pip install flet-media-library

or:

uv add flet-media-library

For a project using pyproject.toml:

[project]
dependencies = [
    "flet>=1.0.0",
    "flet-media-library>=1.1.2",
]

---

Basic example

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 or 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 includes a full demo application designed to exercise the package on real Android hardware.

The demo includes:

Gallery

• Photo gallery
• Video gallery
• Thumbnail grid
• Media metadata

Playback

• Video playback
• Audio playback

Capture

• Camera preview
• Photo capture
• Audio recording

File management

• Save media
• Rename media
• Move media
• Delete media
• Batch deletion

Testing

The demo also contains an automated smoke-test flow for the package's core APIs.

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

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

This makes it possible to test the package without setting up the complete Flutter/Android development environment first.

---

Building a Flet application

For Android:

uv run flet build apk \
  --split-per-abi \
  --arch arm64-v8a \
  --permissions camera microphone \
  --yes

For iOS:

uv run flet build ipa \
  --permissions camera microphone \
  --info-plist NSPhotoLibraryUsageDescription="Browse and select media from device gallery" \
  --info-plist NSPhotoLibraryAddUsageDescription="Save photos and captured media to library"

---

Local development

The project is open source and contributions are welcome.

git clone https://github.com/fazi-gondal/Flet-media-library.git
cd Flet-media-library

uv sync

uv run pytest tests/

cd src/flutter/flet_media_library

flutter pub get
flutter analyze
dart format --set-exit-if-changed --output=none .

The repository also contains the full demo application under:

examples/media_library_demo/

---

Dependencies and ecosystem

The project builds on several parts of the Flet/Flutter ecosystem:

• Flet — Python framework and extension system
• photo_manager — cross-platform Flutter media-library engine
• flet-camera — camera functionality used by the demo
• flet-video — media playback used by the demo
• flet-audio-recorder — audio recording integration used by the demo

The package itself is MIT licensed.

---

Who can use it?

This package can be useful for many types of Flet applications:

• Gallery apps
• Photo viewers
• Video players
• Video downloaders
• Video editors
• Media editors
• Camera apps
• Audio recording apps
• Voice-note applications
• File managers
• Media organizers
• Backup/synchronization tools
• Social-media applications
• Content-management applications

For example, a Flet video downloader can download a video to temporary storage and then simply call:

await media.save_video(
    downloaded_file,
    file_name="video.mp4",
    relative_path="Movies/MyDownloader",
)

A recording application can similarly save recordings directly into:

Music/Recordings

without implementing its own MediaStore integration.

---

What I would like from the Flet community

I would especially appreciate feedback from people building mobile applications with Flet.

Some areas I would like to explore with the community:

• Additional media-library APIs
• Better Android/iOS feature parity
• Large-library performance
• More efficient gallery virtualization
• Additional metadata
• More media-management operations
• Better handling of platform-specific permission changes
• Testing on different Android versions
• Testing on different iOS versions
• Real-world use cases
• API improvements
• Integration with existing Flet extensions

If you are building a Flet application that needs access to photos, videos or audio, I would also be interested in hearing what APIs you currently have to implement yourself.

---

Links

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

PyPI:
https://pypi.org/project/flet-media-library/

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

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

License: MIT

---

Feedback and discussion

If you have tried the package, please share:

1. Your Flet application/use case
2. Android/iOS version
3. Media-library size
4. Which APIs you are using
5. Any performance or permission issues
6. APIs you would like to see added

The goal is to make flet-media-library a useful reusable building block for Flet mobile applications rather than having every project solve device-media integration independently.

[xzripper]

Answered in the first post in issues tab 😅

[fazi-gondal]

Yes i now i check your reply and thanks for feedback