メディアの中断の作成、スケジュール、管理Create, schedule, and manage media breaks

この記事では、メディア再生アプリ用にメディアの中断を作成、スケジュール、管理する方法について説明します。This article shows you how to create, schedule, and manage media breaks to your media playback app. 通常、メディアの中断は、オーディオ広告やビデオ広告をメディア コンテンツに挿入する目的で使います。Media breaks are typically used to insert audio or video ads into media content. Windows 10 バージョン 1607 以降では、MediaBreakManager クラスを使って、MediaPlayer で再生する任意の MediaPlaybackItem にメディアの中断を簡単かつ迅速に追加できます。Starting with Windows 10, version 1607, you can use the MediaBreakManager class to quickly and easily add media breaks to any MediaPlaybackItem that you play with a MediaPlayer.

メディアの中断を 1 つ以上スケジュールすると、再生中の指定した時間に、システムがメディア コンテンツを自動的に再生します。After you schedule one or more media breaks, the system will automatically play your media content at the specified time during playback. MediaBreakManager では、ユーザーがメディアを中断、終了、またはスキップしたときにアプリが反応できるように、イベントが提供されています。The MediaBreakManager provides events so that your app can react when media breaks start, end, or when they are skipped by the user. MediaPlaybackSession にアクセスしてメディアの中断を確認し、ダウンロードや進行状況の更新のバッファリングなどのイベントを監視することもできます。You can also access a MediaPlaybackSession for your media breaks to monitor events such as download and buffering progress updates.

メディアの中断のスケジュールSchedule media breaks

MediaPlaybackItem オブジェクトには、アイテムの再生時に再生されるメディアの中断の構成に使う独自の MediaBreakSchedule があります。Every MediaPlaybackItem object has its own MediaBreakSchedule that you use to configure the media breaks that will play when the item is played. アプリでメディアの中断を使うための最初の手順は、メイン再生コンテンツ用の MediaPlaybackItem の作成です。The first step for using media breaks in your app is to create a MediaPlaybackItem for your main playback content.

MediaPlaybackItem moviePlaybackItem =
    new MediaPlaybackItem(MediaSource.CreateFromUri(new Uri("http://www.fabrikam.com/movie.mkv")));

MediaPlaybackItemMediaPlaybackList、他の基本的なメディアの再生 API の操作の参照については、「メディア項目、プレイリスト、トラック」を参照してください。For more information about working with MediaPlaybackItem, MediaPlaybackList and other fundamental media playback APIs, see Media items, playlists, and tracks.

次の例は、MediaPlaybackItem にプリロール区切りを追加する方法を示しています。これは、区切りが属する再生アイテムを再生する前に、システムがメディアの中断を再生することを意味します。The next example shows how to add a preroll break to the MediaPlaybackItem, which means that the system will play the media break before playing the playback item to which the break belongs. まず、新しい MediaBreak オブジェクトがインスタンス化されます。First a new MediaBreak object is instantiated. この例では、コンストラクター MediaBreakInsertionMethod.Interrupt と共に呼び出されます。つまり、区切りコンテンツの再生中はメイン コンテンツが一時停止されます。In this example, the constructor is called with MediaBreakInsertionMethod.Interrupt, meaning that the main content will be paused while the break content is played.

次に、区切り中に再生されるコンテンツ (広告など) 用に新しい MediaPlaybackItem が作成されます。Next, a new MediaPlaybackItem is created for the content that will be played during the break, such as an ad. この再生アイテムの CanSkip プロパティは false に設定されます。The CanSkip property of this playback item is set to false. つまり、ユーザーは組み込みのメディア コントロールを使ってアイテムをスキップできません。This means that the user will not be able to skip the item using the built-in media controls. ただし、SkipCurrentBreak を呼び出すことで、広告をプログラムによりスキップすることを選ぶことはできます。Your app can still choose to skip the add programatically by calling SkipCurrentBreak.

メディアの中断の PlaybackList プロパティは、複数のメディア アイテムをプレイリストとして再生できるようにする MediaPlaybackList です。The media break's PlaybackList property is a MediaPlaybackList that allows you to play multiple media items as a playlist. 一覧の Items コレクションから 1 つまたは複数の MediaPlaybackItem オブジェクトを追加し、メディアの中断のプレイリストに含めます。Add one or more MediaPlaybackItem objects from the list's Items collection to include them in the media break's playlist.

最後に、メイン コンテンツ再生アイテムの BreakSchedule プロパティを使ってメディアの中断をスケジュールします。Finally, schedule the media break by using the main content playback item's BreakSchedule property. プリロール区切りにする中断を、スケジュール オブジェクトの PrerollBreak プロパティに割り当てることで指定します。Specify the break to be a preroll break by assigning it to the PrerollBreak property of the schedule object.

MediaBreak preRollMediaBreak = new MediaBreak(MediaBreakInsertionMethod.Interrupt);
MediaPlaybackItem prerollAd = 
    new MediaPlaybackItem(MediaSource.CreateFromUri(new Uri("http://www.fabrikam.com/preroll_ad.mp4")));
prerollAd.CanSkip = false;
preRollMediaBreak.PlaybackList.Items.Add(prerollAd);

moviePlaybackItem.BreakSchedule.PrerollBreak = preRollMediaBreak;

これで、メイン メディア アイテムを再生できるようになりました。作成したメディアの中断は、メイン コンテンツの前に再生されます。Now you can play back the main media item, and the media break that you created will play before the main content. 新しい MediaPlayer オブジェクトを作成し、オプションで AutoPlay プロパティをtrue に設定して再生を自動的に開始します。Create a new MediaPlayer object and optionally set the AutoPlay property to true to start playback automatically. MediaPlayerSource プロパティをメイン コンテンツ再生アイテムに設定します。Set the Source property of the MediaPlayer to your main content playback item. 必須ではありませんが、MediaPlayerMediaPlayerElement に割り当てて XAML ページでメディアをレンダリングできます。It's not required, but you can assign the MediaPlayer to a MediaPlayerElement to render the media in a XAML page. MediaPlayer の使い方について詳しくは、「MediaPlayer を使ったオーディオとビデオの再生」をご覧ください。For more information about using MediaPlayer, see Play audio and video with MediaPlayer.

_mediaPlayer = new MediaPlayer();
_mediaPlayer.AutoPlay = true;
_mediaPlayer.Source = moviePlaybackItem;
mediaPlayerElement.SetMediaPlayer(_mediaPlayer);

プリロール区切りを同じ手法を使って、メイン コンテンツを含む MediaPlaybackItem の再生が終わったら再生されるポストロール区切りを追加します。ただし、MediaBreak オブジェクトをPostrollBreak プロパティに再生する点が異なります。Add a postroll break that plays after the MediaPlaybackItem containing your main content finishes playing, by using the same technique as a preroll break, except that you assign your MediaBreak object to the PostrollBreak property.

MediaBreak postrollMediaBreak = new MediaBreak(MediaBreakInsertionMethod.Interrupt);
MediaPlaybackItem postRollAd =
    new MediaPlaybackItem(MediaSource.CreateFromUri(new Uri("http://www.fabrikam.com/postroll_ad.mp4")));
postrollMediaBreak.PlaybackList.Items.Add(postRollAd);

moviePlaybackItem.BreakSchedule.PostrollBreak = postrollMediaBreak;

メイン コンテンツの再生中の指定した時点で再生されるミッドロール区切りを 1 つ以上スケジュールすることもできます。You can also schedule one or more midroll breaks that play at a specified time within the playback of the main content. 次の例では、メイン メディア アイテムの再生中に区切りが生成される時間を指定する TimeSpan オブジェクトを受け入れるコンストラクター オーバーロードを使って MediaBreak が作成されます。In the following example, the MediaBreak is created with the constructor overload that accepts a TimeSpan object, which specifies the time within the playback of the main media item when the break will be played. ここでも、MediaBreakInsertionMethod.Interrupt が指定され、区切りの生成中にメイン コンテンツの再生が一時停止されることが示されます。Again, MediaBreakInsertionMethod.Interrupt is specified to indicate that the main content's playback will be paused while the break plays. InsertMidrollBreak を呼び出すことで、ミッドロール区切りがスケジュールに追加されます。The midroll break is added to the schedule by calling InsertMidrollBreak. MidrollBreaks プロパティにアクセスすることで、スケジュールに含まれている現在のミッドロール区切りの読み取り専用一覧を取得できます。You can get a read-only list of the current midroll breaks in the schedule by accessing the MidrollBreaks property.

MediaBreak midrollMediaBreak = new MediaBreak(MediaBreakInsertionMethod.Interrupt, TimeSpan.FromMinutes(10));
midrollMediaBreak.PlaybackList.Items.Add(
    new MediaPlaybackItem(MediaSource.CreateFromUri(new Uri("http://www.fabrikam.com/midroll_ad_1.mp4"))));
midrollMediaBreak.PlaybackList.Items.Add(
    new MediaPlaybackItem(MediaSource.CreateFromUri(new Uri("http://www.fabrikam.com/midroll_ad_2.mp4"))));
moviePlaybackItem.BreakSchedule.InsertMidrollBreak(midrollMediaBreak);

次のミッドロール区切りの例では、MediaBreakInsertionMethod.Replace 挿入メソッドを使います。つまり、区切りの再生中もメイン コンテンツの再生が続けられます。The next midroll break example shown uses the MediaBreakInsertionMethod.Replace insertion method, which means that the system will continue processing the main content while the break is playing. このオプションは通常、広告の再生中にライブ ストリームを一時停止して遅れを生じさせたくないライブ ストリーミング メディア アプリにより使われます。This option is typically used by live streaming media apps where you don't want the content to pause and fall behind the live stream while the ad is played.

この例では、2 つの TimeSpan パラメーターを受け入れる MediaPlaybackItem コンストラクターのオーバーロードも使います。This example also uses an overload of the MediaPlaybackItem constructor that accepts two TimeSpan parameters. 最初のパラメーターは、メディアの中断アイテム内の、再生が開始される開始点を指定します。The first parameter specifies the starting point within the media break item where playback will begin. 2 番目のパラメーターは、メディアの中断アイテムが再生される時間の長さを指定します。The second parameter specifies the duration for which the media break item will be played. したがって、次の例では、20 分の時点でメイン コンテンツに対して MediaBreak が再生を開始します。So, in the following example, the MediaBreak will begin playing at 20 minutes into the main content. 再生されると、区切りメディア アイテムの先頭から 30 秒後にメディア アイテムが開始され、15 秒間再生されてからメイン メディア コンテンツが再生を再開します。When it plays, the media item will start 30 seconds from the beginning of the break media item and will play for 15 seconds before the main media content resumes playing.

midrollMediaBreak = new MediaBreak(MediaBreakInsertionMethod.Replace, TimeSpan.FromMinutes(20));
MediaPlaybackItem ad = 
    new MediaPlaybackItem(MediaSource.CreateFromUri(new Uri("http://www.fabrikam.com/midroll_ad_3.mp4")),
    TimeSpan.FromSeconds(30),
    TimeSpan.FromSeconds(15));
ad.CanSkip = false;
midrollMediaBreak.PlaybackList.Items.Add(ad);

メディアの中断のスキップSkip media breaks

この記事で既に説明したように、MediaPlaybackItemCanSkip プロパティを設定し、ユーザーが組み込みコントロールを使ってコンテンツをスキップできないようにすることができます。As mentioned previously in this article, the CanSkip property of a MediaPlaybackItem can be set to prevent the user from skipping the content with the built-in controls. ただし、いつでもコードから SkipCurrentBreak を呼び出すと現在の中断をスキップできます。However, you can call SkipCurrentBreak from your code at any time to skip the current break.

private void SkipButton_Click(object sender, RoutedEventArgs e) => _mediaPlayer.BreakManager.SkipCurrentBreak();

MediaBreak イベントの処理Handle MediaBreak events

メディアの中断の状態の変化に基づいてアクションを実行するために登録できる、メディアの中断に関連するいくつかのイベントがあります。There are several events related to media breaks that you can register for in order to take action based on the changing state of media breaks.

_mediaPlayer.BreakManager.BreakStarted += BreakManager_BreakStarted;
_mediaPlayer.BreakManager.BreakEnded += BreakManager_BreakEnded;
_mediaPlayer.BreakManager.BreakSkipped += BreakManager_BreakSkipped;
_mediaPlayer.BreakManager.BreaksSeekedOver += BreakManager_BreaksSeekedOver;

BreakStarted は、メディアの中断が開始すると発生します。The BreakStarted is raised when a media break starts. メディア コンテンツを再生していることがユーザーにわかるように UI を更新できます。You may want to update your UI to let the user know that media break content is playing. この例では、ハンドラーに渡された MediaBreakStartedEventArgs を使って、開始されたメディアの中断への参照を取得します。This example uses the MediaBreakStartedEventArgs passed into the handler to get a reference to the media break that started. 次に、CurrentItemIndex プロパティを使って、メディアの中断のプレイリストにある再生メディア アイテムが決定されます。Then the CurrentItemIndex property is used to determine which media item in the media break's playlist is being played. その後、UI が更新され、現在の広告インデックスと中断中の残りの広告数がユーザーに表示されます。Then the UI is updated to show the user the current ad index and the number of ads remaining in the break. UI の更新は UI スレッドに加える必要があるため、RunAsync の呼び出し内で呼び出しを行う必要がある点に注意してください。Remember that updates to the UI must be made on the UI thread, so the call should be made inside a call to RunAsync.

private async void BreakManager_BreakStarted(MediaBreakManager sender, MediaBreakStartedEventArgs args)
{
    MediaBreak currentBreak = sender.CurrentBreak;
    var currentIndex = currentBreak.PlaybackList.CurrentItemIndex;
    var itemCount = currentBreak.PlaybackList.Items.Count;

    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>            
        statusTextBlock.Text = $"Playing ad {currentIndex + 1} of {itemCount}");
}

BreakEnded は、中断内のすべてのメディア アイテムが再生を終えるか、スキップされたときに発生します。BreakEnded is raised when all of the media items in the break have finished playing or have been skipped over. このイベントのハンドラーを使って UI を更新し、メディアの中断コンテンツがそれ以上再生されないことを示すことができます。You can use the handler for this event to update the UI to indicate that media break content is no longer playing.

private async void BreakManager_BreakEnded(MediaBreakManager sender, MediaBreakEndedEventArgs args)
{
    // Update UI to show that the MediaBreak is no longer playing
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => statusTextBlock.Text = "");

    args.MediaBreak.CanStart = false;
}

BreakSkipped イベントは、CanSkip が true になっているアイテムの再生中ユーザーが組み込み UI の [次へ] ボタンを押したとき、または SkipCurrentBreak を呼び出すことでコードで中断をスキップしたときに発生します。The BreakSkipped event is raised when the user presses the Next button in the built-in UI during playback of an item for which CanSkip is true, or when you skip a break in your code by calling SkipCurrentBreak.

次の例では、MediaPlayerSource プロパティを使って、メイン コンテンツのメディア アイテムへの参照を取得します。The following example uses the Source property of the MediaPlayer to get a reference to the media item for the main content. スキップされたメディアの中断は、このアイテムの中断スケジュールに属しています。The skipped media break belongs to the break schedule of this item. 次に、スキップされたメディアの中断がスケジュールの PrerollBreak プロパティに設定されたメディアの中断と同じであるかどうかをコードがチェックします。Next, the code checks to see if the media break that was skipped is the same as the media break set to the PrerollBreak property of the schedule. 同じである場合、プリロール区切りがスキップされた中断であることを意味します。この場合、新しいミッドロール区切りが作成され、メイン コンテンツの 10 分の時点で再生されるようにスケジュールされます。If so, this means that the preroll break was the break that was skipped, and in this case, a new midroll break is created and scheduled to play 10 minutes into the main content.

private async void BreakManager_BreakSkipped(MediaBreakManager sender, MediaBreakSkippedEventArgs args)
{
    // Update UI to show that the MediaBreak is no longer playing
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => statusTextBlock.Text = "");

    MediaPlaybackItem currentItem = _mediaPlayer.Source as MediaPlaybackItem;
    if(!(currentItem.BreakSchedule.PrerollBreak is  null) 
        && currentItem.BreakSchedule.PrerollBreak == args.MediaBreak)
    {
        MediaBreak mediaBreak = new MediaBreak(MediaBreakInsertionMethod.Interrupt, TimeSpan.FromMinutes(10));
        mediaBreak.PlaybackList.Items.Add(await GetAdPlaybackItem());
        currentItem.BreakSchedule.InsertMidrollBreak(mediaBreak);
    }
}

BreaksSeekedOver は、メイン メディア アイテムの再生位置が、1 つ以上のメディアの中断のスケジュールされた時間を超えたときに発生します。BreaksSeekedOver is raised when the playback position of the main media item passes over the scheduled time for one or more media breaks. 次の例では、1 つ以上のメディアの中断が要求されたかどうか、再生位置が先に移動されたかどうか、先に移動された時間が 10 分未満であるかどうかがチェックされます。The following example checks to see if more than one media break was seeked over, if the playback position was moved forward, and if it was moved forward less than 10 minutes. その場合、要求された最初の中断 (イベント引数により開示された SeekedOverBreaks コレクションから取得されます) が、MediaPlayer.BreakManagerPlayBreak メソッドを呼び出すことですぐに再生されます。If so, the first break that was seeked over, obtained from the SeekedOverBreaks collection exposed by the event args, is played immediately with a call to the PlayBreak method of the MediaPlayer.BreakManager.

private void BreakManager_BreaksSeekedOver(MediaBreakManager sender, MediaBreakSeekedOverEventArgs args)
{
    if(args.SeekedOverBreaks.Count > 1
        && args.NewPosition.TotalMinutes > args.OldPosition.TotalMinutes
        && args.NewPosition.TotalMinutes - args.OldPosition.TotalMinutes < 10.0)
        _mediaPlayer.BreakManager.PlayBreak(args.SeekedOverBreaks[0]);
}

現在の再生セッションへのアクセスAccess the current playback session

MediaPlaybackSession オブジェクトは、MediaPlayer クラスを使って、現在再生中のメディア コンテンツに関連するデータとイベントを提供します。The MediaPlaybackSession object uses the MediaPlayer class to provide data and events related to the currently playing media content. MediaBreakManager にも、再生中のメディアの中断コンテンツに特に関連するデータとイベントを取得するためにアクセスできる MediaPlaybackSession があります。The MediaBreakManager also has a MediaPlaybackSession that you can access to get data and events specifically related to the media break content that is being played. 再生セッションから入手できる情報には、現在の再生状態、再生中か一時停止中か、コンテンツ内の現在の再生位置などがあります。Information you can get from the playback session includes the current playback state, playing or paused, and the current playback position within the content. メディアの中断コンテンツの縦横比がメイン コンテンツと異なる場合、NaturalVideoWidth プロパティおよび NaturalVideoHeight プロパティと NaturalVideoSizeChanged を使って、ビデオ UI を調整することができます。You can use the NaturalVideoWidth and NaturalVideoHeight properties and the NaturalVideoSizeChanged to adjust your video UI if the media break content has a different aspect ratio than your main content. アプリのパフォーマンスに関する貴重な利用統計情報を示す、BufferingStartedBufferingEndedDownloadProgressChanged などのイベントを受け取ることもできます。You can also receive events such as BufferingStarted, BufferingEnded, and DownloadProgressChanged that can provide valuable telemetry about the performance of your app.

次の例では、BufferingProgressChanged イベントのハンドラーを登録します。イベント ハンドラーでは、UI が更新されて現在のバッファリングの進行状況が表示されます。The following example registers a handler for the BufferingProgressChanged event; in the event handler, it updates the UI to show the current buffering progress.

_mediaPlayer.BreakManager.PlaybackSession.BufferingProgressChanged += PlaybackSession_BufferingProgressChanged;
private async void PlaybackSession_BufferingProgressChanged(MediaPlaybackSession sender, object args)
{
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
        bufferingProgressBar.Value = sender.BufferingProgress);
}