기본 사용법

React / Next.js와 UMD(CDN) 환경에서 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" 등)

UMD / HTML

빌드 도구 없이 스크립트 태그로 사용하는 방법입니다.

index.html

<!DOCTYPE html>
<html lang="ko">
<head>
    <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key={YOUR_ACCESS_KEY}"></script>
</head>
<body>
    <div id="player" style="max-width: 800px; margin: 0 auto;"></div>

    <script>
        const player = new ncplayer("player", {
            playlist: [
                {
                    file: "https://example.com/video/master.m3u8",
                    poster: "https://example.com/poster.jpg",
                },
            ],
            autostart: true,
            muted: true,
            aspectRatio: "16/9",
        });
    </script>
</body>
</html>

레이아웃 커스텀

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에서 시각적으로 편집할 수도 있습니다.