Leitores multimédia

A reprodução de multimédia envolve a visualização e audição de vídeo e áudio através de experiências em linha (incorporadas numa página ou com um grupo de outros controlos) ou experiências dedicadas em ecrã inteiro.

Os usuários esperam um conjunto de controle básico, como reproduzir/pausar, pular para trás, pular para frente, que você pode modificar conforme necessário (incluindo os botões do media player, o plano de fundo da barra de controle e disposição ou layout de controle).

Será este o controlo correto?

Utilize um leitor multimédia quando pretender reproduzir áudio ou vídeo na sua aplicação. Para exibir uma coleção de imagens, use um modo de visualização em flip .

Recommendations

O media player suporta temas claros e escuros, mas o tema escuro oferece uma experiência melhor para a maioria dos cenários de entretenimento. O fundo escuro proporciona um melhor contraste, em particular para condições de pouca luz, e limita a barra de controlo de interferir na experiência de visualização.

Ao reproduzir conteúdo de vídeo, incentive uma experiência de visualização dedicada promovendo o modo de ecrã inteiro em vez do modo em linha. A experiência de visualização em tela cheia é ideal e as opções são restritas no modo em linha.

Se tiveres espaço no ecrã, escolhe o layout de linha dupla. Ele fornece mais espaço para controles do que o layout compacto de linha única e pode ser mais fácil de navegar usando uma variedade de entradas.

Os controles padrão foram otimizados para reprodução de mídia, no entanto, você tem a capacidade de adicionar opções personalizadas necessárias ao media player para fornecer a melhor experiência para seu aplicativo. Visite Criar controles de transporte personalizados para saber mais sobre como adicionar controles personalizados.

Criar um leitor multimédia

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

Adicione mídia à sua aplicação criando um objeto MediaPlayerElement em XAML e defina o Source para um MediaSource que aponta para um arquivo de áudio ou vídeo.

Este XAML cria um MediaPlayerElement e define a sua propriedade Source com o URI de um ficheiro de vídeo que é local na aplicação. O MediaPlayerElement começa a ser reproduzido quando a página é carregada. Para impedir que os conteúdos multimédia sejam iniciados imediatamente, pode definir a propriedade Autoplay como false.

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400" AutoPlay="True"/>

Este XAML cria um MediaPlayerElement com os controles de transporte internos habilitados e a propriedade AutoPlay definida como false.

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400"
                    AutoPlay="False"
                    AreTransportControlsEnabled="True"/>

Controles de transporte de multimédia

MediaPlayerElement incorporou controles de transporte que lidam com reprodução, parada, pausa, volume, mudo, busca/progresso, legendas ocultas e seleção de faixas de áudio. Para habilitar esses controles, configure AreTransportControlsEnabled como true. Para desativá-los, defina AreTransportControlsEnabled como false. Os controlos de transporte são representados pela classe MediaTransportControls. Você pode usar os controles de transporte as-isou personalizá-los de várias maneiras. Para obter mais informações, consulte a referência de classe MediaTransportControls eCriar controles de transporte personalizados .

Os controles de transporte suportam layouts de linha única e dupla. O primeiro exemplo aqui é um layout de única linha, com o botão de reprodução/pausa localizado à esquerda da linha do tempo da mídia. Este layout é melhor reservado para reprodução de mídia em linha e telas compactas.

O layout de controles de linha dupla (abaixo) é recomendado para a maioria dos cenários de uso, especialmente em telas maiores. Esse layout fornece mais espaço para controles e torna a linha do tempo mais fácil para o usuário operar.

Controles de transporte de mídia do sistema

MediaPlayerElement é automaticamente integrado com os controles de transporte de mídia do sistema. Os controles de transporte de mídia do sistema são os controles que aparecem quando as teclas de mídia de hardware são pressionadas, como os botões de mídia nos teclados. Para obter mais informações, consulte SystemMediaTransportControls.

Definir a fonte de mídia

Para reproduzir arquivos na rede ou arquivos incorporados ao aplicativo, defina a propriedade Source como MediaSource com o caminho do arquivo.

Esse código tenta definir a propriedade Source do MediaPlayerElement definido em XAML como o caminho de um arquivo inserido em umTextBox .

<TextBox x:Name="txtFilePath" Width="400"
         FontSize="20"
         KeyUp="TxtFilePath_KeyUp"
         Header="File path"
         PlaceholderText="Enter file path"/>

private void TxtFilePath_KeyUp(object sender, KeyRoutedEventArgs e)
{
    if (e.Key == Windows.System.VirtualKey.Enter)
    {
        TextBox tbPath = sender as TextBox;

        if (tbPath != null)
        {
            LoadMediaFromString(tbPath.Text);
        }
    }
}

private void LoadMediaFromString(string path)
{
    try
    {
        Uri pathUri = new Uri(path);
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

Para definir a fonte de mídia como um arquivo de mídia incorporado no aplicativo, inicialize um de Uri de com o caminho prefixado com , crie um MediaSource com o Uri e defina o de origem para o Uri. Por exemplo, para um arquivo chamado video1.mp4 que está em uma subpasta Vídeos , o caminho seria parecido com: ms-appx:///Videos/video1.mp4

Esse código define a propriedade Source do MediaPlayerElement definida anteriormente em XAML como ms-appx:///Videos/video1.mp4.

private void LoadEmbeddedAppFile()
{
    try
    {
        Uri pathUri = new Uri("ms-appx:///Videos/video1.mp4");
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

Abrir arquivos de mídia locais

Para abrir ficheiros no sistema local ou a partir do OneDrive, pode utilizar o FileOpenPicker para obter o ficheiro e Source para definir a fonte de multimédia ou pode aceder às pastas de multimédia do utilizador programaticamente.

Se o seu aplicativo precisar de acesso sem interação do usuário às pastas Música ou Vídeo , por exemplo, se você estiver enumerando todos os arquivos de música ou vídeo na coleção do usuário e exibindo-os em seu aplicativo, precisará declarar os recursos Biblioteca de Música e Biblioteca de Vídeos . Para mais informações, consulte Ficheiros e pastas nas bibliotecas de Música, Imagens e Vídeos.

O FileOpenPicker não requer recursos especiais para acessar arquivos no sistema de arquivos local, como o Music do usuário ou pastas de de vídeo, uma vez que o usuário tem controle total sobre qual arquivo está sendo acessado. Do ponto de vista da segurança e da privacidade, é melhor minimizar o número de recursos que seu aplicativo usa.

Para abrir mídia local usando FileOpenPicker

1. Chame FileOpenPicker para permitir que o usuário escolha um arquivo de mídia.

   Use a classe FileOpenPicker para selecionar um arquivo de mídia. Defina o FileTypeFilter para especificar quais tipos de arquivo são FileOpenPicker exibidos. Chame PickSingleFileAsync para iniciar o seletor de arquivos e obter o arquivo.

2. Use um MediaSource para definir o ficheiro de mídia escolhido como o MediaPlayerElement.Source.

   Para usar o StorageFile retornado do FileOpenPicker, precisa chamar o método CreateFromStorageFile em MediaSource e defini-lo como a Source do MediaPlayerElement. Em seguida, chame Play no MediaPlayerElement.MediaPlayer para iniciar a mídia.

Este exemplo mostra como usar o FileOpenPicker para escolher um ficheiro e definir o ficheiro como a Fonte de um MediaPlayerElement.

<MediaPlayerElement x:Name="mediaPlayerElement"/>
...
<Button Content="Choose file" Click="Button_Click"/>

private async void Button_Click(object sender, RoutedEventArgs e)
{
    await SetLocalMedia();
}

async private System.Threading.Tasks.Task SetLocalMedia()
{
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    WinRT.Interop.InitializeWithWindow.Initialize(openPicker, WinRT.Interop.WindowNative.GetWindowHandle(this));

    openPicker.FileTypeFilter.Add(".wmv");
    openPicker.FileTypeFilter.Add(".mp4");
    openPicker.FileTypeFilter.Add(".wma");
    openPicker.FileTypeFilter.Add(".mp3");

    var file = await openPicker.PickSingleFileAsync();

    // mediaPlayerElement is a MediaPlayerElement control defined in XAML
    if (file != null)
    {
        mediaPlayerElement.Source = MediaSource.CreateFromStorageFile(file);

        mediaPlayerElement.MediaPlayer.Play();
    }
}

Definir a origem do cartaz

Você pode usar a propriedade PosterSource para fornecer ao MediaPlayerElement uma representação visual antes que a mídia seja carregada. Um PosterSource é uma imagem, como uma captura de tela, pôster de filme ou capa de álbum, que é exibida no lugar da mídia. O PosterSource é exibido nas seguintes situações:

• Quando uma fonte válida não está definida. Por exemplo, de origem não está definida, Source foi definida como nullou a origem é inválida (como é o caso quando ocorre um evento MediaFailed).
• Enquanto os media estão a carregar. Por exemplo, uma fonte válida está definida, mas o evento MediaOpened ainda não ocorreu.
• Quando a mídia está sendo transmitida para outro dispositivo.
• Quando a mídia é apenas áudio.

Aqui está um MediaPlayerElement com o seu Source definido como uma faixa do álbum, e o seu PosterSource definido como uma imagem da capa do álbum.

<MediaPlayerElement Source="ms-appx:///Media/Track1.mp4" PosterSource="ms-appx:///Media/AlbumCover.png"/>

Manter o ecrã do dispositivo ativo

Normalmente, um dispositivo escurece a tela (e eventualmente a desliga) para economizar bateria quando o usuário está ausente, mas os aplicativos de vídeo precisam manter a tela ligada para que o usuário possa ver o vídeo. Para evitar que a exibição seja desativada quando a ação do usuário não for mais detetada, como quando um aplicativo estiver reproduzindo vídeo, você pode chamar DisplayRequest.RequestActive. A classe DisplayRequest permite que você diga ao Windows para manter a exibição ativada para que o usuário possa ver o vídeo.

Para economizar energia e bateria, você deve chamar DisplayRequest.RequestRelease para liberar a solicitação de exibição quando ela não for mais necessária. O Windows desativa automaticamente as solicitações de exibição ativas do aplicativo quando o aplicativo sai da tela e as reativa quando o aplicativo volta para o primeiro plano.

Aqui estão algumas situações em que você deve liberar a solicitação de exibição:

• A reprodução de vídeo é pausada, por exemplo, por ação do usuário, buffering ou ajuste devido à largura de banda limitada.
• A reprodução é interrompida. Por exemplo, a reprodução do vídeo terminou ou a apresentação chegou ao fim.
• Ocorreu um erro de reprodução. Por exemplo, problemas de conectividade de rede ou um arquivo corrompido.

Para manter o ecrã ativo

1. Crie uma variável DisplayRequest global. Inicialize-o em null.

   private DisplayRequest appDisplayRequest = null;
   

2. Chame RequestActive para notificar o Windows de que o aplicativo requer que a exibição permaneça ativada.

3. Invoque RequestRelease para liberar a solicitação de exibição sempre que a reprodução de vídeo for parada, pausada ou interrompida por um erro de reprodução. Quando seu aplicativo não tem mais solicitações de exibição ativas, o Windows economiza a vida útil da bateria escurecendo a tela (e, eventualmente, desligando-a) quando o dispositivo não está sendo usado.

Cada MediaPlayerElement.MediaPlayer tem um PlaybackSession do tipo MediaPlaybackSession que controla vários aspetos da reprodução de mídia, como PlaybackRate, PlaybackState e Position. Aqui, você usa o evento PlaybackStateChanged em MediaPlayer.PlaybackSession para detetar situações em que você deve liberar a solicitação de exibição. Em seguida, use a propriedade NaturalVideoHeight para determinar se um arquivo de áudio ou vídeo está sendo reproduzido e mantenha a tela ativa somente se o vídeo estiver sendo reproduzido.

<MediaPlayerElement x:Name="mediaPlayerElement" Source="ms-appx:///Videos/video1.mp4"/>

public sealed partial class MainWindow : Window
{
    public DisplayRequest appDisplayRequest = null;
    // using Microsoft.UI.Dispatching;
    private DispatcherQueue dispatcherQueue = DispatcherQueue.GetForCurrentThread();

    public MainWindow()
    {
        this.InitializeComponent();
        mediaPlayerElement.MediaPlayer.PlaybackSession.PlaybackStateChanged += 
            PlaybackSession_PlaybackStateChanged;
    }

    private void PlaybackSession_PlaybackStateChanged(MediaPlaybackSession sender, object args)
    {
        MediaPlaybackSession playbackSession = sender as MediaPlaybackSession;
        if (playbackSession != null && playbackSession.NaturalVideoHeight != 0)
        {
            if (playbackSession.PlaybackState == MediaPlaybackState.Playing)
            {
                if (appDisplayRequest is null)
                {
                    dispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
                    {
                        appDisplayRequest = new DisplayRequest();
                        appDisplayRequest.RequestActive();
                    });
                }
            }
            else // PlaybackState is Buffering, None, Opening, or Paused.
            {
                if (appDisplayRequest is not null)
                {
                    appDisplayRequest.RequestRelease();
                    appDisplayRequest = null;
                }
            }
        }
    }
}

Controle o media player programaticamente

O MediaPlayerElement disponibiliza várias propriedades, métodos e eventos para controlar a reprodução de áudio e vídeo através da propriedade MediaPlayerElement.MediaPlayer. Para obter uma lista completa de propriedades, métodos e eventos, consulte a página de referência do MediaPlayer .

Cenários avançados de reprodução de multimédia

Para cenários de reprodução de mídia mais complexos, como reproduzir uma lista de reprodução, alternar entre idiomas de áudio ou criar faixas de metadados personalizadas, defina MediaPlayerElement.Source como MediaPlaybackItem ou MediaPlaybackList. Consulte a página de reprodução de mídia para obter mais informações sobre como habilitar várias funcionalidades avançadas de mídia.

Redimensionar e esticar vídeo

Use a propriedade Stretch para alterar a maneira como o conteúdo do vídeo e/ou o PosterSource preenche o contêiner em que está. Isso redimensiona e alonga o vídeo dependendo do valor de Stretch . Os Stretch estados são semelhantes às configurações de tamanho de imagem em muitos aparelhos de TV. Você pode conectar isso a um botão e permitir que o usuário escolha qual configuração prefere.

• Nenhum exibe a resolução nativa do conteúdo em seu tamanho original. Isso pode resultar em alguns dos vídeos sendo cortados ou barras pretas nas bordas do vídeo.
• A funcionalidade uniforme preenche o máximo de espaço possível, preservando a proporção e o conteúdo do vídeo. Isso pode resultar em barras pretas horizontais ou verticais nas bordas do vídeo. Isto é semelhante aos modos de ecrã panorâmico.
• UniformToFill preenche todo o espaço, preservando a proporção. Isso pode resultar em parte do vídeo sendo cortado. Isso é semelhante aos modos de tela cheia.
• Preencher preenche todo o espaço, mas não preserva a proporção. O vídeo não é cortado, mas pode ocorrer esticamento. Isto é semelhante aos modos de estiramento.

Aqui, um AppBarButton é usado para percorrer as opções Stretch. Uma switch instrução verifica o estado atual da propriedade Stretch e a define como o próximo valor na Stretch enumeração. Isto permite que o utilizador atravesse os diferentes estados de alongamento.

<AppBarButton Icon="Trim"
              Label="Resize Video"
              Click="PictureSize_Click" />

private void PictureSize_Click(object sender, RoutedEventArgs e)
{
    switch (mediaPlayerElement.Stretch)
    {
        case Stretch.Fill:
            mediaPlayerElement.Stretch = Stretch.None;
            break;
        case Stretch.None:
            mediaPlayerElement.Stretch = Stretch.Uniform;
            break;
        case Stretch.Uniform:
            mediaPlayerElement.Stretch = Stretch.UniformToFill;
            break;
        case Stretch.UniformToFill:
            mediaPlayerElement.Stretch = Stretch.Fill;
            break;
        default:
            break;
    }
}

Ativar reprodução de baixa latência

Defina a propriedade RealTimePlayback como true num MediaPlayerElement.MediaPlayer para permitir que o elemento reprodutor de média reduza a latência inicial para a reprodução. Isso é fundamental para aplicativos de comunicação bidirecional e pode ser aplicável a alguns cenários de jogos. Esteja ciente de que este modo é mais intensivo em recursos e menos eficiente em termos de energia.

Este exemplo cria um MediaPlayerElement e define o RealTimePlayback para true.

MediaPlayerElement mediaPlayerElement = new MediaPlayerElement();
mediaPlayerElement.MediaPlayer.RealTimePlayback = true;

UWP e WinUI 2

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .

Recomendamos usar a WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Consulte Raio de cantopara obter mais informações.

Se você estiver projetando para a experiência de 10 pés, opte pelo layout de linha dupla. Ele proporciona mais espaço para controlos do que o layout compacto de linha única e é mais fácil de navegar usando um gamepad a uma distância de 10 pés. Consulte o artigo Design para Xbox e TV para obter mais informações sobre como otimizar seu aplicativo para a experiência de 10 pés.

MediaPlayerElement só está disponível no Windows 10, versão 1607 e posterior. Se você estiver desenvolvendo um aplicativo para uma versão anterior do Windows 10, precisará usar o controle MediaElement em vez disso. Todas as recomendações aqui feitas também se aplicam a MediaElement.

Artigos relacionados

• Noções básicas de design de comandos para aplicativos do Windows
• Noções básicas de design de conteúdo para aplicativos do Windows