品質選択プラグイン

このトピックでは、品質選択プラグインの使用方法について説明します。このプラグインは、プレーヤーのコントロールバーにメニューボタンを追加し、HLS または DASH ソースの再生品質を手動で選択できるようにします。

注意：品質選択プラグインはすべての動画ソースで動作するわけではありません。以下の点で状況を明確にします：

このプラグインは HLS/DASH ソースでのみ動作します。
このプラグインは、子レンディションの解像度情報を含む M3U8 マスターファイルがある場合、その解像度情報を表示します。解像度が指定されていない場合、代わりに HD/SD と表示されます。
HLS の M3U8 ファイルがどこにホストされているか、LIVE か VOD かは関係ありません。
このプラグインは MP4 では動作しません。仮に MP4 ソースが 5 つあり HLS ソースが 1 つだけの場合でも、MP4 の品質選択肢は表示されません。

プレーヤー例

以下は品質選択プラグインを使用した Brightcove プレーヤーです。動画を再生すると、コントロールバーに次のアイコンが表示されます：

選択を行うと、DASH ソースの場合は新しい品質が画面に反映されるまで、HLS ソースの場合は新しい品質の読み込みが開始されるまでギアが回転します。選択時に表示される品質オプションやギア回転の動作については、以下で詳しく説明します。

品質オプション

歯車アイコンをクリックすると、ユーザーが選択できる複数の品質オプションが表示されます。例えば、次のレンディションを持つ動画では：

次のような品質オプションが生成されます：

これらのオプションがどのように作成され、特定のレンディションが選択されるかは次のとおりです：

すべてのレンディションは水平解像度（例：270p、360p、540p、720p、1080p）ごとにグループ化され、品質オプションとして使用されます。
ユーザーがグループを選択した後、選択した解像度グループ内に複数のレンディションがある場合、標準のアダプティブビットレート（ABR）アルゴリズムが最適なレンディションを選択します。この処理は通常のレンディション選択と同じですが、選択された解像度グループ内に限定されます。
解像度情報が利用できない場合、オプションは SD と HD（それぞれ標準画質・高画質）にフォールバックします。プラグインはレンディションごとのビットレート情報を使用し、設定された境界線に基づいて SD か HD を判定します。

バッファリング

品質変更時にはバッファリングが発生し、読み込みスピナーが表示される場合があります。これは、品質選択後すぐに品質が変更され、新しいセグメントをダウンロードする必要があるためです。

過去には、自動レンディション切替時と同じようなスムーズな切替動作を希望する場合、以下のオプションを使用してプレーヤーを手動初期化する方法がありました：

      var options = {
        html5: {
          hls: {
            smoothQualityChange: true
          }
        }
      };

この bc() メソッドを使用したプレーヤーの手動初期化についての詳細は、Using bc() and getPlayer() Methods のドキュメントで確認できます。

注意：Brightcove Player v6.56.0 以降、smoothQualityChange オプションは非推奨となり、Player v7 では完全に削除されています。

smoothQualityChange オプションは、プレーヤーの再生エンジン内の fastQualityChange メソッドに置き換えられています。このメソッドは ABR（アダプティブビットレート）切替ロジックに統合されており、手動で呼び出す必要はありません。

smoothQualityChange がバッファを消去せずに滑らかな切替を試みていたのに対し、fastQualityChange は意図的にバッファをクリアし、新しい品質レベルに迅速に切り替え、現在の再生位置に合わせたデータを読み込み始めます。

この方式は、切替にかかる時間を最小限に抑えることを目的としていますが、プレーヤーが新しい品質のデータを再度読み込む必要があるため、一時的に再生が途切れる可能性があります。

歯車アイコンの回転

歯車アイコンの回転は、使用されるレンディションの変更を示します。DASH と HLS では回転のルールが異なります：

DASH ソースの場合：プレーヤーで品質が変更され、それが画面に描画されるまで歯車が回転します。
HLS ソースの場合：内部アルゴリズムが新しい品質の読み込み開始を判断したタイミングで歯車の回転が終了します。これは描画完了ではありません。この判断は非常に速く行われるため、HLS ソースでは歯車の回転が頻繁に見られない可能性があります。

Players モジュールを使用して実装する

Players モジュールを使用して品質選択プラグインを実装するには、次の手順に従います：

PLAYERS モジュールを開き、新しいプレーヤーを作成するか、プラグインを追加したいプレーヤーを見つけます。
プレーヤーのプロパティを開くため、対象プレーヤーのリンクをクリックします。
左側のナビゲーションメニューで コントロール をクリックします。
Quality Selector の前にあるチェックボックスをオンにします。
ラジオボタンを使用して、利用可能な解像度の一覧を表示するか、単純に HD/SD の選択肢のみを表示するかを選択します。
保存をクリックします。
プレーヤーを公開するには、公開と埋め込み > 変更の公開 をクリックします。
ダイアログを閉じるには 閉じる をクリックします。

コードを使用して実装する

コードを使用して品質選択プラグインを実装するには、次の手順に従います：

エディタで Brightcove プレーヤーを配置したい HTML コードを開きます。

head セクションに品質選択プラグインのデフォルトスタイルシートを追加します。

        <link href="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.css" rel='stylesheet'>

body セクションに高度なプレーヤー埋め込みコードを追加します。

後のスクリプトでプレーヤーを参照できるよう、プレーヤー埋め込みコードに id 属性を追加しています。

        <video-js id="myPlayerID"
          data-account="1752604059001"
          data-player="default"
          data-embed="default"
          controls=""
          data-video-id="5842800655001"
          data-playlist-id=""
          data-application-id=""
          width="960" height="540"></video-js>
        <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>

プレーヤー埋め込みコードの後に品質選択プラグインのスクリプトファイルを追加します。
```
        <script src="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.min.js"></script>
```
その下に、次の処理を行うスクリプトを追加します：
- Brightcove プレーヤーへの参照を取得する。
- 品質選択プラグインをプレーヤーに登録する。
- 使用したいプラグインのオプションを指定する。この例では、デフォルトの品質選択を 720p に設定しています。
```
        <script type="text/javascript">
          videojs.getPlayer('myPlayerID').ready(function() {
            var myPlayer = this;
            myPlayer.qualityMenu({
              defaultResolution: '720p'
            });
          });
        </script>
```

コード全体の例

こちらは品質選択プラグインを使用し、初期デフォルト解像度を設定した完全なコード例です：

        <!DOCTYPE html>
        <html>
            <head>
              <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
              <title>Quality Selection</title>
        
              <!-- CSS for the quality selection plugin -->
              <link href="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.css" rel='stylesheet'>
            </head>
        
            <body>
            <h1>Quality Selection</h1>
        
            <!-- Brightcove Player embed code -->
            <video-js id="myPlayerID"
              data-account="1752604059001"
              data-player="default"
              data-embed="default"
              controls=""
              data-video-id="5842800655001"
              data-playlist-id=""
              data-application-id=""
              width="960" height="540"></video-js>
            <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>
        
            <!-- Script for the quality selection plugin -->
            <script src="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.min.js"></script>
        
            <script type="text/javascript">
              // When the player is ready, get a reference to it
              videojs.getPlayer('myPlayerID').ready(function() {
                var myPlayer = this;
        
                // Register the quality selection plugin with options
                myPlayer.qualityMenu({
                  defaultResolution: '720p'
                });
              });
            </script>
            </body>
        </html>

設定オプション

コードを使用してプラグインを実装する場合、次のオプションを利用してプラグインを設定できます：

defaultResolution
- タイプ: String
- デフォルト: none
- 使用するデフォルト解像度または解像度マッピングを定義します。水平解像度（例：720p）または SD/HD を指定できます。
Video Cloud Studio でデフォルトの初期解像度を変更する

Video Cloud Studio でデフォルトの解像度を変更するには、次の手順に従います：
1. PLAYERS モジュールで、品質選択プラグインを追加したプレーヤーを選択します。
2. 左ナビゲーションで JSON エディタ を選択します。
3. プラグイン セクション内の品質選択プラグイン設定を探します。例：
```
{
            "registry_id": "@brightcove/videojs-quality-menu",
            "version": "1.x",
            "options": {
              "useResolutionLabels": true
            }
          }
```
4. オプション セクションに希望のデフォルト解像度を追加します（前の行の末尾にカンマを付け忘れないでください）：
```
{
            "registry_id": "@brightcove/videojs-quality-menu",
            "version": "1.x",
            "options": {
              "useResolutionLabels": true,
              "defaultResolution": "720p"
            }
          }
```
5. 保存をクリックして JSON を保存します。
6. 変更したプレーヤーを公開します。
もちろん、このセクションの他のオプションも同様の手順で Video Cloud Studio から設定できます。
sdBitrateLimit
- タイプ: Number
- デフォルト: 2000000
- SD とみなすレンディションのビットレート上限（排他的）を定義します。
useResolutionLabels
- タイプ: Boolean
- デフォルト: true
- true の場合、利用可能な場合は水平解像度の行数でレンディションを分類します。 false に設定すると、常に SD/HD の分類が使用されます。
useResolutionLabels オプションを使用するには、Studio のプラグイン設定に次のように入力します：
```
        {
          "useResolutionLabels": false
        }
```
結果として、品質オプションは次のようになります：

この場合、プレーヤーは選択されたグループ内で最適なレンディションを選択します。このセクションで説明したように、sdBitrateLimit により、どのレンディションが SD/HD と分類されるかを調整できます。
矛盾した設定は動作しません。例えば、次のいずれも useResolutionLabels の設定に対して無効な値を指定しているため、正しく機能しません：
```
        "useResolutionLabels": true,
        "defaultResolution": "HD"
```
```
        "useResolutionLabels": false,
        "defaultResolution": "1080p"
```
resolutionLabelBitrates
- タイプ: Boolean
- デフォルト: false
- true の場合、解像度ラベルにビットレート情報を付加します（例：720p @ 13806 kbps）。このオプションは、useResolutionLabels が false の場合、または解像度情報が利用できない場合には効果がありません。
この設定を true にすると、品質セレクターは次のように表示されます：

コントロールのスタイリング

CSS を使用して、歯車アイコンおよび表示されるメニューのスタイルを設定できます。以下の表は、スタイル可能な一般的なコンポーネント、そのセレクター、設定する CSS プロパティを示しています。

コンポーネント	セレクター	プロパティ
歯車アイコン	button.vjs-quality-menu-button.vjs-menu-button.vjs-menu-button-popup.vjs-button	color
メニュー項目の背景色	div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item	background-color
メニュー項目の文字色	div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item-text	color
選択されている項目の背景色	div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected	background-color
選択されている項目の文字色	div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected .vjs-menu-item-text	color
HD ラベルの文字色	div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-quality-menu-item-sub-label	color

例えば、以下のようなスタイルにしたい場合：

次の CSS を使用します：

        /* アイコンのスタイル */
        button.vjs-quality-menu-button.vjs-menu-button.vjs-menu-button-popup.vjs-button {
          color: red;
        }
        /* メニュー項目の背景色 */
        div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item {
          background-color: yellow;
        }
        /* メニュー項目の文字色 */
        div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item-text {
          color: green;
        }
        /* 選択されている項目の背景色 */
        div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected {
          background-color: white;
        }
        /* 選択されている項目の文字色 */
        div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected .vjs-menu-item-text{
          color: blue;
        }
        /* HD ラベルの文字色 */
        div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-quality-menu-item-sub-label {
          color: lime;
        }

既知の問題

このプラグインは Brightcove Player バージョン 5.17.0 以降で動作します。これより前のバージョンでは動作はサポートされていません。
品質セレクターは Safari では表示されません。
品質セレクターは iOS では表示されません。これは Apple の制限によるもので、iOS やデスクトップ版 Safari ではユーザーが再生品質を手動で制御することができず、帯域幅や接続速度、画面サイズなどに基づいてアダプティブビットレートが自動的に選択されます。

品質の切り替えが希望のタイミングで発生しないことがあり、予想より時間がかかる場合があります。
プレーヤー設定で source を設定し、Single Video Template を使用してビルドすると、品質メニューが正しく初期化されません。これは、source が videojs コンストラクタで設定されるためで、この時点ではプレーヤーやプラグインへのアクセスができません。source は player.src() を使用して設定する必要があります。この問題は Video Cloud ユーザーには影響しません。
DASH コンテンツを Silverlight で使用している場合、品質メニューは表示されません。
品質セレクター内のビデオ品質は、プレーヤーを再読み込みするたびに Auto にリセットされます。以前の設定は維持されません。

更新履歴

品質メニュー変更履歴を参照してください。

過去のリリースノートについては、こちらの更新履歴を参照してください。

品質選択プラグイン

プレーヤー例

品質オプション

バッファリング

歯車アイコンの回転

Players モジュールを使用して実装する

コードを使用して実装する

コード全体の例

設定オプション

`defaultResolution`

Video Cloud Studio でデフォルトの初期解像度を変更する

`sdBitrateLimit`

`useResolutionLabels`

`resolutionLabelBitrates`

コントロールのスタイリング

既知の問題

更新履歴