---
title: "플레이어 UI 옵션"
slug: "vpe-player-ui-option"
updated: 2026-09-17T09:08:00Z
published: 2026-09-17T09:08:00Z
canonical: "guide.ncloud-docs.com/vpe-player-ui-option"
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

controlBtn 속성으로 컨트롤바의 버튼 UI 사용 여부를 설정할 수 있습니다. 컨트롤바의 모든 버튼 UI를 표시하도록 설정하는 예제는 다음과 같습니다.

```
<VpePlayer
    ...
    options={{
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
          controls: true, // true: 버튼 표시, false: 버튼 표시 안 함
          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 속성으로 컨트롤바가 표시되는 시간을 설정할 수 있습니다. 컨트롤바를 3초간 표시하도록 설정하는 예제는 다음과 같습니다.

```
<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){
                  player.current.controlBarBtnStateUpdate({  //예시 : 영상 길이가 10초 미만일 경우 버튼 숨김 처리
                      fullscreen:false, // 전체 화면 버튼 표시 안 함(true: 전체 화면 버튼 표시)
                      pictureInPicture:false, // PIP 버튼 표시 안 함(true: PIP 버튼 표시)
                      setting:false, // 설정 버튼 표시 안 함(true: 설정 버튼 표시)
                  })
              }
        },
      }}
      options={{
            playlist: [ //재생소스
                {
                    file: 'https://CDN도메인/example_video_01.mp4'
                },
            ],
            controlBtn:{
                play:true,
                fullscreen:true,
                volume:true,
                times:true,
                setting:true,
                subtitle:false,
            },
          }}
      ...
  />
)
```

## 자막 UI 설정

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

```
const playerRef = useRef(null);

return(
  <VpePlayer
      ...
      ref={playerRef}
      
      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)
            },
          }}
      ...
  />
)
```