플레이어 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/디바이스 분기 없이 하나의 컨트롤바 구성
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?)를 호출해 재생 중에도 레이아웃을 동적으로 변경할 수 있습니다. 두 번째 인자 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, // 통째로 교체
);