---
title: "플레이어 UI"
slug: "vpe-example-ui"
tags: ["Video Player Enhancement", "VPE"]
updated: 2026-09-17T09:08:00Z
published: 2026-09-17T09:08:00Z
canonical: "guide.ncloud-docs.com/vpe-example-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와 관련한 옵션을 설정하는 방법을 설명합니다.
참고
- 옵션을 설정하는 속성에 대한 설명은 [플레이어 설정](/docs/vpe-web#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%84%A4%EC%A0%95)을 참고해 주십시오.
- 이용 중인 요금제에 따라 설정할 수 있는 옵션에 차이가 있습니다.
## 화면 비율
`aspectRatio` 속성으로 플레이어의 가로·세로 비율을 지정할 수 있습니다.
참고
- 플레이어가 고정형 사이즈(`width`, `height`)를 가지고 있지 않은 경우에만 적용할 수 있습니다.
- `container`의 크기가 변하더라도 설정한 비율이 유지됩니다.
화면 비율을 16:9로 설정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
aspectRatio: '16/9', // 화면 비율 설정
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
},
],
});
```
## 화면 채움
`objectFit` 속성으로 화면의 채움 방식을 설정할 수 있습니다. 재생 소스의 비율을 유지하고 화면을 꽉 채우도록 설정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
aspectRatio: '16/9',
objectFit: 'cover', // 화면 채움 설정(비율 맞춤+꽉 채움)
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
},
],
});
```
## 컨트롤바 표시
`controls` 속성으로 컨트롤바 표시 여부를 설정할 수 있습니다. 컨트롤바를 표시하지 않도록 설정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
autostart: true,
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
poster: 'https://CDN도메인/example_video_01.png',
},
],
controls: false // 컨트롤바 표시 안 함(true: 컨트롤바 표시)
});
```
## 컨트롤바 버튼 UI
`controlBtn` 속성으로 컨트롤바의 버튼 UI 사용 여부를 설정할 수 있습니다.
참고
이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.
컨트롤바의 모든 버튼 UI를 표시하도록 설정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
autostart: true,
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
poster: 'https://CDN도메인/example_video_01.png',
},
],
controls: true,
// true: 버튼 표시, false: 버튼 표시 안 함
controlBtn: {
play: true, // 재생
progressBar:true // 재생바 사용 여부
fullscreen: true, // 전체 화면 전환
volume: true, // 볼륨 컨트롤
times: true, // 재생 시간
pictureInPicture: true, // PIP
setting: true, // 설정
},
});
```
## 컨트롤바 색상
`progressBarColor` 속성으로 컨트롤바 영상 탐색 슬라이더의 색상을 설정할 수 있습니다.
참고
이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.
컨트롤바 색상을 빨간색으로 설정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
autostart: true,
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
poster: 'https://CDN도메인/example_video_01.png',
},
],
progressBarColor: "#ff0000", // 색상 코드(빨간색)
});
```
## 다국어
`lang` 속성으로 컨트롤바 언어를 고정할 수 있습니다.
참고
기본적으로 브라우저의 언어 설정을 감지하여 컨트롤바에 자동으로 적용합니다. 브라우저에 설정된 언어가 플레이어에서 지원하지 않는 언어일 경우, 영어(en)가 기본값으로 표시됩니다.
컨트롤바 언어를 영어로 고정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video4', {
playlist: 'https://CDN도메인/example_video_01.mp4',
lang:'en' // 다국어 설정(영어로 고정)
});
```
## 컨트롤바 표시 시간
`controlActiveTime` 속성으로 컨트롤바가 표시되는 시간을 설정할 수 있습니다.
참고
이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.
컨트롤바를 3초간 표시하도록 설정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
autostart: true,
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
poster: 'https://CDN도메인/example_video_01.png',
},
],
controlActiveTime: 3000, // 컨트롤바 표시 시간 설정(3000=3초)
});
```
## 컨트롤바 UI 고정
`ui` 속성으로 디바이스에 관계없이 컨트롤바 UI를 고정할 수 있습니다.
참고
- 이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.
- 모바일 전용 UI는 [터치 제스처](/docs/vpe-example-ux#%ED%84%B0%EC%B9%98-%EC%A0%9C%EC%8A%A4%EC%B2%98) 기능을, PC 전용 UI는 [키보드 단축키](/docs/vpe-example-ux#%ED%82%A4%EB%B3%B4%EB%93%9C-%EB%8B%A8%EC%B6%95%ED%82%A4) 기능을 제공합니다.
모바일 전용 컨트롤바 UI로 고정하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
autostart: true,
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
},
],
ui: 'mobile', // 컨트롤바 UI 설정(모바일 전용 UI로 고정)
});
```
## 자막 설정
`playlist.vtt` 속성을 이용하여 자막을 제공할 수 있습니다.
참고
VTT 형식의 캡션(자막)을 지원하며, 배열 형태로 복수의 자막을 제공할 수 있습니다.
한국어 및 영어 자막을 제공하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
new ncplayer('video1', {
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
poster : 'https://CDN도메인/example_image_01.png',
vtt:[
{
file:'https://CDN도메인/subtitles-ko.vtt', // 자막 파일
label:'한국어' // 자막 언어
},
{
file:'https://CDN도메인/subtitles-en.vtt', // 자막 파일
label:'English' // 자막 언어
}
]
}
],
});
```
## 커스텀 버튼 추가
`customBtns` 속성으로 플레이어에 커스텀 버튼을 추가하여 새로운 기능을 제공할 수 있습니다.
참고
- 이 옵션은 Standard 요금제를 이용 중인 경우에만 설정할 수 있습니다.
- 커스텀 버튼은 위치와 관계없이 최대 4개까지 추가할 수 있습니다.
`position` 및 `flow` 속성 설정별 커스텀 버튼 위치는 다음과 같습니다.
오른쪽 하단의 왼쪽에 커스텀 버튼을 추가하는 예제는 다음과 같습니다.
```
// 동영상(MP4)
let player = new ncplayer('video1', {
playlist: [
{
file: 'https://https://CDN도메인/example_video_01.mp4',
},
],
customBtns: [
{
ui: "pc", // 커스텀 버튼 제공 UI
id: "chatBtn", // 커스텀 버튼의 DOM ID
position: "right-bottom", // 커스텀 버튼 추가 영역(오른쪽 하단)
flow: "left", // 커스텀 버튼 추가 위치(왼쪽)
icon: "https://CDN도메인/example_video_01.svg", // 커스텀 버튼 이미지 URL
callback(){ // 커스텀 버튼 클릭 시 발생시킬 이벤트
alert('버튼클릭')
}
},
{
ui: "mobile", // 커스텀 버튼 제공 UI
id: "chatBtn", // 커스텀 버튼의 DOM ID
position: "right-bottom", // 커스텀 버튼 추가 영역(오른쪽 하단)
flow: "left", // 커스텀 버튼 추가 위치(왼쪽)
icon: "https://CDN도메인/example_video_02.svg", // 커스텀 버튼 이미지 URL
callback(){ // 커스텀 버튼 클릭 시 발생시킬 이벤트
alert("버튼클릭")
}
}
]
});
// ready 이벤트를 이용하여 커스텀 버튼에 이벤트 바인딩
player.on('ready',()=>{
documnet.getElementById('chatBtn').addEventListener('click',()=>{
alert('버튼클릭')
});
})
```
### 커스텀 버튼 고도화
기능 활성 상태(ON/OFF)에 따라 커스텀 버튼을 다르게 표시할 수 있습니다. 상태별 아이콘을 추가하고 default 상태를 설정할 수 있으며, 각 버튼의 tooltip(툴팁)도 추가할 수 있습니다.
커스텀 버튼의 상태별 아이콘과 툴팁을 추가하는 예제는 다음과 같습니다. 
```
// 동영상(MP4)
new ncplayer('video', {
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
poster : 'https://CDN도메인/example_image_01.png',
}
],
customBtns:[
{
ui:'pc', // 커스텀 버튼 제공 UI
position:'right-bottom', // 커스텀 버튼 추가 영역(오른쪽 하단)
icon:'/image/frame-corners-off.svg', // off 상태 이미지
activeIcon:'/image/frame-corners.svg', // on 상태 이미지
tooltip:'기본 모드', // off 상태 툴팁
activeTooltip:'몰입 모드', // on 상태 툴팁
flow:'left', // 커스텀 버튼 추가 위치(왼쪽)
default:true, // true(기본값): on, false: off
callback(bool){
// 고객사 코드
console.log('플레이어에 설정된 value boolean', bool)
},
},
],
});
```
### 컨트롤바 UI 동적 수정
영상의 길이에 따라 버튼 UI를 동적으로 수정할 수 있습니다. 예를 들어 영상 길이가 10초 미만일 경우에는 전체 화면, PIP, 설정 버튼을 제공하지 않도록 설정할 수 있습니다. 예제는 다음과 같습니다.
```
// 동영상(MP4)
const player = new ncplayer('video', {
playlist: [
{
file: 'https://CDN도메인/example_video_01.mp4',
poster : 'https://CDN도메인/example_image_01.png',
}
],
controlBtn:{
play:true,
fullscreen:true,
volume:true,
times:true,
pictureInPicture:true,
setting:true,
subtitle:false,
},
});
// 고객사 필요에 따라 동적으로 버튼 제어
const btnDisabled = () =>{
player.controlBarBtnStateUpdate({
fullscreen:false, // 전체 화면 버튼 표시 안 함(true: 전체 화면 버튼 표시)
pictureInPicture:false, // PIP 버튼 표시 안 함(true: PIP 버튼 표시)
setting:false, // 설정 버튼 표시 안 함(true: 설정 버튼 표시)
})
}
// <예시> 영상 길이가 10초 미만일 경우 버튼 숨김 처리
window.player.on('timeupdate',(res)=>{
if(res.duration < 10){
btnDisabled();
}
});
```
### 모바일 UI에서의 탐색바 변경
모바일 UI에서 제공되는 탐색바를 플레이어 최하단에 붙는 형태로 변경할 수 있습니다. 예제는 다음과 같습니다.
```
```