Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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:
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 MediaElement
correctamente 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 MediaSource
y esta clase define tres métodos estáticos:
-
FromFile
, devuelve unaFileMediaSource
instancia de unstring
argumento. -
FromUri
, devuelve unaUriMediaSource
instancia de unUri
argumento. -
FromResource
, devuelve unaResourceMediaSource
instancia de unstring
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 destring
. Esta clase tiene unaPath
propiedad que se puede establecer enstring
. Además, esta clase tiene operadores implícitos para convertir un objetostring
en unFileMediaSource
objeto y unFileMediaSource
objeto enstring
. -
UriMediaSource
, que se usa para especificar un archivo multimedia remoto desde un URI. Esta clase tiene unaUri
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 unaPath
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 noMediaElement
contiene ningún medio. -
Opening
indica que estáMediaElement
validando e intentando cargar el origen especificado. -
Buffering
indica queMediaElement
está cargando el medio para la reproducción. SuPosition
propiedad no avanza durante este estado. Si elMediaElement
objeto estaba reproduciendo vídeo, continúa mostrando el último fotograma mostrado. -
Playing
indica queMediaElement
está reproduciendo la fuente multimedia. -
Paused
indica que noMediaElement
avanza suPosition
propiedad. Si elMediaElement
objeto estaba reproduciendo vídeo, continúa mostrando el fotograma actual. -
Stopped
indica queMediaElement
contiene medios, pero no se está reproduciéndose ni en pausa. SuPosition
propiedad se restablece a 0 y no avanza. -
Failed
indica queMediaElement
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 elMediaFailed
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 Clicked
eventos:
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 CancellationToken para 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.
Vínculos relacionados
.NET MAUI Community Toolkit