플레이어 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)

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

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: [
                            {
                                file: "https://CDN도메인/example_video_01.vtt",
                                label: "한국어",
                                language: "ko",
                                default: true, // 기본 자막 설정
                            },
                        ],
                    },
                ],
            }}
        />
    );
}

레이아웃 시스템으로 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",
                    },
                ],
            }}
        />
    );
}