O principal app de demonstração do ExoPlayer tem duas finalidades:
- Fornecer um exemplo completo do uso do ExoPlayer. O app de demonstração pode ser usado como um ponto de partida conveniente para desenvolver seu próprio app.
- Para que você teste o ExoPlayer. O app de demonstração pode ser usado para testar a reprodução do seu próprio conteúdo, além dos exemplos incluídos.
Esta página descreve como acessar, compilar e executar o app de demonstração. Ela também descreve como usá-lo para reproduzir sua própria mídia.
Como conseguir o código
O código-fonte do app de demonstração principal pode ser encontrado na pasta demos/main do
nosso projeto do GitHub. Se ainda não tiver feito isso, clone o projeto em um
diretório local:
git clone https://github.com/androidx/media.git
Em seguida, abra o projeto no Android Studio. Você verá o seguinte na visualização do projeto do Android (as pastas relevantes do app de demonstração foram expandidas):
Como compilar e executar
Para compilar e executar o app de demonstração, selecione e execute a configuração demo no Android Studio. O app de demonstração será instalado e executado em um dispositivo Android
conectado. Recomendamos usar um dispositivo físico, se possível. Se você quiser usar um
emulador, leia a seção de emuladores em Dispositivos compatíveis e verifique
se o dispositivo virtual usa uma imagem do sistema com um nível da API de pelo menos 23.
O app de demonstração apresenta uma lista de amostras (SampleChooserActivity). Ao selecionar
uma amostra, uma segunda atividade (PlayerActivity) é aberta para reprodução. A demonstração
inclui controles de mídia e funcionalidade de seleção de faixa. Ele também usa
a classe utilitária EventLogger do ExoPlayer para gerar informações de depuração úteis para
o registro do sistema. Esse registro pode ser visualizado (junto com o registro de nível de erro para
outras tags) com o comando:
adb logcat EventLogger:V *:E
Como ativar decodificadores em pacote
O ExoPlayer tem várias extensões que permitem o uso de decodificadores de software integrados, incluindo AV1, VP9, Opus, FLAC e FFmpeg (somente áudio). O app de demonstração pode ser criado para incluir e usar essas extensões da seguinte maneira:
- Crie cada uma das extensões que você quer incluir. Esse é um processo manual. Consulte o arquivo
README.mdem cada extensão para ver as instruções. Na visualização "Build Variants" do Android Studio, defina a variante de build do módulo de demonstração como
withDecoderExtensionsDebugouwithDecoderExtensionsRelease, conforme mostrado na imagem abaixo.
Compile, instale e execute a configuração
demonormalmente.
Por padrão, um decodificador de extensão só será usado se não houver um decodificador de plataforma adequado. É possível especificar que os decodificadores de extensão sejam preferenciais, conforme descrito nas seções a seguir.
Como reproduzir seu próprio conteúdo
Há várias maneiras de reproduzir seu próprio conteúdo no app de demonstração.
1. Editando assets/media.exolist.json
As amostras listadas no app de demonstração são carregadas de assets/media.exolist.json.
Ao editar esse arquivo JSON, é possível adicionar e remover amostras do app de
demonstração. O esquema é o seguinte, em que [O] indica um atributo opcional.
[
{
"name": "Name of heading",
"samples": [
{
"name": "Name of sample",
"uri": "The URI of the sample",
"extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8",
"clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds",
"clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds",
"drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
"drm_license_uri": "[O] URI of the license server if protected",
"drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
"drm_key_request_properties": "[O] Key request headers if protected",
"drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
"drm_multi_session": "[O] Enables key rotation if protected",
"drm_force_software_crypto": "[O] Whether to force DRM to use the software crypto library regardless of the device's hardware crypto capability if supported by the DRM scheme",
"mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
"subtitle_uri": "[O] The URI of a subtitle sidecar file",
"subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
"subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)",
"ad_tag_uri": "[O] The URI of an ad tag to load via the IMA extension"
},
...etc
]
},
...etc
]
As playlists de amostras podem ser especificadas usando o esquema:
[
{
"name": "Name of heading",
"samples": [
{
"name": "Name of playlist sample",
"playlist": [
{
"uri": "The URI of the first sample in the playlist",
"extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8",
"clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds",
"clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds",
"drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
"drm_license_uri": "[O] URI of the license server if protected",
"drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
"drm_key_request_properties": "[O] Key request headers if protected",
"drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
"drm_multi_session": "[O] Enables key rotation if protected",
"drm_force_software_crypto": "[O] Whether to force DRM to use the software crypto library regardless of the device's hardware crypto capability if supported by the DRM scheme",
"mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
"subtitle_uri": "[O] The URI of a subtitle sidecar file",
"subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
"subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)"
},
{
"uri": "The URI of the second sample in the playlist",
...etc
},
...etc
]
},
...etc
]
},
...etc
]
Se necessário, os cabeçalhos da solicitação de chave são especificados como um objeto que contém um atributo de string para cada cabeçalho:
"drm_key_request_properties": {
"name1": "value1",
"name2": "value2",
...etc
}
Na atividade de seletor de amostras, o menu flutuante contém opções para especificar se os decodificadores de extensão são preferenciais.
URIs de arquivos locais e restrições de armazenamento com escopo
Ao especificar URIs de arquivos locais, o app de demonstração solicita as permissões de acesso
ao armazenamento necessárias para ler esses arquivos. No entanto, a partir do Android 13, não é
possível carregar arquivos arbitrários que não terminam em uma extensão de arquivo de mídia
típica (como .mp4). Se você precisar carregar um arquivo desse tipo, coloque-o no
diretório de armazenamento específico do app de demonstração, que não tem restrições de acesso. Esse
arquivo geralmente está localizado em /sdcard/Android/data/androidx.media3.demo.main/files.
2. Como carregar um arquivo exolist.json externo
O app de demonstração pode carregar arquivos JSON externos usando o esquema anterior e nomeados
de acordo com a convenção *.exolist.json. Por exemplo, se você hospedar um arquivo
como esse em https://yourdomain.com/samples.exolist.json, poderá abri-lo no
app de demonstração usando:
adb shell am start -a android.intent.action.VIEW \
-d https://yourdomain.com/samples.exolist.json
Clicar em um link *.exolist.json (por exemplo, no navegador ou em um cliente de e-mail) em um dispositivo com o app de demonstração instalado também o abrirá no app de demonstração. Hospedar um arquivo JSON *.exolist.json é uma maneira de distribuir conteúdo para que outras pessoas testem no app de demonstração.
3. Como acionar uma intent
As intents podem ser usadas para ignorar a lista de amostras e iniciar diretamente a
reprodução. Para tocar uma única amostra, defina a ação da intent como
androidx.media3.demo.main.action.VIEW e o URI de dados como o da
amostra a ser tocada. Essa intent pode ser acionada no terminal usando:
adb shell am start -a androidx.media3.demo.main.action.VIEW \
-d https://yourdomain.com/sample.mp4
Os extras opcionais compatíveis com uma única intent de amostra são:
- Extras de configuração de amostra:
mime_type[String] Exemplo de dica de tipo MIME. Por exemplo,application/dash+xmlpara conteúdo DASH.clip_start_position_ms[Long] Um ponto de início em que a amostra precisa ser cortada, em milissegundos.clip_end_position_ms[Long] Um endpoint de onde a amostra precisa ser cortada, em milissegundos.drm_scheme[String] Esquema de DRM, se protegido. Os valores válidos sãowidevine,playreadyeclearkey. UUIDs de esquema de DRM também são aceitos.drm_license_uri[String] URI do servidor de licença, se protegido.drm_force_default_license_uri[booleano]: se o uso dedrm_license_uriprecisa ser forçado para solicitações de chave que incluem o próprio URI de licença.drm_key_request_properties[matriz de strings] Cabeçalhos da solicitação de chave empacotados como nome1, valor1, nome2, valor2 etc., se protegidos.drm_session_for_clear_content[booleano] Se uma sessão de DRM deve ser anexada para limpar faixas de vídeo e áudio.drm_multi_session[booleano] Ativa a rotação de chaves se estiver protegida.drm_force_software_crypto[Booleano] Indica se o DRM deve ser forçado a usar a biblioteca de criptografia de software, independentemente da capacidade de criptografia de hardware do dispositivo, se houver suporte do esquema de DRM.subtitle_uri[String] O URI de um arquivo de legenda secundário.subtitle_mime_type[String] O tipo MIME de subtitle_uri (obrigatório se subtitle_uri estiver definido).subtitle_language[String] O código de idioma BCP47 do arquivo de legenda (ignorado se subtitle_uri não estiver definido).ad_tag_uri[String] O URI de uma tag de anúncio a ser carregada usando a extensão do IMA.prefer_extension_decoders[booleano] Se os decodificadores de extensão são preferíveis aos da plataforma.
Ao usar adb shell am start para disparar uma intent, uma string extra opcional pode
ser definida com --es (por exemplo, --es extension mpd). Um booleano extra opcional pode
ser definido com --ez (por exemplo, --ez prefer_extension_decoders TRUE). Um
long extra opcional pode ser definido com --el (por exemplo, --el clip_start_position_ms 5000). Uma
matriz de strings extra opcional pode ser definida com --esa (por exemplo,
--esa drm_key_request_properties name1,value1).
Para tocar uma playlist de amostras, defina a ação da intent como
androidx.media3.demo.main.action.VIEW_LIST. Os extras de configuração de amostra
permanecem os mesmos de androidx.media3.demo.main.action.VIEW,
exceto por duas diferenças:
- As chaves dos extras precisam ter um sublinhado e o índice baseado em 0 da amostra
como sufixo. Por exemplo,
extension_0indica o tipo da primeira amostra.drm_scheme_1definiria o esquema de DRM para o segundo exemplo. - O URI da amostra é transmitido como um extra com a chave
uri_<sample-index>.
Outros extras, que não dependem da amostra, não mudam. Por exemplo, execute o comando a seguir no terminal para reproduzir uma playlist com dois itens, substituindo a extensão do segundo item:
adb shell am start -a androidx.media3.demo.main.action.VIEW_LIST \
--es uri_0 https://a.com/sample1.mp4 \
--es uri_1 https://b.com/sample2.fake_mpd \
--es extension_1 mpd