MediaStore API: какво е, възможности и работа с общи медийни файлове

Какво е MediaStore API?

MediaStore API — е системен доставчик на съдържание на платформата Android, предназначен за индексиране, съхранение и предоставяне на достъп до медийни файлове на устройството. API е част от Android SDK и е достъпен от API Level 1.

MediaStore работи чрез единна медийна база данни, която автоматично сканира устройството и събира метаданни на всички медийни файлове. Базата данни се актуализира от системата при добавяне, промяна или изтриване на файлове, така че приложенията винаги получават актуална информация без ръчно сканиране.

Основните таблици на MediaStore: Images (изображения), Video (видео), Audio (аудио) и Files (общи файлове). Всяка таблица съдържа колони с метаданни: име, дата на създаване, размер, MIME тип, GPS координати и други атрибути.

Еволюция на MediaStore във версиите на Android

Преди Android 10 разработчиците използваха READ_EXTERNAL_STORAGE за достъп до всички файлове на устройството. Android 10 (API 29) въведе Scoped Storage: приложенията получиха достъп само до собствените си файлове и чрез MediaStore. Android 11 затегна политиката, напълно блокирайки директния път към споделени директории.

От Android 13 (API 33) Google замени READ_EXTERNAL_STORAGE с гранулирани разрешения: READ_MEDIA_IMAGES, READ_MEDIA_VIDEO и READ_MEDIA_AUDIO. Това позволява на потребителя да даде достъп само до определени типове медия, без да разкрива цялото хранилище.

Как работи MediaStore: архитектура и медийна база данни

MediaStore е изграден върху архитектурата на доставчик на съдържание: всяко приложение има достъп до него чрез ContentResolver и Uri. Системният медиен скенер — MediaScannerConnection — автоматично индексира всички файлове на устройството при зареждане, свързване чрез USB или рестартиране.

Медийната база данни се съхранява в системната база данни и съдържа записи за всеки медиен файл. Колоните се различават за различните типове: изображенията имат ORIENTATION и DATE_TAKEN, видеото — DURATION, аудиото — ARTIST и ALBUM. Разработчиците могат да изпълняват SQL-подобни заявки чрез query с projection и selection за филтриране.

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 и тяхното значение

Всеки медиен файл се идентифицира чрез Content URI от вида content://media/external/images/media/1234. Външният URI (external) сочи към споделеното хранилище, вътрешният (internal) — към системните медийни файлове. Използването на URI вместо пътища на файлове — ключовото предимство на MediaStore: приложението не изисква достъп до файловата система и работи чрез сигурен доставчик на съдържание.

Типове медийни файлове в MediaStore

MediaStore поддържа четири основни типа медия, всеки с отделна таблица и набор от метаданни. Разработчиците избират подходящата таблица в зависимост от типа съдържание, с което работи приложението.

• MediaStore.Images — снимки, екранни снимки и рисунки. Колони: BUCKET_DISPLAY_NAME, IS_PRIVATE, LATITUDE, LONGITUDE.
• MediaStore.Video — видео записи и филми. Колони: DURATION, RESOLUTION, IS_DRM.
• MediaStore.Audio — музикални парчета и звукови файлове. Колони: ARTIST, ALBUM, COMPOSER, TRACK.
• MediaStore.Files — документи и останали файлове. Достъпен от Android 10 за общ достъп.

Освен стандартните колони, всяка таблица съдържа системни полета: _ID, DATA (остарял), SIZE, MIME_TYPE, DATE_ADDED, DATE_MODIFIED. От версия Android 10 полето DATA е маркирано като deprecated и разработчиците трябва да работят чрез отваряне на InputStream по URI.

Разрешения за работа с MediaStore

MediaStore изисква изрични разрешения, които се различават в зависимост от версията на Android. Преди Android 13 се използваше единното разрешение READ_EXTERNAL_STORAGE. От Android 13 (API 33) Google въведе гранулирани разрешения за всеки тип медия.

Записването в MediaStore също изисква WRITE_EXTERNAL_STORAGE за Android 9 и по-ниски. От Android 10 приложението може да записва собствените си файлове в MediaStore без допълнителни разрешения — системата автоматично предоставя достъп при вмъкване на запис чрез ContentResolver.insert.

Искане на разрешения по време на изпълнение

Разрешенията на MediaStore се искат чрез стандартния механизъм ActivityResultContracts.RequestMultiplePermissions. Потребителят може да откаже искането и приложението трябва правилно да обработи този сценарий. Препоръчва се проверка на наличието на разрешение чрез ContextCompat.checkSelfPermission преди всеки достъп до MediaStore.

Примери за код: четене и запис чрез MediaStore

MediaStore позволява не само четене, но и запис на медийни файлове. За запис на изображение или видео разработчикът използва ContentResolver.insert и отваря OutputStream по върнатия URI. Системата автоматично добавя файла в медийната база данни и го индексира.

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 ->
        // запишете байтове в потока
    }
}

Изтриване на медийни файлове чрез MediaStore

Изтриването се извършва чрез ContentResolver.delete с посочване на URI на файла. Системата проверява правата за достъп: ако файлът принадлежи на текущото приложение, изтриването става без допълнителни разрешения. За файлове на други приложения на Android 10+ се изисква потвърждение от потребителя чрез системен диалог.

MediaStore срещу директен достъп до файлове

MediaStore API коренно се различава от директния достъп до файлове чрез File API. Вместо пътища на файлове се използват Content URI, а вместо файлови операции — методи на ContentResolver. Това дава три ключови предимства: сигурност, автоматично индексиране и единен интерфейс.

Директният достъп до файлове е ограничен на Android 10+ за споделени директории. MediaStore остава единственият начин за четене на медия от Pictures, DCIM, Movies, Music и Download. За собствените файлове на приложението (app-specific storage) директният достъп остава — това са папки в Android/data и Android/media.

Изборът между MediaStore и директния достъп зависи от типа съдържание. MediaStore е задължителен за общи медийни файлове, достъпни за други приложения. Директният File API е подходящ за вътрешни файлове на приложението и кеш. Storage Access Framework се използва за избор на произволни документи чрез системния избирател.