---
title: "プレイヤー UI"
slug: "vpe-tv-player-ui"
updated: 2026-09-17T09:22:05Z
published: 2026-09-17T09:22:05Z
canonical: "guide.ncloud-docs.com/vpe-tv-player-ui"
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を構成・設定するためのオプションと、宣言型レイアウトシステムをご案内します。

## controls

`controls` プロパティでコントロールバーの表示有無を設定します。

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: false, // コントロールバーを非表示
    }}
    onBack={() => navigation.goBack()}
/>
```

## controlBtn

`controlBtn` プロパティで個別ボタンの表示有無を設定できます。TV SDKには `fullscreen`、`pictureInPicture` プロパティはありません。

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: true,
        controlBtn: {
            play: true,
            progressBar: true,
            volume: true,
            times: true,
            setting: true,
            subtitle: true,
        },
    }}
    onBack={() => navigation.goBack()}
/>
```

## progressBarColor

`progressBarColor` プロパティでプログレスバーの色を設定できます。

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

## controlActiveTime

- `controlActiveTime` プロパティでコントロールバーが自動的に非表示になるまでの時間を設定します。デフォルト値は3000ms(3秒)です。

              参考

              

`controlActiveTime`を `0`に設定すると、コントロールバーは自動的に非表示にならず**常に表示**されます。ライブコマースのように、UIが常に表示される必要がある画面で役立ちます。

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controlActiveTime: 5000, // 5秒後に自動で非表示
    }}
    onBack={() => navigation.goBack()}
/>
```

## lang

`lang` プロパティで UI言語を設定できます。

| 値 | 言語 |
| --- | --- |
| ko | 韓国語(デフォルト値) |
| en | English |
| ja | 日本語 |

## リモコンイベント

TV SDKは、リモコンの D-pad入力を自動的に処理します。

| イベント | Apple TV | Android TV | 動作 |
| --- | --- | --- | --- |
| select | O | O | 確認/選択 |
| playPause | O | O | 再生/一時停止 |
| up/down | O | O | コントロールバー表示/フォーカス移動 |
| left/right | O | O | `SeekBar`で±10秒シーク |
| menu | O | X | 戻る |
| rewind/fastForward | X | O | 巻き戻し/早送り |

## レイアウトシステム

TV SDKの宣言型レイアウトシステムを使用すると、コントロールバーの UIをカスタマイズできます。

## レイアウト構造

5つのセクション(`top`, `upper`, `center`, `lower`, `bottom`)と `seekbar`で構成される宣言型レイアウトです。

## 使用可能なアイテム

コントロールバーに配置できるアイテムは次の通りです。

| アイテム | 説明 |
| --- | --- |
| `PlayBtn` | 再生 / 一時停止 / リプレイ |
| `BigPlayBtn` | 中央大型再生 + 前へ / 次へ |
| `BackBtn` | 戻る |
| `SeekBar` | シークバー(D-padの左/右で±10秒ずつ移動) |
| `SkipBackBtn / SkipForwardBtn` | ±10秒シーク |
| `PrevBtn / NextBtn / NextPrevBtn` | トラック移動 |
| `TimeBtn / CurrentTimeBtn / DurationBtn` | 時間表示(ライブ時は LIVEインジケータ) |
| `MuteBtn / VolumeBtn` | ミュート/ボリューム(TVではミュートトグル) |
| `SubtitleBtn` | 字幕メニュー |
| `SettingBtn` | 設定メニュー |
| `MetaDesc` | 動画のメタ情報 |
| `Blank / BlankBtn` | 空白 |

TVから除外されたアイテムは `FullscreenBtn`、`PipBtn`、`ShareBtn`であり、レイアウトに含めても無視されます。

## カスタムレイアウトのユースケース

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        top: [
            { items: ['BackBtn'], wrapper: 'Group' },
            { items: ['MetaDesc'] },
            { wrapper: 'Blank', items: [] },
        ],
        center: [
            { items: ['BigPlayBtn'], align: 'center' },
        ],
        lower: [
            { wrapper: 'Blank', items: ['SeekBar'], align: 'center' },
        ],
        bottom: [
            { items: ['PlayBtn'], wrapper: 'Group' },
            { items: ['NextPrevBtn'], wrapper: 'Group' },
            { items: ['MuteBtn'], wrapper: 'Group' },
            { items: ['TimeBtn'], wrapper: 'Group' },
            { wrapper: 'Blank', items: [] },
            { items: ['SubtitleBtn', 'SettingBtn'], wrapper: 'Group' },
        ],
    }}
    onBack={() => navigation.goBack()}
/>
```

## VOD/Liveのバリエーション

VODと Liveでは、それぞれ異なるレイアウトを使用できます。

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        vod: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['SettingBtn'], wrapper: 'Group' },
            ],
        },
        live: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['MuteBtn'], wrapper: 'Group' },
            ],
        },
    }}
    onBack={() => navigation.goBack()}
/>
```

## ランタイムレイアウトの変更

refメソッドを使用すると、ランタイムにレイアウトを変更できます。

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

// 部分アップデート(merge=true、デフォルト値)
playerRef.current?.layout(
    { bottom: [{ items: ['PlayBtn'], wrapper: 'Group' }] },
    true
);

// すべて置き換え(merge=false)
playerRef.current?.layout(newLayout, false);
```

## グループオプション

各グループに設定できるプロパティは、次の通りです。

| プロパティ | タイプ | 説明 |
| --- | --- | --- |
| `items` | string[] | レイアウトアイテムリスト |
| `wrapper` | 'Blank', 'Group' | ラッパータイプ |
| `align` | 'left' , 'right' , 'center' | ソート |
| `size` | number | ボタンサイズ(デフォルト88) |