MediaStore API: o que é, recursos e trabalho com arquivos de mídia compartilhados

O que é MediaStore API?

MediaStore API é um provedor de conteúdo do sistema na plataforma Android projetado para indexar, armazenar e fornecer acesso aos arquivos de mídia do dispositivo. A API faz parte do Android SDK e está disponível desde o API Level 1.

O MediaStore opera por meio de um banco de dados de mídia unificado que varre automaticamente o dispositivo e coleta metadados de todos os arquivos de mídia. O banco de dados é atualizado pelo sistema quando arquivos são adicionados, modificados ou excluídos, então os aplicativos sempre recebem informações atualizadas sem varredura manual.

As principais tabelas do MediaStore são: Images (imagens), Video (vídeos), Audio (áudio) e Files (arquivos gerais). Cada tabela contém colunas com metadados: nome, data de criação, tamanho, tipo MIME, coordenadas GPS e outros atributos.

Evolução do MediaStore nas versões do Android

Antes do Android 10, os desenvolvedores usavam READ_EXTERNAL_STORAGE para acessar todos os arquivos do dispositivo. Android 10 (API 29) introduziu o Scoped Storage: os aplicativos só podiam acessar seus próprios arquivos e através do MediaStore. O Android 11 endureceu a política, bloqueando completamente o caminho direto para diretórios compartilhados.

A partir do Android 13 (API 33), o Google substituiu o READ_EXTERNAL_STORAGE por permissões granulares: READ_MEDIA_IMAGES, READ_MEDIA_VIDEO e READ_MEDIA_AUDIO. Isso permite que os usuários concedam acesso apenas a tipos específicos de mídia sem expor todo o armazenamento.

Como o MediaStore funciona: arquitetura e banco de dados de mídia

MediaStore é construído sobre uma arquitetura de provedor de conteúdo: cada aplicativo o acessa através de ContentResolver e Uri. O scanner de mídia do sistema — MediaScannerConnection — indexa automaticamente todos os arquivos do dispositivo durante a inicialização, conexão USB ou reinicialização.

O banco de dados de mídia é armazenado no banco de dados do sistema e contém registros para cada arquivo de mídia. As colunas diferem por tipo: imagens têm ORIENTATION e DATE_TAKEN, vídeos têm DURATION, arquivos de áudio têm ARTIST e ALBUM. Desenvolvedores podem executar consultas semelhantes a SQL usando query com projection e selection para filtrar.

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 URIs e seu significado

Cada arquivo de mídia é identificado por um Content URI como content://media/external/images/media/1234. O URI externo aponta para o armazenamento compartilhado, enquanto o interno aponta para arquivos de mídia do sistema. Usar URIs em vez de caminhos de arquivo é uma vantagem chave do MediaStore: o aplicativo não precisa de acesso ao sistema de arquivos e funciona através de um provedor de conteúdo seguro.

Tipos de arquivos de mídia no MediaStore

MediaStore suporta quatro tipos principais de mídia, cada um com sua própria tabela e conjunto de metadados. Os desenvolvedores selecionam a tabela apropriada com base no tipo de conteúdo com que o aplicativo trabalha.

• MediaStore.Images — fotos, capturas de tela e imagens. Colunas: BUCKET_DISPLAY_NAME, IS_PRIVATE, LATITUDE, LONGITUDE.
• MediaStore.Video — gravações de vídeo e filmes. Colunas: DURATION, RESOLUTION, IS_DRM.
• MediaStore.Audio — faixas de música e arquivos de som. Colunas: ARTIST, ALBUM, COMPOSER, TRACK.
• MediaStore.Files — documentos e outros arquivos. Disponível desde o Android 10 para acesso compartilhado.

Além das colunas padrão, cada tabela contém campos do sistema: _ID, DATA (obsoleto), SIZE, MIME_TYPE, DATE_ADDED, DATE_MODIFIED. Desde o Android 10, o campo DATA está marcado como obsoleto, e os desenvolvedores devem trabalhar abrindo um InputStream via URI.

Permissões para trabalhar com MediaStore

MediaStore requer permissões explícitas, que diferem dependendo da versão do Android. Antes do Android 13, a permissão única READ_EXTERNAL_STORAGE era usada. A partir do Android 13 (API 33), o Google introduziu permissões granulares para cada tipo de mídia.

Escrever no MediaStore também requer WRITE_EXTERNAL_STORAGE para Android 9 e inferiores. A partir do Android 10, um aplicativo pode escrever seus próprios arquivos no MediaStore sem permissões adicionais — o sistema concede acesso automaticamente ao inserir um registro via ContentResolver.insert.

Solicitando permissões em tempo de execução

As permissões do MediaStore são solicitadas através do mecanismo padrão ActivityResultContracts.RequestMultiplePermissions. O usuário pode negar a solicitação, e o aplicativo deve lidar corretamente com esse cenário. Recomenda-se verificar a permissão via ContextCompat.checkSelfPermission antes de cada acesso ao MediaStore.

Exemplos de código: leitura e escrita via MediaStore

MediaStore permite não apenas ler, mas também escrever arquivos de mídia. Para escrever uma imagem ou vídeo, o desenvolvedor usa ContentResolver.insert e abre um OutputStream para o URI retornado. O sistema adiciona automaticamente o arquivo ao banco de dados de mídia e o indexa.

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 ->
        // escrever bytes no fluxo
    }
}

Excluindo arquivos de mídia via MediaStore

A exclusão é realizada usando ContentResolver.delete com o URI do arquivo. O sistema verifica os direitos de acesso: se o arquivo pertence ao aplicativo atual, a exclusão ocorre sem permissões adicionais. Para arquivos de outros aplicativos no Android 10+, é necessária a confirmação do usuário através de um diálogo do sistema.

MediaStore vs acesso direto a arquivos

MediaStore API difere fundamentalmente do acesso direto a arquivos via File API. Em vez de caminhos de arquivo, são usados Content URIs, e em vez de operações de arquivo, são usados métodos ContentResolver. Isso proporciona três vantagens principais: segurança, indexação automática e interface unificada.

O acesso direto a arquivos é restrito no Android 10+ para diretórios compartilhados. O MediaStore continua sendo a única forma de ler mídia de Pictures, DCIM, Movies, Music e Download. Para arquivos específicos do aplicativo (app-specific storage), o acesso direto é preservado — são as pastas em Android/data e Android/media.

A escolha entre MediaStore e acesso direto depende do tipo de conteúdo. MediaStore é obrigatório para arquivos de mídia compartilhados acessíveis por outros aplicativos. A File API direta é adequada para arquivos internos do aplicativo e cache. O Storage Access Framework é usado para selecionar documentos arbitrários através do seletor do sistema.