メディアプレーヤー

[アーティクル]
03/18/2023

メディアの再生には、インライン (ページに埋め込まれている、または他のコントロールのグループを使用した) または専用の全画面エクスペリエンスを使用した、ビデオとオーディオの表示とリッスンが関与します。

ユーザーは、再生と一時停止、後へスキップ、前へスキップなどの基本的なコントロールセットを必要とします。これは、(メディアプレーヤーのボタン、コントロールバーの背景、コントロールの配置やレイアウトを含め) 必要に応じて変更できます。

てんとう虫のビデオを再生するトランスポートコントロールを含むメディアプレーヤー要素のスクリーンショット

これは適切なコントロールですか?

アプリでオーディオまたはビデオを再生する場合は、メディアプレーヤーを使います。画像のコレクションを表示するには、反転ビューを使用します。

推奨事項

メディアプレイヤーは淡色テーマと濃色テーマの両方をサポートしていますが、ほとんどのエンターテインメントシナリオでは、濃色テーマを使用することでエクスペリエンスが向上します。暗い背景を使うと、(特に高感度条件では) コントラストが強調され、表示エクスペリエンスに影響を及ぼすコントロールバーが制限されます。

ビデオコンテンツを再生する場合、インラインモードよりも全画面表示モードを促進することにより、専用の表示エクスペリエンスを使うことをお勧めします。全画面表示エクスペリエンスが最適であり、インラインモードではオプションが制限されます。

画面領域がある場合は、2 行のレイアウトを採用します。コンパクトな単一行レイアウトよりもコントロールのスペースが多く、さまざまな入力を使用して簡単に移動できます。

既定のコントロールはメディア再生用に最適化されていますが、アプリに最適なエクスペリエンスを提供するためにメディアプレーヤーに必要なカスタムオプションを追加できます。カスタムコントロールの追加について詳しくは、「カスタムトランスポートコントロールを作成する」をご覧ください。

UWP と WinUI 2

重要

この記事の情報と例は、Windows アプリ SDKと WinUI 3 を使用するアプリ向けに最適化されていますが、一般に WinUI 2 を使用する UWP アプリに適用されます。プラットフォーム固有の情報と例については、UWP API リファレンスを参照してください。

このセクションには、UWP または WinUI 2 アプリでコントロールを使用するために必要な情報が含まれています。

このコントロールの API は、Windows.UI.Xaml.Controls 名前空間に存在します。

UWP API:MediaPlayerElement クラス、 MediaTransportControls クラス
WinUI 2 ギャラリーアプリを開き、MediaPlayerElement の動作を確認します。 WinUI 2 ギャラリー アプリには、ほとんどの WinUI 2 コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを入手するか、GitHub でソースコードを取得します。

最新の WinUI 2 を使用して、すべてのコントロールの最新のスタイルとテンプレートを取得することをお勧めします。 WinUI 2.2 以降には、角丸みを使用するこのコントロール用の新しいテンプレートが含まれています。詳しくは、「角の半径」をご覧ください。

10 フィートのエクスペリエンスを設計する場合は、2 行レイアウトを使用します。コンパクトな単一行レイアウトよりもコントロール用のスペースが多く、10 フィートのゲームパッドを使用して移動する方が簡単です。 10 フィートエクスペリエンス用にアプリケーションを最適化する方法の詳細については、 Xbox とテレビの設計に関する記事を参照してください。

MediaPlayerElement は Windows 10 バージョン 1607 以降でのみ使用できます。 Windows 10 の以前のバージョン用にアプリを開発する場合は、代わりに MediaElement コントロールを使用する必要があります。ここで行ったすべての推奨事項も同様に適用 MediaElement されます。

メディアプレーヤーの作成

重要な API:MediaPlayerElement クラス、MediaTransportControls クラス

WinUI 3 ギャラリーアプリを開き、MediaPlayerElement の動作を確認します。

WinUI 3 ギャラリー アプリには、ほとんどの WinUI 3 コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを入手するか、GitHub でソースコードを取得します。

XAML で MediaPlayerElement オブジェクトを作成してアプリにメディアを追加し、オーディオやビデオファイルを指定する MediaSource に Source を設定します。

この XAML は MediaPlayerElement を作成し、その Source プロパティをアプリのローカルにあるビデオファイルの URI に設定するコードを示します。は MediaPlayerElement 、ページの読み込み時に再生を開始します。メディアがすぐに開始されないようにするには、 AutoPlay プロパティをに false設定します。

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400" AutoPlay="True"/>

この XAML により、組み込みのトランスポートコントロールが有効になり、AutoPlay プロパティがに設定された MediaPlayerElement が作成されます。false.

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400"
                    AutoPlay="False"
                    AreTransportControlsEnabled="True"/>

重要

相対 URI (ms-appx/ms-resource) への設定 MediaPlayerElement.Source は、Windows アプリケーションパッケージプロジェクトでパッケージ化されたアプリでのみ機能します。アプリで Windows アプリケーションパッケージプロジェクトを使用しない場合は、相対 ms-appx:/// URI を完全に解決された file:/// URI に変換することをお勧めします。この記事の後半の「メディアソースの設定」および「ローカルメディアファイルを開く」セクションも参照してください。

メディアトランスポートコントロール

MediaPlayerElement には、再生、停止、一時停止、音量、ミュート、シーク (進行状況)、字幕、オーディオトラックの選択を処理する組み込みのトランスポートコントロールがあります。これらのコントロールを有効にするには、 AreTransportControlsEnabled をに true設定します。無効にするには、をに設定 AreTransportControlsEnabled します false。トランスポートコントロールは、MediaTransportControls クラスで表されます。トランスポートコントロールは、そのまま使用することも、さまざまな方法でカスタマイズすることもできます。詳しくは、MediaTransportControls クラスのリファレンスと「Create custom transport controls」をご覧ください。

トランスポートコントロールは 1 行および 2 行のレイアウトをサポートします。最初の例は、メディアのタイムラインの左側に再生/一時停止ボタンを配置した 1 行のレイアウトです。このレイアウトは、インラインメディア再生とコンパクトな画面に適しています。

1 行の MTC コントロールの例

ほとんどの使用シナリオ (特に大きな画面) では、2 行のコントロールのレイアウト (下の図) をお勧めします。このレイアウトでは、コントロールの領域がより多く確保されており、ユーザーが簡単にタイムラインを操作できます。

2 行の MTC コントロールの例

システムメディアトランスポートコントロール

MediaPlayerElement は、システムメディアトランスポートコントロールと自動的に統合されます。システムメディアトランスポートコントロールは、キーボードのメディアボタンなどのハードウェアメディアキーを押すとポップアップするコントロールです。詳しくは、SystemMediaTransportControls をご覧ください。

メディアソースを設定する

ネットワーク上のファイルまたはアプリに埋め込まれたファイルを再生する場合は、ファイルのパスを使用して Source プロパティを MediaSource に設定します。

ヒント

インターネットからファイルを開くには、アプリのマニフェスト (Package.appxmanifest ) でインターネット (クライアント) 機能を宣言する必要があります。機能の宣言について詳しくは、「アプリ機能の宣言」をご覧ください。

次のコードでは、XAML で定義した MediaPlayerElement の Source プロパティを、TextBox に入力したファイルのパスに設定してみます。

<TextBox x:Name="txtFilePath" Width="400"
         FontSize="20"
         KeyUp="TxtFilePath_KeyUp"
         Header="File path"
         PlaceholderText="Enter file path"/>

private void TxtFilePath_KeyUp(object sender, KeyRoutedEventArgs e)
{
    if (e.Key == Windows.System.VirtualKey.Enter)
    {
        TextBox tbPath = sender as TextBox;

        if (tbPath != null)
        {
            LoadMediaFromString(tbPath.Text);
        }
    }
}

private void LoadMediaFromString(string path)
{
    try
    {
        Uri pathUri = new Uri(path);
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

メディアソースをアプリに埋め込まれたメディアファイルに設定するには、でプレフィックスが付ms-appx:///いたパスを使用して Uri を初期化し、Uri を使用して MediaSource を作成し、[ソース] を Uri に設定します。たとえば、Videos サブフォルダー 内のvideo1.mp4 という名前のファイルの場合、パスは次のようになります。ms-appx:///Videos/video1.mp4

重要

相対 URI (ms-appx/ms-resource) への設定 MediaPlayerElement.Source は、Windows アプリケーションパッケージプロジェクトでパッケージ化されたアプリでのみ機能します。

このコードでは、XAML で以前に定義した MediaPlayerElement の Source プロパティをにms-appx:///Videos/video1.mp4設定します。

private void LoadEmbeddedAppFile()
{
    try
    {
        Uri pathUri = new Uri("ms-appx:///Videos/video1.mp4");
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

ローカルメディアファイルを開く

ローカルシステムや OneDrive のファイルを開くには、FileOpenPicker を使ってファイルを取得し、Source を使ってメディアソースを設定します。または、プログラムによってユーザーのメディアフォルダーにアクセスすることもできます。

アプリがユーザーの操作なしで、Music または Video フォルダーにアクセスする必要がある場合、たとえばユーザーのコレクションのすべての音楽ファイルやビデオファイルを列挙し、アプリで表示する場合は、音楽ライブラリおよびビデオライブラリ機能を宣言する必要があります。詳しくは、「ミュージック、画像、およびビデオライブラリのファイルとフォルダー」をご覧ください。

ユーザーはどのファイルにアクセスしているかを完全に制御できるので、FileOpenPicker には、ユーザーの Music または Video フォルダーなど、ローカルファイルシステム上のファイルにアクセスするための特別な機能は必要ありません。セキュリティとプライバシーの観点から、アプリで使用する機能の数は最小限にすることをお勧めします。

FileOpenPicker を使用してローカルメディア開くには

ユーザーがメディアファイルを選べるようにするには、FileOpenPicker を呼び出します。

FileOpenPicker クラスを使って、メディアファイルを選びます。 FileTypeFilter を設定して、表示するファイルの種類をFileOpenPicker指定します。 PickSingleFileAsync を呼び出して、ファイルピッカーを起動し、ファイルを取得します。
MediaSource を使用して、選んだメディアファイルを MediaPlayerElement.Source として設定します。

FileOpenPicker から返された StorageFile を使用するには、MediaSource で CreateFromStorageFile メソッドを呼び出し、MediaPlayerElement の Source として設定する必要があります。その後、MediaPlayerElement.MediaPlayer で Play を呼び出して、メディアを開始します。

この例は、FileOpenPicker を使ってファイルを選び、そのファイルを MediaPlayerElement の Source に設定する方法を示しています。

<MediaPlayerElement x:Name="mediaPlayerElement"/>
...
<Button Content="Choose file" Click="Button_Click"/>

private async void Button_Click(object sender, RoutedEventArgs e)
{
    await SetLocalMedia();
}

async private System.Threading.Tasks.Task SetLocalMedia()
{
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    WinRT.Interop.InitializeWithWindow.Initialize(openPicker, WinRT.Interop.WindowNative.GetWindowHandle(this));

    openPicker.FileTypeFilter.Add(".wmv");
    openPicker.FileTypeFilter.Add(".mp4");
    openPicker.FileTypeFilter.Add(".wma");
    openPicker.FileTypeFilter.Add(".mp3");

    var file = await openPicker.PickSingleFileAsync();

    // mediaPlayerElement is a MediaPlayerElement control defined in XAML
    if (file != null)
    {
        mediaPlayerElement.Source = MediaSource.CreateFromStorageFile(file);

        mediaPlayerElement.MediaPlayer.Play();
    }
}

ポスターソースを設定する

PosterSource プロパティを使って、メディアの読み込みが終わるまで MediaPlayerElement に視覚的な表示を提供することができます。 A PosterSource は、スクリーンショット、映画ポスター、アルバムアートなどの画像で、メディアの代わりに表示されます。 PosterSourceは、次の状況で表示されます。

有効なソースが設定されていないとき。たとえば、Source が設定されていない、にnull設定されている、Sourceまたはソースが無効です (MediaFailed イベントが発生した場合と同様)。
メディアの読み込み中。たとえば、有効なソースが設定されていても、MediaOpened イベントがまだ発生していないときです。
別のデバイスにメディアをストリーミングしているとき。
メディアがオーディオのみであるとき。

Source がアルバムのトラックに設定され、PosterSource がアルバムの表紙の画像を設定された MediaPlayerElement を以下に示します。

<MediaPlayerElement Source="ms-appx:///Media/Track1.mp4" PosterSource="ms-appx:///Media/AlbumCover.png"/>

デバイスの画面をアクティブに維持する

通常、ユーザーがいないときはバッテリーを節約するために画面が暗くなり、最終的には電源がオフになりますが、ビデオアプリでは、ユーザーがビデオを見られるように画面をオンのままにしておく必要があります。アプリでビデオを再生しているときなど、無操作状態が検出されてもディスプレイの電源が切れないようにするには、DisplayRequest.RequestActive を呼び出します。 DisplayRequest クラスを使うと、ユーザーがビデオを見られるように画面をオンのままにするよう Windows に指示することができます。

消費電力とバッテリーの駆動時間を節約するため、不要になったら、DisplayRequest.RequestRelease を呼び出して表示要求を解放してください。 Windows は、アプリが画面から消されると自動的にアプリのアクティブな表示要求を非アクティブ化し、アプリがフォアグラウンドに戻ると再びアクティブ化します。

表示要求を解放する必要があるのは、次のような場合です。

ユーザーの操作、バッファリング、限られた帯域幅のための調整などでビデオの再生が一時停止になる。
再生が停止する。たとえば、ビデオの再生が完了したり、プレゼンテーションが終了したりする。
再生エラーが発生した。たとえば、ネットワーク接続の問題や破損したファイル。

画面をアクティブに維持するには

DisplayRequest グローバル変数を作成します。に初期化します null。
```
private DisplayRequest appDisplayRequest = null;
```
RequestActive を呼び出して、アプリで表示をオンのままにする必要があることを Windows に通知します。
ビデオの再生が再生エラーによって停止、一時停止、中断したときには必ず、RequestRelease を呼び出して表示要求を解放します。アプリにアクティブな表示要求がなくなった場合、Windows は、デバイスが使われていないときには表示を暗くし、最終的には電源をオフにしてバッテリーを節約します。

各 MediaPlayerElement.MediaPlayer には、PlaybackRate、PlaybackState、Position など、メディア再生のさまざまな側面を制御する MediaPlaybackSession 型の PlaybackSession があります。ここでは、MediaPlayer.PlaybackSession で PlaybackStateChanged イベントを使って、表示要求を解放する必要がある状況を検出します。次に、NaturalVideoHeight プロパティを使って、オーディオファイルとビデオファイルのどちらが再生されているかを確認し、ビデオが再生されている場合にのみ画面をアクティブなままにします。

<MediaPlayerElement x:Name="mediaPlayerElement" Source="ms-appx:///Videos/video1.mp4"/>

public sealed partial class MainWindow : Window
{
    public DisplayRequest appDisplayRequest = null;
    // using Microsoft.UI.Dispatching;
    private DispatcherQueue dispatcherQueue = DispatcherQueue.GetForCurrentThread();

    public MainWindow()
    {
        this.InitializeComponent();
        mediaPlayerElement.MediaPlayer.PlaybackSession.PlaybackStateChanged += 
            PlaybackSession_PlaybackStateChanged;
    }

    private void PlaybackSession_PlaybackStateChanged(MediaPlaybackSession sender, object args)
    {
        MediaPlaybackSession playbackSession = sender as MediaPlaybackSession;
        if (playbackSession != null && playbackSession.NaturalVideoHeight != 0)
        {
            if (playbackSession.PlaybackState == MediaPlaybackState.Playing)
            {
                if (appDisplayRequest is null)
                {
                    dispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
                    {
                        appDisplayRequest = new DisplayRequest();
                        appDisplayRequest.RequestActive();
                    });
                }
            }
            else // PlaybackState is Buffering, None, Opening, or Paused.
            {
                if (appDisplayRequest is not null)
                {
                    appDisplayRequest.RequestRelease();
                    appDisplayRequest = null;
                }
            }
        }
    }
}

プログラムでメディアプレーヤーを制御する

MediaPlayerElement には、MediaPlayerElement.MediaPlayer プロパティを介してオーディオやビデオの再生を制御するプロパティ、メソッド、イベントが多数用意されています。プロパティ、メソッド、イベントの完全な一覧については、MediaPlayer のリファレンスページをご覧ください。

高度なメディア再生のシナリオ

再生リストの再生、オーディオ言語の切り替え、カスタムメタデータトラックの作成など、より複雑なメディア再生シナリオの場合は、 MediaPlayerElement.Source を MediaPlaybackItem または MediaPlaybackList に設定します。さまざまな高度なメディア機能を有効にする方法について詳しくは、メディアの再生に関するページをご覧ください。

ビデオのサイズを変更し、拡大する

Stretch プロパティを使って、コンテナー内でのビデオコンテンツや PosterSource のサイズを変更します。この要素は、Stretch の値に応じてビデオのサイズ変更と拡大を行います。状態は Stretch 、多くのテレビセットの画像サイズ設定に似ています。ボタンにフックしてユーザーが好みの設定を選ぶことができるようにします。

None は、コンテンツのネイティブ解像度を元のサイズで表示します。これにより、ビデオの一部がトリミングされたり、ビデオの端に黒いバーが表示されたりする可能性があります。
縦横比とビデオコンテンツを維持しながら、できるだけ多くの領域を均一に塗りつぶします。これにより、ビデオの端に水平方向または垂直方向の黒いバーが表示されることがあります。これはワイドスクリーンモードに似ています。
UniformToFill は、縦横比を維持したままスペース全体を使用します。これにより、ビデオの一部がトリミングされる可能性があります。これは全画面モードに似ています。
Fill は、縦横比を維持せずに、スペース全体を使用します。どのビデオもトリミングされませんが、ストレッチが発生する可能性があります。これはストレッチモードに似ています。

Stretch 列挙値

ここでは、AppBarButton を使って、Stretch オプションを順に切り替えます。ステートメントは switchStretch プロパティの現在の状態をチェックし、列挙体の次の値に Stretch 設定します。これにより、ユーザーはさまざまな拡大の状態を順番に表示することができます。

<AppBarButton Icon="Trim"
              Label="Resize Video"
              Click="PictureSize_Click" />

private void PictureSize_Click(object sender, RoutedEventArgs e)
{
    switch (mediaPlayerElement.Stretch)
    {
        case Stretch.Fill:
            mediaPlayerElement.Stretch = Stretch.None;
            break;
        case Stretch.None:
            mediaPlayerElement.Stretch = Stretch.Uniform;
            break;
        case Stretch.Uniform:
            mediaPlayerElement.Stretch = Stretch.UniformToFill;
            break;
        case Stretch.UniformToFill:
            mediaPlayerElement.Stretch = Stretch.Fill;
            break;
        default:
            break;
    }
}

待機時間が短い再生を可能にする

MediaPlayerElement.MediaPlayer で RealTimePlayback プロパティをにtrue設定して、メディアプレーヤー要素が再生の初期待機時間を短縮できるようにします。これは双方向通信アプリには重要で、ゲームのシナリオにも適用できる場合があります。このモードでは、リソースがより多く消費され、電力効率が低下する点に注意してください。

この例では、 MediaPlayerElement を作成し、 RealTimePlayback をに true設定します。

MediaPlayerElement mediaPlayerElement = new MediaPlayerElement();
mediaPlayerElement.MediaPlayer.RealTimePlayback = true;

メディアプレーヤー

これは適切なコントロールですか?

推奨事項

UWP と WinUI 2

メディアプレーヤーの作成

メディアトランスポートコントロール

メディアソースを設定する

ローカルメディアファイルを開く

ポスターソースを設定する

デバイスの画面をアクティブに維持する

プログラムでメディアプレーヤーを制御する

高度なメディア再生のシナリオ

ビデオのサイズを変更し、拡大する

待機時間が短い再生を可能にする

フィードバック

その他のリソース

メディア プレーヤー

これは適切なコントロールですか?

推奨事項

UWP と WinUI 2

メディア プレーヤーの作成

メディア トランスポート コントロール

メディア ソースを設定する

ローカル メディア ファイルを開く

ポスター ソースを設定する

デバイスの画面をアクティブに維持する

プログラムでメディア プレーヤーを制御する

高度なメディア再生のシナリオ

ビデオのサイズを変更し、拡大する

待機時間が短い再生を可能にする

関連記事

フィードバック

その他のリソース

メディアプレーヤー

メディアプレーヤーの作成

メディアトランスポートコントロール

メディアソースを設定する

ローカルメディアファイルを開く

ポスターソースを設定する

プログラムでメディアプレーヤーを制御する