---
title: "Web environment"
slug: "vpe-web"
updated: 2026-09-17T09:22:36Z
published: 2026-09-17T09:22:36Z
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 environment

Available in Classic and VPC

This section explains how to apply the Video Player Enhancement player and configure player options in a web environment.

              Note

              

The following environment is required to apply and configure the player in a web environment:

- An environment capable of external communication.
- A Chromium-based browser that complies with web standards (see [web browser support specifications](/docs/en/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)).

## Apply player

To apply a player to a web page:

              Note

              

To apply a player to a web page, at least 1 player must exist. To create a player, see [Create a player](/docs/en/vpe-player#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%83%9D%EC%84%B1).

1. Navigate to**Menu** > **All Services** > **Media** > **Video Player Enhancement** from the NAVER Cloud Platform console.
2. Click the **Video Player Management** menu.
3. In the player list, click the **[SDK address]** button of the player you want to apply to the web environment.
4. Select the service environment to apply the player to, and then click the **[Copy]** button next to **SDK address**.
  - The SDK address of the player is copied to the clipboard.
5. Add the copied SDK address to the HTML of the web page as follows:

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

## Set up player

Player options can be easily configured in the NAVER Cloud Platform console (see [Player settings](/docs/en/vpe-player#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%84%A4%EC%A0%95)), or you can customize the player by configuring individual properties. The basic structure of the player is as follows:

```
new ncplayer("HTMLElement id" , {
    playlist:[                
        { file:"http://example.com/myVideo.mp4" } // Playback source
    ]
});
```

### Player options

The customizable options are as follows:

              Note

              

Configurable options may vary depending on the current pricing plan.

| Pricing plan | Property | Type | Description | Default value | Option value | Required |
| --- | --- | --- | --- | --- | --- | --- |
| Basic/Standard | playlist | array | Playlist | - | - | O |
| autostart | boolean | Autoplay | true | - | X |
| muted | boolean | Mute | false | - | X |
| controls | boolean | Enable control bar | true | - | X |
| ui | string | UI settings | all | - all: Auto convert. - pc: Fixed PC UI. - mobile: Fixed mobile UI. | X |
| aspectRatio | string | Aspect ratio | 16/9 | 16/9, 4/3, 1/1, 9/16, 21/9 | X |
| objectFit | string | Screen fit | contain | - contain: Fit to aspect ratio. - cover: Fit to aspect ratio + fill. - fill: Ignore aspect ratio + fill. | X |
| autoPause | boolean | Auto-pause when the tab is inactive | false | - | X |
| repeat | boolean | Loop playback | false | - | X |
| lang | string | UI language settings | auto | - auto: Auto-detect language - ko: Korean - en: English - ja: Japanese - zh: Chinese | - |
| Standard | controlBtn | array | Set the following options: - play boolean: Play button. - fullscreen boolean: Full screen toggle. - volume boolean: Volume control. - times boolean: Time information UI. - pictureInPicture boolean: Mini player. - setting boolean: Settings button. - progressBar boolean: Enable playback bar. | controlBtn: { }, | - | X |
| customBtns | array | Set the following options: - ui string: Target UI. - id string: DOM ID of a button. - position string: Button position in a player. - icon string: Button image URL. - flow string: Button generation location in position (relative to default buttons). - callback function: Event called on button click. | - | - ui - pc: PC environment settings - mobile: Mobile environment settings - position - right-top: Top right - right-bottom: Bottom right - left-top: Top left - left-bottom: Bottom left - flow - right: Right - left: Left | X |
| keyboardShortcut | boolean | Keyboard shortcuts | true | - | X |
| progressBarColor | string | Control bar color | #4299f5 | - | X |
| controlActiveTime | number | Control bar display duration (ms) | 3000 | - | X |
| startMutedInfoNotVisible | boolean | Mute indication | false | - | X |
| playRateSetting | array | Playback speed options | [0.5,0.75,1,1.5,2] | - | X |
| seekingPreview | boolean | Video thumbnail preview | true | - | X |
| touchGestures | boolean | Touch gestures | true | - | X |
| descriptionNotVisible | boolean | Metadata | false | - | X |
| lowLatencyMode | boolean | CMAF LL-HLS | false | - | X |
| watermarkConfig | array | Set the following options: - randPosition boolean: Enable random watermark position (true: random, false: fixed). - randPositionInterVal number: Random position change interval (1000 = 1 sec). - x number: Horizontal position %. - y number: Vertical position %. - opacity number: Opacity (0.1-1). | randPositionInterVal number: 3000 | - | X |

### Change default icon

You can modify the script code to change default icons. The example is as follows:

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

icon:{
        bigPlay:"https://CDNdomain/icon/play-circle-fill.svg", // Big play button before autoplay
        play:"https://CDNdomain/icon/play-fill.svg", // Play
        use:"https://CDNdomain/icon/pause-fill.svg", // Pause
        prev:"https://CDNdomain/icon/skip-back-fill.svg", // Previous video
        next:"https://CDNdomain/icon/skip-forward-fill.svg", // Next video
        replay:"https://CDNdomain/icon/arrow-clockwise-fill.svg", // Replay
        subtitle:"https://CDNdomain/icon/closed-captioning-fill.svg", // Subtitle on
        subtitleOff:"https://CDNdomain/icon/closed-captioning.svg", // Subtitle off
        fullscreen:"https://CDNdomain/icon/corners-out.svg", // Switch to full screen
        fullscreenExit:"https://CDNdomain/icon/corners-in.svg", // Exit full screen
        volumeFull:"https://CDNdomain/icon/speaker-simple-high-fill.svg", // Maximum volume
        volumeMute:"https://CDNdomain/icon/speaker-simple-x-fill.svg", // Volume 0, Mute
        volumeMid:"https://CDNdomain/icon/speaker-simple-low-fill.svg", // Medium volume
        pip:"https://CDNdomain/icon/picture-in-picture-fill.svg", // PIP
        setting:"https://CDNdomain/icon/gear-fill.svg", // Settings
   }
});
```

| Property | Description |
| --- | --- |
| bigPlay | Big play button before autoplay. |
| play | Play. |
| pause | Pause. |
| prev | Play previous video. |
| next | Play next video. |
| replay | Replay. |
| subtitle | Subtitle on. |
| subtitleOff | Subtitle off. |
| fullscreen | Full screen toggle. |
| fullscreenExit | Exit full screen. |
| volumeFull | Maximum volume. |
| volumeMute | Volume 0, mute. |
| volumeMid | Medium volume. |
| pip | PIP |
| setting | Settings. |

### Override Picture In Picture feature

You can replace the provided PIP feature with a floating player feature within the website. The example is as follows:

```
// Video (MP4)
const player = new ncplayer('video', {
    playlist: [
        { 
            file: 'https://CDNdomain/example_video_01.mp4',
            poster: 'https://CDNdomain/example_image_01.png',
        }
    ],
    override:{
        pip:{
            on(){
                window.player.uiHidden(); // Hide all player UI
                // Write code to execute the custom floating player
                // Example: floatingModeStart()
            },
            off(){
                window.player.uiVisible(); // Show all player UI
                // Write code to stop the custom floating player
                // Example: floatingModeStop()
            }
        }
    }
});
```

#### Hide floating player UI

If the PIP feature is replaced with a floating player, you can set whether to display the floating player's control UI. This is a mandatory method to consider when implementing a floating player. In addition to the `controlBarActive`/`controlBarDeactive` methods, you can use the `uiHidden` method to hide all UI or the `uiVisible` method to display all UI. The example is as follows:

```
// Video (MP4)
const player = new ncplayer('video', {
    playlist: [
        { 
            file: 'https://CDNdomain/example_video_01.mp4',
            poster: 'https://CDNdomain/example_image_01.png',
        }
    ]
});

// Hide control bar UI
player.uiHidden();

// Show control bar UI
player.uiVisible();
```

### Playlist

The properties for setting the playback source are as follows:

| Pricing plan | Property | Type | Description | Option example | Required |
| --- | --- | --- | --- | --- | --- |
| Basic/Standard | file | string | - Video information to play. - Can be replaced with `sources`. | playlist: [ ] | O |
| sources | array | - Used when providing various resolutions for the video; it has the following properties: - Can be replaced with `file`. | - | X |
| poster | string | Image displayed before video playback. | - | X |
| Standard | description | array | Metadata displayed at the top of the player, consisting of the following properties: - title string: Title. - created_at string: Date. - profile_name string: Channel name or uploader nickname. - profile_image string: Channel image or uploader profile image. - callback function: Event triggered when metadata is clicked. | description: { } | X |

### Method

The Video Player Enhancement service provides various methods to play a video and implement various features.

              Note

              

You can call a method after you [create a player](/docs/en/vpe-player#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%83%9D%EC%84%B1).

The script to create a player and play video is as follows:

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

#### Supported methods

Methods supported by the Video Player Enhancement service are as follows:

| Method | Description |
| --- | --- |
| ncplayer.play() | Play a video. |
| ncplayer.pause() | Pause a video. |
| ncplayer.prev() | If a previous video exists, play the previous video. |
| ncplayer.next() | If a next video exists, play the next video. |
| ncplayer.mute() | Mute video. |
| ncplayer.controlBarActive() | Enable player control bar UI. |
| ncplayer.controlBarDeactive() | Disable player control bar UI. |
| ncplayer.fullscreen() | Switch to full screen. |
| ncplayer.pip() | Switch to mini player. |
| ncplayer.volume(value) | Adjust the volume. - Set the volume level between 0.0 and 1. |
| ncplayer.destroy() | Remove the player. |
| ncplayer.uiHidden() | Hide all player UIs. |
| ncplayer.uiVisible() | Show all player UIs. |
| ncplayer.fullscreenOn() | Launch full screen (control full screen from outside). |
| ncplayer.fullScreenOff() | Exit full screen (control full screen from outside). |
| ncplayer.currentTime(value) | Change the time of the currently playing video. - Change the playback time of the currently playing video in seconds. Example: 3 minutes 20 seconds -> 200. |
| ncpplayer.on(type, listner) | Receive event. - type string: Name of the event to receive, event list (see [Supported events](/docs/en/vpe-web#%EC%A7%80%EC%9B%90%ED%95%98%EB%8A%94%EC%9D%B4%EB%B2%A4%ED%8A%B8)). - listener function: Pass the function to be called when an event occurs. |

### Event

The Video Player Enhancement service provides various events, and allows you to configure events triggered when clicking metadata.

              Note

              

Event features are only provided in the Standard pricing plan.

Events can be received as follows:

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

player.on('play',(e)=>{
    console.log('Played.',e);
})
```

#### Supported events

The events supported by the Video Player Enhancement service are as follows:

| Event | Description |
| --- | --- |
| play | Event that occurs when a video playback request is successful. |
| pause | Event that occurs when a video pauses. |
| ready | Event that occurs when a player is ready to play. |
| ended | Event that occurs when playback completes. |
| seeking | Event that occurs when the seek action starts. |
| seeked | Event that occurs when the seek action is completed. |
| waiting | Event that occurs when buffering occurs. |
| volumechange | Event that occurs when the volume changes (including mute). |
| controlbarActive | Event that occurs when the control bar has been enabled. |
| controlbarDeactive | Event that occurs when the control bar has been disabled. |
| fullscreen | Event that occurs when full screen state changes. |
| fullscreen_on | Event that occurs when full screen mode starts. |
| fullscreen_off | Event that occurs when full screen mode ends. - Not available on the iOS (iPhone) mobile web. |
| timeupdate | Event that occurs when current play time changes (see [timeupdate script](/docs/en/vpe-web#timeupdate%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)). |
| prevTrack | Event that occurs when moving to the previous video (see [prevTrack script](/docs/en/vpe-web#prevTrack%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)). |
| nextTrack | Event that occurs when moving to the next video (see [nextTrack script](/docs/en/vpe-web#nextTrack%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8)). |

**timeupdate script** The script for the timeupdate event, along with descriptions of each property, is as follows:

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

player.on('timeupdate',(data)=>{
    console.log('Total duration of the video (duration): ',data.duration);
    console.log('Current playback position (currentTime): ',data.currentTime);
    console.log('Current playback percentage (percent): ',data.percent);
    console.log('Accumulated playback time (viewingTime): ',data.viewingTime);
    console.log('playback source type (sourceType): ',data.sourceType); // Playback source type(vod, live)
})
```

| Property | Type | Description |
| --- | --- | --- |
| duration | int | Total duration of the video |
| currentTime | int | Current playback position |
| percent | int | Current playback rate |
| viewingTime | int | Accumulated playback time |
| sourceType | string | Playback source type |

**prevTrack script** The script for the prevTrack event, along with descriptions of each property, is as follows:

```
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);
})
```

| Property | Type | Description |
| --- | --- | --- |
| file | string | Video URL |
| poster | string | Thumbnail image |
| title | string | Video title |
| created_at | string | Video date |
| profile_name | string | Profile name |
| profile_image | string | Profile image |

**nextTrack script** The script for the nextTrack event, along with descriptions of each property, is as follows:

```
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);
})
```

| Property | Type | Description |
| --- | --- | --- |
| file | string | Video URL |
| poster | string | Thumbnail image |
| title | string | Video title |
| created_at | string | Video date |
| profile_name | string | Profile name |
| profile_image | string | Profile image |