---
title: "Web 환경"
slug: "vpe-web"
updated: 2026-10-22T09:11:04Z
published: 2026-10-22T09:11:04Z
canonical: "guide-gov.ncloud-docs.com/vpe-web"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide-gov.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web 환경

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

Web 환경에서는 웹 환경에서 Video Player Enhancement의 플레이어를 적용하는 방법과 플레이어 옵션을 설정하는 방법을 설명합니다.

              참고

              

웹 환경에서 플레이어를 적용하고 설정하려면 다음과 같은 환경이 요구됩니다.

- 외부와의 통신이 가능한 환경
- 크로미엄 기반의 웹 표준을 준수하는 브라우저([웹 브라우저 지원 사양](/docs/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/vpe-player#%ED%94%8C%EB%A0%88%EC%9D%B4%EC%96%B4%EC%83%9D%EC%84%B1)을 참고해 주십시오.

1. 네이버 클라우드 플랫폼 콘솔에서 **Menu** > **All Services** > **Media** > **Video Player Enhancement** 메뉴를 차례대로 클릭해 주십시오.
2. **Video Player Management** 메뉴를 클릭해 주십시오.
3. 플레이어 목록에서 웹 환경에 적용할 플레이어의 **[SDK 주소]** 버튼을 클릭해 주십시오.
4. 플레이어를 적용할 서비스 환경을 선택한 후 **SDK 주소**의 **[복사]** 버튼을 클릭해 주십시오.
  - 해당 플레이어의 SDK 주소가 클립보드에 복사됩니다.
5. 복사한 SDK 주소를 다음과 같이 웹 페이지의 HTML에 추가해 주십시오.

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

## 플레이어 설정

플레이어의 옵션은 네이버 클라우드 플랫폼 콘솔에서 손쉽게 미리 설정할 수 있으며([플레이어 설정](/docs/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 |
| keyboardShortcut | boolean | 키보드 단축키 | true | - | 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 position flow | 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/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.currentTime(value) | 현재 재생 중인 영상의 시간을 변경 - 현재 재생 중인 영상의 재생 시간을 초 단위로 설정하여 변경 <예시> 3분 20초 → 200 |
| ncpplayer.on(type, listner) | 이벤트 수신 - type string: 수신할 이벤트명, 이벤트 목록([지원하는 이벤트](/docs/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/vpe-web#timeupdate%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8) 참고) |
| prevTrack | 이전 영상으로 넘어갈 때 발생하는 이벤트([prevTrack 스크립트](/docs/vpe-web#prevTrack%EC%8A%A4%ED%81%AC%EB%A6%BD%ED%8A%B8) 참고) |
| nextTrack | 다음 영상으로 넘어갈 때 발생하는 이벤트([nextTrack 스크립트](/docs/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 | 프로필 이미지 |