Instancias de Media Player
La reproducción multimedia implica la visualización y la escucha de vídeo y audio a través de experiencias de pantalla completa en línea (incrustadas en una página o con un grupo de controles diferentes) o dedicadas.
Los usuarios esperan un conjunto de controles básicos, como reproducir/pausar, saltar atrás y saltar adelante, que puede modificar según sea necesario (incluidos los botones de Media Player, el fondo de la barra de controles y el diseño o la disposición de los controles).
¿Es este el control adecuado?
Usa un reproductor multimedia cuando quieras reproducir audio o vídeo en tu aplicación. Para mostrar una colección de imágenes, use una vista invertida.
Recomendaciones
El reproductor multimedia admite temas claros y oscuros, pero el tema oscuro proporciona una mejor experiencia para la mayoría de los escenarios de entretenimiento. El fondo oscuro proporciona un mejor contraste, en particular para condiciones de poca luz, y limita la interferencia de la barra de control en la experiencia de visualización.
Durante la reproducción de contenido de vídeo, fomenta una experiencia de visualización dedicada promocionando el modo de pantalla completa sobre el modo incorporado. La experiencia de visualización en pantalla completa es óptima, y las opciones están restringidas en el modo incorporado.
Si dispones de espacio en la pantalla, usa el diseño de dos filas. Proporciona más espacio para los controles que el diseño compacto de una sola fila y puede ser más fácil navegar mediante una variedad de entradas.
Los controles predeterminados se han optimizado para la reproducción multimedia, pero tienes la capacidad de agregar opciones personalizadas que necesitas al reproductor multimedia para proporcionar la mejor experiencia para tu aplicación. Consulta el artículo Crear controles de transporte personalizados para obtener más información sobre cómo agregar controles personalizados.
UWP y WinUI 2
Importante
La información y los ejemplos de este artículo están optimizados para aplicaciones que usan el SDK de Aplicaciones para Windows y WinUI 3, pero generalmente son aplicables a las aplicaciones para UWP que usan WinUI 2. Consulte el material de referencia de las API de UWP para obtener información y ejemplos específicos de la plataforma.
Esta sección contiene información que necesita para usar el control en una aplicación para UWP o WinUI 2.
Las API de este control existen en el espacio de nombres Windows.UI.Xaml.Controls .
- API de UWP:Clase MediaPlayerElement, Clase MediaTransportControls
- Abra la aplicación WinUI 2 Gallery y vea MediaPlayerElement en acción. La aplicación WinUI 2 Gallery incluye ejemplos interactivos de la mayoría de los controles, características y funcionalidades de WinUI 2. Obtenga la aplicación en Microsoft Store u obtenga el código fuente en GitHub.
Se recomienda usar la versión más reciente de WinUI 2 para obtener los estilos y plantillas más actuales para todos los controles. WinUI 2.2 o posterior incluye una nueva plantilla para este control que usa esquinas redondeadas. Para obtener más información, consulta Radio de redondeo.
Si está diseñando para la experiencia de 10 pies, vaya con el diseño de doble fila. Proporciona más espacio para los controles que el diseño compacto de una sola fila y es más fácil navegar usando un controlador para juegos para 10 pies. Consulta el artículo Diseño para Xbox y TV para obtener más información sobre cómo optimizar la aplicación para la experiencia de 10 pies.
MediaPlayerElementsolo está disponible en Windows 10, versión 1607 y posteriores. Si va a desarrollar una aplicación para una versión anterior de Windows 10, tendrá que usar el control MediaElement en su lugar. Todas las recomendaciones realizadas aquí también se aplican a MediaElement .
Crear un reproductor multimedia
- API importantes: Clase MediaPlayerElement y Clase MediaTransportControls
La aplicación WinUI 3 Gallery incluye ejemplos interactivos de la mayoría de los controles, las características y la funcionalidad de WinUI 3. Obtenga la aplicación en Microsoft Store o el código fuente en GitHub.
Agrega elementos multimedia a tu aplicación al crear un objeto MediaPlayerElement en XAML y establece el valor de Source en una clase MediaSource que apunte a un archivo de audio o vídeo.
Este lenguaje XAML crea un objeto MediaPlayerElement y establece su propiedad Source en el URI de un archivo de vídeo que es local para la aplicación. comienza MediaPlayerElement a reproducirse cuando se carga la página. Para suprimir los medios de inicio inmediatamente, puede establecer la propiedad Reproducción automática en false.
<MediaPlayerElement x:Name="mediaPlayerElement"
Source="ms-appx:///Videos/video1.mp4"
Width="400" AutoPlay="True"/>
Este XAML crea un mediaPlayerElement con los controles de transporte integrados habilitados y la propiedad Reproducción automática establecida en false.
<MediaPlayerElement x:Name="mediaPlayerElement"
Source="ms-appx:///Videos/video1.mp4"
Width="400"
AutoPlay="False"
AreTransportControlsEnabled="True"/>
Importante
Establecer MediaPlayerElement.Source en un URI relativo (ms-appx/ms-resource) solo funciona en una aplicación empaquetada con un proyecto de empaquetado de aplicaciones de Windows. Si la aplicación no usa un proyecto de empaquetado de aplicaciones de Windows, la solución alternativa recomendada es convertir el URI relativo ms-appx:/// en un URI totalmente resuelto file:/// . Consulte también las secciones Establecer el origen multimedia y Abrir archivos multimedia locales más adelante en este artículo.
Controles de transporte de contenido multimedia
MediaPlayerElement tiene controles de transporte integrados para reproducir, detener, pausar, cambiar el volumen, silenciar, realizar búsquedas/comprobar el progreso, subtítulos y elegir una pista de audio. Para habilitar estos controles, establezca AreTransportControlsEnabledtrueen . Para deshabilitarlos, establezca en AreTransportControlsEnabledfalse. Los controles de transporte se representan mediante la clase MediaTransportControls. Puedes usar los controles de transporte tal como están o personalizarlos de diversas maneras. Para obtener más información, consulta la referencia de la clase MediaTransportControls y el artículo Crear controles de transporte personalizados.
Los controles de transporte admiten diseños de fila única y doble. El primer ejemplo mostrado aquí es un diseño de fila única, con el botón de reproducir/pausar situado a la izquierda de la escala de tiempo multimedia. Este diseño se reserva para pantallas de reproducción de contenido multimedia compactas e incorporadas.
Se recomienda el diseño de controles de fila doble (a continuación) en la mayoría de los escenarios de uso, especialmente en las pantallas grandes. Este diseño proporciona más espacio para los controles y facilita el uso de la escala de tiempo para el usuario.
Controles de transporte de contenido multimedia del sistema
MediaPlayerElement se integra automáticamente con los controles de transporte de contenido multimedia del sistema. Los controles de transporte de contenido multimedia del sistema son los controles que aparecen cuando se presionan teclas multimedia de hardware, como los botones multimedia de los teclados. Para obtener más información, consulta SystemMediaTransportControls.
Establecer el origen del contenido multimedia
Para reproducir archivos de la red o archivos insertados en la aplicación, establece la propiedad Source en MediaSource con la ruta de acceso del archivo.
Sugerencia
Para abrir archivos desde Internet, debes declarar la funcionalidad Internet (cliente) en el manifiesto de la aplicación (Package.appxmanifest). Para obtener más información sobre las funciones de declaración, consulta Declaraciones de funcionalidades de las aplicaciones.
En este código se intenta establecer la propiedad Source de la clase MediaPlayerElement definida en XAML en la ruta de acceso de un archivo especificado en una clase 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 establecer el origen multimedia en un archivo multimedia incrustado en la aplicación, inicialice un URI con el prefijo de ruta de acceso con ms-appx:///, cree un mediaSource con el URI y, a continuación, establezca el origen en el URI. Por ejemplo, para un archivo denominado video1.mp4 que se encuentra en una subcarpeta Vídeos , la ruta de acceso tendría el siguiente aspecto: ms-appx:///Videos/video1.mp4
Importante
Establecer MediaPlayerElement.Source en un URI relativo (ms-appx/ms-resource) solo funciona en una aplicación empaquetada con un proyecto de empaquetado de aplicaciones de Windows.
Este código establece la propiedad Source del objeto MediaPlayerElement definido anteriormente en XAML ms-appx:///Videos/video1.mp4en .
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 archivos multimedia locales
Para abrir archivos del sistema local o de OneDrive, puedes usar FileOpenPicker para obtener el archivo y Source para establecer el origen del contenido multimedia, o bien puedes acceder a las carpetas de contenido multimedia del usuario mediante programación.
Si la aplicación necesita acceso a las carpetas Música o Vídeo sin interacción con el usuario, por ejemplo al enumerar todos los archivos de música o vídeo en la colección del usuario y mostrarlos en la aplicación, entonces debes declarar las funcionalidades Biblioteca de música y Biblioteca de vídeos . Para obtener más información, consulta Archivos y carpetas en las bibliotecas de música, imágenes y vídeos.
El control FileOpenPicker no requiere funcionalidades especiales para acceder a archivos en el sistema de archivos local, por ejemplo en las carpetas Música o Vídeo del usuario, porque el usuario tiene control total sobre el archivo al cual se accede. Desde una perspectiva de seguridad y privacidad, es mejor minimizar la cantidad de funcionalidades que usa la aplicación.
Para abrir contenido multimedia local con FileOpenPicker
Llama a FileOpenPicker para que el usuario pueda seleccionar un archivo multimedia.
Usa la clase FileOpenPicker para seleccionar un archivo multimedia. Establezca FileTypeFilter para especificar los tipos de archivo que se
FileOpenPickermuestran. Llama a PickSingleFileAsync para iniciar el selector de archivos y obtener el archivo.Usa una clase MediaSource para establecer el archivo multimedia elegido como la propiedad MediaPlayerElement.Source.
Para usar el storageFile devuelto desde FileOpenPicker, debes llamar al método CreateFromStorageFile en MediaSource y establecerlo como source deMediaPlayerElement. Después, llama a Play en MediaPlayerElement.MediaPlayer para iniciar el archivo multimedia.
En este ejemplo se muestra cómo usar la clase FileOpenPicker para elegir un archivo y establecerlo como la propiedad Source de una clase 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();
}
}
Establecer el origen de póster
Puedes usar la propiedad PosterSource para proporcionar a la clase MediaPlayerElement una representación visual antes de cargar el contenido multimedia. Es PosterSource una imagen, como una captura de pantalla, un póster de película o una imagen de álbum, que se muestra en lugar de los medios. PosterSource Se muestra en las situaciones siguientes:
- Cuando no hay un origen válido establecido. Por ejemplo, source is not set,
Sourcewas set tonull, or the source is invalid (as is the case when a MediaFailed event occurs). - Mientras se carga el contenido multimedia. Por ejemplo, se estableció un origen válido, pero aún no se desencadenó el evento MediaOpened.
- Cuando se hace streaming del contenido multimedia a otro dispositivo.
- Cuando el contenido multimedia es solo audio.
Esta es una clase MediaPlayerElement con su propiedad Source establecida en una pista de álbum y su propiedad PosterSource establecida en una imagen de portada de álbum.
<MediaPlayerElement Source="ms-appx:///Media/Track1.mp4" PosterSource="ms-appx:///Media/AlbumCover.png"/>
Mantener activa la pantalla del dispositivo
Por lo general, los dispositivos oscurecen la pantalla (y terminan apagándola) para ahorrar batería cuando el usuario se ausenta, pero las aplicaciones de vídeo necesitan mantenerla activada para que el usuario pueda ver el vídeo. Para evitar que se desactive la pantalla cuando no se detecte ninguna acción del usuario (por ejemplo, cuando una aplicación reproduce un vídeo), puedes llamar al método DisplayRequest.RequestActive. La clase DisplayRequest te permite indicarle a Windows que mantenga activada la pantalla para que el usuario pueda ver el vídeo.
Para ahorrar energía y duración de la batería, debes llamar a DisplayRequest.RequestRelease para liberar la solicitud de pantalla cuando ya no sea necesaria. Windows desactiva automáticamente la pantalla activa de la aplicación cuando la aplicación se quita de la pantalla y vuelve a activarla cuando la aplicación vuelve a estar en primer plano.
Estas son algunas situaciones en las que debes liberar la solicitud de pantalla:
- La reproducción de vídeo se pone en pausa, por ejemplo, por una acción del usuario, por almacenamiento en búfer o por un ajuste a causa de ancho de banda limitado.
- La reproducción se detiene. Por ejemplo, se terminó de reproducir el vídeo o finalizó la presentación.
- Error de reproducción. Por ejemplo, problemas de conectividad de red o un archivo dañado.
Para mantener la pantalla activa
Crea una variable DisplayRequest global. Inicialícelo en
null.private DisplayRequest appDisplayRequest = null;Llama a RequestActive para notificar a Windows que la aplicación requiere que la pantalla permanezca activada.
Llama a RequestRelease para liberar la solicitud de pantalla siempre que la reproducción de vídeo se detenga, ponga en pausa o se interrumpa por un error de reproducción. Cuando la aplicación ya no tiene ninguna solicitud de pantalla activa, Windows ahorra batería oscureciendo la pantalla (y terminará apagándola) cuando el dispositivo no esté en uso.
Cada propiedad MediaPlayerElement.MediaPlayer tiene una propiedad PlaybackSession de tipo MediaPlaybackSession que controla diversos aspectos de la reproducción de contenido multimedia como PlaybackRate, PlaybackState y Position. Aquí, usas el evento PlaybackStateChanged en MediaPlayer.PlaybackSession para detectar situaciones en las que deberías liberar la solicitud de presentación. Por lo tanto, usa la propiedad NaturalVideoHeight para determinar si hay un archivo de audio o vídeo en reproducción y mantener la pantalla activa solo si el vídeo se está reproduciendo.
<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 el reproductor multimedia mediante programación
MediaPlayerElement proporciona gran cantidad de propiedades, métodos y eventos para controlar la reproducción de audio y vídeo a través de la propiedad MediaPlayerElement.MediaPlayer. Para obtener una lista completa de propiedades, métodos y eventos, consulta la página de referencia de MediaPlayer.
Escenarios de reproducción avanzada de contenido multimedia
Para escenarios de reproducción multimedia más complejos, como reproducir una lista de reproducción, cambiar entre idiomas de audio o crear pistas de metadatos personalizadas, establezca MediaPlayerElement.Source en mediaPlaybackItem o mediaPlaybackList. Consulta la página Reproducción de contenido multimedia para obtener más información sobre cómo habilitar diversas funciones multimedia avanzadas.
Cambiar el tamaño del vídeo y ampliarlo
Usa la propiedad Stretch para cambiar la forma en que el contenido de vídeo y/o PosterSource rellenan el contenedor en el que se encuentran. Esto amplía el vídeo y cambia su tamaño según el valor de Stretch. Los Stretch estados son similares a la configuración de tamaño de imagen en muchos televisores. Puedes enlazarlo con un botón y dejar que el usuario elija qué configuración prefiere.
- Ninguno muestra la resolución nativa del contenido en su tamaño original. Esto puede dar lugar a que algunos de los vídeos se recorten o barras negras en los bordes del vídeo.
- Uniforme rellena la mayor cantidad de espacio posible, al tiempo que conserva la relación de aspecto y el contenido del vídeo. Esto puede hacer que aparezcan barras negras horizontales o verticales en los bordes del vídeo. Esto es similar a los modos de pantalla panorámica.
- UniformToFill rellena todo el espacio, pero conserva la relación de aspecto. Esto puede dar lugar a que se recorte parte del vídeo. Esto es similar a los modos de pantalla completa.
- Fill rellena todo el espacio, pero no conserva la relación de aspecto. Ninguno de los vídeos se recorta, pero puede producirse el ajuste. Esto es similar a los modos con ajuste.
Aquí, un AppBarButton se usa para recorrer las opciones Stretch. Una switch instrucción comprueba el estado actual de la propiedad Stretch y la establece en el siguiente valor de la Stretch enumeración. Esto permite que el usuario recorra los distintos estados de imagen ampliada.
<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 la reproducción de latencia baja
Establezca la propiedad trueRealTimePlayback en en un objeto MediaPlayerElement.MediaPlayer para permitir que el elemento del reproductor multimedia reduzca la latencia inicial de la reproducción. Esto es fundamental para las aplicaciones de comunicaciones bidireccionales y se puede aplicar a algunos escenarios de juegos. Ten en cuenta que este modo consume más recursos y es menos eficiente desde el punto de vista energético.
En este ejemplo se crea un objeto MediaPlayerElement y se establece RealTimePlayback en true.
MediaPlayerElement mediaPlayerElement = new MediaPlayerElement();
mediaPlayerElement.MediaPlayer.RealTimePlayback = true;
Artículos relacionados
Comentarios
Próximamente: a lo largo de 2024, eliminaremos gradualmente los problemas de GitHub como mecanismo de comentarios para el contenido y lo reemplazaremos por un nuevo sistema de comentarios. Para obtener más información, consulte: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de