---
title: "플레이어 UI"
slug: "vpe-tv-player-ui"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-tv-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를 구성하고 설정하는 옵션과 선언적 레이아웃 시스템을 안내합니다.

## controls

`controls` 속성으로 컨트롤바 표시 여부를 설정할 수 있습니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: false, // 컨트롤바 숨김
    }}
    onBack={() => navigation.goBack()}
/>
```

## controlBtn

`controlBtn` 속성으로 개별 버튼의 표시 여부를 설정할 수 있습니다. TV SDK에서는 `fullscreen`, `pictureInPicture` 속성이 없습니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: true,
        controlBtn: {
            play: true,
            progressBar: true,
            volume: true,
            times: true,
            setting: true,
            subtitle: true,
        },
    }}
    onBack={() => navigation.goBack()}
/>
```

## progressBarColor

`progressBarColor` 속성으로 진행바의 색상을 설정할 수 있습니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        progressBarColor: '#00E0FF',
    }}
    onBack={() => navigation.goBack()}
/>
```

## controlActiveTime

- `controlActiveTime` 속성으로 컨트롤바가 자동으로 숨겨지는 시간을 설정합니다. 기본값은 3000ms(3초)입니다.

참고

`controlActiveTime`을 `0`으로 설정하면 컨트롤바가 자동으로 숨겨지지 않고 **항상 표시**됩니다. 라이브커머스처럼 UI가 늘 보여야 하는 화면에 유용합니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controlActiveTime: 5000, // 5초 후 자동 숨김
    }}
    onBack={() => navigation.goBack()}
/>
```

## lang

`lang` 속성으로 UI 언어를 설정할 수 있습니다.

| 값 | 언어 |
| --- | --- |
| ko | 한국어 (기본값) |
| en | English |
| ja | 日本語 |

## 리모컨 이벤트

TV SDK는 리모컨 D-pad 입력을 자동으로 처리합니다.

| 이벤트 | Apple TV | Android TV | 동작 |
| --- | --- | --- | --- |
| select | O | O | 확인/선택 |
| playPause | O | O | 재생/일시정지 |
| up/down | O | O | 컨트롤바 표시/포커스 이동 |
| left/right | O | O | `SeekBar`에서 ±10초 시킹 |
| menu | O | X | 뒤로가기 |
| rewind/fastForward | X | O | 되감기/빨리감기 |

## 레이아웃 시스템

TV SDK의 선언적 레이아웃 시스템을 사용하여 컨트롤바 UI를 커스터마이징할 수 있습니다.

## 레이아웃 구조

5개 섹션(`top`, `upper`, `center`, `lower`, `bottom`)과 `seekbar`로 구성된 선언적 레이아웃입니다.

## 사용 가능한 아이템

컨트롤바에 배치할 수 있는 아이템은 다음과 같습니다.

| 아이템 | 설명 |
| --- | --- |
| `PlayBtn` | 재생 / 일시정지 / 다시 재생 |
| `BigPlayBtn` | 중앙 대형 재생 + 이전 / 다음 |
| `BackBtn` | 뒤로가기 |
| `SeekBar` | 탐색바(D-pad 좌/우로 ±10초 탐색) |
| `SkipBackBtn / SkipForwardBtn` | ±10초 탐색 |
| `PrevBtn / NextBtn / NextPrevBtn` | 트랙 이동 |
| `TimeBtn / CurrentTimeBtn / DurationBtn` | 시간 표시(라이브 시 LIVE 인디케이터) |
| `MuteBtn / VolumeBtn` | 음소거 / 볼륨(TV에서는 뮤트 토글) |
| `SubtitleBtn` | 자막 메뉴 |
| `SettingBtn` | 설정 메뉴 |
| `MetaDesc` | 영상 메타 정보 |
| `Blank / BlankBtn` | 빈 공간 |

TV에서 제거된 아이템은 `FullscreenBtn`, `PipBtn`, `ShareBtn`이며, 레이아웃에 포함해도 무시됩니다.

## 커스텀 레이아웃 예제

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        top: [
            { items: ['BackBtn'], wrapper: 'Group' },
            { items: ['MetaDesc'] },
            { wrapper: 'Blank', items: [] },
        ],
        center: [
            { items: ['BigPlayBtn'], align: 'center' },
        ],
        lower: [
            { wrapper: 'Blank', items: ['SeekBar'], align: 'center' },
        ],
        bottom: [
            { items: ['PlayBtn'], wrapper: 'Group' },
            { items: ['NextPrevBtn'], wrapper: 'Group' },
            { items: ['MuteBtn'], wrapper: 'Group' },
            { items: ['TimeBtn'], wrapper: 'Group' },
            { wrapper: 'Blank', items: [] },
            { items: ['SubtitleBtn', 'SettingBtn'], wrapper: 'Group' },
        ],
    }}
    onBack={() => navigation.goBack()}
/>
```

## VOD/Live 변형

VOD와 Live에서 서로 다른 레이아웃을 사용할 수 있습니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        vod: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['SettingBtn'], wrapper: 'Group' },
            ],
        },
        live: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['MuteBtn'], wrapper: 'Group' },
            ],
        },
    }}
    onBack={() => navigation.goBack()}
/>
```

## 런타임 레이아웃 변경

ref 메서드를 통해 런타임에 레이아웃을 변경할 수 있습니다.

```
const playerRef = useRef<PlayerHandle>(null);

// 부분 업데이트 (merge=true, 기본값)
playerRef.current?.layout(
    { bottom: [{ items: ['PlayBtn'], wrapper: 'Group' }] },
    true
);

// 전체 교체 (merge=false)
playerRef.current?.layout(newLayout, false);
```

## 그룹 옵션

각 그룹에 설정할 수 있는 속성은 다음과 같습니다.

| 속성 | 타입 | 설명 |
| --- | --- | --- |
| `items` | string[] | 레이아웃 아이템 목록 |
| `wrapper` | 'Blank', 'Group' | 래퍼 타입 |
| `align` | 'left' , 'right' , 'center' | 정렬 |
| `size` | number | 버튼 크기(기본 88) |