플레이어 UI

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로 제어합니다.

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 속성

progressBarColor (컨트롤바 색상)

컨트롤바 진행 바의 색상을 CSS 색상값으로 설정합니다.

const player = new ncplayer("player", {
  progressBarColor: "#2e6ae0", // 컨트롤바 진행 색상 지정
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

controlActiveTime (컨트롤바 표시 시간)

컨트롤바가 자동으로 숨겨지기까지의 시간을 밀리초(ms) 단위로 설정합니다. 기본값은 3000(3초)입니다.

const player = new ncplayer("player", {
  controlActiveTime: 5000, // 컨트롤바 표시 시간 설정(ms)
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});

ui (컨트롤바 UI 고정)

UI 타입을 지정합니다. 설정하지 않으면 브라우저 가로폭이나 기기에 따라 자동 전환됩니다.

• 모바일 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)을 각각 분리해 관리할 수 있습니다.

기본 레이아웃 구성

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로 정렬과 묶음 방식을 조정합니다.

사용 가능한 레이아웃 아이템

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>