MediaStore API: co to jest, możliwości i praca ze wspólnymi plikami multimedialnymi

Czym jest MediaStore API?

MediaStore API — to systemowy dostawca treści na platformie Android, przeznaczony do indeksowania, przechowywania i zapewniania dostępu do plików multimedialnych urządzenia. API wchodzi w skład Android SDK i jest dostępne od API Level 1.

MediaStore działa poprzez jednolitą bazę multimediów, która automatycznie skanuje urządzenie i zbiera metadane wszystkich plików multimedialnych. Baza jest aktualizowana przez system podczas dodawania, modyfikacji lub usuwania plików, więc aplikacje zawsze otrzymują aktualne informacje bez ręcznego skanowania.

Główne tabele MediaStore: Images (obrazy), Video (wideo), Audio (audio) i Files (pliki ogólne). Każda tabela zawiera kolumny z metadanymi: nazwa, data utworzenia, rozmiar, typ MIME, współrzędne GPS i inne atrybuty.

Ewolucja MediaStore w wersjach Androida

Przed Androidem 10 deweloperzy używali READ_EXTERNAL_STORAGE do dostępu do wszystkich plików urządzenia. Android 10 (API 29) wprowadził Scoped Storage: aplikacje uzyskały dostęp tylko do własnych plików i przez MediaStore. Android 11 zaostrzył politykę, całkowicie blokując bezpośrednią ścieżkę do katalogów współdzielonych.

Począwszy od Androida 13 (API 33), Google zastąpił READ_EXTERNAL_STORAGE szczegółowymi uprawnieniami: READ_MEDIA_IMAGES, READ_MEDIA_VIDEO i READ_MEDIA_AUDIO. Pozwala to użytkownikowi udzielać dostępu tylko do określonych typów multimediów bez ujawniania całego magazynu.

Jak działa MediaStore: architektura i baza multimediów

MediaStore jest zbudowany w architekturze dostawcy treści: każda aplikacja uzyskuje do niego dostęp przez ContentResolver i Uri. Systemowy skaner multimediów — MediaScannerConnection — automatycznie indeksuje wszystkie pliki na urządzeniu podczas uruchamiania, podłączenia przez USB lub restartu.

Baza multimediów jest przechowywana w systemowej bazie danych i zawiera rekordy dla każdego pliku multimedialnego. Kolumny różnią się dla różnych typów: obrazy mają ORIENTATION i DATE_TAKEN, wideo — DURATION, audio — ARTIST i ALBUM. Deweloperzy mogą wykonywać zapytania podobne do SQL przez query z projection i selection do filtrowania.

val projection = arrayOf(
    MediaStore.Images.Media._ID,
    MediaStore.Images.Media.DISPLAY_NAME,
    MediaStore.Images.Media.DATE_ADDED
)

val cursor = contentResolver.query(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    projection,
    null,
    null,
    MediaStore.Images.Media.DATE_ADDED + " DESC"
)

cursor?.use {
    while (moveToNext()) {
        val name = getString(getColumnIndexOrThrow(MediaStore.Images.Media.DISPLAY_NAME))
    }
}

Content URI i ich znaczenie

Każdy plik multimedialny jest identyfikowany przez Content URI postaci content://media/external/images/media/1234. Zewnętrzny URI (external) wskazuje na magazyn współdzielony, wewnętrzny (internal) — na systemowe pliki multimedialne. Używanie URI zamiast ścieżek plików — kluczowa zaleta MediaStore: aplikacja nie wymaga dostępu do systemu plików i działa przez bezpiecznego dostawcę treści.

Typy plików multimedialnych w MediaStore

MediaStore obsługuje cztery główne typy multimediów, każdy z osobną tabelą i zestawem metadanych. Deweloperzy wybierają odpowiednią tabelę w zależności od typu treści, z którą pracuje aplikacja.

• MediaStore.Images — zdjęcia, zrzuty ekranu i rysunki. Kolumny: BUCKET_DISPLAY_NAME, IS_PRIVATE, LATITUDE, LONGITUDE.
• MediaStore.Video — nagrania wideo i filmy. Kolumny: DURATION, RESOLUTION, IS_DRM.
• MediaStore.Audio — utwory muzyczne i pliki dźwiękowe. Kolumny: ARTIST, ALBUM, COMPOSER, TRACK.
• MediaStore.Files — dokumenty i pozostałe pliki. Dostępny od Androida 10 do ogólnego dostępu.

Oprócz standardowych kolumn, każda tabela zawiera pola systemowe: _ID, DATA (przestarzałe), SIZE, MIME_TYPE, DATE_ADDED, DATE_MODIFIED. Od wersji Android 10 pole DATA jest oznaczone jako deprecated, a deweloperzy powinni pracować przez otwieranie InputStream po URI.

Uprawnienia do pracy z MediaStore

MediaStore wymaga jawnych uprawnień, które różnią się w zależności od wersji Androida. Przed Androidem 13 używano jednego uprawnienia READ_EXTERNAL_STORAGE. Począwszy od Androida 13 (API 33), Google wprowadził szczegółowe uprawnienia dla każdego typu multimediów.

Zapis do MediaStore również wymaga WRITE_EXTERNAL_STORAGE dla Androida 9 i niższych. Począwszy od Androida 10, aplikacja może zapisywać własne pliki do MediaStore bez dodatkowych uprawnień — system automatycznie udziela dostępu przy wstawianiu rekordu przez ContentResolver.insert.

Żądanie uprawnień w czasie wykonania

Uprawnienia MediaStore są żądane przez standardowy mechanizm ActivityResultContracts.RequestMultiplePermissions. Użytkownik może odrzucić żądanie, a aplikacja powinna poprawnie obsłużyć ten scenariusz. Zaleca się sprawdzanie obecności uprawnienia przez ContextCompat.checkSelfPermission przed każdym dostępem do MediaStore.

Przykłady kodu: odczyt i zapis przez MediaStore

MediaStore pozwala nie tylko czytać, ale także zapisywać pliki multimedialne. Do zapisu obrazu lub wideo deweloper używa ContentResolver.insert i otwiera OutputStream po zwróconym URI. System automatycznie dodaje plik do bazy multimediów i indeksuje go.

val values = ContentValues().apply {
    put(MediaStore.Images.Media.DISPLAY_NAME, "photo_2025.jpg")
    put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg")
    put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/MyApp")
}

val uri = contentResolver?.insert(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values
)

uri?.let {
    val outputStream = contentResolver?.openOutputStream(it)
    outputStream?.use { stream ->
        // zapisz bajty do strumienia
    }
}

Usuwanie plików multimedialnych przez MediaStore

Usunięcie wykonuje się przez ContentResolver.delete z podaniem URI pliku. System sprawdza prawa dostępu: jeśli plik należy do bieżącej aplikacji, usunięcie następuje bez dodatkowych uprawnień. Dla plików innych aplikacji na Android 10+ wymagane jest potwierdzenie użytkownika przez okno systemowe.

MediaStore a bezpośredni dostęp do plików

MediaStore API zasadniczo różni się od bezpośredniego dostępu do plików przez File API. Zamiast ścieżek do plików używane są Content URI, a zamiast operacji plikowych — metody ContentResolver. Daje to trzy kluczowe zalety: bezpieczeństwo, automatyczną indeksację i jednolity interfejs.

Bezpośredni dostęp do plików jest ograniczony na Android 10+ dla katalogów współdzielonych. MediaStore pozostaje jedynym sposobem odczytu multimediów z Pictures, DCIM, Movies, Music i Download. Dla własnych plików aplikacji (app-specific storage) bezpośredni dostęp pozostaje — to foldery w Android/data i Android/media.

Wybór między MediaStore a bezpośrednim dostępem zależy od typu treści. MediaStore jest obowiązkowy dla wspólnych plików multimedialnych dostępnych dla innych aplikacji. Bezpośrednie File API nadaje się do wewnętrznych plików aplikacji i pamięci podręcznej. Storage Access Framework jest używany do wyboru dowolnych dokumentów przez systemowy selektor.