概要
MV パネルは、楽曲検出 で得られた曲名から YouTube Data API 経由でミュージックビデオを検索し、メイン映像の上にオーバーレイ表示するレイヤーです。MV の有無、不透明度、サイズ、表示位置、アニメ優先モード、再生タイミングのオフセットをここで管理します。MV が見つからない曲やブロック動画にあたった場合は自動で非表示になり、楽曲検出 側の次の Lookup を待つ作りです。
YouTube API は 1 日 10,000 quota の制限があるため、一度ヒットした曲は Firestore の mv_cache に保存され、同じ曲の再表示では API を消費しません。実効的にユニーク曲のみが API を消費するため、通常運用なら 1 日 99 曲前後までは安定して使えます。アニメ優先モードを ON にすると、検索結果からアニメ MV を優先的に選ぶようになり、リップシンク重視の現場で重宝します。Offset 値は曲ごとに保存されるので、一度合わせれば次回以降は調整不要です。
コントロール詳細
- 表示トグル（ヘッダー右、目アイコン）
MV オーバーレイの表示 / 非表示を切り替えます。検出処理は走り続けるので、一時的に隠したいだけのときに使用。
- MV 自動検出スイッチ（label ON）
MV 検索とロードを ON / OFF します。OFF のときはパネル全体が半透明 + 操作不可になります。
- Anime Mode スイッチ
YouTube 検索クエリにアニメ優先のヒントを足し、結果からアニメ MV を選びやすくします。MV 自動検出が OFF だと無効化。
- ステータスバッジ
Loading: 現在 YouTube API に問い合わせ中。Found: ロードに成功して再生中。Not Found: 候補なし、またはすべてブロック動画だった。Quota Exceeded: その日の API 上限に達した。
- MV タイトル表示（読み込み成功時）
ロード中の YouTube 動画タイトルを 2 行までクランプ表示。
- OPC スライダー（不透明度、warm 表示、0〜100%、5% 刻み）
MV 表示の不透明度。低くするとメイン映像と混ざり、高くすると MV が前面を支配します。
- SIZE スライダー（20〜100%、5% 刻み）
MV のサイズ比率。100% でフル画面、低くすると中央寄せの小窓表示。
- オフセットコントロール群
楽曲とのリップシンクを補正します。範囲は ±10000ms (±10 秒)。
«ボタン: -1000ms（早送り側にずらす）。‹ボタン: -100ms。- 中央の値表示: 現在のオフセット（例
+1.5s）。 ›ボタン: +100ms。»ボタン: +1000ms。Resetボタン: オフセットを 0 に戻す（自動検出 OFF や既に 0 のときは無効化）。
- 折りたたみ矢印
パネルを最小化します。
現場での使い所
MV を強く前に出したい時間帯はサイズと不透明度を上げ、歌詞を読ませたい時間帯は不透明度を下げて MV を背景化する使い分けが基本です。リップシンクが重要な楽曲では、最初の数小節で Offset を ±0.5 秒単位で詰めれば、それ以降は曲ごとの保存値が効くので調整不要になります。アニメ MV を頻繁に使うイベントは Anime Priority を常時 ON にしておくと検索ヒット率が安定します。
関連設定
このパネルは 楽曲検出 の認識結果が前提になります。MV 表示中は フィルター の HUE / BRT / SAT が肌色を壊しやすいので、MV Skin Protect を活用してください。
実運用で詰まった点や不足している説明があれば、Feedback パネルから送信できます。
自動認識や自動ローテーションなどの放置運用向け機能は Event Pass で解放されます。