プレイヤー UI

Classic/VPC環境で利用できます。

スクリプトコードを変更して UIに関連するオプションを設定する方法について説明します。

デフォルトオプション

aspectRatio(画面アスペクト比)

プレイヤー領域の画面アスペクト比を設定します。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        aspectRatio: '16/9', //アスペクト比を指定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

objectFit(全画面表示)

動画が画面領域に合わせる方法を設定します。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        objectFit: "cover", // 動画の表示方法を指定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

language(多言語)

プレイヤーで使用する言語を設定します。設定しない場合は、ブラウザで設定されている言語に従います。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        lang: "ko", // 言語設定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

コントロールバー

controls(コントロールバーの表示)

デフォルトコントロールバー UIの表示有無を設定します。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        controls: true, // コントロールバーの表示有無を設定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

controlBtn(コントロールバーボタン UI)

コントロールバーボタンの表示/非表示を個別に設定します。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        controlBtn: {
          play: true,             // 再生
          progressBar: true,      // コントロールバー
          fullscreen: true,       // 全画面表示
          volume: true,           // ボリューム
          times: true,            // 残り時間
          pictureInPicture: true, // PIP
          setting: true,          // 設定
          subtitle: true,         // 字幕
        },
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

progressBarColor(コントロールバーの色)

コントロールバーの進行状況の色を設定します。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        progressBarColor: "#2e6ae0", // コントロールバーの進捗状況の色を指定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

controlActiveTime(コントロールバーの表示時間)

コントロールバーが表示される時間を設定します。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        controlActiveTime: 3000, // コントロールバーの表示時間を設定(ms)
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

ui(コントロールバー UI固定)

UIのタイプを指定します。

• モバイル UIは touchGestures、PC UIは keyboardShortcutを提供します。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        ui: "mobile", // UIタイプを設定
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

字幕

字幕設定(VTT)

VTT字幕をリンクします。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 動画(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
            poster: "https://CDNドメイン/example_video_01.png",
            vtt: [
              {
                id: "ko",
                file: "https://CDNドメイン/example_video_01.vtt",
                label: "韓国語",
                default: true, // デフォルトの字幕設定
              },
            ],
          },
        ],
      }}
    />
  );
}

captionType(字幕のレンダリング方式)

字幕の描画方法を決定するオプションです。"html" (デフォルト)、"native"の中から選択でき、デザインの一貫性を優先するか、OSのアクセシビリティ設定を優先するかによって異なります。

htmlモード: captionStyleで直接スタイリング(デフォルト)

<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    captionType: "html", // 省略可能 — デフォルト値
    captionStyle: {
      fontSize: 20,
      color: "#FFFF00",
      edgeStyle: "uniform",
    },
    playlist: [
      {
        file: "https://CDNドメイン/example_video_01.mp4",
        vtt: [{ id: "ko", file: "https://CDNドメイン/example_video_01.vtt", label: "韓国語", default: true }],
      },
    ],
  }}
/>

nativeモード: OSのアクセシビリティ設定にある字幕設定をそのまま反映

<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    captionType: "native",
    // captionStyleは適用されない
    playlist: [
      {
        file: "https://CDNドメイン/example_video_01.mp4",
        vtt: [{ id: "ko", file: "https://CDNドメイン/example_video_01.vtt", label: "韓国語", default: true }],
      },
    ],
  }}
/>

captionStyle(字幕スタイル)

字幕のフォントサイズ、色、背景、縁取り、行間、位置などをオプションで直接設定します。captionTypeが "html" (デフォルト)の場合にのみ適用され、"native" モードでは無視されます。ブランドカラーやダークモード UIなど、一貫した字幕のスタイリングが必要な場合に利用できます。

<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [
      {
        file: "https://CDNドメイン/example_video_01.mp4",
        vtt: [
          {
            id: "ko",
            file: "https://CDNドメイン/example_video_01.vtt",
            label: "韓国語",
            default: true,
          },
        ],
      },
    ],
    captionStyle: {
      fontSize: {
        pc: 18,      // 字幕のフォントサイズ(pxまたは%)
        mobile: 14,
      },
      color: "#ffffff",
      edgeStyle: "uniform",  // テキストの縁取り(dropshadow、raised、depressed、uniform)
      bottomOffset: {
        pc: 30,      // コントロールバーと重ならないよう、もっと上へ
        mobile: 50,
      },
      sidePadding: {
        pc: 60,      // 左右の余白をもっと広く
        mobile: 40,
      },
      lineHeight: {
        pc: 1,       // 字幕の行間を狭く
        mobile: 1.2,
      },
    },
  }}
/>

captionStyleプロパティ

指定がない場合はデフォルト値が自動的に適用され、オプションが指定された場合はデフォルト値と deep-mergeされます。(例: { fontSize: 20 }さえ超えたら fontSize=20 + 残りはデフォルト値)

レスポンシブ分岐: fontSize、lineHeight、bottomOffset、sidePaddingは単一の値または { pc, mobile } オブジェクトとして指定できます。

レイアウトシステム

レイアウトシステムを使用すると、コントロールバーのボタンの配置、領域の構成、カスタムコンポーネントの挿入を、JSONベースで宣言型に定義できます。画面環境別(PC/モバイル/全画面)およびコンテンツのタイプ別(VOD/Live)に、それぞれ分けて管理できます。

デフォルトレイアウトの構成

orderでセクションの順序を決め、各セクションに Rowを配置します。Rowの itemsには、ビルトインコンポーネントやカスタム要素を配置できます。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

const layout = {
  pc: {
    vod: {
      order: ["top", "center", "bottom"],
      top: [{ items: ["MetaDesc"] }],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["ProgressBar"] },
        { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: ["SettingBtn", "PipBtn", "FullscreenBtn"], wrapper: "Group" },
      ],
    },
  },
};

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      layout={layout}
      options={{
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

レイアウトタイプ

layout propは、次の3つの形式で渡すことができます。

// 1) 単一レイアウト — ライブ/VOD/デバイスの分岐なしに、1つのコントロールバーを構成
type ControlBarLayout = {
  order?: string[];
  top?: Group[];
  upper?: Group[];
  center?: Group[];
  lower?: Group[];
  bottom?: Group[];
};

// 2) ライブ / VODを分岐
type ControlBarLayoutVariant = {
  live: ControlBarLayout;
  vod: ControlBarLayout;
};

// 3) レスポンシブ(PC / Mobile / Fullscreenを分岐)
type ControlBarLayoutResponsive = {
  pc: { live: ControlBarLayout; vod: ControlBarLayout };
  mobile: { live: ControlBarLayout; vod: ControlBarLayout };
  fullscreen: { live: ControlBarLayout; vod: ControlBarLayout };
  breakpoint?: number; // デフォルト768
};

構成構造

最上位キーは pc、mobile、fullscreenに分かれており、各環境内で vodと live のレイアウトを定義します。

{
  "pc": {
    "vod": { },
    "live": { }
  },
  "mobile": {
    "vod": { },
    "live": { }
  },
  "fullscreen": {
    "vod": { },
    "live": { }
  }
}

layout.json

セクションと順序

order 配列によってレンダリング順序が決まります。デフォルトセクションは top、upper、center、lower、bottomです。

{
  "order": ["top", "upper", "center", "lower", "bottom"],
  "top": [
    { "items": ["MetaDesc"] },
    { "wrapper": "Blank", "items": [], "align": "left" },
    { "items": ["ShareBtn"] }
  ],
  "center": [
    { "items": ["BigPlayBtn"], "align": "center" }
  ],
  "bottom": [
    { "items": ["ProgressBar"] },
    { "items": ["PlayBtn", "VolumeBtn", "TimeDisplay"], "align": "left" },
    { "items": ["SettingBtn", "PIPBtn", "FullscreenBtn"], "align": "right" }
  ]
}

pc.vod.json

行(Row)の構成

各セクションは複数の Rowで構成されています。Rowは、items 配列を通じてボタンやコンポーネントを配置し、alignおよび wrapperでソートやグループ化の方法を調整します。

デフォルトレイアウトのユースケース

各 Groupに keyを指定すると、ランタイムのマージ時に特定の Groupのみを安全に置き換えられます。

const layout: ControlBarLayout = {
  top: [],
  center: [{ key: "bigPlayBtn", items: ["BigPlayBtn"] }],
  bottom: [
    { key: "play",   items: ["PlayBtn"],    wrapper: "Group", noPadding: true },
    { key: "volume", items: ["VolumeBtn"],  wrapper: "Group" },
    { key: "time",   items: ["TimeBtn"],    wrapper: "Group" },
    { key: "blank",  wrapper: "Blank",      items: [] },
    { key: "right",  items: ["SubtitleBtn", "FullscreenBtn"], cap: 2, wrapper: "Group" },
  ],
};

カスタムコンポーネントの挿入

レイアウトの items 配列に、ビルトインキーの代わりに自作のコンポーネントを渡すことで、コントロールバー内の希望する位置にカスタム UIを配置できます。

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// カスタムロゴのコンポーネント
function Logo() {
  return (
    <div style={{ padding: "0 15px" }}>
      <a href="https://example.com" target="_blank">
        <img
          src="https://example.com/logo.webp"
          style={{ height: 24 }}
          alt="Logo">
      </a>
    </div>
  );
}

const layout = {
  pc: {
    vod: {
      order: ["top", "center", "bottom"],
      top: [{ items: ["MetaDesc"] }],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["PlayBtn", "PrevBtn", "NextBtn"], wrapper: "Group" },
        { items: ["VolumeBtn"], wrapper: "Group" },
        { items: ["TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: [Logo()], wrapper: "Group" }, // カスタムコンポーネント
        { items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"], cap: 2, wrapper: "Group" },
      ],
    },
  },
};

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      layout={layout}
      options={{
        playlist: [
          {
            file: "https://CDNドメイン/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

リアルタイム変更(ref)

playerRef.current?.layout(nextLayout, merge?) を呼び出すと、再生中でもレイアウトを動的に変更できます。2番目の引数 mergeのデフォルト値は trueです。

マージルール(merge: true)

1. top / upper / center / lower / bottom / order のうち、nextで定義されていないセクションは baseのまま維持
2. section内の Groupマージは key ベース:
   • baseと nextにある同じ keyの Group → nextに置き換え
   • baseにのみある key → baseを維持
   • nextにのみある key → 結果の末尾に append
   • nextに keyがない Group → 結果の末尾に append(新規追加とみなす)
3. 両方の Groupに keyがない場合 → section丸ごと置き換え(下位互換)

例: 特定の Groupのみ置き換え

// base (default pcLayout.vod)
// bottom: [
//   { key: "play",   items: ["PlayBtn"] },
//   { key: "volume", items: ["VolumeBtn"] },
//   { key: "time",   items: ["TimeBtn"] },
//   { key: "blank",  wrapper: "Blank", items: [] },
//   { key: "right",  items: ["SubtitleBtn", "FullscreenBtn"] },
// ]

playerRef.current?.layout({
  bottom: [{ key: "right", items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"] }],
});
// 結果: play/volume/time/blankを維持、rightのみ置き換え

例: 新しい Groupを追加

playerRef.current?.layout({
  bottom: [{ key: "extra", items: ["ShareBtn"] }],
});
// 結果: 既存の5つの Group + 末尾に extra(ShareBtn) append

例: section全体を置き換え(merge: false)

playerRef.current?.layout(
  { bottom: [{ items: ["PlayBtn"] }] },
  false, // 丸ごと置き換え
);