MediaElement

MediaElement — это элемент управления для воспроизведения видео и звука. Носители, поддерживаемые базовой платформой, можно воспроизводить из следующих источников:

• Веб-сайт с помощью URI (HTTP или HTTPS).
• Ресурс, внедренный в приложение платформы, с помощью embed:// схемы URI.
• Файлы, поступающие из локальной файловой системы приложения, с помощью filesystem:// схемы URI.

MediaElement можно использовать элементы управления воспроизведением платформы, которые называются элементами управления транспортировкой. Однако они отключены по умолчанию и могут быть заменены собственными элементами управления транспортом. На следующих снимках экрана показан MediaElement воспроизведение видео с помощью элементов управления транспортировкой платформы:

Использует MediaElement следующие реализации платформы.

Начало работы

Чтобы использовать функцию MediaElement набора средств сообщества .NET MAUI, необходимо выполнить следующие действия.

Установка пакета NuGet

Прежде чем вы сможете использовать MediaElement внутри приложения, необходимо установить CommunityToolkit.Maui.MediaElement пакет NuGet и добавить строку инициализации в MauiProgram.cs. Следующим образом:

Имя пакета: CommunityToolkit.Maui.MediaElement

URL-адрес пакета:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

Инициализация пакета

Сначала необходимо добавить инструкцию using в начало файла MauiProgram.cs

using CommunityToolkit.Maui.MediaElement;

Чтобы правильно использовать MediaElement метод, необходимо вызвать в UseMauiCommunityToolkitMediaElement классе при загрузке приложения MauiAppBuilder MauiProgram.cs-файл. В следующем примере показано, как это сделать.

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

Дополнительные сведения о том, как это сделать, см. на странице "Начало работы ".

Инициализация конкретной платформы

Для доступа к MediaElement функциям требуется следующая настройка для конкретной платформы.

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

 <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>

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>

<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" />

<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"/>

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>audio</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string></string>

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Поддерживаемые форматы

Поддерживаемые мультимедийные форматы могут отличаться на каждую платформу. В некоторых случаях это может даже зависеть от того, какие декодеры доступны или установлены в операционной системе, которая используется при запуске приложения. Дополнительные сведения о том, какие форматы поддерживаются на каждой платформе, см. в приведенных ниже ссылках.

Распространенные сценарии

В следующих разделах рассматриваются распространенные сценарии использования.MediaElement

Воспроизведение удаленного носителя

Можно MediaElement воспроизводить удаленные файлы мультимедиа с помощью схем URI HTTP и HTTPS. Для этого необходимо задать для свойства универсальный Source код ресурса (URI) файла мультимедиа:

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

По умолчанию носитель, определенный свойством Source , не сразу начинает воспроизводиться после открытия носителя. Чтобы включить автоматическое воспроизведение мультимедиа, задайте ShouldAutoPlay для trueсвойства значение .

Предоставленные платформой элементы управления воспроизведением мультимедиа включены по умолчанию и могут быть отключены, задав ShouldShowPlaybackControls для свойства значение false.

Использование метаданных

Можно MediaElement использовать метаданные для MediaElement.MetadataTitle, MediaElement.MetadataArtist а также MediaElement.MetadataArtworkUrl. Вы можете задать название или художник, чтобы показать, что в настоящее время играет на элементах управления блокировки для Windows, Mac Catalyst, iOS и Android. Вы можете задать локальный или удаленный URL-адрес с рисунками для экрана блокировки. Оно должно быть не менее 1080P, чтобы лучшее качество отображалось. Это должен быть URL-адрес и быть либо .jpg или .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";

Воспроизведение локального носителя

Локальный носитель можно воспроизводить из следующих источников:

• Ресурс, внедренный в приложение платформы, с помощью embed:// схемы URI.
• Файлы, поступающие из локальной файловой системы приложения, с помощью filesystem:// схемы URI.

Воспроизведение мультимедиа, внедренного в пакет приложения

Файл MediaElement мультимедиа, внедренный в пакет приложения, может воспроизводиться с помощью embed:// схемы URI. Файлы мультимедиа внедряются в пакет приложения, помещая их в проект платформы.

Чтобы включить воспроизведение файла мультимедиа из локальных ресурсов, добавьте файл в папку Resources/Raw проекта .NET MAUI. При добавлении файла в корневой каталог URI будет embed://MyFile.mp4.

Вы также можете поместить файлы в вложенные папки. Если MyFile.mp4 бы он был в Resources/Raw/MyVideos этом случае, универсальный код ресурса (URI), с MediaElement которым он будет использоваться, будет embed://MyVideos/MyFile.mp4.

Ниже приведен пример использования этого синтаксиса в XAML.

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

Общие сведения о типах MediaSource

Носитель MediaElement может воспроизводиться, задав его Source свойство удаленному или локальному файлу мультимедиа. Свойство имеет типSource, и этот MediaSource класс определяет три статических метода:

• FromFile, возвращает FileMediaSource экземпляр из аргумента string .
• FromUri, возвращает UriMediaSource экземпляр из аргумента Uri .
• FromResource, возвращает ResourceMediaSource экземпляр из аргумента string .

Кроме того, класс MediaSource также имеет неявные операторы, возвращающие MediaSource экземпляры из string и Uri аргументов.

Класс также имеет следующие производные MediaSource классы:

• FileMediaSource, который используется для указания локального stringфайла мультимедиа из . Этот класс имеет Path свойство, которое можно задать stringдля параметра . Кроме того, этот класс имеет неявные операторы для преобразования stringFileMediaSource объекта в объект и FileMediaSource объекта в stringобъект.
• UriMediaSource, который используется для указания удаленного файла мультимедиа из URI. Этот класс имеет Uri свойство, которое можно задать Uriдля параметра .
• ResourceMediaSource— используется для указания внедренного файла, предоставленного с помощью файлов ресурсов приложения. Этот класс имеет Path свойство, которое можно задать stringдля параметра .

Изменение пропорций видео

Свойство Aspect определяет, как будет масштабироваться видеомедий, чтобы соответствовать области отображения. По умолчанию это свойство присваивается элементу AspectFit перечисления, но его можно задать любому из Aspect элементов перечисления:

• AspectFit указывает, что видео будет отформатировано( при необходимости), чтобы поместиться в область отображения, сохраняя пропорции.
• AspectFill указывает, что видео будет обрезано таким образом, чтобы оно заполняло область отображения, сохраняя пропорции.
• Fill указывает, что видео будет растянуто для заполнения области отображения.

Определение MediaElement состояния

Класс MediaElement определяет привязываемое свойство только для чтения с именем CurrentStateтипа MediaElementState. Это свойство указывает текущее состояние элемента управления, например воспроизведение или приостановка носителя, или если оно еще не готово к воспроизведению мультимедиа.

Перечисление MediaElementState определяет следующие члены:

• None указывает, что не MediaElement содержит носителя.
• Opening указывает, что MediaElement проверка и попытка загрузить указанный источник.
• Buffering указывает, что MediaElement носитель загружается для воспроизведения. Его Position свойство не выполняется во время этого состояния. MediaElement Если видео воспроизводилось, он продолжает отображать последний отображаемый кадр.
• Playing указывает, что MediaElement воспроизведение источника мультимедиа.
• Paused указывает, что MediaElement свойство Position не перемещается. MediaElement Если видео воспроизводилось, он продолжает отображать текущий кадр.
• Stopped указывает, что MediaElement содержит носитель, но он не воспроизводится или не приостановлен. Его Position свойство сбрасывается до 0 и не выполняется заранее.
• Failed указывает, что MediaElement не удалось загрузить или воспроизвести носитель. Это может произойти при попытке загрузить новый элемент мультимедиа, при попытке воспроизведения элемента мультимедиа или при прерывании воспроизведения мультимедиа из-за сбоя. Используйте событие для получения дополнительных сведений MediaFailed .

Обычно при использовании CurrentState элементов управления транспортом не требуется проверять MediaElement свойство. Однако это свойство становится важным при реализации собственных элементов управления транспортировкой.

Реализация пользовательских элементов управления транспортировкой

Элементы управления транспортом проигрывателя мультимедиа включают кнопки, выполняющие функции воспроизведения, приостановки и остановки. Эти кнопки обычно определяются по знакомым значкам, а не тексту. Как правило, функции Воспроизведение и Пауза объединены в одну кнопку.

По умолчанию MediaElement элементы управления воспроизведением отключены. Это позволяет управлять MediaElement программными средствами или предоставлять собственные элементы управления транспортом. В поддержку этого, MediaElement включают PlayPauseи Stop методы.

В следующем примере XAML показана страница, содержащая элементы управления транспортом MediaElement и настраиваемые элементы управления транспортировкой:

<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>

В этом примере пользовательские элементы управления транспортом определяются как Button объекты. Однако существует только два Button объекта, причем первый Button представляет воспроизведение и паузу, а второй Button — stop. DataTrigger Объекты используются для включения и отключения кнопок, а также для переключения первой кнопки между воспроизведением и приостановкой. Дополнительные сведения об триггерах данных см. в статье .NET MAUI Triggers.

В файле кода программной части есть обработчики событий 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();
}

Кнопка воспроизведения может быть нажата, когда она станет включена, чтобы начать воспроизведение. Нажатие кнопки "Пауза" приводит к приостановке воспроизведения. Нажатие кнопки "Остановить " останавливает воспроизведение и возвращает положение файла мультимедиа в начало.

Реализация пользовательского элемента управления томом

Элементы управления воспроизведением мультимедиа, реализованные каждой платформой, включают панель томов. Эта панель похожа на ползунок и показывает объем носителя. Кроме того, можно управлять панелью томов, чтобы увеличить или уменьшить объем.

Пользовательская панель томов может быть реализована с помощью следующего Sliderпримера:

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

В этом примере Slider данные привязывают его Value свойство к Volume свойству объекта MediaElement. Это возможно, так как Volume свойство использует привязку TwoWay . Поэтому изменение Value свойства приведет к изменению Volume свойства.

Дополнительные сведения об использовании Sliderползунка .NET MAUI

Очистка MediaElement ресурсов

Чтобы предотвратить утечку памяти, вам придется освободить ресурсы MediaElement. Это можно сделать, отключив обработчик. Где это необходимо сделать, зависит от того, где и как вы используете MediaElement в приложении, но обычно, если у вас есть MediaElement на одной странице и не воспроизводится мультимедиа в фоновом режиме, вы хотите освободить ресурсы, когда пользователь переходит от страницы.

Ниже приведен фрагмент примера кода, в котором показано, как это сделать. Во-первых, обязательно подключите Unloaded событие на странице.

<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>

Затем в коде в программной части вызовите метод для отключения обработчика.

public partial class FreeResourcesPage : ContentPage
{
    void ContentPage_Unloaded(object? sender, EventArgs e)
    {
        // Stop and cleanup MediaElement when we navigate away
        mediaElement.Handler?.DisconnectHandler();
    }
}

Дополнительные сведения о обработчиках см. в документации по .NET MAUI для обработчиков.

Свойства

События

Методы

Примеры

Примеры этого элемента управления можно найти в действии в примере приложения .NET MAUI Community Toolkit.

API

Исходный код MediaElementможно найти в репозитории .NET MAUI Community Toolkit GitHub.

Дополнительные ссылки

• Триггеры .NET MAUI
• Ползунок .NET MAUI
• Android ExoPlayer: поддерживаемые форматы мультимедиа
• iOS: поддерживаемые форматы мультимедиа
• Windows: поддерживаемые кодеки
• Привязки ExoPlayer для Android