Imagem em imagem

No Android N, os usuários do Android TV agora podem assistir a um vídeo em uma janela fixada em um canto da tela enquanto navegam em aplicativos. O modo de imagem em imagem (PIP) permite que os aplicativos executem uma atividade de vídeo na janela fixada enquanto outra atividade continua em segundo plano. A janela do PIP permite que os usuários realizem várias tarefas enquanto usam seu aplicativo, o que os ajuda a ser mais produtivos.

Seu aplicativo pode decidir quando acionar o modo de PIP. Veja alguns exemplos de quando entrar no modo de PIP:

  • Seu aplicativo pode passar um vídeo para o modo de PIP quando o usuário sai do vídeo para procurar outro conteúdo.
  • Seu aplicativo pode passar um vídeo para o modo de PIP quando um usuário assiste ao final de um episódio de conteúdo. A janela principal exibe informações promocionais ou de resumo sobre o próximo episódio da série.
  • Seu aplicativo pode fornecer uma maneira de os usuários colocarem conteúdo adicional em uma fila enquanto assistem a um vídeo. O vídeo continua a ser reproduzido no modo de PIP enquanto a tela principal exibe uma atividade de seleção de conteúdo.

A janela do modo de PIP tem 240x135 dp e é mostrada na camada superior de um dos quatro cantos da tela, escolhido pelo sistema. O usuário pode exibir um menu de PIP que permite que coloque a janela do PIP em tela inteira ou feche-a ao pressionar o botão Home do controle remoto. Se outro vídeo começar a ser reproduzido na tela principal, a janela do PIP será fechada automaticamente. Os usuários também podem fechar a janela do PIP em Recents.

Figura 1. Um vídeo no modo de imagem em imagem visível no canto da tela enquanto o usuário navega por conteúdo na janela principal.

O PIP utiliza as APIs de várias janelas disponíveis no Android N para fornecer a janela sobreposta de vídeo fixo. Para adicionar o modo de PIP ao seu aplicativo, você deve registrar as atividades que oferecem suporte a PIP, alternar a atividade para o modo de PIP conforme a necessidade e garantir que os elementos de IU sejam ocultados e que a reprodução do vídeo continue quando a atividade estiver no modo de PIP.

Declarar que sua atividade oferece suporte ao modo de imagem em imagem

Por padrão, o sistema não oferece suporte ao modo de PIP automaticamente para seus aplicativos. Se quiser esse suporte para seu aplicativo, registre a atividade de vídeo no manifesto definindo android:supportsPictureInPicture e android:resizeableActivity como true. Além disso, especifique que a atividade processa alterações na configuração de layout de forma que a atividade não seja reiniciada quando ocorrem essas alterações durante as transições do modo de PIP.

<activity android:name="VideoActivity"
    android:resizeableActivity="true"
    android:supportsPictureInPicture="true"
    android:configChanges=
        "screenSize|smallestScreenSize|screenLayout|orientation"
    ...

Ao registrar a atividade, lembre-se de que, no modo de PIP, ela é mostrada em uma pequena janela sobreposta em uma tela de TV. Atividades de reprodução de vídeo com uma quantidade mínima de itens de IU oferecem a melhor experiência do usuário. Atividades que contêm pequenos elementos de IU podem não oferecer uma boa experiência do usuário no modo de PIP, pois ele não conseguirá enxergar os detalhes desses elementos na janela do PIP.

Alternar a atividade para o modo de imagem em imagem

Quando precisar colocar a atividade no modo de PIP, chame Activity.enterPictureInPictureMode(). O exemplo a seguir entra no modo de PIP quando o usuário seleciona um botão dedicado ao PIP na barra de controle de uma mídia:

@Override
public void onActionClicked(Action action) {
    if (action.getId() == R.id.lb_control_picture_in_picture) {
        getActivity().enterPictureInPictureMode();
        return;
    }
    ...

Adicionar um botão de PIP à barra de controle de mídia permite que o usuário entre no modo de PIP com facilidade ao controlar a reprodução de um vídeo.

Figura 1. Um botão do modo de imagem em imagem em uma barra de controle de mídia.

O Android N inclui uma nova classe PlaybackControlsRow.PictureInPictureAction que define ações do PIP para a barra de controle e usa o ícone do PIP.

Lidar com a IU durante o modo de imagem em imagem

Quando a atividade entra no modo de PIP, ela deve mostrar apenas a reprodução do vídeo. Remova elementos de IU antes que a atividade entre no modo de PIP e restaure esses elementos quando a atividade voltar ao modo de tela inteira. Substitua Activity.onPictureInPictureModeChanged() ou Fragment.onPictureInPictureModeChanged() e ative ou desative os elementos de interface conforme for necessário. Por exemplo:

@Override
public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) {
    if (isInPictureInPictureMode) {
        // Hide the controls in picture-in-picture mode.
        ...
    } else {
        // Restore the playback UI based on the playback status.
        ...
    }
}

Continuar reprodução de vídeo no modo de imagem em imagem

Quando a atividade entra no modo de PIP, o sistema a considera pausada e chama o método onPause() da atividade. A reprodução de vídeos não deverá ser pausada se a atividade for pausada devido ao modo de PIP. Verifique o PIP no método onPause() da atividade e realize a reprodução da forma apropriada. Por exemplo:

@Override
public void onPause() {
    // If called while in PIP mode, do not pause playback
    if (isInPictureInPictureMode()) {
        // Continue playback
        ...
    }
    // If paused but not in PIP, pause playback if necessary
    ...
}

Quando a atividade sai do modo de PIP e volta à tela inteira, o sistema retoma a atividade e chama o método onResume().

Usar uma única atividade de reprodução para imagem em imagem

Ao navegar pelo conteúdo da tela principal de seu aplicativo, um usuário pode selecionar um novo vídeo enquanto uma atividade de reprodução de vídeo estiver em modo de PIP. Reproduza o novo vídeo na atividade de reprodução existente em modo de tela cheia em vez de lançar uma nova atividade que pode confundir o usuário.

Para que uma única atividade seja usada para solicitações de reprodução de vídeo e com o modo de PIP ativado ou desativado, conforme necessário, configure o android:launchMode da atividade para singleTask em seu manifesto.

<activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...

Na atividade, modifique Activity.onNewIntent() e processe o novo vídeo, interrompendo qualquer reprodução existente, caso necessário.

Práticas recomendadas

O PIP é destinado a atividades que reproduzem vídeos em tela inteira. Ao passar a atividade para o modo de PIP, evite mostrar qualquer coisa que não seja o conteúdo do vídeo. Rastreie quando a atividade entrar no modo de PIP e oculte os elementos de IU, conforme descrito em Lidar com a interface durante o modo de imagem em imagem.

Como a janela do PIP é mostrada como uma janela flutuante no canto da tela, você deve evitar exibir informações essenciais em qualquer área da janela principal que possa ser ocultada pela janela do PIP.

Quando uma atividade está no modo de PIP, ela não recebe foco de entrada por padrão. Para receber eventos de entrada no modo de PIP, use MediaSession.setMediaButtonReceiver().