Aplicativo de demonstração do ExoPlayer

O principal app de demonstração do ExoPlayer tem duas finalidades:

  1. 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.
  2. 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):

O projeto no Android Studio
Figura 1. O projeto no Android Studio.

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.

SampleChooserActivity e PlayerActivity no app de demonstração do ExoPlayer
Figura 2. SampleChooserActivity e PlayerActivity.

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:

  1. Crie cada uma das extensões que você quer incluir. Esse é um processo manual. Consulte o arquivo README.md em cada extensão para ver as instruções.
  2. Na visualização "Build Variants" do Android Studio, defina a variante de build do módulo de demonstração como withDecoderExtensionsDebug ou withDecoderExtensionsRelease, conforme mostrado na imagem abaixo.

    Como selecionar a variante de build de demonstração "withDecoderExtensionsDebug"

  3. Compile, instale e execute a configuração demo normalmente.

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+xml para 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ão widevine, playready e clearkey. 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 de drm_license_uri precisa 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_0 indica o tipo da primeira amostra. drm_scheme_1 definiria 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