---
title: "플레이어 UI"
slug: "vpe-umd-player-ui"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-umd-player-ui"
stale: true
---
> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 플레이어 UI
Classic/VPC 환경에서 이용 가능합니다.
플레이어 UI에서는 컨트롤바, 버튼, 진행 바 등 UI와 관련된 옵션을 설정하는 방법을 설명합니다.
참고
- 옵션을 설정하는 속성에 대한 설명은 옵션 레퍼런스를 참고해 주십시오.
- 이용 중인 요금제에 따라 설정 가능한 옵션이 다를 수 있습니다.
## 기본 옵션
### language (다국어)
플레이어에서 사용하는 언어를 설정합니다. 설정하지 않으면 브라우저에서 사용하는 언어를 따라갑니다.
```
const player = new ncplayer("player", {
lang: "ko", // 언어 설정("auto", "ko", "en")
playlist: [
{
file: "https://example.com/video/master.m3u8",
},
],
});
```
## 컨트롤바
### controls (컨트롤바 표시)
기본 컨트롤바 UI의 표시 여부를 설정합니다. `false`로 설정하면 컨트롤바가 표시되지 않습니다.
```
const player = new ncplayer("player", {
controls: true, // 컨트롤바 표시 여부 설정
playlist: [
{
file: "https://example.com/video/master.m3u8",
},
],
});
```
### controlBtn (컨트롤바 버튼 UI)
컨트롤바의 개별 버튼 표시 또는 숨김을 설정합니다. 각 버튼을 `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초)입니다.
참고
`controlActiveTime: 0` 으로 설정하면 컨트롤바가 자동으로 숨겨지지 않고 항상 표시됩니다. 라이브커머스처럼 UI가 늘 보여야 하는 화면에 유용합니다.
```
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",
},
],
});
```
## 레이아웃 시스템
레이아웃 시스템을 사용하면 컨트롤바의 버튼 배치, 영역 구성, 커스텀 컴포넌트 삽입을 JSON 기반으로 선언적으로 정의할 수 있습니다. 화면 환경별(PC/모바일/전체화면)과 콘텐츠 유형별(VOD/Live)을 각각 분리해 관리할 수 있습니다.
참고
- Standard 요금제에서만 사용할 수 있습니다.
- 레이아웃 JSON은 [UI Editor](https://vpe-player-editor.web.app/)에서 시각적으로 편집하고 결과를 그대로 코드에 적용할 수 있습니다. 자세한 구조와 속성은 [레이아웃 시스템 가이드](https://developer.vpe.naverncp.com/docs/layout-system)를 참조해 주십시오.
### 기본 레이아웃 구성
`order`로 섹션 순서를 정하고, 각 섹션에 Row를 배치합니다. Row의 `items`에 빌트인 컴포넌트나 커스텀 요소를 넣을 수 있습니다.
```
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",
},
],
});
```
### 구성 구조
최상위 키는 `pc`, `mobile`, `fullscreen`으로 나뉘며, 각 환경 내부에 `vod`와 `live` 레이아웃을 정의합니다.
```
{
"pc": {
"vod": { ... },
"live": { ... }
},
"mobile": {
"vod": { ... },
"live": { ... }
},
"fullscreen": {
"vod": { ... },
"live": { ... }
}
}
```
### 섹션과 순서
`order` 배열이 렌더링 순서를 결정합니다. 기본 섹션은 `top`, `upper`, `center`, `lower`, `bottom`입니다.
```
{
"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", "TimeBtn"], "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 내 표시 아이템 수 제한 |
### 사용 가능한 레이아웃 아이템
`PlayBtn` `VolumeBtn` `TimeBtn` `SubtitleBtn` `FullscreenBtn` `SettingBtn` `PipBtn` `MetaDesc` `BigPlayBtn` `SeekBar` `SettingModal` `DurationBtn` `SkipForwardBtn` `SkipBackBtn` `CurrentTimeBtn` `MuteBtn` `PrevBtn` `NextBtn` `NextPrevBtn` `ShareBtn` `Blank`
### 커스텀 HTML 요소 삽입
레이아웃의 `items` 배열에 빌트인 키 대신 HTML 문자열을 전달하면 컨트롤바 내 원하는 위치에 커스텀 UI를 배치할 수 있습니다.
```
// 커스텀 로고 HTML
const Logo = `
