MediaElement

MediaElement は、ビデオとオーディオを再生するためのコントロールです。 基になるプラットフォームでサポートされているメディアは、次のソースから再生できます:

• URI (HTTP または HTTPS) を使用する Web。
• embed:// URI スキームを使用して、プラットフォーム アプリケーションに埋め込まれたリソース。
• filesystem:// URI スキームを使用して、アプリのローカル ファイルシステムから取得されたファイル。

MediaElement は、プラットフォーム再生コントロール (トランスポート コントロールと呼ばれます) を使用できます。 ただし、既定では無効になっており、独自のトランスポート コントロールに置き換えることができます。 次のスクリーンショットは、プラットフォーム トランスポート コントロールでビデオを再生している MediaElement を示しています:

Note

MediaElement は、iOS、Android、Windows、macOS、Tizen で使用できます。

MediaElement では、次のプラットフォーム実装を使用します。

プラットフォーム	プラットフォーム メディア プレーヤーの実装
Android	ExoPlayer、ExoPlayerXamarin メンテナーに感謝!
iOS/macOS	AVPlayer
Windows	MediaPlayer

作業の開始

.NET MAUI Community Toolkit の MediaElement 機能を使用するには、次の手順が必要です。

NuGet パッケージのインストール

アプリケーション内で MediaElement を使用するには、CommunityToolkit.Maui.MediaElement NuGet パッケージをインストールし、MauiProgram.cs に初期化行を追加する必要があります。 次に例を示します:

パッケージ名:CommunityToolkit.Maui.MediaElement

パッケージ URL:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

パッケージを初期化しています

まず、ステートメントの使用を MauiProgram.cs ファイルの先頭に追加する必要があります

using CommunityToolkit.Maui.MediaElement;

MediaElement を正しく使用するには、MauiProgram.cs ファイルをアプリケーションにブートストラップするときに、MauiAppBuilder クラスで UseMauiCommunityToolkitMediaElement メソッドを呼び出す必要があります。 次の例は、これを実行する方法を示します。

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

これを行う方法の詳細については、「作業の開始」ページを参照してください。

プラットフォーム固有の初期化

MediaElement 機能にアクセスするには、次のプラットフォーム固有の設定が必要です。

Android

MediaElement を使うときは、次の手順を実行する必要があります。

1. アクティビティに ResizableActivity と Launchmode を追加します

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

2. AndroidManifest.xml の <application> タグ内に次のコードを追加します。

 <service android:name="CommunityToolkit.Maui.Media.Services" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
   <intent-filter>
     <action android:name="android.intent.action.MEDIA_BUTTON" />
   </intent-filter>
   <intent-filter>
     <action android:name="androidx.media3.session.MediaSessionService"/>
   </intent-filter>
 </service>

3. 次のアクセス許可を 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" />

AndroidManifest.xml で必要な設定の例を次に示します

<application android:allowBackup="true" android:icon="@mipmap/appicon" android:enableOnBackInvokedCallback="true" android:supportsRtl="true">
<service android:name="CommunityToolkit.Maui.Media.Services" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
    <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
    <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" />

Note

Android マニフェストをこのように変更すると、ビデオの再生時にメタデータが表示されます。 これは、通知のサポートを提供し、関連するすべての API で通知が機能するために不可欠です。 この変更により、サービスが導入され、必要なアクセス許可が付与されます。

アプリケーションに含まれるこのメソッドの完全な例については、.NET MAUI Community Toolkit サンプル アプリケーションのを参照してください

Mac Catalyst

MacCatalyst の Info.plist を編集し、次のキーを追加します。

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

iOS

iOS の Info.plist を編集し、次のキーを追加します。

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

Windows

セットアップは必要ありません。

Tizen

セットアップは必要ありません。

サポートされる形式

サポートされているマルチメディア形式は、プラットフォームごとに異なる場合があります。 場合によっては、アプリの実行中に使用されるオペレーティング システムで使用できるデコーダーやインストールされているデコーダーに依存する場合もあります。 各プラットフォームでサポートされている形式の詳細については、以下のリンクを参照してください。

プラットフォーム	リンク	メモ
Android	ExoPlayer でサポートされている形式
iOS/macOS	iOS/macOS でサポートされる形式	これに関する公式ドキュメントは存在しません
Windows	Windows でサポートされている形式	Windows では、サポートされている形式は、ユーザーのコンピューターにインストールされているコーデックに大きく依存します
Tizen	Tizen でサポートされている形式

重要

ユーザーが Windows N エディションを使用している場合、既定ではビデオ再生はサポートされません。 Windows N エディションには、設計によってインストールされたビデオ再生形式はありません。

一般的なシナリオ

次のセクションでは、MediaElementの一般的な使用シナリオについて説明します。

リモート メディアの再生

MediaElement は、HTTP および HTTPS URI スキームを使用してリモート メディア ファイルを再生できます。 これを行うには、Source プロパティをメディア ファイルの URI に設定します:

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

重要

HTTP エンドポイントからリモート ソースを再生する場合は、セキュリティで保護されていない Web エンドポイントへのアクセスを妨げるオペレーティング システムのセキュリティ対策を無効にする必要がある可能性があります。 これは、少なくとも iOS と Android に当てはまります。

既定では、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"
    MetasataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg" />

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

重要

メタデータは、XAML またはコードビハインドで設定できます。 コードビハインドで設定する場合は、コードビハインドでソースを設定する必要があります。 ソースは最後に設定する必要があります。 XAML またはコンストラクターでメタデータを設定する場合は、この注を無視しても問題ありません。

ローカル メディアの再生

ローカル メディアは、次のソースから再生できます:

• embed:// URI スキームを使用して、プラットフォーム アプリケーションに埋め込まれたリソース。
• filesystem:// URI スキームを使用して、アプリのローカル ファイルシステムから取得されたファイル。

Note

短縮形の embed:// と filesystem:// は XAML からのみ機能します。 コードでは、それぞれ MediaSource.FromResource() と MediaSource.FromFile() を使用してください。 これらのメソッドを使用すると、embed:// プレフィックスと filesystem:// プレフィックスを省略できます。 残りのパスは同じである必要があります。

アプリ パッケージに埋め込まれたメディアを再生する

MediaElement は、embed:// URI スキームを使用して、アプリ パッケージに埋め込まれているメディア ファイルを再生できます。 メディア ファイルは、プラットフォーム プロジェクトに配置することでアプリ パッケージに埋め込まれます。

ローカル リソースから再生するメディア ファイルを有効にするには、.NET MAUI プロジェクトの Resources/Raw フォルダーにファイルを追加します。 ルートにファイルを追加すると、URI は embed://MyFile.mp4　になります。

サブフォルダーにファイルを配置することもできます。 MyFile.mp4 が Resources/Raw/MyVideos 内にある場合は、MediaElement と共にそれを使用する URI は embed://MyVideos/MyFile.mp4 になります。

XAML でこの構文を使用する方法の例を次に示します。

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

MediaSource の種類について

MediaElement は、その Source プロパティをリモート メディア ファイルまたはローカル メディア ファイルに設定することで、メディアを再生できます。 Source プロパティは MediaSource 型であり、このクラスは 3 つの静的メソッドを定義します:

• FromFile、string 引数から FileMediaSource インスタンスを返します。
• FromUri、Uri 引数から UriMediaSource インスタンスを返します。
• FromResource、string 引数から ResourceMediaSource インスタンスを返します。

さらに、MediaSource クラスには、string および Uri 引数から MediaSource インスタンスを返す暗黙的な演算子もあります。

Note

XAML で Source プロパティを設定すると、型コンバーターが呼び出され、string または Uri から MediaSource インスタンスが返されます。

MediaSource クラスには、次の派生クラスもあります:

• FileMediaSource、string からローカル メディア ファイルを指定するために使用されます。 このクラスには、string に設定できる Path プロパティがあります。 さらに、このクラスには、string を FileMediaSource オブジェクトに変換する暗黙的な演算子と、FileMediaSource オブジェクトを string に変換する暗黙的な演算子があります。
• UriMediaSource、URI からローカル メディア ファイルを指定するために使用されます。 このクラスには、Uri に設定できる Uri プロパティがあります。
• ResourceMediaSource、アプリのリソース ファイルを介して提供される埋め込みファイルを指定するために使用されます。 このクラスには、string に設定できる Path プロパティがあります。

Note

XAML で FileMediaSource オブジェクトが作成されると、型コンバーターが呼び出され、string から FileMediaSourceインスタンスが返されます。

ビデオの縦横比を変更する

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 イベントを使用して、追加の詳細を取得します。

一般に、MediaElement トランスポート コントロールを使用する場合、CurrentState プロパティを調べる必要はありません。 ただし、このプロパティは、独自のトランスポート コントロールを実装するときに重要になります。

カスタム トランスポート コントロールの実装

メディア プレーヤーのトランスポート コントロールには、再生、一時停止、および停止機能を実行するボタンが含まれています。 これらのボタンは一般的に、テキストではなく使い慣れたアイコンで識別されます。また、再生と一時停止機能は一般的に、1 つのボタンに結合されています。

既定では、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 オブジェクトは 2 つだけで、最初の Button は "再生" と "一時停止" を表し、2 番目の Button は "停止" を表します。 DataTrigger オブジェクトは、ボタンを有効または無効にしたり、 "再生" と "一時停止" の間で最初のボタンを切り替えるために使用されます。 データ トリガーの詳細については、「.NET MAUI トリガー」を参照してください。

分離コード ファイルには、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 プロパティを MediaElement の Volume プロパティにバインドします。 これは、Volume プロパティが TwoWay バインディングを使用するため可能です。 したがって、Value プロパティを変更すると、Volume プロパティが変更されます。

Note

Volume プロパティには検証コールバックがあり、その値が 0.0 以上 1.0 以下であることを確認します。

Slider の使用の詳細については、「.NET MAUI スライダー」を参照してください

MediaElement リソースをクリーンアップする

メモリ リークを防ぐには、MediaElement のリソースを解放する必要があります。 これを行うには、ハンドラーを切断します。 これを行う必要がある場所は、アプリで MediaElement を使用する場所と方法によって異なりますが、通常、1 つのページに 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 の文書を参照してください。

Properties

プロパティ	タイプ	説明	Default Value
側面	特徴	現在読み込まれている (ビジュアル) メディアのスケーリング モードを決定します。 これはバインド可能なプロパティです。	Aspect.AspectFit
CurrentState	MediaElementState	コントロールの現在の状態を示します。 これはバインド可能な読み取り専用プロパティです。	MediaElementState.None
Duration	TimeSpan	現在開いているメディアの期間を示します。 これはバインド可能な読み取り専用プロパティです。	TimeSpan.Zero
位置	TimeSpan	メディアの再生時間の現在の進行状況について説明します。 これはバインド可能な読み取り専用プロパティです。 Position を設定する場合は、SeekTo() メソッドを使用します。	TimeSpan.Zero
ShouldAutoPlay	bool	Source プロパティが設定されているときにメディアの再生を自動的に開始するかどうかを示します。 これはバインド可能なプロパティです。	false
ShouldLoopPlayback	bool	現在読み込まれているメディア ソースが、最後に到達した後、最初から再生を再開する必要があるかどうかを説明します。 これはバインド可能なプロパティです。	false
ShouldKeepScreenOn	bool	メディアの再生中にデバイス画面をオンにするかどうかを決定します。 これはバインド可能なプロパティです。	false
ShouldMute	bool	オーディオが現在ミュートされているかどうかを決定します。 これはバインド可能なプロパティです。	false
ShouldShowPlaybackControls	bool	プラットフォームの再生コントロールを表示するかどうかを決定します。 これはバインド可能なプロパティです。 iOS と Windows では、コントロールは画面を操作した後、しばらくの間だけ表示されることに注意してください。 コントロールを常に表示する方法はありません。	true
ソース	MediaSource?	コントロールに読み込まれたメディアのソース。	null
速度	double	メディアの再生速度を決定します。 これはバインド可能なプロパティです	1
MediaHeight	int	読み込まれたメディアの高さ (ピクセル単位)。 これはバインド可能な読み取り専用プロパティです。	0
MediaWidth	int	読み込まれたメディアの幅 (ピクセル単位)。 これはバインド可能な読み取り専用プロパティです。	0
体積	double	0 から 1 の間の線形スケール上で表されるメディアのボリュームを決定します。 これはバインド可能なプロパティです。	1

Events

Event	説明
MediaOpened	メディア ストリームが検証されて開かれたときに発生します。
MediaEnded	MediaElement がメディアの再生を終了したときに発生します。
MediaFailed	メディア ソースに関連するエラーが発生したときに発生します。
PositionChanged	Position プロパティ値が変更されたときに発生します。
SeekCompleted	要求されたシーク操作のシーク ポイントが再生の準備ができたときに発生します。

メソッド

イベント	説明
Play	読み込まれたメディアの再生を開始します。
一時停止	現在のメディアの再生を一時停止します。
停止	再生を停止し、現在のメディアの位置をリセットします。
SeekTo	Position プロパティを設定する TimeSpan 値を受け取り、Task を取り消す CancellationToken を受け取ります。

例

このコントロールの動作例は、「.NET MAUI Community Toolkit サンプル アプリケーション」で確認できます。

API

MediaElement のソース コードは、.NET MAUI Community Toolkit の GitHub リポジトリにあります。

関連リンク

• .NET MAUI トリガー
• .NET MAUI スライダー
• Android ExoPlayer: サポートされているメディア形式
• iOS: サポートされているメディア形式
• Windows: サポートされているコーデック
• Android ExoPlayer バインド