Integrar aos Controles de transporte de mídia do sistema

  • Artigo

Este artigo mostra como interagir com os controles de transporte de mídia do sistema (SMTC). O SMTC é um conjunto de controles que são comuns em todos os dispositivos Windows 10 e que oferecem aos usuários uma maneira consistente de controlar a reprodução de mídia para todos os aplicativos em execução que usam o MediaPlayer para reprodução.

Os Controles de Transporte de Mídia do Sistema permitem que os desenvolvedores de aplicativos de mídia se integrem à interface do usuário interna do sistema para exibir metadados de mídia, como artista, título do álbum ou título do capítulo. O controle de transporte do sistema também permite que um usuário controle a reprodução de um aplicativo de mídia usando a interface do usuário interna do sistema, como pausar a reprodução e pular para frente e para trás em uma playlist.

Controles de Transtransporte de Mídia do Sistema

Para ver um exemplo completo que demonstra a integração com o SMTC, consulte o exemplo de controles de transporte de mídia do sistema no github.

Integração automática com o SMTC

A partir do Windows 10, versão 1607, os aplicativos UWP que usam a classe MediaPlayer para reproduzir mídia são integrados automaticamente com o SMTC por padrão. Basta criar uma nova instância de MediaPlayer e atribuir MediaSource, MediaPlaybackItem ou MediaPlaybackList à propriedade Source para o usuário ver o nome de seu aplicativo no SMTC e poder reproduzir, pausar e percorrer suas playlists usando os controles SMTC.

Seu aplicativo pode criar e usar vários objetos MediaPlayer ao mesmo tempo. Para cada instância MediaPlayer ativa em seu aplicativo, uma guia separada é criada no SMTC, permitindo que o usuário alterne entre os players de mídia ativos e os outros aplicativos em execução. O player de mídia que estiver selecionado no momento no SMTC será o afetado pelos controles.

Para obter mais informações sobre como usar MediaPlayer em seu aplicativo, inclusive como associá-lo a um MediaPlayerElement na página XAML, consulte Reproduzir áudio e vídeo com o MediaPlayer.

Para obter mais informações sobre como trabalhar com MediaSource, MediaPlaybackItem e MediaPlaybackList, consulte Itens de mídia, playlists e faixas.

Adicionar metadados a serem exibidos pelo SMTC

Se quiser adicionar ou modificar os metadados que são exibidos para seus itens de mídia no SMTC, como um título de vídeo ou música, você precisará atualizar as propriedades de exibição do MediaPlaybackItem que representa o item de mídia. Primeiro, obtenha uma referência para o objeto MediaItemDisplayProperties chamando GetDisplayProperties. Em seguida, defina o tipo de mídia, música ou vídeo, para o item com a propriedade Type. Depois, você pode preencher os campos de MusicProperties ou VideoProperties, dependendo do tipo de mídia especificado. Por fim, atualize os metadados para o item de mídia chamando ApplyDisplayProperties.

MediaItemDisplayProperties props = mediaPlaybackItem.GetDisplayProperties();
props.Type = Windows.Media.MediaPlaybackType.Video;
props.VideoProperties.Title = "Video title";
props.VideoProperties.Subtitle = "Video subtitle";
props.VideoProperties.Genres.Add("Documentary");
mediaPlaybackItem.ApplyDisplayProperties(props);

props = mediaPlaybackItem.GetDisplayProperties();
props.Type = Windows.Media.MediaPlaybackType.Music;
props.MusicProperties.Title = "Song title";
props.MusicProperties.Artist = "Song artist";
props.MusicProperties.Genres.Add("Polka");
mediaPlaybackItem.ApplyDisplayProperties(props);

Observação

Os aplicativos devem definir um valor para a propriedade Type mesmo que não estejam fornecendo outros metadados de mídia a serem exibidos pelos Controles de Transporte de Mídia do Sistema. Esse valor ajuda o sistema a lidar com o conteúdo da mídia corretamente, incluindo impedir que o protetor de tela seja ativado durante a reprodução.

Usar CommandManager para modificar ou substituir os comandos SMTC padrão

Seu aplicativo pode modificar ou substituir completamente o comportamento dos controles SMTC com a classe MediaPlaybackCommandManager. Uma instância do gerenciador de comando pode ser obtida para cada instância da classe MediaPlayer acessando a propriedade CommandManager.

Para cada comando, como o comando Next que, por padrão, passa para o próximo item de uma MediaPlaybackList, o gerenciador de comando expõe um evento recebido, como NextReceived, e um objeto que gerencia o comportamento do comando, como NextBehavior.

O exemplo a seguir registra um manipulador para o evento NextReceived e para o evento IsEnabledChanged do NextBehavior.

_mediaPlayer.CommandManager.NextReceived += CommandManager_NextReceived;
_mediaPlayer.CommandManager.NextBehavior.IsEnabledChanged += NextBehavior_IsEnabledChanged;

O exemplo a seguir ilustra um cenário em que o aplicativo deseja desabilitar o comando Next depois que o usuário clicar em cinco itens da playlist, talvez exigindo alguma interação do usuário antes de continuar a reproduzir o conteúdo. Cada vez que o evento NextReceived é gerado, um contador é incrementado. Depois que o contador atingir o número de destino, EnablingRule para o comando Next será definido como Never, o que desabilita o comando.

int _nextPressCount = 0;
private void CommandManager_NextReceived(MediaPlaybackCommandManager sender, MediaPlaybackCommandManagerNextReceivedEventArgs args)
{
    _nextPressCount++;
    if (_nextPressCount > 5)
    {
        sender.NextBehavior.EnablingRule = MediaCommandEnablingRule.Never;
        // Perform app tasks while the Next button is disabled
    }
}

Você também pode definir o comando como Always, que significa que o comando sempre será habilitado mesmo que, para o exemplo de comando Next, não haja nenhuma mais itens na playlist. Ou você pode definir o comando como Auto, onde o sistema determina se o comando deve ser habilitado com base no conteúdo atual em reprodução.

Para o cenário descrito acima, em algum momento o aplicativo vai querer reabilitar o comando Next e fará isso definindo EnablingRule como Auto.

_mediaPlayer.CommandManager.NextBehavior.EnablingRule = MediaCommandEnablingRule.Auto;
_nextPressCount = 0;

Como seu aplicativo pode ter a própria interface do usuário para controlar a reprodução enquanto estiver em primeiro plano, você pode usar os eventos IsEnabledChanged para atualizar sua própria interface do usuário para corresponder ao SMTC à medida que os comandos são habilitados ou desabilitados acessando o IsEnabled do MediaPlaybackCommandManagerCommandBehavior passado para o manipulador.

private void NextBehavior_IsEnabledChanged(MediaPlaybackCommandManagerCommandBehavior sender, object args)
{
    MyNextButton.IsEnabled = sender.IsEnabled;
}

Em alguns casos, convém substituir completamente o comportamento de um comando SMTC. O exemplo a seguir ilustra um cenário em que um aplicativo usa os comandos Next e Previous para alternar entre estações de rádio da internet em vez de pular faixas da playlist atual. Como no exemplo anterior, um manipulador é registrado quando um comando é recebido, neste caso é o evento PreviousReceived.

_mediaPlayer.CommandManager.PreviousReceived += CommandManager_PreviousReceived;

No manipulador PreviousReceived , primeiro um Adiamento é obtido chamando GetDeferral do MediaPlaybackCommandManagerPreviousReceivedEventArgs passado para o manipulador. Isso diz para o sistema aguardar até que o adiamento seja concluído antes de executar o comando. Isso é extremamente importante se você pretende fazer chamadas assíncronas no manipulador. Neste ponto, o exemplo chama um método personalizado que retorna um MediaPlaybackItem que representa a estação de rádio anterior.

Em seguida, a propriedade Handled é verificada para garantir que o evento ainda não tenha sido manipulado por outro manipulador. Caso contrário, a propriedade Handled é definida como true. Isso permite que o SMTC e outros manipuladores inscritos saibam que não devem tomar nenhuma medida ao executar esse comando, pois ele já foi manipulado. Em seguida, o código define a nova fonte para o media player e inicia o player.

Por fim, Complete é chamado no objeto de adiamento para informar ao sistema que você terminou de processar o comando.

private async void CommandManager_PreviousReceived(MediaPlaybackCommandManager sender, MediaPlaybackCommandManagerPreviousReceivedEventArgs args)
{
    var deferral = args.GetDeferral();
    MediaPlaybackItem mediaPlaybackItem = await GetPreviousStation();

    if(args.Handled != true)
    {
        args.Handled = true;
        sender.MediaPlayer.Source = mediaPlaybackItem;
        sender.MediaPlayer.Play();
    }
    deferral.Complete();
}

Controle manual do SMTC

Como mencionado anteriormente neste artigo, o SMTC detectará e exibirá automaticamente informações de cada instância de MediaPlayer que seu aplicativo criar. Se você quiser usar várias instâncias de MediaPlayer, mas quiser que o SMTC forneça uma única entrada para seu aplicativo, deverá controlar manualmente o comportamento do SMTC em vez de depender da integração automática. Além disso, se você estiver usando MediaTimelineController para controlar um ou mais media players, deverá usar a integração do SMTC manual. Além disso, se seu aplicativo usa uma API diferente de MediaPlayer, como a classe AudioGraph, para reproduzir mídia, você deve implementar a integração do SMTC manual para o usuário usar o SMTC para controlar seu aplicativo. Para obter informações sobre como controlar o SMTC manualmente, consulte Controle manual dos controles de transporte de mídia do sistema.