Поделиться через

MediaElement

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

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

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

Снимок экрана: MediaElement для воспроизведения видео в Android и iOS.

Примечание.

MediaElement доступна в iOS, Android, Windows, macOS и Tizen.

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

Платформа Реализация медиаплеера платформы
Андроид ExoPlayer, большое спасибо библиотекам Android поддержки!
iOS и macOS AVPlayer
Виндоус MediaPlayer

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

Чтобы использовать функцию 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 функциям требуется следующая настройка для конкретной платформы.

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

1. Добавьте ResizableActivity и Launchmode в действие

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

Для полного примера данного метода, включенного в приложение, просмотрите пример приложения .NET MAUI Community Toolkit.

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

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

Платформа Ссылка Примечания.
Андроид Поддерживаемые форматы ExoPlayer
iOS и macOS Поддерживаемые форматы iOS и macOS Нет официальной документации по этой статье
Виндоус Поддерживаемые форматы Windows В Windows поддерживаемые форматы очень зависят от того, какие кодеки установлены на компьютере пользователя
Tizen Поддерживаемые форматы Tizen

Внимание

Если пользователь использует выпуск Windows N, воспроизведение видео по умолчанию не поддерживается. Выпуски Windows N не имеют форматов воспроизведения видео, установленных по дизайну.

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

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

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

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

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

Внимание

При воспроизведении удаленных источников из конечных точек HTTP, скорее всего, потребуется отключить меры безопасности операционной системы, которые препятствуют доступу к небезопасным веб-конечным точкам. Это верно по крайней мере для iOS и Android.

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

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

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

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

Внимание

Метаданные можно задать либо в XAML, либо в файле кода. Если вы устанавливаете это в коде за кулисами, вам нужно установить источник данных также в коде за кулисами. Источник должен быть задан последним. Если вы задаете метаданные в XAML или конструкторе, это примечание можно безопасно игнорировать.

Использование TextureView

На платформе Android можно использовать MediaElement с помощью TextureView. Поведение платформы по умолчанию — использовать SurfaceView. Использование представления текстур добавляет поддержку для обеспечения прозрачности и других эффектов. Настройка осуществляется путем изменения построителя для использования функций

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

Вы также можете задать TextureView для каждого используемого элемента мультимедиа. Его можно задать в XAML и в фоновом коде. С помощью этого метода переопределится команда .UseMauiCommunityToolkitMediaElement()построителя.

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

<toolkit:MediaElement AndroidViewType="TextureView" />

Внимание

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

Воспроизведение локальных медиа

Локальные медиа могут воспроизводиться из следующих источников.

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

Примечание.

Сокращения embed:// и filesystem:// работают только из XAML. В коде используйте MediaSource.FromResource() и MediaSource.FromFile() соответственно. С помощью этих методов можно опустить embed:// префиксы и filesystem:// префиксы. Оставшаяся часть пути должна совпадать.

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

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

Чтобы включить воспроизведение файла мультимедиа из локальных ресурсов, добавьте файл в папку 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 аргументов.

Примечание.

При установке свойства Source в XAML вызывается преобразователь типов для возврата экземпляра MediaSource из string или Uri.

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

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

Примечание.

При создании FileMediaSource объекта в XAML вызывается конкретный преобразователь типов для возврата экземпляра FileMediaSource из 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 включает Play, Pause и 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 свойства.

Примечание.

Свойство Volume имеет обратный вызов проверки, который гарантирует, что его значение больше или равно 0,0 и меньше или равно 1,0.

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

Свойства

Свойство Тип Описание Значение по умолчанию
Аспект Аспект Определяет режим масштабирования для загруженного (визуального) носителя. Это свойство может быть привязано. Aspect.AspectFit
ТекущееСостояние MediaElementState Указывает текущее состояние элемента управления. Это свойство только для чтения, привязываемое свойство. MediaElementState.None
Продолжительность TimeSpan Указывает длительность текущего открытого носителя. Это свойство только для чтения, привязываемое свойство. TimeSpan.Zero
Должность TimeSpan Описывает текущий прогресс во времени воспроизведения медиа. Это свойство только для чтения, привязываемое свойство. Если вы хотите задать Position, используйте метод SeekTo(). TimeSpan.Zero
Параметр ShouldAutoPlay bool Указывает, начнется ли воспроизведение мультимедиа автоматически при условии установки свойства Source. Это свойство может быть привязано. false
ShouldLoopPlayback bool Описывает, должен ли загруженный медиа-источник возобновить воспроизведение с начала после достижения конца. Это свойство может быть привязано. false
ДолженДержатьЭкранВключённым bool Определяет, должен ли экран устройства оставаться на экране во время воспроизведения мультимедиа. Это свойство может быть привязано. false
ДолженОтключитьЗвук bool Определяет, отключен ли звук в данный момент. Это свойство может быть привязано. false
ДолженПоказыватьЭлементыУправленияВоспроизведением bool Определяет, отображаются ли элементы управления воспроизведением платформы. Это свойство может быть привязано. Обратите внимание, что в iOS и Windows элементы управления отображаются только в течение короткого периода после взаимодействия с экраном. Не существует способа постоянного отображения элементов управления. true
Источник MediaSource? Источник мультимедийного контента, загружаемого в элемент управления. null
Скорость double Определяет скорость воспроизведения мультимедиа. Это привязываемое свойство 1
MediaHeight int Высота загруженного носителя в пикселях. Это свойство только для чтения, привязываемое свойство. Не сообщается для не визуальных медиа и может не всегда отображаться на iOS/macOS для потокового видео. 0
Ширина медиа int Ширина загруженного носителя в пикселях. Это свойство только для чтения, привязываемое свойство. Не сообщается для не визуальных медиа и может не всегда отображаться на iOS/macOS для потокового видео. 0
Громкость double Определяет громкость носителя, которая измеряется по линейной шкале от 0 до 1. Это свойство может быть привязано. 1

События

Мероприятие Описание
MediaOpened Происходит после проверки и открытия мультимедийного потока.
MediaEnded; Происходит, когда MediaElement завершает воспроизведение своего медиа.
MediaFailed; Возникает при возникновении ошибки, связанной с источником мультимедиа.
ИзменениеПозиции Происходит, если значение свойства Position было изменено.
ЗавершёнПоиск Происходит, когда точка поиска запрошенной операции поиска готова к воспроизведению.

Методы

Мероприятие Описание
Воспроизвести Запускает воспроизведение загруженного медиа.
Пауза Приостанавливает воспроизведение текущего медиафайла.
Стоп Останавливает воспроизведение и сбрасывает положение текущего носителя.
SeekTo Принимает значение TimeSpan, чтобы установить свойство Position, и значение CancellationToken, чтобы отменить Task.

Примеры

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

API (Интерфейс программирования приложений)

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