Aplicativo de demonstração do ExoPlayer

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

  1. Para fornecer um exemplo relativamente simples, mas cheio de recursos, do uso do ExoPlayer. O app de demonstração pode ser usado como um ponto de partida prático 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 conteúdo, além das amostras incluídas.

Esta página descreve como instalar, compilar e executar o app de demonstração. Ela também descreve como usá-lo para reproduzir sua própria mídia.

Receber 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. Clone o projeto em um diretório local:

git clone https://github.com/androidx/media.git

Em seguida, abra o projeto no Android Studio. O seguinte vai aparecer Visualização "Projeto Android" (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 em 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 quiser usar um emulador, Leia a seção de emuladores em Dispositivos compatíveis e verifique se que seu Dispositivo virtual usa uma imagem do sistema com um nível de API de pelo menos 23.

SampleChooserActivity e PlayerActivity

O app de demonstração apresenta uma lista de exemplos (SampleChooserActivity). Selecionando um sample abrirá uma segunda atividade (PlayerActivity) para reprodução. A demonstração contém controles de mídia e a funcionalidade de seleção de faixas. Ele também usa A classe de utilitário EventLogger do ExoPlayer gera informações de depuração úteis para no 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 software empacotado. decodificadores, 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. Observe que este é 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 para a demonstração módulo para withDecoderExtensionsDebug ou withDecoderExtensionsRelease como como mostrado na imagem a seguir.

    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 será usado somente se um decodificador de plataforma adequado não existe. É possível especificar que os decodificadores de extensão de sua preferência, 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. Como editar recursos/media.exolist.json

Os exemplos listados no app de demonstração são carregados de assets/media.exolist.json. Ao editar este arquivo JSON, é possível adicionar e remover amostras da demonstração app. 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. 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",
        "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. 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",
            "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 uma string para cada cabeçalho:

"drm_key_request_properties": {
  "name1": "value1",
  "name2": "value2",
  ...etc
}

Na atividade do seletor de amostra, o menu flutuante contém opções para especificando se prefere 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 o armazenamento necessário para ler esses arquivos. No entanto, a partir do Android 13, não é mais carregar arquivos arbitrários que não terminam em um arquivo de mídia típico (como .mp4). Se precisar carregar esse arquivo, coloque-o em ao diretório de armazenamento específico do app de demonstração que não tem restrições de acesso. Isso normalmente fica neste endereço: /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 acima e nomeados de acordo com a convenção *.exolist.json. Por exemplo, se você hospedar arquivo em https://yourdomain.com/samples.exolist.json, é possível abri-lo app de demonstração usando:

adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com/samples.exolist.json

Clicando em um link *.exolist.json (por exemplo, no navegador ou em um e-mail cliente) em um dispositivo com o app de demonstração instalado, também vai abri-lo na demonstração app. Portanto, hospedar um arquivo JSON *.exolist.json fornece uma maneira simples de distribuindo conteúdo para outras pessoas testarem no app de demonstração.

3. Como disparar uma intent

Intents podem ser usadas para ignorar a lista de amostras e iniciar diretamente a reprodução. Para reproduzir uma única amostra, defina a ação da intent como androidx.media3.demo.main.action.VIEW e o URI de dados dele para o amostra para tocar. Essa intent pode ser acionada a partir 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 com uma única intent de amostra 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 [longo] Um ponto de partida para a amostra recortados, em milissegundos.
    • clip_end_position_ms [longo] Um ponto final de onde a amostra deve ser recortados, em milissegundos.
    • drm_scheme [String] Esquema de DRM se protegido. Os valores válidos são widevine, playready e clearkey. Os UUIDs do esquema DRM também são aceitos.
    • drm_license_uri [String] URI do servidor de licença se protegido.
    • drm_force_default_license_uri [Booleano] Define se 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 empacotados como nome1, valor1, nome2, valor2 etc. se protegido.
    • drm_session_for_clear_content [Booleano] Indica se uma sessão de DRM será anexada para limpar faixas de vídeo e áudio.
    • drm_multi_session [Booleano] Ativa a rotação de chaves quando protegido.
    • 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 está 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 o [extensão do IMA][].
    • prefer_extension_decoders [Booleano] Define se os decodificadores de extensão são preferenciais às da plataforma.

Ao usar adb shell am start para disparar uma intent, uma string opcional extra pode ser definido com --es (por exemplo, --es extension mpd). Um booleano opcional extra pode ser definido com --ez (por exemplo, --ez prefer_extension_decoders TRUE). Um parâmetro opcional O extra longo pode ser definido com --el (por exemplo, --el clip_start_position_ms 5000). Um O extra da matriz de strings opcional pode ser definido com --esa (por exemplo, --esa drm_key_request_properties name1,value1).

Para reproduzir uma playlist de amostras, defina a ação da intent como androidx.media3.demo.main.action.VIEW_LIST: O exemplo de configuração os extras permanecem os mesmos de androidx.media3.demo.main.action.VIEW, exceto por duas diferenças:

  • Os extras chaves devem ter um sublinhado e o índice baseado em zero da amostra como sufixo. Por exemplo, extension_0 sugere o tipo de amostra para o primeiro 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 amostras, não mudam. Por exemplo, Execute o seguinte comando 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