Compartir a través de

MediaElement

MediaElement es un control para reproducir vídeo y audio. Los medios compatibles con la plataforma subyacente se pueden reproducir desde los orígenes siguientes:

  • La web, mediante un URI (HTTP o HTTPS).
  • Un recurso incrustado en la aplicación de la plataforma, utilizando el esquema URI embed://.
  • Archivos que proceden del sistema de archivos local de la aplicación mediante el filesystem:// esquema URI.

MediaElement puede usar los controles de reproducción de plataforma, a los que se hace referencia como controles de transporte. Sin embargo, se deshabilitan de forma predeterminada y se pueden reemplazar por sus propios controles de transporte. Las capturas de pantalla siguientes muestran MediaElement la reproducción de un vídeo con los controles de transporte de la plataforma:

Captura de pantalla de una clase MediaElement que reproduce un vídeo, en Android e iOS.

Nota:

MediaElement está disponible en iOS, Android, Windows, macOS y Tizen.

El MediaElement usa las siguientes implementaciones de plataforma.

Plataforma Implementación del reproductor multimedia de plataforma
Androide ExoPlayer, ¡muchas gracias a los responsables de las bibliotecas Android!
iOS/macOS AVPlayer
Windows MediaPlayer

Cómo empezar

Para usar la MediaElement característica de .NET MAUI Community Toolkit, se requieren los pasos siguientes.

Instalación de paquetes NuGet

Antes de poder usar MediaElement dentro de la aplicación, deberá instalar el CommunityToolkit.Maui.MediaElement paquete NuGet y agregar una línea de inicialización en el MauiProgram.cs. A continuación se indica cómo:

Nombre del paquete:CommunityToolkit.Maui.MediaElement

Dirección URL del paquete:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

Inicialización del paquete

En primer lugar, se debe agregar la instrucción using a la parte superior del archivo MauiProgram.cs

using CommunityToolkit.Maui.MediaElement;

Para poder usar MediaElementcorrectamente el UseMauiCommunityToolkitMediaElement método debe llamarse en la MauiAppBuilder clase al arrancar una aplicación el archivo MauiProgram.cs. El siguiente ejemplo muestra cómo hacerlo.

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement()

Para obtener más información sobre cómo hacerlo, consulte la página Introducción.

Inicialización específica de la plataforma

Para acceder a la funcionalidad de MediaElement, se requiere la siguiente configuración específica para la plataforma.

Al usar MediaElement es esencial realizar los pasos siguientes:

1. Agregue ResizableActivity y Launchmode a la actividad.

[Activity(Theme = "@style/Maui.SplashTheme", ResizeableActivity = true, MainLauncher = true, LaunchMode = LaunchMode.SingleTask)]
public class MainActivity : MauiAppCompatActivity
{
}

Para obtener un ejemplo completo de este método incluido en una aplicación, consulte la Aplicación de ejemplo .NET MAUI Community Toolkit

Formatos compatibles

Los formatos multimedia admitidos pueden ser diferentes por plataforma. En algunos casos, incluso puede depender de qué descodificadores están disponibles o instalados en el sistema operativo que se usa mientras se ejecuta la aplicación. Para obtener información más detallada sobre qué formatos se admiten en cada plataforma, consulte los vínculos siguientes.

Plataforma Vínculo Notas
Androide Formatos compatibles con ExoPlayer
iOS/macOS Formatos compatibles con iOS/macOS No existe ninguna documentación oficial sobre esto
Windows Formatos compatibles con Windows En Windows, los formatos admitidos dependen mucho de los códecs que se instalan en el equipo del usuario
Tizen Formatos admitidos de Tizen

Importante

Si el usuario usa una edición de Windows N, no se admite la reproducción de vídeo de forma predeterminada. Las ediciones de Windows N no tienen formatos de reproducción de vídeo instalados por diseño.

Escenarios frecuentes

En las secciones siguientes se tratan los escenarios de uso comunes de MediaElement.

Reproducir medios remotos

Un MediaElement puede reproducir archivos multimedia remotos mediante los esquemas de URI HTTP y HTTPS. Esto se logra estableciendo la propiedad Source en el URI del archivo multimedia:

<toolkit:MediaElement Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
              ShouldShowPlaybackControls="True" />

Importante

Al reproducir orígenes remotos desde puntos de conexión HTTP, es probable que tenga que deshabilitar las medidas de seguridad del sistema operativo que impiden el acceso a puntos de conexión web no seguros. Esto es cierto para al menos iOS y Android.

De forma predeterminada, el medio definido por la Source propiedad no empieza a reproducirse inmediatamente después de abrir el medio. Para habilitar la reproducción automática de medios, establezca la ShouldAutoPlay propiedad en true.

Los controles de reproducción multimedia proporcionados por la plataforma están habilitados de forma predeterminada y se pueden deshabilitar estableciendo la ShouldShowPlaybackControls propiedad enfalse.

Utilización de los metadatos

MediaElement puede usar metadatos para MediaElement.MetadataTitle, MediaElement.MetadataArtist y MediaElement.MetadataArtworkUrl. Puede establecer el título o el artista para mostrar lo que se está reproduciendo actualmente en los controles de pantalla de bloqueo para Windows, Mac Catalyst, iOS y Android. Puede establecer una dirección URL local o remota con ilustraciones para la pantalla de bloqueo. Debe ser al menos 1080P para que se muestre con la mejor calidad. Debe ser una dirección URL y ser .jpg o .png

<toolkit:MediaElement 
    MetadataTitle="Title"
    MetadataArtist="Artist"
    MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg" />

    MediaElement.MetadataTitle="Title";
    MediaElement.MetadataArtist="Artist";
    MediaElement.MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg";

Importante

Puede establecer los metadatos en XAML o en el código subyacente. Si los va a establecer en el código subyacente, debe establecer el origen en el código subyacente. El origen debe establecerse en último lugar. Si establece los metadatos en XAML o en el constructor, esta nota se puede omitir de manera segura.

Uso de TextureView

Un MediaElement puede usar TextureView en la plataforma Android. El comportamiento predeterminado de la plataforma es usar SurfaceView. El uso de la vista de textura agrega compatibilidad para permitir transparencias y otros efectos. Esto se establece cambiando el generador que se va a usar

.UseMauiCommunityToolkitMediaElement(static options => 
{
				options.SetDefaultAndroidViewType(AndroidViewType.TextureView);
})

También puede establecer TextureView para cada elemento multimedia que use. Se puede establecer en XAML y codebehind. Al usarlo de esta manera, se invalidará el comando .UseMauiCommunityToolkitMediaElement()del generador .

var mediaElement = new MediaElement
{
    AndroidViewType = AndroidViewType.TextureView
}

<toolkit:MediaElement AndroidViewType="TextureView" />

Importante

No se recomienda usar TextureView a menos que tenga una necesidad específica. Tiene posibles problemas relacionados con el rendimiento si está habilitado y solo se recomienda para aquellos que necesitan transparencias y otras características avanzadas.

Reproducir medios locales

Los medios locales se pueden reproducir desde los orígenes siguientes:

  • Un recurso incrustado en la aplicación de la plataforma, utilizando el esquema URI embed://.
  • Archivos que proceden del sistema de archivos local de la aplicación mediante el filesystem:// esquema URI.

Nota:

La abreviatura embed:// y filesystem:// solo funcionan desde XAML. En el código, use MediaSource.FromResource() y MediaSource.FromFile() respectivamente. Con estos métodos, puede omitir los embed://y filesystem:// prefijos. El resto del camino debería ser el mismo.

Reproducir contenido multimedia insertado en el paquete de la aplicación

Un MediaElement puede reproducir archivos multimedia que están incrustados en el paquete de la aplicación, utilizando el esquema URI embed://. Los archivos multimedia se insertan en el paquete de la aplicación colocándolos en el proyecto de plataforma.

Para habilitar un archivo multimedia para la reproducción desde los recursos locales, agregue el archivo a la carpeta Resources/Raw del proyecto MAUI de .NET. Cuando se agrega un archivo en la raíz, el URI sería embed://MyFile.mp4.

También puede colocar archivos en subcarpetas. Si MyFile.mp4 estuviera en Resources/Raw/MyVideos, el URI para usarlo con MediaElement sería embed://MyVideos/MyFile.mp4.

A continuación se puede ver un ejemplo de cómo usar esta sintaxis en XAML.

<toolkit:MediaElement Source="embed://MyFile.mp4"
              ShouldShowPlaybackControls="True" />

Descripción de los tipos de MediaSource

Un MediaElement objeto puede reproducir elementos multimedia estableciendo su Source propiedad en un archivo multimedia remoto o local. La Source propiedad es de tipo MediaSourcey esta clase define tres métodos estáticos:

  • FromFile, devuelve una FileMediaSource instancia de un string argumento.
  • FromUri, devuelve una UriMediaSource instancia de un Uri argumento.
  • FromResource, devuelve una ResourceMediaSource instancia de un string argumento.

Además, la MediaSource clase también tiene operadores implícitos que devuelven MediaSource instancias de string y Uri argumentos.

Nota:

Cuando la Source propiedad se establece en XAML, se invoca un convertidor de tipos para devolver una MediaSource instancia de string o Uri.

La MediaSource clase también tiene estas clases derivadas:

  • FileMediaSource, que se usa para especificar un archivo multimedia local de string. Esta clase tiene una Path propiedad que se puede establecer enstring. Además, esta clase tiene operadores implícitos para convertir un objeto string en un FileMediaSource objeto y un FileMediaSource objeto en string.
  • UriMediaSource, que se usa para especificar un archivo multimedia remoto desde un URI. Esta clase tiene una Uri propiedad que se puede establecer enUri.
  • ResourceMediaSource, que se usa para especificar un archivo incrustado que se proporciona a través de los archivos de recursos de la aplicación. Esta clase tiene una Path propiedad que se puede establecer enstring.

Nota:

Cuando se crea un FileMediaSource objeto en XAML, se invoca un convertidor de tipos para devolver una FileMediaSource instancia de string.

Cambio de la relación de aspecto del vídeo

La Aspect propiedad determina cómo se escalarán los medios de vídeo para ajustarse al área de visualización. De forma predeterminada, esta propiedad se establece en el AspectFit miembro de enumeración, pero se puede establecer en cualquiera de los Aspect miembros de enumeración:

  • AspectFit indica que el vídeo se colocará en el formato letterbox, si es necesario, para ajustarse al área de visualización, a la vez que conserva la relación de aspecto.
  • AspectFill indica que el vídeo se recortará para que rellene el área de visualización, a la vez que conserva la relación de aspecto.
  • Fill indica que el vídeo se extenderá para rellenar el área de visualización.

Determinación del MediaElement estado

La clase MediaElement define una propiedad enlazable de solo lectura denominada CurrentState del tipo MediaElementState. Esta propiedad indica el estado actual del control, como por ejemplo si el medio se está reproduciendo o está en pausa, o si aún no está listo para reproducir el medio.

La enumeración MediaElementState define los miembros siguientes:

  • None indica que no MediaElement contiene ningún medio.
  • Opening indica que está MediaElement validando e intentando cargar el origen especificado.
  • Buffering indica que MediaElement está cargando el medio para la reproducción. Su Position propiedad no avanza durante este estado. Si el MediaElement objeto estaba reproduciendo vídeo, continúa mostrando el último fotograma mostrado.
  • Playing indica que MediaElement está reproduciendo la fuente multimedia.
  • Paused indica que no MediaElement avanza su Position propiedad. Si el MediaElement objeto estaba reproduciendo vídeo, continúa mostrando el fotograma actual.
  • Stopped indica que MediaElement contiene medios, pero no se está reproduciéndose ni en pausa. Su Position propiedad se restablece a 0 y no avanza.
  • Failed indica que MediaElement no se pudo cargar o reproducir el contenido multimedia. Esto puede ocurrir al intentar cargar un nuevo elemento multimedia, al intentar reproducir el elemento multimedia o cuando se interrumpe la reproducción multimedia debido a un error. Use el MediaFailed evento para recuperar detalles adicionales.

Por lo general, no es necesario examinar la propiedad CurrentState cuando se utilizan los controles de transporte MediaElement. Sin embargo, esta propiedad es importante al implementar sus propios controles de transporte.

Implementación de controles de transporte personalizados

Los controles de transporte de un reproductor de vídeo son los botones que realizan las funciones Reproducir, Pausa y Detener. Estos botones suelen identificarse con iconos conocidos en lugar de texto, y las funciones Reproducir y Pausa suelen combinarse en un mismo botón.

De forma predeterminada, los MediaElement controles de reproducción están deshabilitados. Esto le permite controlar el MediaElement mediante programación, o proporcionando sus propios controles de transporte. En compatibilidad con esto, MediaElement incluye Play, Pause, y Stop métodos.

En el ejemplo siguiente XAML se muestra una página que contiene un MediaElement y controles de transporte personalizados:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MediaElementDemos.CustomTransportPage"
             Title="Custom transport">
    <Grid>
        ...
        <toolkit:MediaElement x:Name="mediaElement"
                      ShouldAutoPlay="False"
                      ... />
        <HorizontalStackLayout BindingContext="{x:Reference mediaElement}"
                     ...>
            <Button Text="Play"
                    HorizontalOptions="Center"
                    Clicked="OnPlayPauseButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Playing}">
                        <Setter Property="Text"
                                Value="Pause" />
                    </DataTrigger>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Buffering}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
            <Button Text="Stop"
                    HorizontalOptions="Center"
                    Clicked="OnStopButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Stopped}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
        </HorizontalStackLayout>
    </Grid>
</ContentPage>

En este ejemplo, los controles de transporte personalizados se definen como Button objetos. Sin embargo, solo hay dos Button objetos, con el primero Button que representa Reproducir y Pausar, y el segundo Button que representa Detener. DataTrigger se usan los objetos para habilitar y deshabilitar los botones, y para cambiar el primer botón entre Reproducir y Pausar. Para obtener más información sobre los desencadenadores de datos, consulte Desencadenadores .NET MAUI.

El archivo de código subyacente tiene los controladores para los Clickedeventos:

void OnPlayPauseButtonClicked(object sender, EventArgs args)
{
    if (mediaElement.CurrentState == MediaElementState.Stopped ||
        mediaElement.CurrentState == MediaElementState.Paused)
    {
        mediaElement.Play();
    }
    else if (mediaElement.CurrentState == MediaElementState.Playing)
    {
        mediaElement.Pause();
    }
}

void OnStopButtonClicked(object sender, EventArgs args)
{
    mediaElement.Stop();
}

Se puede presionar el botón Reproducir, una vez habilitado, para comenzar la reproducción. Al presionar el botón Pausar, se pausa la reproducción. Al presionar el botón Detener, se detiene la reproducción y se devuelve la posición del archivo multimedia al principio.

Implementación de un control de volumen personalizado

Los controles de reproducción multimedia implementados por cada plataforma incluyen una barra de volumen. Esta barra se parece a un control deslizante y muestra el volumen del medio. Además, puede manipular la barra de volumen para aumentar o disminuir el volumen.

Una barra de volumen personalizada se puede implementar mediante Slider, como se muestra en el ejemplo siguiente:

<StackLayout>
    <toolkit:MediaElement ShouldAutoPlay="False"
                          Source="{StaticResource AdvancedAsync}" />
    <Slider Maximum="1.0"
            Minimum="0.0"
            Value="{Binding Volume}"
            Rotation="270"
            WidthRequest="100" />
</StackLayout>

En este ejemplo, los Slider datos enlazan su Value propiedad a la Volume propiedad de MediaElement. Esto es posible porque la Volume propiedad usa un TwoWay enlace. Por lo tanto, cambiar la Value propiedad dará como resultado el Volume cambio de propiedad.

Nota:

La Volume propiedad tiene una devolución de llamada de validación que garantiza que su valor sea mayor o igual que 0,0 y menor o igual que 1,0.

Para obtener más información sobre el uso de una Slider consulte, Control deslizante MAUI NET

Propiedades

Propiedad Tipo Descripción Valor predeterminado
Aspecto Aspecto Determina el modo de escalado de los medios (visuales) que se cargan actualmente. Esta es una propiedad enlazable. Aspect.AspectFit
Estado actual MediaElementState Indica el estado actual del control. Esta propiedad enlazable es de solo lectura. MediaElementState.None
Duración TimeSpan Indica la duración del medio actualmente abierto. Esta propiedad enlazable es de solo lectura. TimeSpan.Zero
Posición TimeSpan Describe el progreso actual a través del tiempo de reproducción del medio. Esta propiedad enlazable es de solo lectura. Si desea establecer el Position, use el método SeekTo(). TimeSpan.Zero
ShouldAutoPlay bool Indica si la reproducción multimedia comenzará automáticamente cuando se Source establezca la propiedad. Esta es una propiedad enlazable. false
ShouldLoopPlayback bool Describe si el origen multimedia cargado actualmente debe reanudar la reproducción desde el principio después de alcanzar su fin. Esta es una propiedad enlazable. false
ShouldKeepScreenOn bool Determina si la pantalla del dispositivo debe permanecer activada durante la reproducción multimedia. Esta es una propiedad enlazable. false
ShouldMute bool Determina si el audio está silenciado actualmente. Esta es una propiedad enlazable. false
ShouldShowPlaybackControls bool Determina si se muestran los controles de reproducción de las plataformas. Esta es una propiedad enlazable. Tenga en cuenta que en iOS y Windows los controles solo se muestran durante un breve período después de interactuar con la pantalla. No hay forma de mantener visibles los controles en todo momento. true
Origen MediaSource? Origen del medio cargado en el control. null
Velocidad double Determina la velocidad de reproducción del medio. Es una propiedad enlazable 1
MediaHeight int La altura del contenido cargado en píxeles. Esta propiedad enlazable es de solo lectura. No se notifica para medios no visuales y es posible que no siempre se rellene en iOS/macOS para el contenido transmitido en vivo. 0
MediaWidth int Ancho del medio cargado en píxeles. Esta propiedad enlazable es de solo lectura. No se notifica para medios no visuales y es posible que no siempre se rellene en iOS/macOS para el contenido transmitido en vivo. 0
Volumen double Determina el volumen del medio, que se representa en una escala lineal entre 0 y 1. Esta es una propiedad enlazable. 1

Eventos

Evento Descripción
MediaOpened Se produce cuando se ha validado y abierto la secuencia multimedia.
MediaEnded Ocurre cuando MediaElement termina de reproducir su contenido.
MediaFailed Se produce cuando hay un error asociado al origen multimedia.
CambioDePosición Se produce cuando cambia el valor de la propiedad Position.
SeekCompleted Se produce cuando el punto de búsqueda de una operación de búsqueda solicitada está listo para la reproducción.

Métodos

Evento Descripción
Reproducir Comienza a reproducir el contenido cargado.
Pausar Pausa la reproducción del contenido actual.
Detener Detiene la reproducción y restablece la posición del medio actual.
SeekTo Toma un TimeSpan valor para establecer la Position propiedad en y toma CancellationTokenpara cancelar el Task.

Ejemplos

Puede encontrar ejemplos de este control en acción en la Aplicación de ejemplo del Kit de herramientas de la Comunidad de .NET MAUI.

API (Interfaz de Programación de Aplicaciones)

Puede encontrar el código fuente de MediaElement en el repositorio de GitHub del Kit de herramientas de la comunidad de .NET MAUI.