MediaElement

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

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

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

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

作業の開始

.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

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

まず、using宣言をMauiProgram.csファイルの先頭に追加する必要があります。

using CommunityToolkit.Maui.MediaElement;

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

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement(enableForegroundService: true); // Set to `false` if Rich Notifications and background playback is not required

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

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

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

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

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

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

既定では、Source プロパティで定義されているメディアは、メディアを開いた直後に再生を開始しません。 メディアの自動再生を有効にするには、ShouldAutoPlay プロパティを true に設定します。

プラットフォームが提供するメディア再生コントロールは既定で有効になっており、ShouldShowPlaybackControls プロパティを false に設定することで無効にすることができます。

リッチ メディア通知を使用する

MediaElementでは、メディアがバックグラウンドで再生されているときに、Android、iOS、Mac Catalyst、Windows でリッチ メディア通知を表示できます。 リッチ メディア通知を有効にするには、次の手順が必要です。

1. MauiProgram.csで enableForegroundService メソッドを呼び出すときに、true パラメーターを UseMauiCommunityToolkitMediaElement に設定して、バックグラウンド ビデオの再生を有効にします。 詳細については、上記の 「パッケージの初期化 」セクションを参照してください。
2. プラットフォーム固有の初期化セクションに記載された説明に従って、プラットフォーム固有のセットアップを行います。
3. MetadataTitle、MetadataArtist、およびMetadataArtworkUrlプロパティを設定して、「メタデータの使用」セクションの説明に従って、再生中のメディアのメタデータを提供します。

Android でのフォアグラウンド サービス

Android でバックグラウンド再生を有効にするには、MauiProgram.cs で enableForegroundService メソッドを呼び出すときに、true パラメーターを UseMauiCommunityToolkitMediaElement に設定します。 MediaElement では、フォアグラウンド サービスに AndroidManifest.xml アクセス許可を追加する必要はありません。通知とバックグラウンド再生機能を有効にするには、 enableForegroundService: true を使用してビルダー メソッドを呼び出す必要があります。 enableForegroundServiceがtrueされると、ツールキットによって、フォアグラウンド サービスと通知に必要な Android マニフェスト エントリが自動的に追加されます。 enableForegroundServiceがfalseの状態で、バックグラウンド再生機能を使用しようとすると、Androidで例外が発生する可能性があります。

メタデータを使用する

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

TextureView の使用

MediaElementは Android プラットフォームでTextureViewを使用できます。 プラットフォームの既定の動作では、 SurfaceViewを使用します。 テクスチャ ビューを使用すると、トランスパレンシーやその他の効果を許可するサポートが追加されます。 これは、使用するビルダーを変更することによって設定されます

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

使用するメディア要素ごとに TextureView を設定することもできます。 XAML にセットし、コード分離できます。 この方法を使用すると、builder コマンドの .UseMauiCommunityToolkitMediaElement()がオーバーライドされます。

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

<toolkit:MediaElement AndroidViewType="TextureView" />

ローカルメディアを再生する

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

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

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

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、FileMediaSource 引数から string インスタンスを返します。
• FromUri、UriMediaSource 引数から Uri インスタンスを返します。
• FromResource、ResourceMediaSource 引数から string インスタンスを返します。

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

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

• FileMediaSource、string からローカル メディア ファイルを指定するために使用されます。 このクラスには、Path に設定できる string プロパティがあります。 さらに、このクラスには、string を FileMediaSource オブジェクトに変換する暗黙的な演算子と、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 プロパティを調べる必要はありません。 ただし、このプロパティは、独自のトランスポート コントロールを実装するときに重要になります。

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

メディア プレーヤーのトランスポート コントロールには、再生、一時停止、および停止機能を実行するボタンが含まれています。 これらのボタンは一般的に、テキストではなく使い慣れたアイコンで識別されます。また、再生と一時停止機能は一般的に、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 プロパティを Volume の MediaElement プロパティにバインドします。 これは、Volume プロパティが TwoWay バインディングを使用するため可能です。 したがって、Value プロパティを変更すると、Volume プロパティが変更されます。

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

プロパティ

イベント

メソッド

例

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

API

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

関連リンク

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