Aplicativo de demonstração do ExoPlayer

O principal app de demonstração do ExoPlayer tem dois propósitos principais:

  1. Para fornecer um exemplo relativamente simples, mas 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 facilitar o teste do ExoPlayer. O app de demonstração pode ser usado para testar a reprodução do seu próprio conteúdo, além das amostras incluídas.

Nesta página, descrevemos como receber, compilar e executar o app de demonstração. Também explicamos 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 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. Na visualização do projeto Android, você vai encontrar o seguinte (as pastas relevantes do app de demonstração foram expandidas):

O projeto no Android Studio

Compilação e execução

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 sobre emuladores em Dispositivos compatíveis e confira se o dispositivo virtual usa uma imagem do sistema com um nível da API de pelo menos 23.

SampleChooserActivity e PlayerActivity

O app de demonstração apresenta uma lista de exemplos (SampleChooserActivity). Ao selecionar um exemplo, uma segunda atividade (PlayerActivity) será aberta para reprodução. A demonstração tem controles de reprodução e funcionalidade de seleção de faixas. Ele também usa a classe utilitária EventLogger do ExoPlayer para gerar informações de depuração úteis no registro do sistema. É possível conferir esse registro (junto com o registro de nível de erro para outras tags) com o comando:

adb logcat EventLogger:V *:E

Como ativar decodificadores agrupados

O ExoPlayer tem várias extensões que permitem o uso de decodificadores de software agrupados, 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 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 a seguir.

    Selecionar a variante de build de demonstração `withDecoderExtensionsDebug`

  3. Compile, instale e execute a configuração do 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 preferidos, conforme descrito nas seções a seguir.

Reproduzir seu próprio conteúdo

Há várias maneiras de reproduzir seu próprio conteúdo no app de demonstração.

1. Editar 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",
        "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",
            "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 principais cabeçalhos de solicitação serã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 escolha de amostra, o menu flutuante contém opções para especificar se é preferível usar decodificadores de extensão.

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 com 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. Normalmente, ele fica em /sdcard/Android/data/androidx.media3.demo.main/files.

2. Carregar um arquivo exolist.json externo

O app de demonstração pode carregar arquivos JSON externos usando o esquema acima e nomeados de acordo com a convenção *.exolist.json. Por exemplo, se você hospedar um arquivo 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 abre no app. Portanto, hospedar um arquivo JSON *.exolist.json é uma maneira simples de distribuir conteúdo para que outras pessoas testem no app de demonstração.

3. Acionar uma intent

As intents podem ser usadas para ignorar a lista de exemplos e iniciar a reprodução diretamente. 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 disparada do terminal usando:

adb shell am start -a androidx.media3.demo.main.action.VIEW \
    -d https://yourdomain.com/sample.mp4

Os extras opcionais compatíveis para uma única intent de exemplo são:

  • Exemplos de extras de configuração:
    • 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 para o qual a amostra deve ser cortada, em milissegundos.
    • clip_end_position_ms [Long] Um ponto de extremidade de onde a amostra deve 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] Indica se é necessário forçar o uso de drm_license_uri para solicitações de chave que incluem o próprio URI de licença.
    • drm_key_request_properties [Matriz de strings] Cabeçalhos de solicitação de chave compactados como name1, value1, name2, value2 etc. se protegidos.
    • drm_session_for_clear_content [booleano]: indica se uma sessão de DRM será anexada a faixas de áudio e vídeo sem criptografia.
    • drm_multi_session [booleano] Ativa a rotação de chaves se estiver protegida.
    • subtitle_uri [String] O URI de um arquivo secundário de legenda.
    • 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 da IMA][].
    • prefer_extension_decoders [booleano] Indica se os decodificadores de extensão são preferidos aos da plataforma.

Ao usar adb shell am start para acionar uma intent, um extra de string opcional pode ser definido com --es (por exemplo, --es extension mpd). Um extra booleano opcional pode ser definido com --ez (por exemplo, --ez prefer_extension_decoders TRUE). Um extra long opcional pode ser definido com --el (por exemplo, --el clip_start_position_ms 5000). Um extra de matriz de strings opcional pode ser definido 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 de base zero da amostra como sufixo. Por exemplo, extension_0 sugeriria o tipo da primeira amostra. drm_scheme_1 definiria o esquema de DRM para a segunda amostra.
  • O URI da amostra é transmitido como um extra com a chave uri_<sample-index>.

Outros extras, que não dependem de amostra, não mudam. Por exemplo, você pode executar o seguinte comando no terminal para tocar 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