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
機能にアクセスするには、次のプラットフォーム固有の設定が必要です。
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 サンプル アプリケーションのを参照してください
サポートされる形式
サポートされているマルチメディア形式は、プラットフォームごとに異なる場合があります。 場合によっては、アプリの実行中に使用されるオペレーティング システムで使用できるデコーダーやインストールされているデコーダーに依存する場合もあります。 各プラットフォームでサポートされている形式の詳細については、以下のリンクを参照してください。
プラットフォーム | リンク | メモ |
---|---|---|
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"
MetadataArtworkUrl="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 |
読み込まれたメディアの高さ (ピクセル単位)。 これはバインド可能な読み取り専用プロパティです。 非視覚的なメディアでは報告されず、iOS/macOS ではライブ ストリーミング コンテンツで常に設定されるとは限りません。 | 0 |
MediaWidth | int |
読み込まれたメディアの幅 (ピクセル単位)。 これはバインド可能な読み取り専用プロパティです。 非視覚的なメディアでは報告されず、iOS/macOS ではライブ ストリーミング コンテンツで常に設定されるとは限りません。 | 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 Community Toolkit