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

## 기본 옵션

### aspectRatio (화면 비율)

`aspectRatio` 속성으로 플레이어의 가로·세로 비율을 지정할 수 있습니다. 플레이어가 고정형 사이즈(width, height)를 가지고 있지 않은 경우에만 적용할 수 있습니다. container의 크기가 변하더라도 설정한 비율이 유지됩니다.

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    aspectRatio: '16/9', // 화면 비율 설정
  }}
/>
```

### objectFit (화면 채움)

`objectFit` 속성으로 화면의 채움 방식을 설정할 수 있습니다. 재생 소스의 비율을 유지하고 화면을 꽉 채우도록 설정하는 예제는 다음과 같습니다.

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    aspectRatio: '16/9',
    objectFit: 'cover', // 화면 채움 설정(비율 맞춤 + 꽉 채움)
  }}
/>
```

## 컨트롤바

### controls (컨트롤바 표시)

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

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    controls: false, // 컨트롤바 표시 안 함(true: 컨트롤바 표시)
  }}
/>
```

### controlBtn (컨트롤바 버튼 UI)

`controlBtn` 속성으로 컨트롤바의 버튼 UI 사용 여부를 설정할 수 있습니다.

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    controls: true,
    controlBtn: {
      play: true,        // 재생
      progressBar: true, // 재생바 사용 여부
      fullscreen: true,  // 전체 화면 전환
      volume: true,      // 볼륨 컨트롤
      times: true,       // 재생 시간
      setting: true,     // 설정
    },
  }}
/>
```

### progressBarColor (컨트롤바 색상)

`progressBarColor` 속성으로 컨트롤바 영상 탐색 슬라이더의 색상을 설정할 수 있습니다.

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    progressBarColor: "#ff0000", // 색상 코드(빨간색)
  }}
/>
```

### controlActiveTime (컨트롤바 표시 시간)

`controlActiveTime` 속성으로 컨트롤바가 표시되는 시간을 설정할 수 있습니다.

참고

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

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    controlActiveTime: 3000, // 컨트롤바 표시 시간 설정(3000 = 3초)
  }}
/>
```

### 컨트롤바 UI 동적 수정

영상의 길이에 따라 버튼 UI를 동적으로 수정할 수 있습니다. 예를 들어 영상 길이가 10초 미만일 경우 전체 화면, PIP, 설정 버튼을 제공하지 않도록 설정할 수 있습니다.

```
const playerRef = useRef(null);

return (
  <VpePlayer
    ref={playerRef}
    events={{
      timeupdate: (res) => {
        if (res.duration < 10) {
          playerRef.current.controlBarBtnStateUpdate({
            fullscreen: false,
            pictureInPicture: false,
            setting: false,
          });
        }
      },
    }}
    options={{
      playlist: [
        { file: 'https://CDN도메인/example_video_01.mp4' },
      ],
      controlBtn: {
        play: true,
        fullscreen: true,
        volume: true,
        times: true,
        setting: true,
        subtitle: false,
      },
    }}
  />
);
```

## 자막 UI 설정

자막의 크기, 배경, 스타일을 설정할 수 있습니다.

```
<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDN도메인/example_video_01.mp4' },
    ],
    captionStyle: {
      fontSize: 12,
      color: '#FFFFFF',
      backgroundColor: 'rgba(0, 0, 0, 0.7)',
      edgeStyle: 'dropshadow', // dropshadow, raised, depressed, uniform
    },
  }}
/>
```

## 레이아웃 시스템

지원 플랫폼: `Android` `iOS`

VPE React Native SDK는 웹 SDK에서 포팅된 layout-driven ControlBar 시스템을 제공합니다. JSON 선언으로 컨트롤 버튼의 배치, 그룹화, 화면 환경별(PC/모바일/전체화면)과 콘텐츠 유형별(VOD/Live) 구성을 정의할 수 있습니다.

### 개요

`layout` prop에 레이아웃 객체를 전달하여 ControlBar의 모든 영역을 사용자 정의할 수 있습니다. `layout` prop이 없을 경우 기본 반응형 레이아웃이 사용됩니다.

- 5개 섹션: `top`, `upper`, `center`, `lower`, `bottom`
- 환경별 분리: `pc` / `mobile` / `fullscreen`
- 콘텐츠 유형 분리: `vod` / `live`
- 모바일 판정 breakpoint: 기본 768
- 사용자 layout × 디폴트 layout 자동 병합 (섹션 단위 replace)

### 구성 구조

최상위 키는 `pc`, `mobile`, `fullscreen`으로 나뉘며, 각 환경 내부에 `vod`와 `live` 레이아웃을 정의합니다.

```
{
  "pc": {
    "vod": {},
    "live": {}
  },
  "mobile": {
    "vod": {},
    "live": {}
  },
  "fullscreen": {
    "vod": {},
    "live": {}
  },
  "breakpoint": 768
}
```

`layout.json`

각 variant 내부는 5개 섹션의 순서와 그룹/아이템 정렬로 구성됩니다.

```
{
  "order": ["top", "upper", "center", "lower", "bottom"],
  "top": [
    { "wrapper": "Group", "items": ["BackBtn"] },
    { "wrapper": "Blank" },
    { "wrapper": "Group", "items": ["ShareBtn", "SettingBtn"] }
  ],
  "center": [
    { "wrapper": "Blank", "items": ["BigPlayBtn"] }
  ],
  "bottom": {
    "seekbar": ["SeekBar"],
    "left": [
      { "wrapper": "Group", "items": ["PlayBtn", "VolumeBtn"] },
      { "wrapper": "Group", "items": ["TimeBtn"] }
    ],
    "right": [
      { "wrapper": "Group", "items": ["SubtitleBtn", "FullscreenBtn"] }
    ]
  }
}
```

`variant.json`

### 사용 가능한 컨트롤 아이템

`items` 배열에 다음 이름들을 사용할 수 있습니다.

| 이름 | 설명 |
| --- | --- |
| `PlayBtn` | 재생/일시정지/다시보기 토글 (isEnded 분기) |
| `BigPlayBtn` | 중앙 큰 재생 버튼. playlist > 1 시 양옆 prev/next 자동 표시 |
| `VolumeBtn` | 음량 토글 |
| `MuteBtn` | 음소거 전용 버튼 |
| `TimeBtn` | 현재시간 / 총시간 또는 LIVE 인디케이터 |
| `CurrentTimeBtn` | 현재 재생 시간 (분리 버전) |
| `DurationBtn` | 총 재생 시간 (분리 버전) |
| `SeekBar` | 진행도 슬라이더 |
| `FullscreenBtn` | 전체화면 토글 |
| `SubtitleBtn` | 자막 즉시 토글 (SettingsMenu 거치지 않음) |
| `SettingBtn` | SettingsMenu 토글 (화질/재생속도/자막) |
| `PrevBtn` | 이전 트랙 |
| `NextBtn` | 다음 트랙 |
| `NextPrevBtn` | 이전/다음 통합 버튼 |
| `BackBtn` | 뒤로가기. `events.backPress` 호출 |
| `ShareBtn` | React Native Share API 호출 |
| `SkipForwardBtn` | 10초 앞으로 이동 |
| `SkipBackBtn` | 10초 뒤로 이동 |
| `MetaDesc` | 영상 메타데이터 (제목/프로필/등록일) |
| `Blank` | 자식이 없으면 spacer(`flex:1`), 있으면 정렬용 row |

참고

React Native에서는 명시적 PIP 버튼(`PipBtn`)이 비표준이므로 폐지되었습니다. 대신 `playerRef.current.pip()` 또는 `options.allowsPictureInPicture` lifecycle을 사용해 주십시오.

### wrapper 종류

- `Group` — 기본 알약 모양 그룹 (반투명 배경, borderRadius 999). 단일 자식이면 원형(`aspectRatio: 1`) 처리, `TimeBtn`은 단독일 때 우회.
- `Blank` — 자식이 없으면 spacer, 자식이 있으면 align 적용 row.

### 기본 사용 예제

```
import { VpePlayer } from 'vpe-react-native';

const myLayout = {
  pc: {
    vod: {
      order: ['top', 'center', 'bottom'],
      top: [
        { wrapper: 'Group', items: ['BackBtn'] },
        { wrapper: 'Blank' },
        { wrapper: 'Group', items: ['ShareBtn', 'SettingBtn'] },
      ],
      center: [{ wrapper: 'Blank', items: ['BigPlayBtn'] }],
      bottom: {
        seekbar: ['SeekBar'],
        left: [
          { wrapper: 'Group', items: ['PlayBtn', 'VolumeBtn'] },
          { wrapper: 'Group', items: ['TimeBtn'] },
        ],
        right: [
          { wrapper: 'Group', items: ['SubtitleBtn', 'FullscreenBtn'] },
        ],
      },
    },
    live: { /* ... */ },
  },
  mobile: {
    vod: { /* ... */ },
    live: { /* ... */ },
  },
  fullscreen: {
    vod: { /* ... */ },
    live: { /* ... */ },
  },
  breakpoint: 768,
};

export default function MyPlayer() {
  return (
    <VpePlayer
      accessKey={'YOUR_ACCESS_KEY'}
      layout={myLayout}
      options={{
        playlist: [{ file: 'https://CDN도메인/master.m3u8' }],
        aspectRatio: '16/9',
      }}
    />
  );
}
```

### 레이아웃 병합 동작

사용자가 전달한 layout은 디폴트 layout과 자동 병합됩니다. 일부 환경(예: `pc`만) 또는 일부 섹션만 정의해도 나머지는 디폴트가 사용됩니다. 단, **섹션 단위 replace** 방식이므로 한 섹션을 정의하면 디폴트의 같은 섹션은 완전히 대체됩니다.

개발(`__DEV__`) 모드에서는 잘못된 아이템 이름, 누락된 필수 섹션 등에 대해 콘솔 경고가 출력됩니다.

### 터치 제스처

ControlBar는 단일/더블탭 제스처를 처리합니다. 화면을 좌/중/우 1/3 영역으로 나누어 더블탭 시 10초씩 누적 seek가 발생하며, 단일탭은 컨트롤바 토글입니다.

- 단일탭 토글은 300ms 지연 (그동안 두 번째 탭이 들어오면 더블탭으로 처리되어 컨트롤 깜빡임 방지)
- 더블탭 좌/우 → 10초 누적 seek (500ms 후 실제 seek 실행)
- `options.touchGestures: false` 시 더블탭 비활성화 (단일탭 토글만 동작)

## 관련 가이드

- [커스텀 아이콘 (IconOverrides)](https://developer.vpe.naverncp.com/docs/rn/custom-icon)
- [플레이어 UI 옵션](https://developer.vpe.naverncp.com/docs/rn/player-ui)
- [플레이어 UX 옵션](https://developer.vpe.naverncp.com/docs/rn/player-ux)