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

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

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)

컨트롤바 버튼 표시/숨김을 개별적으로 설정합니다.

참고

Standard 요금제에서만 사용할 수 있습니다.

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 (컨트롤바 색상)

컨트롤바 진행 색상을 설정합니다.

참고

Standard 요금제에서만 사용할 수 있습니다.

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 (컨트롤바 표시 시간)

컨트롤바가 표시되는 시간을 설정합니다.

참고

controlActiveTime: 0 으로 설정하면 컨트롤바가 자동으로 숨겨지지 않고 항상 표시됩니다. 라이브커머스처럼 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={{
        controlActiveTime: 3000, // 컨트롤바 표시 시간 설정(ms)
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}

ui (컨트롤바 UI 고정)

UI 타입을 지정합니다.

참고

Standard 요금제에서만 사용할 수 있습니다.

  • 모바일 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" (기본) "native"
렌더링 주체 SDK가 플레이어 위에 직접 <div>로 자막을 그림 브라우저/OS의 기본 ::cue 렌더링을 사용
captionStyle 옵션 모두 적용됨 (인라인 스타일로 직접 제어) 무시됨 (브라우저별 ::cue 지원 차이로 일관된 스타일링 불가)
OS 접근성 자막 설정 영향 없음 (모바일 네이티브 자막 UI는 track.mode="hidden"으로 차단되어 일관된 스타일이 유지됨) 그대로 반영됨 (iOS 설정 > 손쉬운 사용 > 자막 및 자막 사용, Android 설정 > 접근성 > 자막 환경설정을 그대로 따라감)
추천 케이스 디자인 일관성 우선 (다크모드 UI, 브랜드 컬러 자막 등) 웹 접근성 우선 (시각 보조 정책상 OS 접근성 설정을 반드시 따라가야 하는 서비스)
참고

웹 접근성(WCAG) 가이드라인에 따라 자막 글꼴, 크기, 색상은 사용자가 직접 조정할 수 있어야 합니다. captionType: "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 } 객체로 지정할 수 있습니다.

속성 타입 기본값 설명
fontSize number | string | { pc?, mobile? } { pc: 20, mobile: 14 } 자막 폰트 크기 (px/CSS 단위). PC/모바일 분기 지원
fontFamily string — 자막 폰트 (CSS font-family)
color string #ffffff 자막 글자 색상 (CSS 색상값)
backgroundColor string transparent 자막 박스 배경색. 예: rgba(0,0,0,0.4)
opacity number 1 자막 텍스트 전체 불투명도 (0~1)
lineHeight number | string | { pc?, mobile? } { pc: 1.3, mobile: 1.2 } 자막 행간 (배수). PC/모바일 분기 지원
edgeStyle none | dropshadow | raised | depressed | uniform uniform 텍스트 가장자리 처리 방식 (밝은/어두운 영상 모두 가독성 우수)
bottomOffset number | { pc?, mobile? } { pc: 30, mobile: 10 } 플레이어 하단으로부터 간격 (px). 컨트롤바와 겹치지 않게 조정. PC/모바일 분기 지원
sidePadding number | { pc?, mobile? } { pc: 60, mobile: 40 } 좌/우 안전 영역 (px). PC/모바일 분기 지원
padding number | string 3px 5px 자막 텍스트 박스 내부 패딩 (CSS padding 값)
참고

edgeStyle 종류: none (효과 없음) / dropshadow (그림자) / raised (솟아 보이는 효과) / depressed (들어가 보이는 효과) / uniform (4방향 외곽선, 기본 권장)

레이아웃 시스템

레이아웃 시스템을 사용하면 컨트롤바의 버튼 배치, 영역 구성, 커스텀 컴포넌트 삽입을 JSON 기반으로 선언적으로 정의할 수 있습니다. 화면 환경별(PC/모바일/전체화면)과 콘텐츠 유형별(VOD/Live)을 각각 분리해 관리할 수 있습니다.

참고
  • Standard 요금제에서만 사용할 수 있습니다.
  • 레이아웃 JSON은 UI Editor에서 시각적으로 편집하고 결과를 그대로 코드에 적용할 수 있습니다. 자세한 구조와 속성은 레이아웃 시스템 가이드를 참조해 주십시오.

기본 레이아웃 구성

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/디바이스 분기 없이 하나의 컨트롤바 구성
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로 정렬과 묶음 방식을 조정합니다.

키 타입 설명
key string Group 식별자. 런타임 layout() 머지 시 같은 key의 Group끼리 교체 (권장)
items (string | ReactNode)[] Row에 배치할 컨트롤 목록 (빌트인 키 또는 커스텀 컴포넌트)
align left | center | right Row 내 콘텐츠 정렬 방식
wrapper "Group" | "Blank" Row에 적용할 래퍼 타입 (Group=묶음, Blank=빈 공간/간격)
cap number Row 내 표시 아이템 수 제한
noPadding boolean Group 좌우 패딩 제거

기본 레이아웃 예제

각 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?)를 호출해 재생 중에도 레이아웃을 동적으로 변경할 수 있습니다. 두 번째 인자 merge의 기본값은 true입니다.

머지 규칙 (merge: true)

  1. top / upper / center / lower / bottom / order 중 next에 정의되지 않은 section은 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, // 통째로 교체
);
Business Registration Number: 129-86-31394 E-commerce Permit Number:No. 2009-GyeonggiSeongnam-0510
CEO: Kim Yuwon Address: NAVER Green Factory 17th–26th Floors, Buljeong-ro 6, Bundang-gu, Seongnam-si, Gyeonggi-do 13561, Republic of Korea. Customer Support Number: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.