---
title: "재생 관련 옵션"
slug: "vpe-play-option"
updated: 2026-09-17T09:08:00Z
published: 2026-09-17T09:08:00Z
canonical: "guide.ncloud-docs.com/vpe-play-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.

# 재생 관련 옵션

Classic/VPC 환경에서 이용 가능합니다.

이 페이지에서는 플레이어를 실행하는데 설정하는 옵션을 다루고 있습니다.

          참고

          

Android, iOS에 공통으로 적용되는 사항입니다.

## 기본설정

플레이어의 재생 소스 설정 옵션을 설명합니다.

### playlist

재생할 영상을 설정합니다. 재생 소스는 mp4, hls, dash 형식을 지원합니다.

```
<VpePlayer
    ...
    options={{
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
        }}
    ...
/>
```

### 여러 영상 재생

playlist 속성으로 여러 개의 재생 소스를 전달하여 여러 개의 영상을 연속하여 재생할 수 있습니다. 또한, 여러 영상 재생 기능을 재정의(Override)할 수 있으며, 다음 재생할 영상을 동적 플레이리스트로 구성할 수 있습니다.

```
<VpePlayer
    ...
    options={{
          playlist: [ //재생소스
              { 
                file: 'https://CDN도메인/example_video_01.mp4',
                poster: 'https://CDN도메인/example_image_01.png' 
              },
              { 
                file: 'https://CDN도메인/example_video_02.mp4',
                poster: 'https://CDN도메인/example_image_02.png'  
              },
              { 
                file: 'https://CDN도메인/example_video_03.mp4/index.m3u8', 
                poster: 'https://CDN도메인/example_image_03.png'  
              }
          ],
        }}
    ...
/>
```

### 동적 플레이리스트 구성

영상 재생이 완료된 후 다음에 재생할 영상을 동적으로 추가할 수 있는 기능을 제공합니다. 예를 들어 다음과 같이 추천 영상을 썸네일과 함께 안내하도록 구성할 수 있습니다.

```
const playerRef = useRef(null);
       
return (
      <VpePlayer
          ...
          ref={playerRef}
          options={{
                playlist: [ //재생소스
                    { 
                      file: 'https://CDN도메인/example_video_01.mp4',
                      poster: 'https://CDN도메인/example_image_01.png' 
                    }
                ],
              }}
          ...
      />
    
      <TouchableOpacity onPress={()=>{
        playerRef.current.addNextSource({
            file: 'https://CDN도메인/example_video_02.mp4',
                      poster: 'https://CDN도메인/example_image_02.png' 
        })
        }}>다음 영상 추가</TouchableOpacity>
        
      <TouchableOpacity onPress={()=>{
        playerRef.current.addPrevSource({
            file: 'https://CDN도메인/example_video_02.mp4',
                      poster: 'https://CDN도메인/example_image_02.png' 
        })
        }}>이전 영상 추가</TouchableOpacity>
        
)
```

## 재생 설정

플레이어의 재생 옵션을 설명합니다.

### autostart

autostart 속성으로 플레이어의 재생 소스를 자동 재생할 수 있습니다. 예제는 다음과 같습니다.

```
<VpePlayer
    ...
    options={{
          autostart: true, // 자동 재생(false: 자동 재생 안 함)
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
        }}
    ...
/>
```

### autoPause

autoPause 속성으로 앱이 백그라운드로 전환될시 플레이어의 재생 소스를 자동 정지할 수 있습니다.

          주의

          

autoPause = true가 되어야 PictureInPicture 기능이 활성화 됩니다.

```
<VpePlayer
    ...
    options={{
          autostart: true, // 자동 재생(false: 자동 재생 안 함)
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
        }}
    ...
/>
```

### muted

muted 속성으로 플레이어를 처음 재생 시 음소거 상태로 재생할 수 있습니다. 예제는 다음과 같습니다.

```
<VpePlayer
    ...
    options={{
          playbackRate: 0.5, // 재생 속도 조절(기본값: 1.0)
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
        }}
    ...
/>
```

### playRateSetting

playRateSetting 속성으로 사용자가 재생 속도를 직접 설정할 수 있도록 UI를 제공할 수 있습니다.

```
<VpePlayer
    ...
    options={{
          playRateSetting: [0.5,0.75,1.0,1.25,1.5,1.75,2.0], // 0.5배속 ~ 2배속 지원
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
        }}
    ...
/>>
```

### repeat

repeat 속성으로 영상을 반복 재생할 수 있습니다. 예제는 다음과 같습니다.

```
<VpePlayer
    ...
    options={{
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
          repeat: true, // 반복 재생(false: 반복 재생 안 함)
        }}
    ...
/>
```

### setStartTime

setStartTime 속성으로 라이브 방송처럼 VOD를 모든 사용자가 동시에 동일 구간을 시청하도록 설정할 수 있습니다.

```
<VpePlayer
    ...
    options={{
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
              },
          ],
          setStartTime:"2023-02-08 06:07:00+00:00", // 최초 공개일 설정
        }}
    ...
/>
```

### 자막 설정

playlist.vtt 속성을 이용하여 자막을 제공할 수 있습니다. VTT 형식의 캡션(자막)을 지원하며, 배열 형태로 복수의 자막을 제공할 수 있습니다. 한국어 및 영어 자막을 제공하는 예제는 다음과 같습니다.

```
<VpePlayer
    ...
    options={{
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4'
                  vtt:[
                      {
                        id: 'ko',
                        file: 'https://vpe.sgrsoft.com/ncp_overview_script_kr_v2.vtt',
                        label: '한국어',
                        default: true,
                      },
                      {
                        id: 'en',
                        file: 'https://vpe.sgrsoft.com/ncp_overview_script_en_v2.vtt',
                        label: 'English',
                      },
                  ]
              },
          ]
        }}
    ...
/>
```

### 메타데이터 설정

플레이어 상단에 메타데이터 표시 여부를 설정할 수 있습니다. 풀스크린때 오른쪽 상단에 메타데이터가 표시됩니다.

```
<VpePlayer
    ...
    options={{
          playlist: [ //재생소스
              {
                  file: 'https://CDN도메인/example_video_01.mp4',
                  description:{
                        "title": "네이버클라우드 소개", // 제목
                        "created_at": "2023.01.01", // 업로드 날짜
                        "profile_name": "네이버클라우드", // 업로더 닉네임 또는 채널명
                        "profile_image": "https://CDN도메인/example_image_profile.png", // 프로필 이미지 또는 채널 이미지
                  },
              },
          ]
        }}
    ...
/>
```