---
title: "재생 설정"
slug: "vpe-tv-player-options"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-tv-player-options"
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 환경에서 이용 가능합니다.

플레이어의 재생 관련 옵션을 설정하는 방법을 안내합니다.

## 기본 설정 - playlist

재생할 영상을 설정합니다. 재생 소스는 MP4, HLS, DASH 형식을 지원합니다.

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

## 여러 영상 재생

`playlist` 속성으로 여러 개의 재생 소스를 전달하여 연속 재생할 수 있습니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [
            {
                file: 'https://example.com/video1.m3u8',
                poster: 'https://example.com/poster1.jpg',
                description: { title: '첫 번째 영상' },
            },
            {
                file: 'https://example.com/video2.m3u8',
                description: { title: '두 번째 영상' },
            },
        ],
        autostart: true,
    }}
    onBack={() => navigation.goBack()}
/>
```

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

영상 재생 완료 후 다음에 재생할 영상을 동적으로 추가할 수 있습니다.

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

// 단일 영상 추가
playerRef.current?.addNextSource({
    file: 'https://example.com/new_video.m3u8',
    description: { title: '새로운 영상' },
});

// 여러 영상 동시 추가
playerRef.current?.addPrevSource([
    { file: 'https://example.com/video_1.mp4' },
    { file: 'https://example.com/video_2.mp4' },
]);
```

## autostart

`autostart` 속성으로 영상을 자동 재생할 수 있습니다. 기본값은 `true`입니다.

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

## muted

`muted` 속성으로 처음 재생 시 음소거 상태로 시작할 수 있습니다.

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

## playRateSetting

`playRateSetting` 속성으로 사용자가 재생 속도를 선택할 수 있는 UI를 제공합니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playRateSetting: [0.5, 0.75, 1, 1.5, 2],
        playlist: [{ file: 'https://example.com/video.m3u8' }],
    }}
    onBack={() => navigation.goBack()}
/>
```

## repeat

`repeat` 속성으로 영상을 반복 재생할 수 있습니다.

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

## 자막 설정

`playlist.vtt` 속성으로 자막을 제공할 수 있습니다. VTT 및 SMI 형식을 지원하며, SMI 파일의 EUC-KR 인코딩은 자동 디코딩됩니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{
            file: 'https://example.com/video.m3u8',
            vtt: [
                { id: 'ko', file: 'https://example.com/ko.vtt', label: '한국어', default: true },
                { id: 'en', file: 'https://example.com/en.vtt', label: 'English' },
                { id: 'ja', file: 'https://example.com/ja.smi', label: '日本語' },
            ],
        }],
    }}
    onBack={() => navigation.goBack()}
/>
```

## lowLatencyMode (라이브)

`lowLatencyMode` 속성으로 LL-HLS 저지연 모드를 활성화할 수 있습니다. 라이브 스트림은 자동으로 감지됩니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        lowLatencyMode: true,
        playlist: [{
            file: 'https://example.com/live.m3u8',
            description: { title: '라이브 방송' },
        }],
    }}
    onBack={() => navigation.goBack()}
/>
```

라이브로 감지되면 다음과 같이 동작합니다.

- `TimeBtn`에 빨간 점과 "LIVE" 표시
- 재생 속도 메뉴 숨김
- `SeekBar` 탐색(시킹) 비활성화

## lowLatencyMode 플랫폼별 동작

`lowLatencyMode` 활성화 시 플랫폼별 동작은 다음과 같습니다.

| 플랫폼 | 동작 |
| --- | --- |
| Android TV | ExoPlayer `targetOffsetMs: 2000`(라이브 엣지 2초 목표) |
| tvOS | AVPlayer `preferredForwardBufferDuration: 2` |

5초 이상 뒤처지면 라이브 엣지로 자동 복귀합니다.

## 메타데이터 설정

`playlist.description` 속성으로 영상의 메타 정보를 표시할 수 있습니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{
            file: 'https://example.com/video.m3u8',
            description: {
                title: '네이버클라우드 소개',
                created_at: '2024.01.01',
                profile_name: '네이버클라우드',
                profile_image: 'https://example.com/profile.png',
            },
        }],
    }}
    onBack={() => navigation.goBack()}
/>
```

## 워터마크

`visibleWatermark` 속성으로 워터마크를 표시할 수 있습니다.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        visibleWatermark: true,
        watermarkText: 'SAMPLE@example.com',
        watermarkConfig: {
            randPosition: true,
            randPositionInterVal: 5000,
            opacity: 0.4,
        },
    }}
    onBack={() => navigation.goBack()}
/>
```