레이아웃 시스템

VPE 2.0의 레이아웃 시스템은 JSON으로 컨트롤바, 버튼 배치, 영역 구성을 선언적으로 정의합니다. 화면 환경별(PC/모바일/전체화면)과 콘텐츠 유형별(VOD/Live)을 각각 분리해 관리할 수 있습니다.

인터랙티브 데모

아래 버튼으로 레이아웃을 전환하여 컨트롤바 구성의 차이를 확인해 보세요.

구성 구조

최상위 키는 pc, mobile, fullscreen으로 나뉘며, 각 환경 내부에 vod와 live 레이아웃을 정의합니다.

layout.json

{
    "pc": {
        "vod": { ... },
        "live": { ... }
    },
    "mobile": {
        "vod": { ... },
        "live": { ... }
    },
    "fullscreen": {
        "vod": { ... },
        "live": { ... }
    }
}

섹션과 순서

order 배열이 렌더링 순서를 결정합니다. 기본 섹션은 top, upper, center, lower, bottom입니다.

pc.vod.json

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

행(Row) 구성

각 섹션은 여러 개의 Row로 구성됩니다. Row는 items 배열을 통해 버튼이나 컴포넌트를 배치하고, align과 wrapper로 정렬과 묶음 방식을 조정합니다.

키	타입	설명
items	string[]	Row에 배치할 컨트롤 목록
align	left \| center \| right	Row 내 컨텐츠 정렬 방식
wrapper	string	Row에 적용할 래퍼 타입(예: Group, Blank)
cap	number	Row 내 표시 아이템 수 제한

React 적용

레이아웃 JSON은 layout prop으로 전달합니다. React에서는 커스텀 컴포넌트를 함수 호출 형태로 주입할 수 있습니다.

app/player/page.tsx

"use client";

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

function Logo() {
    return (
        <div style={{ padding: "0 15px" }}>
            <a href="https://www.ncloud.com/v2/product/media/videoPlayerEnhancement" target="_blank">
                <img
                    src="https://player.vpe.naverncp.com/images/ncp-logo-white.webp"
                    style={{ height: 24 }}
                    alt="NCloud"
                />
            </a>
        </div>
    );
}

const vpeLayout = {
    pc: {
        vod: {
            order: ["top", "upper", "center", "seekbar", "lower", "bottom"],
            top: [{ items: ["MetaDesc"] }],
            upper: [],
            center: [{ items: ["BigPlayBtn"], align: "center" }],
            lower: [],
            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 default function PlayerPage() {
    return (
        <VpePlayer
            hls={Hls}
            accessKey="YOUR_ACCESS_KEY"
            layout={vpeLayout}
            options={{
                playlist: [
                    {
                        file: "https://example.com/video/master.m3u8",
                        poster: "https://example.com/poster.jpg",
                    },
                ],
            }}
        />
    );
}

UMD / HTML 적용

UMD 환경에서는 HTML 문자열을 그대로 레이아웃 아이템으로 전달할 수 있습니다.

index.html

const Logo = `
    <div style="padding:0 15px;">
        <a href="https://www.ncloud.com/v2/product/media/videoPlayerEnhancement" target="_blank">
            <img src="https://player.vpe.naverncp.com/images/ncp-logo-white.webp" style="height:24px;"/>
        </a>
    </div>`;

const vpeLayout = {
    pc: {
        vod: {
            order: ["top", "upper", "center", "seekbar", "lower", "bottom"],
            top: [{ items: ["MetaDesc"] }],
            upper: [],
            center: [{ items: ["BigPlayBtn"], align: "center" }],
            lower: [],
            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" },
            ],
        },
    },
};

window.vpeLayout = vpeLayout;

UI Editor 활용

레이아웃 JSON은 UI Editor에서 시각적으로 편집하고 결과 JSON을 그대로 적용할 수 있습니다.