Players de mídia
A reprodução de mídia envolve a exibição e a escuta de vídeo e áudio por meio de experiências de tela inteira internas (inseridas em uma página ou com um grupo de outros controles) ou dedicadas.
Os usuários esperam um conjunto de controle básico, como reproduzir/pausar, ignorar, ignorar, avançar, que você pode modificar conforme necessário (incluindo os botões do player de mídia, o plano de fundo da barra de controle e a organização ou layout de controle).
Esse é o controle correto?
Use um media player quando você quiser reproduzir áudio ou vídeo em seu aplicativo. Para exibir uma coleção de imagens, use um modo de exibição de inversão.
Recomendações
O player de mídia dá suporte a temas claras e escuros, mas o tema escuro proporciona uma experiência melhor para a maioria dos cenários de entretenimento. A tela de fundo escura oferece melhor contraste, particularmente em condições com pouca luz, e limita a interferência da barra de controle na experiência de visualização.
Durante a execução de conteúdo em vídeo, incentive uma experiência de visualização dedicada ao promover o modo de tela inteira em vez do modo embutido. A experiência de visualização em tela inteira é ideal, e as opções são restritas no modo embutido.
Se você tiver o imóvel de tela, vá com 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 personalizados de transporte para saber mais sobre como adicionar controles personalizados.
UWP e WinUI 2
Importante
As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência da API da UWP para obter informações e exemplos específicos da plataforma.
Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.
As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .
- Classe UWP APIs:MediaPlayerElement, classe MediaTransportControls
- Abra o aplicativo Galeria do WinUI 2 e consulte MediaPlayerElement em ação. Os aplicativos da Galeria do WinUI 2 incluem exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 2. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub.
Recomendamos usar o WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. O WinUI 2.2 ou posterior inclui um novo modelo para esse controle que usa cantos arredondados. Para obter mais informações, confira Raio de canto.
Se você estiver projetando para a experiência de 3 metros, vá com o layout de linha dupla. Ele fornece mais espaço para controles do que o layout compacto de linha única e é mais fácil navegar usando um gamepad para 3 metros. Consulte o artigo Projetando para Xbox e TV para obter mais informações sobre como otimizar seu aplicativo para a experiência de 3 metros.
MediaPlayerElementsó está disponível em Windows 10, versão 1607 e posterior. Se estiver desenvolvendo um aplicativo para uma versão anterior do Windows 10, você precisará usar o controle MediaElement em vez disso. Todas as recomendações feitas aqui também se aplicam.MediaElement
Criar um media player
- APIs importantes: classe MediaPlayerElement, classe MediaTransportControls
O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub
Adicione mídia ao aplicativo criando um objeto MediaPlayerElement em XAML e defina uma Source como uma MediaSource que aponta para um arquivo de áudio ou vídeo.
Este XAML cria o MediaPlayerElement e define sua propriedade Source como o URI de um arquivo de vídeo que seja local para o aplicativo. O MediaPlayerElement começa a ser reproduzido quando a página é carregada. Para suprimir a mídia de iniciar imediatamente, você pode definir a propriedade Reprodução Automática 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"/>
Importante
A configuração MediaPlayerElement.Source para um URI relativo (ms-appx/ms-resource) só funciona em um aplicativo empacotado com um Projeto de Empacotamento de Aplicativos do Windows. Se o aplicativo não usar um Projeto de Empacotamento de Aplicativos do Windows, a solução alternativa recomendada será converter o URI relativo ms-appx:/// em um URI totalmente resolvido file:/// . Consulte também as seções Definir a fonte de mídia e Abrir arquivos de mídia local mais adiante neste artigo.
Controles de transporte de mídia
MediaPlayerElement tem controles de transporte internos que manipulam recursos de reprodução, parada, pausa, volume, ativação de mudo, busca/progresso, legendas ocultas e seleção de faixa de áudio. Para habilitar esses controles, defina AreTransportControlsEnabled como true. Para desabilitá-los, defina AreTransportControlsEnabled como false. Os controles de transporte são representados pela classe MediaTransportControls. Você pode usar os controles de transporte como estão ou personalizá-los de várias maneiras. Para saber mais, confira a referência de classe MediaTransportControls e Criar controles personalizados de transporte.
Os controles de transporte dão suporte a layouts de linha única e dupla. O primeiro exemplo é um layout de linha única, com o botão Reproduzir/Pausar localizado à esquerda da linha do tempo de mídia. Este layout é mais reservado para telas de reprodução de mídia embutidas e compactas.
O layout de controles de linha dupla (abaixo) é recomendado para a maioria dos cenários de uso, especialmente em telas maiores. Esse layout oferece mais espaço para controles e facilita a operação da linha do tempo pelo usuário.
Controles de transporte de mídia do sistema
MediaPlayerElement é integrado automaticamente aos controles de transporte de mídia do sistema. Os controles de transporte de mídia do sistema são os controles exibidos quando teclas de mídia de hardware são pressionadas, como os botões de mídia em teclados. Para saber mais, confira SystemMediaTransportControls.
Definir a origem da mídia
Para reproduzir arquivos na rede ou arquivos inseridos com o aplicativo, defina a propriedade Source como uma MediaSource com o caminho do arquivo.
Dica
Para abrir arquivos da Internet, você precisa declarar a funcionalidade internet (cliente) no manifesto do aplicativo (Package.appxmanifest). Para obter mais informações sobre como declarar recursos, consulte Declarações de recursos de aplicativos.
Esse código tenta definir a propriedade Source do MediaPlayerElement definida em XAML como o caminho de um arquivo inserido em uma TextBox.
<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 inserido no aplicativo, inicialize um Uri com o caminho prefixado com ms-appx:///, crie um MediaSource com o Uri e defina a Origem como o Uri. Por exemplo, para um arquivo chamado video1.mp4 que está em uma subpasta de Vídeos , o caminho seria semelhante a: ms-appx:///Videos/video1.mp4
Importante
A configuração MediaPlayerElement.Source para um URI relativo (ms-appx/ms-resource) só funciona em um aplicativo empacotado com um Projeto de Empacotamento de Aplicativos do Windows.
Esse código define a propriedade Source do MediaPlayerElement definido 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 local
Para abrir arquivos no sistema local ou no OneDrive, você pode usar o FileOpenPicker para obter o arquivo e Source para definir a origem da mídia, ou ainda acessar programaticamente as pastas de mídia do usuário.
Se o aplicativo precisar ter acesso sem a interação do usuário com as pastas Música ou Vídeo, por exemplo, se você precisar enumerar todos os arquivos de música ou vídeo na coleção do usuário e exibi-los em seu aplicativo, declare os recursos Biblioteca de Músicas e Biblioteca de Vídeos. Para obter mais informações, consulte arquivos e pastas nas bibliotecas de música, imagens e vídeos.
O FileOpenPicker não precisa de recursos especiais para acessar os arquivos no sistema de arquivos local, como as pastas Música ou Vídeo do usuário, já que o usuário tem controle total sobre qual arquivo está sendo acessado. Em relação à segurança e à privacidade, é melhor minimizar as funcionalidades que seu aplicativo usa.
Para abrir a mídia local usando FileOpenPicker
Chame FileOpenPicker para permitir que o usuário escolha um arquivo de mídia.
Use a classe FileOpenPicker para escolher um arquivo de mídia. Defina o FileTypeFilter para especificar quais tipos de arquivo o
FileOpenPickerexibe. Chame PickSingleFileAsync para iniciar o seletor de arquivos e obter o arquivo.Use uma MediaSource para definir o arquivo de mídia escolhido como o MediaPlayerElement.Source.
Para usar o StorageFile retornado do FileOpenPicker, você precisa chamar o método CreateFromStorageFile em MediaSource e defini-lo como a Origem do MediaPlayerElement. Em seguida, chame Play no MediaPlayerElement.MediaPlayer para iniciar a mídia.
Este exemplo mostra como usar o FileOpenPicker para escolher um arquivo e definir o arquivo como o Source 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 seu MediaPlayerElement com uma representação visual antes de a mídia ser carregada. Um PosterSource é uma imagem, como uma captura de tela, pôster de filme ou arte do á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, Source não está definido,
Sourcefoi definidonullcomo ou a origem é inválida (como é o caso quando ocorre um evento MediaFailed ). - Enquanto a mídia está sendo carregada. Por exemplo, uma origem válida está definida, mas o evento MediaOpened ainda não ocorreu.
- Quando há streaming de mídia para outro dispositivo.
- Quando a mídia é somente áudio.
Aqui está um MediaPlayerElement com seu Source definido como uma faixa de álbum, e PosterSource definido como uma imagem da capa do álbum.
<MediaPlayerElement Source="ms-appx:///Media/Track1.mp4" PosterSource="ms-appx:///Media/AlbumCover.png"/>
Mantenha a tela do dispositivo ativa
Normalmente, um dispositivo reduz a luminosidade da tela (e depois a desliga) para economizar bateria quando o usuário está longe, mas os aplicativos de vídeo precisam manter a tela ligada para que o usuário possa vê-lo. Para evitar que a exibição seja desativada quando não for mais detectada atividade de usuário, como quando um aplicativo estiver reproduzindo um vídeo, você pode chamar DisplayRequest.RequestActive. A classe DisplayRequest permite que você informe ao Windows que mantenha a tela ligada para que o usuário possa conferir o vídeo.
Para economizar energia e a vida útil da bateria, chame 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 for movido para fora da tela e as reativa quando ele voltar ao primeiro plano.
Consulte algumas situações em que você deve liberar a solicitação de exibição:
- Por exemplo, a reprodução do vídeo foi pausada por uma ação do usuário, buffer ou ajuste devido à largura de banda limitada.
- A reprodução foi interrompida. Por exemplo, a reprodução do vídeo ou a apresentação acabou.
- Erro na reprodução. Por exemplo, problemas com a conectividade de rede ou um arquivo corrompido.
Para manter a tela ativa
Crie uma variável DisplayRequest global. Inicialize-o para
null.private DisplayRequest appDisplayRequest = null;Chame RequestActive para notificar o Windows que o aplicativo requer que a tela fique ligada.
Chame RequestRelease para liberar a solicitação de exibição sempre que a reprodução do vídeo por parada, pausada ou interrompida por um erro de reprodução. Quando o seu aplicativo não tem mais solicitações de exibição ativas, o Windows economiza a duração da bateria ao reduzir a luminosidade da tela (e, depois, desligando-a) quando o dispositivo não estiver em uso.
Cada MediaPlayerElement.MediaPlayer tem uma PlaybackSession do tipo MediaPlaybackSession que controla diversos aspectos da reprodução de mídia como PlaybackRate, PlaybackState e Position. Aqui, você usa o evento PlaybackStateChanged em MediaPlayer.PlaybackSession para detectar situações em que 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 executado, e mantenha a tela ativa somente se o vídeo estiver sendo executado.
<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;
}
}
}
}
}
Controlar o media player de forma programática
MediaPlayerElement oferece inúmeras propriedades, métodos e eventos para controlar a reprodução de áudio e vídeo por meio da propriedade MediaPlayerElement.MediaPlayer. Para uma listagem completa de propriedades, métodos e eventos, confira página de referência do MediaPlayer.
Cenários de reprodução de mídia avançada
Para cenários de reprodução de mídia mais complexos, como reproduzir uma playlist, alternar entre idiomas de áudio ou criar faixas de metadados personalizadas, defina MediaPlayerElement.Source como mediaPlaybackItem ou mediaPlaybackList. Confira a página Reprodução de mídia no Centro de Desenvolvimento para obter mais informações sobre como habilitar diversas funcionalidades de mídia avançada.
Redimensionar e ampliar vídeo
Use a propriedade Stretch para mudar a forma como o conteúdo e/ou a PosterSource preenche seu contêiner. Isso redimensiona e amplia o vídeo de acordo com o valor de Stretch. Os Stretch estados são semelhantes às configurações de tamanho da imagem em muitos conjuntos de TV. Você pode enganchá-la em um botão para que o usuário possa escolher a configuração de sua preferência.
- Nenhum exibe a resolução nativa do conteúdo em seu tamanho original. Isso pode fazer com que alguns dos vídeos sejam cortados ou barras pretas nas bordas do vídeo.
- Uniforme preenche o máximo de espaço possível, preservando a taxa de proporção e o conteúdo do vídeo. Isso pode produzir barras pretas horizontais ou verticais nas bordas do vídeo. Isso é semelhante aos modos widescreen.
- UniformToFill preenche todo o espaço, mantendo a taxa de proporção. Isso pode fazer com que parte do vídeo seja cortado. Isso é semelhante aos modos de tela inteira.
- Fill preenche todo o espaço, mas não mantém a taxa de proporção. Nenhum vídeo é cortado, mas pode ocorrer alongamento. Isso é semelhante aos modos de alongamento.
Aqui, um AppBarButton é usado para percorrer as opções de Stretch. Uma switch instrução verifica o estado atual da propriedade Stretch e a define como o próximo valor na Stretch enumeração . Isso permite ao usuário circular pelos vários estados de ampliação.
<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;
}
}
Habilitar a reprodução de baixa latência
Defina a propriedade RealTimePlayback como true em um MediaPlayerElement.MediaPlayer para permitir que o elemento media player reduza a latência inicial para reprodução. Isso é essencial para aplicativos de comunicação bidirecionais e pode ser aplicável a alguns cenários de jogos. Esse modo consome mais recursos e energia.
Este exemplo cria um MediaPlayerElement e define RealTimePlayback como true.
MediaPlayerElement mediaPlayerElement = new MediaPlayerElement();
mediaPlayerElement.MediaPlayer.RealTimePlayback = true;
Artigos relacionados
Windows developer
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários