플레이어 UI

플레이어 UI에서는 스크립트 코드를 수정하여 UI와 관련한 옵션을 설정하는 방법을 설명합니다. 본 기능은 Classic/VPC 환경에서 사용할 수 있습니다.

옵션을 설정하는 속성에 대한 설명은 플레이어 설정을 참고하세요.
이용 중인 요금제에 따라 설정 가능한 옵션이 다를 수 있습니다.

화면 비율 (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",
                    },
                ],
            }}
        />
    );
}

컨트롤바 표시 (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",
                    },
                ],
            }}
        />
    );
}

컨트롤바 버튼 UI (controlBtn)

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

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

다국어 (lang)

플레이어에서 사용하는 언어를 설정합니다.

설정하지 않으면 브라우저에서 사용하는 언어를 따라갑니다.

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

컨트롤바 표시 시간 (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, // 기본 자막 설정
                            },
                        ],
                    },
                ],
            }}
        />
    );
}

SRT(SubRip) 자막

.vtt 대신 .srt 파일을 사용할 경우 playlist 항목의 srt 배열에 등록합니다. 구조(id / file / label / default)는 vtt 와 동일합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    hls={Hls}
    options={{
        playlist: [
            {
                file: "https://CDN도메인/example_video_01.mp4",
                srt: [
                    {
                        id: "ko",
                        file: "https://CDN도메인/example_video_01.srt",
                        label: "한국어",
                        default: true,
                    },
                    {
                        id: "en",
                        file: "https://CDN도메인/example_video_01_en.srt",
                        label: "English",
                    },
                ],
            },
        ],
    }}
/>

브라우저 <track> 은 SRT 를 native 로 파싱하지 못하므로, SDK 가 런타임에 SRT 를 fetch → WebVTT 로 변환 → Blob URL 로 만들어 내부 vtt 트랙으로 합칩니다.
변환 특성상 SRT 사용 시 자막 렌더는 자동으로 captionType: "html" (div 오버레이) 로 강제됩니다.
같은 item 에 vtt 와 srt 를 동시에 선언하면 vtt 가 우선되고 srt 는 무시됩니다 (둘 중 하나만 사용).
fetch 기반이므로 SRT 파일은 video 와 같은 origin 이거나 적절한 CORS 헤더가 있어야 합니다 (cross-origin 인데 CORS 미설정이면 자막이 로드되지 않음 — VTT <track> 직접 로드보다 제약이 큼).

자막 렌더링 방식 (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 가 제공하는 접근성 자막 환경설정을 그대로 반영하므로, 시각 보조가 필요한 사용자에게 가장 가까운 경험을 제공합니다.

// (1) 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 }],
            },
        ],
    }}
/>

// (2) 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: {
                // 자막 폰트 크기 (px 또는 %)
                pc: 18,
                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방향 외곽선, 기본 권장)

레이아웃 시스템으로 UI 커스터마이징

레이아웃 시스템을 사용하면 컨트롤바의 버튼 배치, 영역 구성, 커스텀 컴포넌트 삽입을 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",
                    },
                ],
            }}
        />
    );
}

커스텀 컴포넌트 삽입

레이아웃의 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",
                    },
                ],
            }}
        />
    );
}