YTPlayerのオプションを完全マスターしよう。出来ること。

Youtubeの動画を背景に指定できるjQueryのプラグイン「YTPlayer」。クライアントからちょこちょこ背景に動画を入れてみたいという要望がくるので、YTPlayerをマスターしておこうと思います。
本記事は初心者向けではなく、jQueryのプラグインに慣れた中級以上の方を対象にしています。「ウェブページの背景を動画にしたい」といったような初歩的なFAQは他のサイトを参考にしてください。

YTPlayerは要素の背景に指定できるので番組テロップ風の装飾をHTMLとCSSで付けれますね。
↓の記事はNスタ風テロップをHTMLとCSSで実装したものです。見てみてください。

前提：オプションの記載はHTMLタグの中に書く仕様
YTPlayerのオプションを使って何ができるか
「ratio」
1. 「quality」
その他のオプション
Chromeのデベロッパーツールを開くとYTPlayerの動画が止まるのを阻止したい場合
YTPlayer動画にフィルターをかけてオシャレにしたい場合
まとめ

前提：オプションの記載はHTMLタグの中に書く仕様

ご存知だと思いますが、YTPlayerのオプションは一般的なjQueryプラグインとは多少異なり、メソッド（コンストラクタ？）の引数に書くのではなく、HTMLのタグにdata-propertyとして、data属性に記載します。
よくあるプラグインでは、例えば

$('.className').plugIn({
  option: 1,
  option_sub: false
});

のように、プラグインの関数の引数に配列で渡すことが多いですね。しかし、このYTPlayerはちょっと違ってオプションを<html>内の任意のタグに記載する仕様となっています。次に例を挙げますのでなんとなく理解していただけるかなと思います。

 <div id="videoPlay" data-property="{
			videoURL: 'https://youtu.be/uD3W0pJw6Io',
			containment: 'body',
			mute: true,
			loop: true,
			autoPlay: true,
			startAt: 0,
			stopMovieOnBlur: false,
			opacity: 0.5,
			showControls: false,
			showYTLogo: false,
			abundance: 0.01
		}"> </div>

<div id=”videPlay”>タグの中に「data-property=」として、data属性（プロパティ）にオプションを記載しています。
では早速使用可能なオプションを見ていきましょう。

YTPlayerのオプションを使って何ができるか

YTPlayerのオプションは公式に明記されているのですが、英語で拒絶反応が出る方もいらっしゃるかと思います。なので分かりやすく日本語に訳してそれぞれの項目を見てみましょう。全部見れば、YTPlayerで出来ること、出来なことが明確になるはずです。ちょっと量が多いのでご自身の興味のある項目以外は読み飛ばしていただいて構いません。

※以下「true（ブール値）」「false（ブール値）」となっている箇所は【初期値（boolian型だよ）】という意味です。

「mute」

：true（ブール値）オーディオをミュートします。

muteについてみてみましょう。特に問題ないかと思います。補足としては「true」と書いたのは初期値のことです。デフォルトではミュートされているので、いきなり音楽が鳴って「ギャォス！」ってならなくてよいとうことですね。ちなみに音を鳴らしたいときは、

 <div id="videoPlay" data-property="{
			videoURL: 'https://youtu.be/uD3W0pJw6Io',
			mute: false
		}"> </div>

上記のようにmute: falseを指定してあげればOKです。

「useOnMobile」

：true（ブール値）プレーヤーをモバイルデバイスで表示するかどうかを定義します。

これは実際にやってみてiPhoneやAndroidの実機で見た方が理解できるでしょう。ちょっと作ってみます。

 <div id="videoPlay01" data-property="{
  videoURL: 'https://youtu.be/uD3W0pJw6Io',
  containment: '.video-wrapper',
  mute: true,
  useOnMovile: true,
  ratio: '16/9'
  }"> </div>
</div>

YTPlayer DEMO – QooTechWEB

↑QRコードを読み混んでスマホで確認してみてください。

こんな感じでブロック単位で背景にYoutube動画を指定できました。今度は「useOnMobile」をfalseにしてスマホでは動画表示しない設定にしてみましょう。

YTPlayer DEMO – QooTechWEB

↑QRコードを読み混んでスマホで確認してみてください。

はい、useOnMobile: false,を指定することで動画が表示されず真っ白になりました。

「mobileFallbackImage」

：画像へのパス（string）モバイルでバックグラウンドビデオがあり、「useOnMobile」オプションがfalseに設定されている場合のフォールバック画像へのパス。

 <div id="videoPlay01-3" data-property="{
  videoURL: 'https://youtu.be/hGiDUUrcDEI',
  containment: '.video-wrapper-no2',
  mute: true,
  useOnMobile: false,
  ratio: '16/9',
  mobileFallbackImage: 'https://engineering.webstudio168.jp/sample/YTPlayer/dist/cover.jpg'
  }"> </div>
</div>

YTPlayer DEMO – QooTechWEB

↑QRコードを読み混んでスマホで確認してみてください。

あれ、画像にならないですね。githubのissueにも動作しない人がいるようなのでjqueryのバージョン違いとかその辺の不具合かもしれません。時間があったら詳しく見てみます。

「coverImage」

：画像パス。自動再生がfalseに設定されている場合、プレーヤーの背景として使用される画像へのパス。設定されていない場合、プレーヤーは最初のフレームを表示します。

背景にYoutubeを使う場合にはあんまり使わなそうですが、自動再生がOFFの時に表示する画像を指定することが出来ます。自動再生のオプションautoPlayがfalseに指定されている必要がありますね。

「ratio」

：アスペクト比を設定するための「4/3」、「16/9」、または「auto」（文字列）。「自動」の場合、アスペクト比はgetDataFromFeedメソッドから取得されます。

動画の比率を指定することが出来ます。基本はautoで良いかと思いますが、指定が必要な場合は下記のように記述します。

 <div id="videoPlay01" data-property="{
  videoURL: 'https://youtu.be/uD3W0pJw6Io',
  containment: '.video-wrapper',
  ratio: '16/9'
  }"> </div>

16:9はratio: ’16/9’で指定します。実際に入れてみると次のように動作します。

YTPlayer DEMO – QooTechWEB

↑QRコードを読み混んでスマホで確認してみてください。

4:3の指定をしてみましょう。

YTPlayer DEMO – QooTechWEB

↑QRコードを読み混んでスマホで確認してみてください。

背景の動画の見え方が変わりました。比率が変わるので動画が壊れるかと思ったのですが、何か綺麗に表示されてますね。Chromeのデベロッパーツールで見ると、生成されている<iframe>の比率が4:3で指定されています。でも<iframe>の親にoverflow: hidden;があるのであんまり実感がわかない仕様みたいですね…

「quality」

品質パラメータはYTAPIで非推奨になり、これ以上使用されることはありません。 YouTubeは、視聴条件に基づいてビデオストリームの品質を調整します。

動画の品質はYoutube APIで非推奨になったため、YTPlayerでは利用できなくなりました。指定しても通信状況で自動的に指定されるので諦めましょう。

その他のオプション

記事が長くなってきて心が折れ始めてきたので、その他のオプションは表形式にまとめておきます。

opacity	0から1（数値）は、ビデオの不透明度を定義します。
containment	（文字列）ビデオの背景が必要なDOM要素のセレクター。指定されていない場合は、「body」。「self」に設定されている場合、プレーヤーはその要素にインスタンス化されます。
optimizeDisplay	true（ブール値）は、ビューを最適化するウィンドウサイズにビデオサイズを適合させます。
loop	false（ブール値）または終了後にビデオがループする回数を表す数値。
vol	1〜100（数字）で動画の音量レベルを設定します。
startAt	20（数値）ビデオを開始する秒数を設定します。
stopAt	20（数値）ビデオが停止する秒数を設定します。 0が無視される場合。
remember_last_time	true（ブール値）trueの場合、ブラウザのタブ移動などで停止された時に同じ場所から再開されます。
showYTLogo	true（ブール値）Youtubeロゴと元のビデオURLへのリンクを表示または非表示にします。
addRaster	false（ブール値）ビデオ上でラスター画像を表示または非表示にします。
mask	「path/to/ mask」またはfalse。オブジェクトも指定可能。{0：「path / to / mask1」、20：「path / to / mask2」、…} ⇒バージョン3.0から。指定された時間ごとに、プレーヤーまたはマスクのマップにマスクを追加します。
realfullscreen	true（ブール値）は、新しいHTML5フルスクリーン動作をアクティブにします。
stopMovieOnBlur	true（ブール値）は、ウィンドウのフォーカスが失われたときに一時停止動作をアクティブにします。
playOnlyIfVisible	false（ブール値）は、プレーヤーが画面外にあるときに一時停止動作をアクティブにします。
gaTrack	true（ブール値）は、そのプレーヤーのGoogleAnalyticsイベントトラッカーをアクティブにします。
anchor	‘center、center’（文字列）バージョン3.0.3以降。ウィンドウのサイズが変更された後のビデオの動作を定義します。可能な値は次のとおりです。「上、下、左、右、中央」。カンマ区切りの値のペアを受け入れます（例：「top、right」または「bottom、left」）。
showAnnotations	false（ブール値）プレーヤーが注釈を表示するかどうかを定義します。
cc_load_policy	false（ブール値）プレーヤーが字幕を表示するかどうかを定義します。
abundance	0.2（フロート）は、アバンダンスとして追加するサイズのパーセンテージを定義します。※アバンダンスは余白とほぼ同義だと思われます（筆者追記）
useNoCookie	true（bool）https://www.youtube-nocookie.comホストを使用してビデオを提供します。
onReady	（関数）プレーヤーの準備ができたら起動される関数を渡すことができます。 YTPlayerオブジェクトをパラメーターとして渡します。
onError	（関数）ビデオの読み込み中にエラーが発生した場合に起動される関数を渡すことができます。 YTPlayerオブジェクトとエラーをパラメーターとして渡します。

Chromeのデベロッパーツールを開くとYTPlayerの動画が止まるのを阻止したい場合

開発側からするとデベロッパーツールを開くときに動画が止まってしまって、スマホの検証が出来なくて困る場合があります。

そんなときは、上に挙げた「stopMovieOnBlur」がデフォルトでtrueになってしまっているので、「stopMovieOnBlur: false」をオプションとして指定してあげるとスマホ検証がスムースになります。

YTPlayer動画にフィルターをかけてオシャレにしたい場合

YTPlayerにはフィルターをかける機能があります。動画をモノクロにしたり、セピア色にしたり、青味がけたりカラーリングエフェクトがかけられます。※ただし、古いバージョンだとこの機能はないのでバージョンアップが必要になります。

サンプルコードを見た方が早いので見てみましょう。

  $(function () {
    var myPlayer = $('#videoPlay').YTPlayer({
      onReady: function (player) {
        let filters = {
          sepia: 100,
          hue_rotate: 220
        }
      myPlayer.YTPApplyFilters(filters)
      }
    });
  });

オプションの「onReady」を使って「YTApplyFilters」を実行することでフィルターを書けることが出来ます。これを実行すると次のようなおしゃれな背景動画の出来上がりです。

YTPlayer DEMO – QooTechWEB

↑QRコードを読み混んでスマホで確認してみてください。

YTPApplyFiltersに使えるパラメータをまとめておきます。

grayscale	グレースケール	1-100
hue_rotate	色相回転	1-360
invert	反転	1-100
opacity	不透明度	1-100
saturate	彩度	1-400
sepia	セピア	1-100
brightness	輝度	1-400
contrast	コントラスト	1-400
blur	ぼかし	1-100

まとめ

githubを確認したところ、最終コミットが2022年の1月ですので、まだまだ開発が続いているYTPlayerです。結構いろんなところで使われているのでフロントエンドエンジニアは押さえておいた方が吉だと思われます。オプションを書く場所が<html>タグだったり、フィルターを追加する際にはJavaScriptに書いたりと少しクセがありますが便利です。ただ、デザイン調整が難しいプラグインかなぁという感想です。まだまだ使っていけるプラグインなのは間違いないでしょう。

全画面表示のサンプルは別途載せていますのでそちらでご確認ください。https://engineering.webstudio168.jp/sample/YTPlayer/

サンプルで使った僕の愛猫のくぅちゃんのYoutubeチャンネルもよろしく！