Documentation Index

Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt

Use this file to discover all available pages before exploring further.

プレイヤー UI

Prev Next

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

プレイヤー UIでは、コントロールバー、ボタン、プログレスバーなど、UIに関連するオプションの設定方法について説明します。

参考
  • オプションを設定するプロパティに関する説明は、オプションリファレンスをご参照ください。
  • ご利用中の料金プランによって、設定可能なオプションが異なる場合があります。

デフォルトオプション

language(多言語)

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

const player = new ncplayer("player", {
  lang: "ko", // 言語設定("auto"、"ko"、"en")
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

コントロールバー

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

デフォルトコントロールバー UIの表示有無を設定します。falseに設定すると、コントロールバーは表示されません。

const player = new ncplayer("player", {
  controls: true, // コントロールバーの表示有無を設定
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

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

コントロールバーの個別ボタンの表示/非表示を設定します。各ボタンは true または falseで制御します。

参考

Standard料金プランでのみご利用いただけます。

const player = new ncplayer("player", {
  controlBtn: {
    play: true,             // 再生ボタン
    progressBar: true,      // プログレスバー
    fullscreen: true,       // 全画面表示ボタン
    volume: true,           // ボリュームボタン
    times: true,            // 時間表示
    pictureInPicture: true, // PIP設定
    setting: true,          // 設定ボタン
    subtitle: true,         // 字幕ボタン
  },
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

controlBtnプロパティ

プロパティ タイプ デフォルト値 説明
play boolean true 再生/一時停止ボタン
progressBar boolean true プログレスバー
fullscreen boolean true 全画面表示ボタン
volume boolean true ボリュームボタン
times boolean true 再生時間表示
pictureInPicture boolean true Picture-In-Picture(PIP)ボタン
setting boolean true 設定ボタン
subtitle boolean true 字幕ボタン

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

コントロールバーの進捗状況の色を、CSSの色値で設定します。

参考

Standard料金プランでのみご利用いただけます。

const player = new ncplayer("player", {
  progressBarColor: "#2e6ae0", // コントロールバーの進捗状況の色を指定
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

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

コントロールバーが自動的に非表示になるまでの時間をミリ秒(ms)単位で設定します。デフォルト値は 3000(3秒)です。

参考

controlActiveTime: 0 に設定すると、コントロールバーは自動的に非表示にならず常に表示されます。ライブコマースのように、UIが常に表示される必要がある画面で役立ちます。

const player = new ncplayer("player", {
  controlActiveTime: 5000, // コントロールバーの表示時間を設定(ms)
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

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

UIのタイプを指定します。設定しない場合は、ブラウザの幅やデバイスに応じて自動的に切り替えます。

参考

Standard料金プランでのみご利用いただけます。

  • モバイル UIは touchGestures、PC UIは keyboardShortcutを提供します。
const player = new ncplayer("player", {
  ui: "mobile", // UIタイプを設定("auto"、"pc"、"mobile")
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

レイアウトシステム

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

参考
  • Standard料金プランでのみご利用いただけます。
  • レイアウトの JSONは、UI Editorで視覚的に編集し、その結果をそのままコードに反映させることができます。詳細な構造やプロパティについては、レイアウトシステムガイドをご参照ください。

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

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

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" },
      ],
    },
  },
};

const player = new ncplayer("player", {
  layout: layout,
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

構成構造

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

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

セクションと順序

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", "TimeBtn"], "align": "left" },
    { "items": ["SettingBtn", "PipBtn", "FullscreenBtn"], "align": "right" }
  ]
}

行(Row)の構成

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

キー タイプ 説明
items string[] Rowに配置するコントロールリスト
align left | center | right Row内のコンテンツのソート方法
wrapper string Rowに適用するラッパータイプ(例: Group、Blank)
cap number Row内の表示アイテム数を制限

使用可能なレイアウトアイテム

PlayBtn VolumeBtn TimeBtn SubtitleBtn FullscreenBtn SettingBtn PipBtn MetaDesc BigPlayBtn SeekBar SettingModal DurationBtn SkipForwardBtn SkipBackBtn CurrentTimeBtn MuteBtn PrevBtn NextBtn NextPrevBtn ShareBtn Blank

カスタム HTML要素の挿入

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

// カスタムロゴの HTML
const Logo = `
  <div style="padding:0 15px;">
    <a href="https://example.com" target="_blank">
      <img src="https://example.com/logo.webp" style="height:24px;" 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" }, // カスタム HTML
        { items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"], cap: 2, wrapper: "Group" },
      ],
    },
  },
};

const player = new ncplayer("player", {
  layout: layout,
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

ランタイムレイアウトの変更

player.layout() メソッドを使用すると、再生中でもレイアウトを動的に変更できます。

// 新しいレイアウトに変更
player.layout({
  pc: {
    vod: {
      order: ["center", "bottom"],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: ["FullscreenBtn"], wrapper: "Group" },
      ],
    },
  },
});

全 HTMLのユースケース

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE Player - レイアウトシステム</title>

  <!-- hls.js / dash.jsを VPEスクリプトよりも先にロード -->
  <script src="https://player.vpe.naverncp.com/lib/js/hls.min.js"></script>
  <script src="https://player.vpe.naverncp.com/lib/js/dash.all.min.js"></script>
  <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
  <div id="video" style="max-width: 800px; margin: 0 auto;"></div>
  <button id="btn-layout1">Layout 1</button>
  <button id="btn-layout2">Layout 2</button>

  <script>
    var Logo = '<div style="padding:0 15px;"><a href="https://www.ncloud.com" target="_blank"><img src="https://player.vpe.naverncp.com/images/ncp-logo-white.webp" style="height:24px;" /></a></div>';

    var layout1 = {
      pc: {
        vod: {
          order: ["top", "center", "bottom"],
          top: [{ items: ["MetaDesc"] }],
          center: [{ items: ["BigPlayBtn"], align: "center" }],
          bottom: [
            { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
            { wrapper: "Blank", items: [] },
            { items: [Logo], wrapper: "Group" },
            { items: ["SettingBtn", "FullscreenBtn"], wrapper: "Group" },
          ],
        },
      },
    };

    var layout2 = {
      pc: {
        vod: {
          order: ["center", "bottom"],
          center: [{ items: ["BigPlayBtn"], align: "center" }],
          bottom: [
            { items: ["PlayBtn", "VolumeBtn"], wrapper: "Group" },
            { wrapper: "Blank", items: [] },
            { items: ["FullscreenBtn"], wrapper: "Group" },
          ],
        },
      },
    };

    var player = new ncplayer("video", {
      playlist: [
        {
          file: "https://CDN_DOMAIN/example.m3u8",
          poster: "https://CDN_DOMAIN/poster.jpg",
        },
      ],
      autostart: true,
      muted: true,
      layout: layout1,
    });

    document.getElementById("btn-layout1").addEventListener("click", function() {
      player.layout(layout1);
    });

    document.getElementById("btn-layout2").addEventListener("click", function() {
      player.layout(layout2);
    });
  </script>
</body>
</html>
事業者登録番号: 129-86-31394 通信販売業申告番号:第2009-京畿城南-0510号
代表取締役: キム・ユウォン アドレス: 13561 京畿道 城南市 盆唐区 仏亭路6 グリーンファクトリー, 17~26F お客様センターの代表電話: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.