MediaElement
MediaElement
é um controle para reproduzir vídeo e áudio. A mídia suportada pela plataforma subjacente pode ser reproduzida das seguintes fontes:
- Web, usando um URI (HTTP ou HTTPS).
- Um recurso incorporado no aplicativo da plataforma, usando o esquema de URI
embed://
. - Arquivos provenientes do sistema de arquivos local do aplicativo, usando o esquema de URI
filesystem://
.
MediaElement
pode usar os controles de reprodução da plataforma, que são chamados de controles de transporte. No entanto, eles são desativados por padrão e podem ser substituídos por seus próprios controles de transporte. As capturas de ecrã a seguir mostram o MediaElement
a reproduzir um vídeo com os controlos de transporte da plataforma.
Observação
MediaElement
está disponível para iOS, Android, Windows, macOS e Tizen.
O MediaElement
usa as seguintes implementações de plataforma.
Plataforma | Implementação de media player de plataforma |
---|---|
Androide | ExoPlayer, muito obrigado aos responsáveis pelas Bibliotecas Android! |
iOS/macOS | do AVPlayer |
Windows | Leitor de Mídia |
Primeiros passos
Para usar o recurso MediaElement
do .NET MAUI Community Toolkit, as etapas a seguir são necessárias.
Instalar o pacote NuGet
Antes de poderes usar MediaElement
dentro da tua aplicação, precisarás de instalar o pacote NuGet CommunityToolkit.Maui.MediaElement
e adicionar uma linha de inicialização no teu MauiProgram.cs. Como se segue:
Nome do pacote:CommunityToolkit.Maui.MediaElement
URL do pacote:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement
Inicializando o pacote
Primeiro, a instrução using precisa ser adicionada à parte superior do arquivo de MauiProgram.cs
using CommunityToolkit.Maui.MediaElement;
Para usar o MediaElement
corretamente, o método UseMauiCommunityToolkitMediaElement
deve ser chamado na classe MauiAppBuilder
ao inicializar um aplicativo, o arquivo MauiProgram.cs. O exemplo a seguir mostra como executar isso.
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.UseMauiCommunityToolkitMediaElement()
Para obter mais informações sobre como fazer isso, consulte a página Introdução.
Inicialização específica da plataforma
Para aceder à funcionalidade MediaElement
, é necessária a seguinte configuração específica da plataforma.
Ao usar MediaElement
é essencial executar as seguintes etapas:
1. Adicionar ResizableActivity
e Launchmode
à atividade
[Activity(Theme = "@style/Maui.SplashTheme", ResizeableActivity = true, MainLauncher = true, LaunchMode = LaunchMode.SingleTask)]
public class MainActivity : MauiAppCompatActivity
{
}
2. Adicione o seguinte a AndroidManifest.xml
dentro da tag <application>
.
<service android:name="communityToolkit.maui.media.services" android:stopWithTask="true" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
<intent-filter>
<action android:name="androidx.media3.session.MediaSessionService"/>
</intent-filter>
</service>
3. Atualize a versão mínima da API do Android
No arquivo .csproj
do projeto, atualize a versão mínima da API do Android para 26.
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>
4. Adicione as seguintes permissões ao AndroidManifest.xml
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL" />
Aqui está um exemplo de configurações necessárias no AndroidManifest.xml
<service android:name="communityToolkit.maui.media.services" android:stopWithTask="true" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
<intent-filter>
<action android:name="androidx.media3.session.MediaSessionService"/>
</intent-filter>
</service>
</application>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL"/>
Observação
Esta modificação no manifesto do Android permite a exibição de metadados ao reproduzir um vídeo. Ele fornece suporte para notificações e é essencial para que as notificações funcionem em todas as APIs relevantes. A alteração introduz um serviço e concede as permissões necessárias.
Para obter um exemplo completo desse método incluído em um aplicativo, consulte o .NET MAUI Community Toolkit Sample Application
Formatos suportados
Os formatos multimédia suportados podem ser diferentes por plataforma. Em alguns casos, pode até depender de quais decodificadores estão disponíveis ou instalados no sistema operacional que é usado durante a execução do seu aplicativo. Para obter informações mais detalhadas sobre quais formatos são suportados em cada plataforma, consulte os links abaixo.
Plataforma | Ligação | Observações |
---|---|---|
Androide | Formatos suportados pelo ExoPlayer | |
iOS/macOS | formatos suportados por iOS/macOS | Não existe documentação oficial sobre isso |
Windows | Formatos suportados pelo Windows | No Windows, os formatos suportados dependem muito de quais codecs estão instalados na máquina do usuário |
Tizen | Formatos Suportados do Tizen |
Importante
Se o usuário estiver usando uma edição do Windows N, nenhuma reprodução de vídeo é suportada por padrão. As edições do Windows N não têm formatos de reprodução de vídeo instalados por design.
Cenários comuns
As seções a seguir abordam cenários de uso comuns para o MediaElement
.
Reproduzir multimédia remota
Um MediaElement
pode reproduzir arquivos de mídia remotos usando os esquemas de URI HTTP e HTTPS. Isso é feito definindo a propriedade Source
para o URI do arquivo de mídia:
<toolkit:MediaElement Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
ShouldShowPlaybackControls="True" />
Importante
Ao reproduzir fontes remotas a partir de terminais HTTP, vai provavelmente precisar desativar as medidas de segurança do sistema operativo que impedem o acesso a terminais web inseguros. Isso é verdade pelo menos para iOS e Android.
Por padrão, a mídia definida pela propriedade Source
não começa a ser reproduzida imediatamente depois que a mídia é aberta. Para habilitar a reprodução automática de mídia, defina a propriedade ShouldAutoPlay
como true
.
Os controles de reprodução de mídia fornecidos pela plataforma são habilitados por padrão e podem ser desabilitados definindo a propriedade ShouldShowPlaybackControls
como false
.
Usando metadados
Um MediaElement
pode usar metadados para MediaElement.MetadataTitle
, MediaElement.MetadataArtist
e MediaElement.MetadataArtworkUrl
. Você pode definir o título ou artista para mostrar o que está sendo reproduzido atualmente nos controles de tela de bloqueio para Windows, Mac Catalyst, iOS e Android. Você pode definir uma URL local ou remota com ilustrações para a tela de bloqueio. Deve ser pelo menos 1080P para que a melhor qualidade seja exibida. Deve ser um endereço URL e deve ser .jpg
ou .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
Você pode definir os metadados em XAML ou code-behind. Se você estiver definindo-o em code-behind, você precisa definir o código-fonte no code-behind. A fonte deve ser definida em último lugar. Se você definir os metadados em XAML ou no construtor, esta nota poderá ser ignorada com segurança.
Reproduzir multimédia local
Os conteúdos locais podem ser reproduzidos a partir das seguintes fontes:
- Um recurso incorporado no aplicativo da plataforma, usando o esquema de URI
embed://
. - Arquivos provenientes do sistema de arquivos local do aplicativo, usando o esquema de URI
filesystem://
.
Observação
A abreviatura embed://
e filesystem://
funcionam apenas a partir de XAML. Em código, use MediaSource.FromResource()
e MediaSource.FromFile()
, respectivamente. Usando esses métodos, você pode omitir os prefixos embed://
e filesystem://
. O resto do caminho deve ser o mesmo.
Reproduzir multimédia incorporada no pacote da aplicação
Um MediaElement
pode reproduzir arquivos de mídia incorporados no pacote do aplicativo, usando o esquema de URI embed://
. Os arquivos de mídia são incorporados no pacote do aplicativo, colocando-os no projeto da plataforma.
Para habilitar um arquivo de mídia para reprodução dos recursos locais, adicione o arquivo à pasta Resources/Raw
do seu projeto .NET MAUI. Quando um arquivo é adicionado na raiz, o URI seria embed://MyFile.mp4
.
Você também pode colocar arquivos em subpastas. Se MyFile.mp4
estivesse em Resources/Raw/MyVideos
então o URI para usá-lo com MediaElement
seria embed://MyVideos/MyFile.mp4
.
Um exemplo de como usar essa sintaxe em XAML pode ser visto abaixo.
<toolkit:MediaElement Source="embed://MyFile.mp4"
ShouldShowPlaybackControls="True" />
Compreender os tipos de MediaSource
Um MediaElement
pode reproduzir mídia definindo sua propriedade Source
como um arquivo de mídia remoto ou local. A propriedade Source
é do tipo MediaSource
, e essa classe define três métodos estáticos:
-
FromFile
, retorna uma instânciaFileMediaSource
de um argumentostring
. -
FromUri
, retorna uma instânciaUriMediaSource
de um argumentoUri
. -
FromResource
, retorna uma instânciaResourceMediaSource
de um argumentostring
.
Além disso, a classe MediaSource
também tem operadores implícitos que retornam instâncias MediaSource
a partir de argumentos string
e Uri
.
Observação
Quando a propriedade Source
é definida em XAML, um conversor de tipo é invocado para retornar uma instância MediaSource
de um string
ou Uri
.
A classe MediaSource
também tem estas classes derivadas:
-
FileMediaSource
, que é usado para especificar um arquivo de mídia local de umstring
. Esta classe tem uma propriedadePath
que pode ser definida como umstring
. Além disso, essa classe tem operadores implícitos para converter umstring
em um objetoFileMediaSource
e um objetoFileMediaSource
em umstring
. -
UriMediaSource
, que é usado para especificar um ficheiro de mídia remoto a partir de um URI. Esta classe tem uma propriedadeUri
que pode ser definida como umUri
. -
ResourceMediaSource
, que é usado para especificar um arquivo incorporado que é fornecido por meio dos arquivos de recursos do aplicativo. Esta classe tem uma propriedadePath
que pode ser definida como umstring
.
Observação
Quando um objeto FileMediaSource
é criado em XAML, um conversor de tipo é invocado para retornar uma instância FileMediaSource
de um string
.
Alterar a proporção do vídeo
A propriedade Aspect
determina como a mídia de vídeo será dimensionada para se ajustar à área de exibição. Por padrão, essa propriedade é definida como o membro de enumeração AspectFit
, mas pode ser definida como qualquer um dos membros de enumeração Aspect
:
-
AspectFit
indica que o vídeo será colocado em caixa de correio, se necessário, para caber na área de exibição, preservando a proporção. -
AspectFill
indica que o vídeo será cortado para preencher a área de exibição, preservando a proporção. -
Fill
indica que o vídeo será esticado para preencher a área de exibição.
Determinar o status MediaElement
A classe MediaElement
define uma propriedade vinculável somente leitura chamada CurrentState
, do tipo MediaElementState
. Essa propriedade indica o status atual do controle, como se a mídia está sendo reproduzida ou pausada, ou se ainda não está pronta para reproduzir a mídia.
A enumeração MediaElementState
define os seguintes membros:
-
None
indica que oMediaElement
não contém mídia. -
Opening
indica que oMediaElement
está validando e tentando carregar a fonte especificada. -
Buffering
indica que oMediaElement
está a carregar os conteúdos multimédia para reprodução. Sua propriedadePosition
não avança durante este estado. Se oMediaElement
estava reproduzindo vídeo, ele continua a exibir o último quadro exibido. -
Playing
indica que oMediaElement
está reproduzindo a fonte de mídia. -
Paused
indica que oMediaElement
não avança a sua propriedadePosition
. Se oMediaElement
estava a reproduzir vídeo, continua a apresentar a moldura atual. -
Stopped
indica que oMediaElement
contém mídia, mas não está sendo reproduzido ou pausado. Sua propriedadePosition
é redefinida para 0 e não avança. -
Failed
indica que oMediaElement
falhou ao carregar ou reproduzir a mídia. Isso pode ocorrer ao tentar carregar um novo item de mídia, ao tentar reproduzir o item de mídia ou quando a reprodução de mídia é interrompida devido a uma falha. Use o eventoMediaFailed
para recuperar detalhes adicionais.
Geralmente, não é necessário examinar a propriedade CurrentState
ao usar os controles de transporte MediaElement
. No entanto, essa propriedade torna-se importante ao implementar seus próprios controles de transporte.
Implementar controles de transporte personalizados
Os controles de transporte de um media player incluem os botões que executam as funções Reproduzir, Pausare Parar. Esses botões geralmente são identificados com ícones familiares em vez de texto, e as funções Play e Pause geralmente são combinadas em um botão.
Por padrão, os controles de reprodução MediaElement
estão desativados. Isso permite que você controle o MediaElement
programaticamente ou fornecendo seus próprios controles de transporte. Em apoio a isso, MediaElement
inclui métodos Play
, Pause
e Stop
.
O exemplo XAML a seguir mostra uma página que contém um MediaElement
e 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>
Neste exemplo, os controles de transporte personalizados são definidos como objetos Button
. No entanto, existem apenas dois objetos Button
, com o primeiro Button
representando Play e Pause, e o segundo Button
representando Stop.
DataTrigger
objetos são usados para ativar e desativar os botões e para alternar o primeiro botão entre Play e Pause. Para obter mais informações sobre gatilhos de dados, consulte .NET MAUI Triggers.
O arquivo code-behind tem os manipuladores para os eventos Clicked
:
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();
}
O botão Play pode ser pressionado, assim que estiver ativado, para iniciar a reprodução. Pressionar o botão Pausar resulta em pausa na reprodução. Pressionar o botão Parar interrompe a reprodução e retorna a posição do arquivo de mídia para o início.
Implementar um controle de volume personalizado
Os controles de reprodução de mídia implementados por cada plataforma incluem uma barra de volume. Esta barra se assemelha a um controle deslizante e mostra o volume da mídia. Além disso, você pode manipular a barra de volume para aumentar ou diminuir o volume.
Uma barra de volume personalizada pode ser implementada usando um Slider
, conforme mostrado no exemplo a seguir:
<StackLayout>
<toolkit:MediaElement ShouldAutoPlay="False"
Source="{StaticResource AdvancedAsync}" />
<Slider Maximum="1.0"
Minimum="0.0"
Value="{Binding Volume}"
Rotation="270"
WidthRequest="100" />
</StackLayout>
Neste exemplo, os dados Slider
vinculam sua propriedade Value
à propriedade Volume
do MediaElement
. Isso é possível porque a propriedade Volume
usa uma ligação TwoWay
. Portanto, alterar a propriedade Value
resultará na alteração da propriedade Volume
.
Observação
A propriedade Volume
tem um retorno de chamada de validação que garante que seu valor seja maior ou igual a 0,0 e menor ou igual a 1,0.
Para obter mais informações sobre como usar um Slider
consulte .NET MAUI Slider
Limpar os recursos MediaElement
Para evitar vazamentos de memória você terá que liberar os recursos de MediaElement
. Isso pode ser feito desconectando o manipulador.
Onde você precisa fazer isso depende de onde e como você usa MediaElement
em seu aplicativo, mas normalmente se você tiver um MediaElement
em uma única página e não estiver reproduzindo mídia em segundo plano, você deseja liberar os recursos quando o usuário navega para fora da página.
Abaixo você pode encontrar um trecho de código de exemplo que mostra como fazer isso. Primeiro, certifique-se de conectar o evento Unloaded
na sua página.
<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.FreeResourcesPage"
Title="Free Resources"
Unloaded="ContentPage_Unloaded">
<toolkit:MediaElement x:Name="mediaElement"
ShouldAutoPlay="False"
... />
</ContentPage>
Em seguida, no código subjacente, chame o método para desconectar o manipulador.
public partial class FreeResourcesPage : ContentPage
{
void ContentPage_Unloaded(object? sender, EventArgs e)
{
// Stop and cleanup MediaElement when we navigate away
mediaElement.Handler?.DisconnectHandler();
}
}
Para ler mais sobre manipuladores, consulte a documentação do .NET MAUI em Handlers.
Propriedades
Propriedade | Tipo | Descrição | Valor padrão |
---|---|---|---|
Aspeto | Aspeto | Determina o modo de dimensionamento para a mídia (visual) que está carregada no momento. Esta é uma propriedade vinculável. | Aspect.AspectFit |
Estado Atual | MediaElementState |
Indica o status atual do controle. Esta é uma propriedade somente leitura e vinculável. | MediaElementState.None |
Duração | TimeSpan |
Indica a duração da mídia aberta no momento. Esta é uma propriedade somente leitura e vinculável. | TimeSpan.Zero |
Posição | TimeSpan |
Descreve o progresso atual através do tempo de reprodução da mídia. Esta é uma propriedade apenas de leitura e vinculável. Se você quiser definir o Position use o método SeekTo() . |
TimeSpan.Zero |
DeveReproduzirAutomaticamente | bool |
Indica se a reprodução de mídia começará automaticamente quando a propriedade Source estiver definida. Esta é uma propriedade vinculável. |
false |
ShouldLoopPlayback | bool |
Descreve se a fonte de mídia carregada atualmente deve retomar a reprodução desde o início depois de chegar ao seu fim. Esta é uma propriedade vinculável. | false |
DeveManterEcrãLigado | bool |
Determina se a tela do dispositivo deve permanecer ligada durante a reprodução de mídia. Esta é uma propriedade vinculável. | false |
ShouldMute | bool |
Determina se o áudio está silenciado no momento. Esta é uma propriedade vinculável. | false |
DeveMostrarControlesDeReprodução | bool |
Determina se os controles de reprodução da plataforma estão visíveis. Esta é uma propriedade vinculável. Observe que no iOS e no Windows os controles são mostrados apenas por um breve período após a interação com a tela. Não há como manter os controles visíveis em todos os momentos. | true |
Fonte | MediaSource? |
A fonte da mídia carregada no controle. | null |
Velocidade | double |
Determina a velocidade de reprodução do media. Esta é uma propriedade vinculável | 1 |
MediaHeight | int |
A altura da mídia carregada em pixels. Esta é uma propriedade somente leitura e vinculável. Não relatado para mídia não visual e nem sempre pode ser preenchido no iOS/macOS para conteúdo transmitido ao vivo. | 0 |
Largura de Mídia | int |
A largura da mídia carregada em pixels. Esta é uma propriedade somente leitura e passível de vinculação. Não reportado para meios não visuais e poderá não ser sempre preenchido no iOS/macOS para conteúdo transmitido em direto. | 0 |
Volume | double |
Determina o volume da mídia, que é representada em uma escala linear entre 0 e 1. Esta é uma propriedade vinculável. | 1 |
Eventos
Evento | Descrição |
---|---|
Mídia Aberta | Ocorre quando o fluxo de mídia foi validado e aberto. |
MediaEnded | Ocorre quando o MediaElement termina de reproduzir sua mídia. |
MediaFailed | Ocorre quando há um erro associado à fonte de mídia. |
PosiçãoAlterada | Ocorre quando o valor da propriedade Position foi alterado. |
Busca Concluída | Ocorre quando o ponto de procura de uma operação de procura solicitada está pronto para reprodução. |
Metodologia
Evento | Descrição |
---|---|
Reproduzir | Começa a reproduzir a mídia carregada. |
Pausa | Pausa a reprodução do conteúdo atual. |
Parar | Interrompe a reprodução e redefine a posição da mídia atual. |
Procurar: | Utiliza um valor TimeSpan para definir a propriedade Position e requer um CancellationToken para cancelar o Task . |
Exemplos
Você pode encontrar exemplos desse controle em ação no .NET MAUI Community Toolkit Sample Application.
API
Você pode encontrar o código-fonte para MediaElement
no repositório GitHub do .NET MAUI Community Toolkit.
Ligações úteis
.NET MAUI Community Toolkit