기본 사용법

React / Next.js 환경에서 VPE 플레이어를 사용하는 방법을 설명합니다.

React / Next.js

VpePlayer 컴포넌트를 import하고 필수 props를 전달합니다.

app/player/page.tsx

"use client";

import Hls from "hls.js";
import { VpePlayer, type PlayerHandle } from "@sgrsoft/vpe-react-sdk";
import { useRef } from "react";

export default function PlayerPage() {
    const playerRef = useRef<PlayerHandle>(null);

    return (
        <div style={{ maxWidth: "800px", margin: "0 auto" }}>
            <VpePlayer
                ref={playerRef}
                hls={Hls}
                accessKey="YOUR_ACCESS_KEY"
                options={{
                    playlist: [
                        {
                            file: "https://example.com/video/master.m3u8",
                            poster: "https://example.com/poster.jpg",
                            description: {
                                title: "영상 제목",
                                profile_name: "채널명",
                            },
                        },
                    ],
                    autostart: true,
                    muted: true,
                    aspectRatio: "16/9",
                }}
            />
        </div>
    );
}

필수 Props

Prop	타입	설명
hls	typeof Hls	hls.js 모듈 (HLS 재생 시 필수)
accessKey	string	네이버클라우드 Access Key
options	PlayerOptions	플레이어 옵션 객체

선택 Props

Prop	타입	설명
ref	Ref<PlayerHandle>	플레이어 제어 핸들 (메서드 호출용)
dashjs	typeof dashjs	dashjs 모듈 (DASH 재생 시)
layout	LayoutConfig	커스텀 레이아웃 설정
platform	string	플랫폼 구분 ("pub" 등)
hlsConfig	Record<string, unknown>	hls.js 생성자에 그대로 전달되는 추가 설정 (SDK 기본값보다 우선 적용)
dashConfig	Record<string, unknown>	dashjs updateSettings()에 그대로 전달되는 추가 설정

스트리밍 엔진 설정 (hlsConfig / dashConfig)

hlsConfig,dashConfig prop으로 버퍼링·ABR 등 스트리밍 엔진(hls.js / dashjs)의 세부 동작을 직접 조정할 수 있습니다. 두 값은 각 엔진에 그대로 전달(패스스루)되며, SDK 기본값보다 뒤에 병합되어 우선 적용됩니다.

hlsConfig: hls.js 생성자(new Hls(config))에 병합됩니다. 설정 가능한 키는 hls.js 공식 문서를 참고하세요.
dashConfig: dashjsplayer.updateSettings()에initialize() 이전에 적용됩니다.

import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export default function PlayerPage() {
    return (
        <VpePlayer
            hls={Hls}
            dashjs={dashjs}
            accessKey="YOUR_ACCESS_KEY"
            // hls.js 생성자에 전달되는 추가 설정 (HLS 재생 시)
            hlsConfig={{
                abrBandWidthUpFactor: 0.5,
                maxBufferLength: 60,
                capLevelToPlayerSize: true,
            }}
            // dashjs updateSettings()에 전달되는 추가 설정 (DASH 재생 시)
            dashConfig={{
                streaming: {
                    abr: {
                        autoSwitchBitrate: { video: true },
                    },
                },
            }}
            options={{
                playlist: [
                    {
                        file: "https://example.com/video/master.m3u8",
                    },
                ],
            }}
        />
    );
}

잘못된 설정값이 전달되어도 재생 자체는 중단되지 않도록 방어 처리되어 있으나, 엔진 동작에 직접 영향을 주므로 각 엔진 문서의 유효한 키/값을 확인하고 사용하세요.

레이아웃 커스텀

layout prop으로 플레이어 UI를 커스터마이징할 수 있습니다. 레이아웃은 pc, mobile, fullscreen 환경별로 독립 정의됩니다.

layout.json

{
    "pc": {
        "vod": {
            "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"
                }
            ]
        }
    }
}

레이아웃 JSON은 UI Editor에서 시각적으로 편집할 수도 있습니다.