레이아웃 시스템

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

{
    "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 내 표시 아이템 수 제한

사용 가능한 레이아웃 아이템

PlayBtnVolumeBtnTimeBtnSubtitleBtnFullscreenBtnSettingBtnPipBtnMetaDescBigPlayBtnSeekBarSettingModalDurationBtnSkipForwardBtnSkipBackBtnCurrentTimeBtnMuteBtnPrevBtnNextBtnNextPrevBtnShareBtnBlank

UMD / HTML 적용

UMD 환경에서는 레이아웃 JSON을 layout 옵션으로 전달합니다. 커스텀 HTML 요소를 items 배열에 문자열로 직접 삽입할 수 있습니다.

// 커스텀 HTML 요소 정의
const Logo = `
    <div style="padding:0 15px;">
        <a href="https://www.ncloud.com" 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" },
            ],
        },
    },
};

const player = new ncplayer("video", {
    playlist: [
        {
            file: "https://CDN_DOMAIN/example.m3u8",
            poster: "https://CDN_DOMAIN/poster.jpg",
        },
    ],
    layout: vpeLayout,
});

런타임 레이아웃 변경

player.layout() 메서드를 사용하면 재생 중에도 레이아웃을 동적으로 변경할 수 있습니다.

// 새 레이아웃으로 변경
player.layout({
    pc: {
        vod: {
            order: ["center", "bottom"],
            center: [{ items: ["BigPlayBtn"], align: "center" }],
            bottom: [
                { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
                { wrapper: "Blank", items: [] },
                { items: ["FullscreenBtn"], wrapper: "Group" },
            ],
        },
    },
});

전체 HTML 예제

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>VPE Player - 레이아웃 시스템</title>
    <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
    <div id="video" style="max-width: 800px; margin: 0 auto;"></div>
    <button id="btn-layout1">Layout 1</button>
    <button id="btn-layout2">Layout 2</button>

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

        var layout1 = {
            pc: {
                vod: {
                    order: ["top", "center", "bottom"],
                    top: [{ items: ["MetaDesc"] }],
                    center: [{ items: ["BigPlayBtn"], align: "center" }],
                    bottom: [
                        { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
                        { wrapper: "Blank", items: [] },
                        { items: [Logo], wrapper: "Group" },
                        { items: ["SettingBtn", "FullscreenBtn"], wrapper: "Group" },
                    ],
                },
            },
        };

        var layout2 = {
            pc: {
                vod: {
                    order: ["center", "bottom"],
                    center: [{ items: ["BigPlayBtn"], align: "center" }],
                    bottom: [
                        { items: ["PlayBtn", "VolumeBtn"], wrapper: "Group" },
                        { wrapper: "Blank", items: [] },
                        { items: ["FullscreenBtn"], wrapper: "Group" },
                    ],
                },
            },
        };

        var player = new ncplayer("video", {
            playlist: [
                {
                    file: "https://CDN_DOMAIN/example.m3u8",
                    poster: "https://CDN_DOMAIN/poster.jpg",
                },
            ],
            autostart: true,
            muted: true,
            layout: layout1,
        });

        document.getElementById("btn-layout1").addEventListener("click", function() {
            player.layout(layout1);
        });
        document.getElementById("btn-layout2").addEventListener("click", function() {
            player.layout(layout2);
        });
    </script>
</body>
</html>

UI Editor 활용

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