---
title: "TV SDK 개요"
slug: "vpe-tv-sdk"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-tv-sdk"
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.

# TV SDK 개요

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

Video Player Enhancement TV SDK는 Android TV / Apple TV(tvOS) / Fire TV 전용 React Native 비디오 플레이어 SDK입니다.

## TV 전용 컴포넌트

`@sgrsoft/vpe-reactnative-tv-sdk`는 react-native-tvos 기반의 TV 전용 비디오 플레이어 SDK입니다. 웹 SDK(`vpe-react-sdk`)와 동일한 API를 제공하여 플랫폼 간 일관된 개발 경험을 지원합니다.

## 주요 기능

TV SDK가 제공하는 주요 기능은 다음과 같습니다.

- HLS / DASH / MP4 네이티브 재생 (ExoPlayer / AVPlayer)
- DRM 지원 (Widevine + FairPlay)
- IMA 광고 (Google Interactive Media Ads)
- 플레이리스트 (자동 다음 재생)
- 자막 (VTT / SMI, EUC-KR 자동 디코딩)
- 선언적 레이아웃 커스터마이징
- 라이브 스트림 + LL-HLS 저지연 모드
- 다국어 (ko / en / ja)
- 이어보기 (onExit + initialPosition)
- D-pad / 리모컨 내비게이션
- 캡처 방지

## 웹 SDK와의 차이점

웹 SDK와 TV SDK의 주요 차이점은 다음과 같습니다.

| 항목 | 웹 SDK | TV SDK |
| --- | --- | --- |
| 플랫폼 | 브라우저(React/Next.js) | Android TV / tvOS / Fire TV |
| 스트리밍 엔진 | 브라우저 MSE 기반 | 네이티브 엔진 (ExoPlayer / AVPlayer) |
| 전체 화면 | `requestFullscreen()` | 항상 전체 화면 (no-op) |
| PiP | `requestPictureInPicture()` | 미지원 (no-op) |
| 볼륨 | 슬라이더 UI | 시스템 볼륨 (MuteBtn = 뮤트 토글) |
| 입력 | 마우스/키보드 | 리모컨 D-pad |
| 광고 | IMA | IMA |
| TV 전용 props | - | onBack, onExit, initialPosition |

## 언어 지원

디바이스 언어 설정을 감지하여 한국어(ko), 영어(en), 일본어(ja)를 지원합니다.

## 버전 호환성

TV SDK의 버전별 호환성 정보는 다음과 같습니다.

| 항목 | 최소 | 권장 |
| --- | --- | --- |
| react-native-tvos | 0.83.1-1 | 0.84.0-0 |
| React | 19.x | 19.2.x |
| Node.js | 22.11+ | 22.x LTS |
| tvOS | 15.1+ | 16.0+ |
| Android API | 24 (7.0) | 28+ |
| TypeScript | 5.0+ | 5.8.x |

## 빠른 시작

다음 예시 코드로 플레이어를 빠르게 구성할 수 있습니다.

```
import React, { useRef } from 'react';
import { View, StyleSheet } from 'react-native';
import { VpePlayer } from '@sgrsoft/vpe-reactnative-tv-sdk';
import type { PlayerHandle } from '@sgrsoft/vpe-reactnative-tv-sdk';

export default function PlayerScreen() {
    const playerRef = useRef<PlayerHandle>(null);

    return (
        <View style={styles.container}>
            <VpePlayer
                ref={playerRef}
                accessKey="YOUR_ACCESS_KEY"
                options={{
                    playlist: [{
                        file: 'https://example.com/video.m3u8',
                        description: { title: '영상 제목' },
                    }],
                    autostart: true,
                }}
                onBack={() => {
                    // 뒤로가기 처리
                }}
                onEvent={(event) => {
                    if (event.type === 'ready') {
                        console.log('Player ready');
                    }
                }}
            />
        </View>
    );
}

const styles = StyleSheet.create({
    container: { flex: 1, backgroundColor: '#000' },
});
```