---
title: "Web 環境"
slug: "vpe-web"
updated: 2026-09-17T09:28:48Z
published: 2026-09-17T09:28:48Z
canonical: "guide.ncloud-docs.com/vpe-web"
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.

# Web 環境

Classic/VPC環境で利用できます。

Web環境では、ウェブ環境で Video Player Enhancementのプレイヤーを適用する方法と、プレイヤーのオプションを設定する方法について説明します。

              参考

              

ウェブ環境でプレイヤーを適用して設定するには、次のような環境が求められます。

- 外部との通信が可能な環境
- Chromiumベースのウェブ標準を遵守するブラウザ([ウェブブラウザサポート環境](/docs/ja/vpe-spec#%EC%9B%B9%EB%B8%8C%EB%9D%BC%EC%9A%B0%EC%A0%80%EC%A7%80%EC%9B%90%EC%82%AC%EC%96%91)を参照)

## プレイヤー適用

ウェブページにプレイヤーを適用する方法は、次の通りです。

              参考

              

ウェブページにプレイヤーを適用するには、1つ以上のプレイヤーが必要です。プレイヤーを作成する方法は、[プレイヤー作成](/docs/ja/vpe-player#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%83%9D%EC%84%B1)をご参照ください。

1. NAVERクラウドプラットフォームコンソールで、 **Menu** > **All Services** > **Media** > **Video Player Enhancement**メニューを順にクリックします。
2. **Video Player Management**メニューをクリックします。
3. プレイヤーリストからウェブ環境に適用するプレイヤーの **[SDKアドレス]** ボタンをクリックします。
4. プレイヤーを適用するサービス環境を選択し、**SDKアドレス**の **[コピー]** ボタンをクリックします。
  - そのプレイヤーの SDKアドレスがクリップボードにコピーされます。
5. コピーした SDKアドレスを次のようにウェブページの HTMLに追加します。

```
<script src="플레이어의 SDK 주소"></script>
```

## プレイヤー設定

プレイヤーのオプションは NAVERクラウドプラットフォームコンソールで簡単にプリセットでき([プレイヤー設定](/docs/ja/vpe-player#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%84%A4%EC%A0%95)を参照)、それぞれのプロパティを設定してプレイヤーをカスタマイズできます。 プレイヤーの基本構造は、次の通りです。

```
new ncplayer("HTMLElement id" , {
    playlist:[                
        { file:"http://example.com/myVideo.mp4" } // 再生ソース
    ]
});
```

### プレイヤーオプション

カスタマイズできるオプションは、次の通りです。

              参考

              

利用中の料金プランに応じて設定できるオプションが異なります。

| 料金プラン | プロパティ(属性) | タイプ | 説明 | デフォルト値 | オプションの値 | 必須有無 |
| --- | --- | --- | --- | --- | --- | --- |
| Basic/Standard | playlist | array | プレイリスト | - | - | O |
| autostart | boolean | 自動再生 | true | - | X |
| muted | boolean | ミュート | false | - | X |
| controls | boolean | コントロールバーの使用有無 | true | - | X |
| ui | string | UIの設定 | all | - all: 自動変換 - pc: PC専用 UIの固定 - mobile: モバイル専用 UIの固定 | X |
| aspectRatio | string | 画面アスペクト比 | 16/9 | 16/9, 4/3, 1/1, 9/16, 21/9 | X |
| objectFit | string | 画面拡大 | contain | - contain: 比率維持 - cover: 比率を維持する + 画面サイズに合わせる - fill: 比率は無視する + 画面サイズに合わせる | X |
| autoPause | boolean | タブを無効化すると自動で停止 | false | - | X |
| repeat | boolean | ループ再生 | false | - | X |
| lang | string | UI言語の設定 | auto | - auto: 言語検出 - ko: 韓国語 - en: 英語 - ja: 日本語 - zh: 中国語 | - |
| Standard | controlBtn | array | 以下のオプションを設定 - play boolean: プレイボタン - fullscreen boolean: フルスクリーンに切り替え - volume boolean: ボリュームコントロール - times boolean: 時間情報 UI - pictureInPicture boolean: ミニプレイヤー - setting boolean: セッティングボタン - progressBar boolean: 再生バーの使用有無 | controlBtn: { }, | - | X |
| customBtns | array | 以下のオプションを設定 - ui string: インストールする UI - id string: ボタンの DOM ID - position string: プレイヤー内のボタンポジション - icon string: ボタン画像 URL - flow string: ポジション内のボタン作成位置(デフォルトボタン基準) - callback function: ボタンをクリックすると発生するイベント | - | - ui - pc: pc環境設定 - mobile: モバイル環境設定 - position - right-top: 右上 - right-bottom: 右下 - left-top: 左上 - left-bottom: 左下 - flow - right: 右 - left: 左 | X |
| keyboardShortcut | boolean | キーボードショートカットキー | true | - | X |
| progressBarColor | string | コントロールバーの色 | #4299f5 | - | X |
| controlActiveTime | number | コントロールバーの有効時間(ms) | 3000 | - | X |
| startMutedInfoNotVisible | boolean | ミュート表示 | false | - | X |
| playRateSetting | array | 再生速度選択オプション | [0.5,0.75,1,1.5,2] | - | X |
| seekingPreview | boolean | 動画区間移動のプレビュー | true | - | X |
| touchGestures | boolean | タッチジェスチャー | true | - | X |
| descriptionNotVisible | boolean | メタデータ | false | - | X |
| lowLatencyMode | boolean | CMAF LL-HLS | false | - | X |
| watermarkConfig | array | 以下のオプションを設定 - randPosition boolean: ウォーターマークランダム位置の有効化有無(true: ランダム、false: 固定) - randPositionInterVal number: ウォーターマーク位置のランダム変更時間(1000=1秒) - x number: 横位置% - y number: 縦位置% - opacity number: 透明度(0.1~1) | randPositionInterVal number: 3000 | - | X |

### デフォルトアイコンの変更

スクリプトコードを修正してデフォルトアイコンを変更できます。ユースケースは次の通りです。

```
// 動画(MP4)
const player = new ncplayer('video', {
    playlist: [
        { 
            file: 'https://CDNドメイン/example_video_01.mp4',
            poster: 'https://CDNドメイン/example_image_01.png',
        }
    ],
    controlBtn:{
    play:true,
    fullscreen:true,
    volume:true,
    times:true,
    pictureInPicture:true,
    setting:true,
    subtitle:true,
},

icon:{
        bigPlay:"https://CDNドメイン/icon/play-circle-fill.svg", // 自動再生前の大きなプレイボタン
        play:"https://CDNドメイン/icon/play-fill.svg", // 再生
        use:"https://CDNドメイン/icon/pause-fill.svg", // 一時停止
        prev:"https://CDNドメイン/icon/skip-back-fill.svg", // 前の動画
        next:"https://CDNドメイン/icon/skip-forward-fill.svg", // 次の動画
        replay:"https://CDNドメイン/icon/arrow-clockwise-fill.svg", // もう一度見る
        subtitle:"https://CDNドメイン/icon/closed-captioning-fill.svg", // 字幕を有効化
        subtitleOff:"https://CDNドメイン/icon/closed-captioning.svg", // 字幕を無効化
        fullscreen:"https://CDNドメイン/icon/corners-out.svg", // フルスクリーンに切り替え
        fullscreenExit:"https://CDNドメイン/icon/corners-in.svg", // フルスクリーンを解除
        volumeFull:"https://CDNドメイン/icon/speaker-simple-high-fill.svg", // ボリューム最大
        volumeMute:"https://CDNドメイン/icon/speaker-simple-x-fill.svg", // ボリューム0、ミュート
        volumeMid:"https://CDNドメイン/icon/speaker-simple-low-fill.svg", // ボリューム中間
        pip:"https://CDNドメイン/icon/picture-in-picture-fill.svg", // PIP
        setting:"https://CDNドメイン/icon/gear-fill.svg", // 設定
   }
});
```

| プロパティ(属性) | 説明 |
| --- | --- |
| bigPlay | 自動再生前の大きなプレイボタン |
| play | 再生 |
| pause | 一時停止 |
| prev | 前の動画を再生 |
| next | 次の動画を再生 |
| replay | もう一度見る |
| subtitle | 字幕を有効化 |
| subtitleOff | 字幕を無効化 |
| fullscreen | フルスクリーンに切り替え |
| fullscreenExit | フルスクリーンを解除 |
| volumeFull | ボリューム最大 |
| volumeMute | ボリューム0、ミュート |
| volumeMid | ボリューム中間 |
| pip | PIP |
| setting | 設定 |

### Picture In Picture機能のオーバーライド(Override)

提供される PIP機能をウェブサイト内のフローティングプレイヤー機能に変更できます。ユースケースは次の通りです。

```
// 動画(MP4)
const player = new ncplayer('video', {
    playlist: [
        { 
            file: 'https://CDNドメイン/example_video_01.mp4',
            poster: 'https://CDNドメイン/example_image_01.png',
        }
    ],
    override:{
        pip:{
            on(){
                window.player.uiHidden(); // プレイヤーのすべての UIを隠す
                // 顧客会社のフローティングプレイヤーの実行コードを作成
                // 例) floatingModeStart()
            },
            off(){
                window.player.uiVisible(); // プレイヤーのすべての UIを表示
                // 顧客会社のフローティングプレイヤーの終了コードを作成
                // 例) floatingModeStop()
            }
        }
    }
});
```

#### フローティングプレイヤーの UIを非表示

PIP機能をフローティングプレイヤーに変更した場合、フローティングプレイヤーのコントロール UIの表示有無を設定できます。 この機能はフローティングプレイヤーの実装時に必ず検討すべきメソッドであり、`controlBarActive`/`controlBarDeactive`メソッドとは別に `uiHidden` メソッドを使用してすべての UIを隠したり、`uiVisible`メソッドを使用してすべての UIを表示するように設定できます。 ユースケースは次の通りです。

```
// 動画(MP4)
const player = new ncplayer('video', {
    playlist: [
        { 
            file: 'https://CDNドメイン/example_video_01.mp4',
            poster: 'https://CDNドメイン/example_image_01.png',
        }
    ]
});

//コントロール UIを非表示
player.uiHidden();

//コントロール UIを表示
player.uiVisible();
```

### Playlist

再生ソースの設定に関するプロパティ情報は、次の通りです。

| 料金プラン | プロパティ(属性) | タイプ | 説明 | オプションのユースケース | 必須有無 |
| --- | --- | --- | --- | --- | --- |
| Basic/Standard | file | string | - 再生したい動画情報 - `sources`で代用可能 | playlist: [ ] | O |
| sources | array | - 動画に色々な解像度を提供する場合、次のようなプロパティを有する - `file`で代用可能 | - | X |
| poster | string | 動画再生前に表示する画像 | - | X |
| Standard | description | array | プレイヤーの上に表示するメタデータであり、次のようにプロパティを有する - title string: タイトル - created_at string: 日付 - profile_name string: チャンネル名またはアップローダのハンドルネーム - profile_image string: チャンネル画像またはアップローダプロファイル画像 - callback function: メタデータをクリックすると発生するイベント | description: { } | X |

### Method

Video Player Enhancementサービスは、動画を再生して様々な機能を実現できる様々なメソッドを提供します。

              参考

              

[プレイヤーを作成](/docs/ja/vpe-player#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%83%9D%EC%84%B1)した後からメソッドを呼び出すことができます。

プレイヤーを作成して再生するスクリプトは、次の通りです。

```
let player = new ncplayer('myElement', {
    playlist: [
        { 
            file:"http://example.com/myVideo.mp4",
            poster:"http://example.com/myVideoThumb.png" 
        }
    ]
});
player.play();
```

#### 対応 Method

Video Player Enhancementサービスで対応するメソッドは、次の通りです。

| メソッド | 説明 |
| --- | --- |
| ncplayer.play() | 動画再生 |
| ncplayer.pause() | 動画の一時停止 |
| ncplayer.prev() | 前の動画がある場合、前の動画を再生 |
| ncplayer.next() | 次の動画がある場合、次の動画を再生 |
| ncplayer.mute() | 動画ミュート |
| ncplayer.controlBarActive() | プレイヤーコントロールバー UIの有効化 |
| ncplayer.controlBarDeactive() | プレイヤーコントロールバー UIの無効化 |
| ncplayer.fullscreen() | フルスクリーンに切り替え |
| ncplayer.pip() | ミニプレイヤーに切り替え |
| ncplayer.volume(value) | ボリュームコントロール - 0.0~1の間の値で設定 |
| ncplayer.destroy() | プレイヤー削除 |
| ncplayer.uiHidden() | プレイヤー UIをすべて非表示 |
| ncplayer.uiVisible() | プレイヤー UIをすべて表示 |
| ncplayer.fullscreenOn() | フルスクリーン実行(外部からフルスクリーンをコントロール) |
| ncplayer.fullScreenOff() | フルスクリーン終了(外部からフルスクリーンをコントロール) |
| ncplayer.currentTime(value) | 現在再生中の映像の時間を変更 - 現在再生中の映像の再生時間を秒単位で設定して変更 例) 3分20秒 -> 200 |
| ncpplayer.on(type, listner) | イベント受信 - type string: 受信するイベント名、イベントリスト([対応するイベント](/docs/ja/vpe-web#%EC%A7%80%EC%9B%90%ED%95%98%EB%8A%94%EC%9D%B4%EB%B2%A4%ED%8A%B8)を参照) - listner function: イベントが発生すると呼び出す関数を転送 |

### イベント

Video Player Enhancementサービスはユーザーのための様々なイベントを提供し、メタデータをクリックすると発生するイベントを設定できます。

              参考

              

イベント機能は、Standard料金プランでのみ提供されます。

イベントは次のように受け取ることができます。

```
let player = new ncplayer('myElement', {
    playlist: [
        { 
            file:"http://example.com/myVideo.mp4",
            poster:"http://example.com/myVideoThumb.png" 
        }
    ]
});

player.on('play',(e)=>{
    console.log('Playしました。',e);
})
```

#### 対応するイベント

Video Player Enhancementサービスで対応するイベントは、次の通りです。

| イベント | 説明 |
| --- | --- |
| play | 動画再生リクエストが成功した時に発生するイベント |
| pause | 動画が一時停止した時に発生するイベント |
| ready | プレイヤーが再生する準備が完了した時に発生するイベント |
| ended | 再生が最後まで完了した時に発生するイベント |
| seeking | seek動作を開始する時に発生するイベント |
| seeked | Seek動作が完了した時に発生するイベント |
| waiting | バッファが発生した時に発生するイベント |
| volumechange | ボリュームを変更する時に発生するイベント(ミュートを含む) |
| controlbarActive | コントロールバーが有効化した時に発生するイベント |
| controlbarDeactive | コントロールバーが無効化した時に発生するイベント |
| fullscreen | フルスクリーン状態が変更した時に発生するイベント |
| fullscreen_on | フルスクリーンが開始した時に発生するイベント |
| fullscreen_off | フルスクリーンが終了した時に発生するイベント - iOS(iPhone)モバイルウェブでは使用不可 |
| timeupdate | 現在の再生時間が変更される時に発生するイベント([timeupdateスクリプト](/docs/ja/vpe-web#timeupdate%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)を参照) |
| prevTrack | 前の動画に移動する時に発生するイベント([prevTrackスクリプト](/docs/ja/vpe-web#prevTrack%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)を参照) |
| nextTrack | 次の動画に移動する時に発生するイベント([nextTrackスクリプト](/docs/ja/vpe-web#nextTrack%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)を参照) |

**timeupdateスクリプト** timeupdateイベントに対するスクリプトおよび各プロパティの説明は、次の通りです。

```
let player = new ncplayer('myElement', {
    playlist: [
        { 
            file:"http://example.com/myVideo.mp4",
            poster:"http://example.com/myVideoThumb.png" 
        }
    ]
});

player.on('timeupdate',(data)=>{
    console.log('動画全体の長さ(duration) : ',data.duration);
    console.log('現在の再生位置(currentTime) : ',data.currentTime);
    console.log('現在の再生パーセント(percent) : ',data.percent);
    console.log('累計再生時間(viewingTime) : ',data.viewingTime);
    console.log('再生ソースタイプ(sourceType) : ',data.sourceType); // 再生ソースタイプ(vod、live)
})
```

| プロパティ(属性) | タイプ | 説明 |
| --- | --- | --- |
| duration | int | 動画全体の長さ |
| currentTime | int | 現在の再生位置 |
| percent | int | 現在の再生率 |
| viewingTime | int | 累計再生時間 |
| sourceType | string | 再生ソースタイプ |

**prevTrackスクリプト** prevTrackイベントに対するスクリプトと各プロパティの説明は、次の通りです。

```
let player = new ncplayer('myElement', {
    playlist: [
        { 
            file:"http://example.com/myVideo.mp4",
            poster:"http://example.com/myVideoThumb.png" 
        },
        { 
            file:"http://example.com/myVideo2.mp4",
            poster:"http://example.com/myVideoThumb2.png" 
        }
    ]
});

player.on('prevTrack',(data)=>{
    console.log('prevTrack' , data);
})
```

| プロパティ(属性) | タイプ | 説明 |
| --- | --- | --- |
| file | string | 動画 URL |
| poster | string | サムネイル画像 |
| title | string | 動画タイトル |
| created_at | string | 動画の日付 |
| profile_name | string | プロファイル名 |
| profile_image | string | プロファイル画像 |

**nextTrackスクリプト** nextTrackイベントに対するスクリプトと各プロパティの説明は、次の通りです。

```
let player = new ncplayer('myElement', {
    playlist: [
        { 
            file:"http://example.com/myVideo.mp4",
            poster:"http://example.com/myVideoThumb.png" 
        },
        { 
            file:"http://example.com/myVideo2.mp4",
            poster:"http://example.com/myVideoThumb2.png" 
        }
    ]
});

player.on('nextTrack',(data)=>{
    console.log('nextTrack' , data);
})
```

| プロパティ(属性) | タイプ | 説明 |
| --- | --- | --- |
| file | string | 動画 URL |
| poster | string | サムネイル画像 |
| title | string | 動画タイトル |
| created_at | string | 動画の日付 |
| profile_name | string | プロファイル名 |
| profile_image | string | プロファイル画像 |