플레이어 UI

플레이어 UI에서는 컨트롤바, 버튼, 진행 바 등 UI와 관련한 옵션을 설정하는 방법을 설명합니다. 본 기능은 Classic/VPC 환경에서 사용할 수 있습니다.

옵션을 설정하는 속성에 대한 설명은 옵션 레퍼런스를 참고하세요.
이용 중인 요금제에 따라 설정 가능한 옵션이 다를 수 있습니다.

컨트롤바 표시 (controls)

기본 컨트롤바 UI의 표시 여부를 설정합니다. false로 설정하면 컨트롤바가 표시되지 않습니다.

const player = new ncplayer("player", {
    controls: true, // 컨트롤바 표시 여부 설정
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

컨트롤바 버튼 UI (controlBtn)

컨트롤바의 개별 버튼 표시/숨김을 설정합니다. 각 버튼을 true 또는 false로 제어합니다.

Standard 요금제에서만 사용할 수 있습니다.

const player = new ncplayer("player", {
    controlBtn: {
        play: true,           // 재생 버튼
        progressBar: true,    // 진행 바
        fullscreen: true,     // 전체화면 버튼
        volume: true,         // 볼륨 버튼
        times: true,          // 시간 표시
        pictureInPicture: true, // PIP 버튼
        setting: true,        // 설정 버튼
        subtitle: true,       // 자막 버튼
    },
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

controlBtn 속성

속성	타입	기본값	설명
play	boolean	true	재생/일시정지 버튼
progressBar	boolean	true	진행 바
fullscreen	boolean	true	전체화면 버튼
volume	boolean	true	볼륨 버튼
times	boolean	true	재생 시간 표시
pictureInPicture	boolean	true	PIP(Picture in Picture) 버튼
setting	boolean	true	설정 버튼
subtitle	boolean	true	자막 버튼

컨트롤바 색상 (progressBarColor)

컨트롤바 진행 바의 색상을 CSS 색상값으로 설정합니다.

Standard 요금제에서만 사용할 수 있습니다.

const player = new ncplayer("player", {
    progressBarColor: "#2e6ae0", // 컨트롤바 진행 색상 지정
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

컨트롤바 표시 시간 (controlActiveTime)

컨트롤바가 자동으로 숨겨지기까지의 시간을 밀리초(ms) 단위로 설정합니다. 기본값은 3000(3초)입니다.

const player = new ncplayer("player", {
    controlActiveTime: 5000, // 컨트롤바 표시 시간 설정(ms)
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

컨트롤바 UI 고정 (ui)

UI 타입을 지정합니다. 설정하지 않으면 브라우저 가로폭이나 기기를 따라 자동 전환됩니다.

Standard 요금제에서만 사용할 수 있습니다.

모바일 UI는 touchGestures, PC UI는 keyboardShortcut을 제공합니다.

const player = new ncplayer("player", {
    ui: "mobile", // UI 타입 설정 ("auto", "pc", "mobile")
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

다국어 (lang)

플레이어에서 사용하는 언어를 설정합니다. 설정하지 않으면 브라우저에서 사용하는 언어를 따라갑니다.

const player = new ncplayer("player", {
    lang: "ko", // 언어 설정 ("auto", "ko", "en")
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
        },
    ],
});

레이아웃 시스템으로 UI 커스터마이징

레이아웃 시스템을 사용하면 컨트롤바의 버튼 배치, 영역 구성, 커스텀 HTML 요소 삽입을 JSON 기반으로 선언적으로 정의할 수 있습니다.

Standard 요금제에서만 사용할 수 있습니다.

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" },
            ],
        },
    },
};

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

커스텀 HTML 요소 삽입

레이아웃의 items 배열에 빌트인 키 대신 HTML 문자열을 전달하면 컨트롤바 내 원하는 위치에 커스텀 UI를 배치할 수 있습니다.

// 커스텀 로고 HTML
const Logo = `
    <div style="padding:0 15px;">
        <a href="https://example.com" target="_blank">
            <img src="https://example.com/logo.webp" style="height:24px;" 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" }, // 커스텀 HTML
                { items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"], cap: 2, wrapper: "Group" },
            ],
        },
    },
};

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

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