---
title: "Basic usage"
slug: "vpe-tv-getting-started"
updated: 2026-09-17T09:22:39Z
published: 2026-09-17T09:22:39Z
canonical: "guide.ncloud-docs.com/vpe-tv-getting-started"
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.

# Basic usage

Available in Classic and VPC

This guide explains the basic usage of the VPE TV SDK.

## Basic example

Import the `VpePlayer` component, then configure `accessKey` and `options.playlist` to play video.

```
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',
                        poster: 'https://example.com/poster.jpg',
                        description: {
                            title: 'Video title',
                            profile_name: 'Channel name',
                        },
                    }],
                    autostart: true,
                }}
                onBack={() => {
                    // Handle back button (for example: navigation.goBack())
                }}
                onEvent={(event) => {
                    if (event.type === 'ready') {
                        console.log('Player ready');
                    }
                }}
            />
        </View>
    );
}

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

The TV SDK uses **Native video engines (ExoPlayer and AVPlayer)** to play HLS and DASH streams directly. You do not need to inject additional streaming libraries.

## Props (PlayerProps)

The `VpePlayer` component supports the following props.

| Prop | Type | Default value | Description |
| --- | --- | --- | --- |
| accessKey | string | - | APIs access key (required) |
| platform | 'pub' \| 'gov' | 'pub' | Public/government cloud |
| options | PlayerOptions | - | Player options |
| layout | ControlBarLayout | - | Layout customization |
| onEvent | (event) => void | - | Event handlers |
| onBack | () => void | - | Back button callback (for TV) |
| onExit | (info) => void | - | Playback information upon exit (for TV) |
| initialPosition | number | - | Start position (seconds, for resume, for TV) |
| errorOverride | ReactNode \| Component \| Function | - | Custom error UI |

## Caution

Note that the following code patterns are not available in the TV SDK:

```
// ❌ Using unsupported props
<VpePlayer src="https://..." />
<VpePlayer videoUrl="https://..." />

// ❌ Passing a file directly without a playlist
<VpePlayer options={{ file: "https://..." }} />

// ❌ Using web-only layout items
layout={{ bottom: [{ items: ["FullscreenBtn", "PipBtn"] }] }}

// ✅ Correct approach — the native video engine plays HLS and DASH streams directly
<VpePlayer options={{ playlist: [{ file: "https://..." }] }} />
```