Playlist UI プラグイン

概要

Playlist UI プラグインには、プレイリストの動作をカスタマイズするためのオプションが含まれています。多数のオプションにより、レイアウト、動作、実装方法など、プレイリストにさまざまな変更を加えることができます。以下の例では、縦型および横型という 2 つの基本的なプレイリストレイアウトを示しています。各例では、カスタマイズ可能な内容を理解するために、いくつかの代表的な動作を紹介しています。

縦型レイアウト

以下のプレイリスト例では、次の点を示しています。

プレーヤーの右側に配置された縦型プレイリストには表示／非表示ボタンがあり、プレイリストは自動的にサイズ調整および配置されます。これは iframe プレーヤー実装を使用した場合のデフォルトの動作です。
プレイリストは初期状態で表示されます。これは hideOnStart オプションを使用して変更できます。
動画の終盤付近で、次の動画までの時間と次の動画のサムネイルを表示するオーバーレイが表示されます。これはデフォルトの動作であり、nextOverlay オプションによって制御されます。

横型レイアウト

以下のプレイリスト例では、次の点を示しています。

動画の下に配置された横型プレイリスト。
上記の例と同様に、動画の終盤でオーバーレイが表示されるほか、次の動画の再生が始まるまでの時間を表示するエンドスクリーンが表示されます。これは autoadvance オプションが 0 以外に設定されており、動画間の一時停止中にエンドスクリーンが表示されるためです。エンドスクリーンは nextEndscreen オプションを使用して変更できます。

プレーヤー／プレイリストの関連付け

デフォルトでは、Playlist UI プラグインは、指定されたプレーヤーに対して正しいプレイリストコンテナ要素を自動的に検出します。つまり、DOM 内で最初に見つかった空の .vjs-playlist 要素を使用します。ただし、このプラグインでは、複数のプレーヤーを使用する複雑なワークフローを構築する場合に、プレーヤーとプレイリストコンテナをより明示的に関連付ける方法も提供しています。

`data-for` 属性

data-for 属性は、プレイリストコンテナに適用して、プレーヤーの id と関連付けることができます。例は以下のとおりです。

        <video-js id="myPlayerID"
          ...></video-js>
        
        <div class="vjs-playlist" data-for="myPlayerID"></div>

これは利用可能な明示的な関連付け方法の中で最も具体的な方法です。他の方法よりも優先されます。

`data-player` および `data-embed` 属性

data-player および data-embed 属性は、プレイリストコンテナを Brightcove プレーヤーに関連付けるために使用できます。この関連付けを正しく機能させるには、両方の属性を指定する必要があります。以下の例では、明示的な関連付けが行われているため、 2 つ目の <div> タグのみがプレーヤー用のプレイリストを保持します。最初の <div> は空のままとなります。

        <video-js data-playlist-id="5455901760001"
            data-account="1507807800001"
            data-player="SJLNAJye7"
            data-embed="default"...></video-js>
        <script src="https://players.brightcove.net/1507807800001/SJLNAJye7_default/index.min.js"></script>
        
        <div class="vjs-playlist"></div>
        
        <div class="vjs-playlist" data-player="SJLNAJye7" data-embed="default"></div>

プレイリスト項目の追加／削除

Playlist UI プラグインでは、プレイリスト全体を置き換えるだけでなく、個々のプレイリスト項目を追加または削除することができます。 add および remove メソッドがプレイリストオブジェクトに追加され、さらに playlistadd と playlistremove という 2 つの新しいイベントも追加されています。

これらのメソッドおよびイベントは、このプラグインにバンドルされているオープンソースの videojs-playlist プラグインによって提供されています。詳細については、オープンソースのドキュメントを参照してください。以下は、これらの新しいメソッドを使用する例です。

              var samplePlaylist = [{
                  sources: [{
                    src: 'aaa.mp4',
                    type: 'video/mp4'
                  }]
                }];
                
                player.playlist(samplePlaylist);
                
                // playlistadd および playlistremove イベントをログに出力
                player.on('playlistadd', 'playlistremove', ({count, index, type}) => {
                  player.log(`saw ${type} event`, count, index);
                  player.log(`playlist total length is now ${player.playlist().length}`);
                });
                
                // プレイリストに 1 件追加
                // この呼び出し後、プレイリストには aaa.mp4 と bbb.mp4 の 2 件が含まれます
                player.playlist.add({
                  sources: [{
                    src: 'bbb.mp4',
                    type: 'video/mp4'
                  }]
                });
                
                // インデックス 1 に複数項目を追加
                // この呼び出し後、プレイリストには aaa.mp4、ccc.mp4、ddd.mp4、bbb.mp4 の 4 件が含まれます
                player.playlist.add([{
                  sources: [{
                    src: 'ccc.mp4',
                    type: 'video/mp4'
                  }]
                }, {
                  sources: [{
                    src: 'ddd.mp4',
                    type: 'video/mp4'
                  }]
                }], 1);
                
                // プレイリストから 1 件削除
                // この呼び出し後、プレイリストには ccc.mp4、ddd.mp4、bbb.mp4 の 3 件が含まれます
                player.playlist.remove(0);
                
                // プレイリストから複数項目を削除
                // この呼び出し後、プレイリストには bbb.mp4 の 1 件のみが含まれます
                player.playlist.remove(1, 2);

オプション

プラグインの初期化時にオプションオブジェクトを渡すことができます。このオブジェクトには、以下のいずれかのオプションを含めることができます。

autoadvance

autoadvance:
- 型: number
- デフォルト: undefined
- プレイリスト内の動画間で一時停止を行うかどうか、またその時間を指定します。詳細については、プレイリスト API ガイドの autoadvance セクションを参照してください。

hideOnStart

hideOnStart:
- 型: boolean
- デフォルト: false
- プレイリストを初期表示時に非表示にするかどうかを指定します。このオプションは iframe プレーヤー実装を使用している場合にのみ有効です。これは、プレイリストの表示／非表示機能が iframe 内でのみ利用可能であるためです。このオプションは横型プレイリストでは機能しません。
- 要件／依存関係:
  - playlistPicker: true
  - iframe 埋め込み
  - horizontal: false

horizontal

horizontal:
- 型: boolean
- デフォルト: false
- プレイリストを縦型ではなく、プレーヤーの下に横型で表示します。
- 要件／依存関係:
  - playlistPicker: true

nextButton

nextButton:
- 型: boolean
- デフォルト: true
- true の場合、次のプレイリスト項目へ移動するためのボタンが追加されます。このボタンは、オプションを false に設定することで無効にできます。ボタンは、再生ボタンの右側にコントロールバー内へ追加されます。

nextEndscreen

nextEndscreen:
型: boolean
デフォルト: true
true の場合、再生終了後にプレーヤー上へモーダル形式のエンドスクリーンが表示されます。このエンドスクリーンは、オプションを false に設定することで無効にできます。エンドスクリーンでは、次に再生されるプレイリスト内の動画がプレビュー表示されます。このオプションの動作条件は以下のとおりです。
- autoadvance オプションは 0 より大きい値に設定されている必要があります（そうでない場合、エンドスクリーンを表示する時間がなくスキップされます）。
- 表示されるカウントダウンは、autoadvance がトリガーされるまでの残り時間を示します。
- プレーヤーにカスタムエンドスクリーンプラグイン、または動画再生後に表示されるよう設定されたソーシャルプラグインが含まれていない必要があります。いずれかが検出された場合、エンドスクリーンは表示されません。

nextOverlay

nextOverlay:
- 型: boolean
- デフォルト: true
- true の場合、プレーヤー右下に小さなオーバーレイが表示されます。このオーバーレイは、オプションを false に設定することで無効にできます。オーバーレイには、次に再生されるプレイリスト内の動画がプレビュー表示されます。動作条件は以下のとおりです。
  - 次のプレイリスト項目が存在する必要があります。
  - autoadvance オプションは 0 以上に設定されている必要があります。
  - カウントダウンは、動画の残り時間と autoadvance の待機時間を合計したものです。
  - オーバーレイは、動画終了の 10 秒前に表示されます。ただし、動画が 30 秒未満の場合は、再生時間の 2/3 の時点で表示されます。
  - ユーザーがオーバーレイを閉じた場合、ソースが変更されるまで再表示されません。新しいソースでは再表示されます。
  - 次の動画エンドスクリーン が有効な場合、動画終了時にオーバーレイは非表示になります。無効な場合は、次の動画が始まるまで表示されたままになります。

playlist

playlist:
- 型: array
- デフォルト: undefined
- 初期プレイリストデータを渡すために使用します。詳細については、プレイリスト API ガイドの playlist セクションを参照してください。

playlistPicker

playlistPicker:
- 型: boolean
- デフォルト: true
- ユーザーがクリックして動画を選択できる、視覚的なプレイリスト一覧を表示するかどうかを指定します。 hideOnStart および horizontal オプションは、その表示や動作を変更します。 playlistPicker が false の場合でも、 nextButton、nextEndscreen、 nextOverlay オプションを使用して他の UI 要素を表示できます。

playOnSelect

playOnSelect:
- 型: boolean
- デフォルト: false
- プレイリスト内の動画をクリックした際に、自動的に再生を開始するかどうかを制御します。 true に設定すると、プレーヤーが一時停止中であっても、新しい動画を選択した時点で再生が開始されます。デフォルトでは、プレイリストから新しい動画をクリックすると動画は読み込まれますが、事前に一時停止されていた場合は再生されません。
- 要件／依存関係:
  - playlistPicker: true

repeat

repeat:
- 型: boolean
- デフォルト: false
- プレイリストの最後の動画が再生終了した後、プレイリストを繰り返し再生します。この機能により、最後の動画終了後に最初の動画が再生されます。

showDescription

showDescription:
- 型: boolean
- デフォルト: false
- 各プレイリスト項目に動画の説明を表示します。

shuffle

shuffle:
- 型: boolean
- デフォルト: false
- 新しいデータが読み込まれるたびに、プレイリスト項目をシャッフルします。

オプションの使用方法

オプションを利用する方法は 2 つあります。

Studio の PLAYERS > プラグイン セクションで設定する。
プレーヤーで JavaScript を使用して設定する。

Studio を使用する

Studio では、プレーヤーのプロパティの スタイリング セクションでプレイリストを使用するようにプレーヤーを選択している場合、上記の一部のオプションを UI から設定できます。プレイリストプレーヤーの再生セクションでは、次のオプションが利用できます。

連続再生モード を選択すると、動画カウントダウン オプションを選択できます。選択肢の視覚的なイメージを以下に示します。

次の動画カード

次の動画エンドスクリーン

JavaScript を使用する

コードでオプションを実装するには、オブジェクトを作成し、必要なオプションにそれぞれ値を設定したうえで、プラグイン呼び出し時にそのオプションオブジェクトを渡します。

        videojs.getPlayer('myPlayerID').ready(function() {
         var myPlayer = this,
          options = {};
          options.horizontal = true;
          options.nextButton = false;
          myPlayer.bcPlaylistUi(options);
        });

変更履歴

v5.1.3 までの過去のリリースノートおよび変更履歴については、Playlist UI プラグインのリリース情報を参照してください。

v5.1.3 以降に行われた主な変更は、Brightcove Player リリースノートに掲載されます。