Player UI

Available in Classic and VPC

Player UI explains how to configure options related to the control bar, buttons, progress bar, and other UI elements.

Default option

Language (multilingual)

Set the language used in the player. If not set, it follows the language used in the browser.

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

Control bar

controls (show control bar)

Set whether to display the default control bar UI. If set to false, the control bar will not be displayed.

const player = new ncplayer("player", {
  controls: true, // Set whether to display the control bar
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

controlBtn (control bar button UI)

Set whether to show or hide individual buttons in the control bar. Control each button with true or false.

const player = new ncplayer("player", {
  controlBtn: {
    play: true,             // Playback button
    progressBar: true,      // Progress bar
    fullscreen: true,       // Full screen button
    volume: true, // Volume button
    times: true,            // Time display
    pictureInPicture: true, // PIP button
    setting: true,          // Settings button
    subtitle: true,         // Subtitle button
  },
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

controlBtn property

progressBarColor (control bar color)

Set the color of the control bar progress bar using a CSS color value.

const player = new ncplayer("player", {
  progressBarColor: "#2e6ae0", // Specifies the control bar progress color
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

controlActiveTime (control bar display duration)

Set the time until the control bar automatically hides, in milliseconds (ms). The default value is 3000 (3 seconds).

const player = new ncplayer("player", {
  controlActiveTime: 5000, // Control bar display duration setting (ms)
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

UI (fix control bar UI)

Designate the UI type. If not set, it will automatically switch depending on the browser width or device.

• The mobile UI provides touchGestures, while the PC UI provides keyboardShortcut.

const player = new ncplayer("player", {
  ui: "mobile", // UI type setting ("auto", "pc", "mobile")
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

Layout system

By using the layout system, you can declaratively define the placement of control bar buttons, area composition, and insertion of custom components based on JSON. You can separately manage screen environments (PC/mobile/Full screen) and content types (VOD/Live).

Default layout configuration

Use to order define the section order, and place rows in each section. You can insert built-in components or custom elements into the items of a row.

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

Configuration structure

The top-level keys are divided into pc, mobile, and fullscreen, and each environment defines the vod and live layouts.

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

Section and sequence

The order array determines the rendering order. The default sections are top, upper, center, lower, and 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 configuration

Each section is composed of multiple rows. A row places buttons or components through an items array, and adjusts alignment and grouping using align and wrapper.

Available layout items

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

Insert custom HTML element

If you pass HTML strings instead of built-in keys to the items array of the layout, you can place custom UI at the desired position within the control bar.

// Custom logo 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" }, // Custom 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",
    },
  ],
});

Runtime layout change

By using the player.layout() method, you can dynamically change the layout even during playback.

// Change to a new 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" },
      ],
    },
  },
});

Full HTML example

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE Player - layout system</title>

  <!-- Load hls.js/dash.js before the VPE script -->
  <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>