---
title: "Web 환경"
slug: "vpe-web"
updated: 2026-05-21T09:01:51Z
published: 2026-05-21T09:03:18Z
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 환경

<p class="platform-info type-classic-vpc">Classic/VPC 환경에서 이용 가능합니다.</p>

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

:::(Info) (참고)
웹 환경에서 플레이어를 적용하고 설정하려면 다음과 같은 환경이 요구됩니다.
* 외부와의 통신이 가능한 환경
* 크로미엄 기반의 웹 표준을 준수하는 브라우저([웹 브라우저 지원 사양](/docs/vpe-spec#웹브라우저지원사양) 참고)
:::

## 플레이어 적용 <a name="플레이어적용"></a>

웹 페이지에 플레이어를 적용하는 방법은 다음과 같습니다.

:::(Info) (참고)
웹 페이지에 플레이어를 적용하려면 1개 이상의 플레이어가 존재해야 합니다. 플레이어 생성 방법은 [플레이어 생성](/docs/vpe-player#플레이어생성)을 참고해 주십시오.
:::

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

## 플레이어 설정 <a name="플레이어설정"></a>

플레이어의 옵션은 네이버 클라우드 플랫폼 콘솔에서 손쉽게 미리 설정할 수 있으며([플레이어 설정](/docs/vpe-player#플레이어설정) 참고), 각각의 속성을 설정하여 플레이어를 커스터마이징할 수도 있습니다.
플레이어의 기본 구조는 다음과 같습니다.
```JavaScript
new ncplayer("HTMLElement id" , {
    playlist:[                
        { file:"http://example.com/myVideo.mp4" } // 재생 소스
    ]
});
```

### 플레이어 옵션 <a name="플레이어옵션"></a>

커스터마이징할 수 있는 옵션은 다음과 같습니다.

:::(Info) (참고)
이용 중인 요금제에 따라 설정할 수 있는 옵션에 차이가 있습니다.
:::

<table>
  <thead>
    <tr>
      <th align="left">요금제</th>
      <th align="left">프로퍼티(속성)</th>
      <th align="left">유형</th>
      <th align="left">설명</th>
      <th align="left">기본값</th>
      <th align="left">옵션값</th>
      <th align="left">필수 여부</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="11">Basic/Standard</td>
      <td>playlist</td>
      <td>array</td>
      <td>플레이리스트</td>
      <td>-</td>
      <td>-</td>
      <td>O</td>
    </tr>
    <tr>
      <td>autostart</td>
      <td>boolean</td>
      <td>자동 재생</td>
      <td>true</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>muted</td>
      <td>boolean</td>
      <td>음소거</td>
      <td>false</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>keyboardShortcut</td>
      <td>boolean</td>
      <td>키보드 단축키</td>
      <td>true</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>controls</td>
      <td>boolean</td>
      <td>컨트롤바 사용 여부</td>
      <td>true</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>ui</td>
      <td>string</td>
      <td>UI 설정</td>
      <td>all</td>
      <td><li>all: 자동 변환</li><li>pc: PC 전용 UI 고정</li><li>mobile: 모바일 전용 UI 고정</li></td>
      <td>X</td>
    </tr>
    <tr>
      <td>aspectRatio</td>
      <td>string</td>
      <td>화면 비율</td>
      <td>16/9</td>
      <td>16/9, 4/3, 1/1, 9/16, 21/9</td>
      <td>X</td>
    </tr>
    <tr>
      <td>objectFit</td>
      <td>string</td>
      <td>화면 맞춤</td>
      <td>contain</td>
      <td><li>contain: 비율 맞춤</li><li>cover: 비율 맞춤 + 꽉 채움</li><li>fill: 비율 무시 + 꽉 채움</td>
      <td>X</td>
    </tr>
    <tr>
      <td>autoPause</td>
      <td>boolean</td>
      <td>탭 비활성화 시 자동 멈춤</td>
      <td>false</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>repeat</td>
      <td>boolean</td>
      <td>반복 재생</td>
      <td>false</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>lang</td>
      <td>string</td>
      <td>UI 언어 설정</td>
      <td>auto</td>
      <td><li>auto: 언어 감지</li><li>ko: 한국어</li><li>en: 영어</li><li>ja: 일본어</li><li>zh: 중국어</li></td>
      <td>-</td>
    </tr>
    <tr>
      <td rowspan="11">Standard</td>
      <td>controlBtn</td>
      <td>array</td>
      <td>다음과 같은 옵션 설정<ul><li>play boolean: 플레이 버튼</li><li>fullscreen boolean: 전체 화면 전환</li><li>volume boolean: 볼륨 컨트롤</li><li>times boolean: 시간 정보 UI</li><li>pictureInPicture boolean: 미니 플레이어</li><li>setting boolean: 세팅 버튼</li><li>progressBar boolean : 재생바 사용 여부</li></ul></td>
      <td>controlBtn: {<br><ul>play: true,<br>fullscreen: true,<br>volume: true,<br>times: true,<br>pictureInPicture: true,<br>setting: true,,<br>progressBar : true</ul>},</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>customBtns</td>
      <td>array</td>
      <td>다음과 같은 옵션 설정<ul><li>ui string: 설치할 UI</li><li>id string: 버튼의 DOM ID</li><li>position string: 플레이어 내 버튼 포지션</li><li>icon string: 버튼 이미지 URL</li><li>flow string: 포지션 내 버튼 생성 위치(기본 버튼 기준)</li><li>callback function: 버튼 클릭 시 발생하는 이벤트</li></ul></td>
      <td>-</td>
      <td><li>ui</li><ul><ul><li>pc: pc 환경 설정</li><li>mobile: 모바일 환경 설정</li></ul></ul><li>position</li><ul><ul><li>right-top: 우측 상단</li><li>right-bottom: 우측 하단</li><li>left-top: 좌측 상단</li><li>left-bottom: 좌측 하단</li></ul></ul><li>flow</li><ul><ul><li>right: 오른쪽</li><li>left: 왼쪽</li></ul></ul></td>
      <td>X</td>
    </tr>
    <tr>
      <td>progressBarColor</td>
      <td>string</td>
      <td>컨트롤바 색상</td>
      <td>#4299f5</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>controlActiveTime</td>
      <td>number</td>
      <td>컨트롤바 활성 시간(ms)</td>
      <td>3000</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>startMutedInfoNotVisible</td>
      <td>boolean</td>
      <td>음소거 알림</td>
      <td>false</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>playRateSetting</td>
      <td>array</td>
      <td>배속 선택 옵션</td>
      <td>[0.5,0.75,1,1.5,2]</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>seekingPreview</td>
      <td>boolean</td>
      <td>영상 구간 이동 미리 보기</td>
      <td>true</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>touchGestures</td>
      <td>boolean</td>
      <td>터치 제스처</td>
      <td>true</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>descriptionNotVisible</td>
      <td>boolean</td>
      <td>메타데이터</td>
      <td>false</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>lowLatencyMode</td>
      <td>boolean</td>
      <td>CMAF LL-HLS</td>
      <td>false</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>watermarkConfig</td>
      <td>array</td>
      <td>다음과 같은 옵션 설정<ul><li>randPosition boolean: 워터마크 렌덤 위치 활성화 여부(true: 랜덤, false: 고정)</li><li>randPositionInterVal number: 워터마크 위치 랜덤 변경 시간(1000=1초)</li><li>x number: 가로 위치 %</li><li>y number: 세로 위치 %</li><li>opacity number: 투명도(0.1 ~ 1)</li></ul></td>
      <td>randPositionInterVal number: 3000</td>
      <td>-</td>
      <td>X</td>
    </tr>
  </tbody>
</table>

### 기본 아이콘 변경 <a name="기본아이콘변경"></a>

스크립트 코드를 수정하여 기본 아이콘을 변경할 수 있습니다. 예제는 다음과 같습니다.
```JavaScript
// 동영상(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) <a name="PictureInPicture기능의재정의Override"></a>

제공되는 PIP 기능을 웹사이트 내 플로팅 플레이어 기능으로 변경할 수 있습니다. 예제는 다음과 같습니다.
```JavaScript
// 동영상(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 숨김 <a name="플로팅플레이어UI숨김"></a>

PIP 기능을 플로팅 플레이어로 변경한 경우, 플로팅 플레이어의 컨트롤 UI 표시 여부를 설정할 수 있습니다.
해당 기능은 플로팅 플레이어 구현 시 반드시 고려해야 할 메소드이며, `controlBarActive`/`controlBarDeactive` 메소드와 별개로 `uiHidden` 메소드를 사용하여 모든 UI를 숨기거나 `uiVisible` 메소드를 사용하여 모든 UI를 표시하도록 설정할 수 있습니다.
예제는 다음과 같습니다.
```JavaScript
// 동영상(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 <a name="Playlist"></a>

재생 소스 설정에 대한 속성 정보는 다음과 같습니다.

<table>
  <thead>
    <tr>
      <th align="left">요금제</th>
      <th align="left">프로퍼티(속성)</th>
      <th align="left">유형</th>
      <th align="left">설명</th>
      <th align="left">옵션 예제</th>
      <th align="left">필수 여부</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="3">Basic/Standard</td>
      <td>file</td>
      <td>string</td>
      <td><ul><li>재생하고자 하는 영상 정보</li><ul><li>hls, dash, mp4 지원</li></ul><li><code>sources</code>로 대체 가능</li></ul></td>
      <td>playlist: [<ul>{<ul>file: 'https://CDN도메인/example_video_01.mp4',</ul>}</ul>]</td>
      <td>O</td>
    </tr>
    <tr>
      <td>sources</td>
      <td>array</td>
      <td><ul><li>영상에 여러 가지 해상도를 제공하는 경우 사용하며 다음과 같은 속성을 가짐</li><ul><li>file string: 해상도별 영상 파일 경로</li><li>label string: 해상도 조절 컨트롤에 표시되는 텍스트</li><li>default boolean: 기본 해상도 적용</li></ul><li><code>file</code>로 대체 가능</li></ul></td>
      <td>-</td>
        <td>X</td>
    </tr>
    <tr>
      <td>poster</td>
      <td>string</td>
      <td>영상 재생 전 표시할 이미지</td>
      <td>-</td>
      <td>X</td>
    </tr>
    <tr>
      <td>Standard</td>
      <td>description</td>
      <td>array</td>
      <td>플레이어 상단에 표시할 메타데이터로 다음과 같은 속성을 가짐<ul><li>title string: 제목</li><li>created_at string: 날짜</li><li>profile_name string: 채널명 또는 업로더 닉네임</li><li>profile_image string: 채널 이미지 또는 업로더 프로필 이미지</li><li>callback function: 메타데이터 클릭 시 발생하는 이벤트</li></ul></td>
      <td>description: {<br><ul>title: "제목",<br>created_at: "날짜",<br>profile_name: "업로더 닉네임",<br>profile_image: "채널 이미지",<br>callback(){<ul>location.href='...'</ul>}</ul>}</br></td>
      <td>X</td>
    </tr>
  </tbody>
</table>

### Method <a name="Method"></a>

Video Player Enhancement 서비스는 영상을 재생하고 다양한 기능을 구현할 수 있는 여러 가지 메소드를 제공합니다.

:::(Info) (참고)
[플레이어를 생성](/docs/vpe-player#플레이어생성)한 후부터 메소드를 호출할 수 있습니다.
:::

플레이어를 생성하고 재생하는 스크립트는 다음과 같습니다.

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

#### 지원하는 Method <a name="지원하는Method"></a>

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) | 볼륨 조절<ul><li>0.0~1 사잇값으로 설정</li></ul> |
| ncplayer.currentTime(value) | 현재 재생 중인 영상의 시간을 변경<ul><li>현재 재생 중인 영상의 재생 시간을 초 단위로 설정하여 변경<br><예시> 3분 20초 → 200</li></ul> |
| ncpplayer.on(type, listner) | 이벤트 수신<ul><li>type string: 수신할 이벤트명, 이벤트 목록([지원하는 이벤트](#지원하는이벤트) 참고)</li><li>listner function: 이벤트가 발생하면 호출시킬 함수 전달</li></ul> |

### 이벤트 <a name="이벤트"></a>

Video Player Enhancement 서비스는 사용자를 위한 여러 가지 이벤트를 제공하며, 메타데이터 클릭 시 발생시킬 이벤트를 설정할 수 있습니다.

:::(Info) (참고)
이벤트 기능은 Standard 요금제에서만 제공됩니다.
:::

이벤트는 다음과 같이 수신할 수 있습니다.
```JavaScript
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);
})
```

#### 지원하는 이벤트 <a name="지원하는이벤트"></a>

Video Player Enhancement 서비스에서 지원하는 이벤트는 다음과 같습니다.
| 이벤트 | 설명 |
| :---- | :---- |
| play | 영상 재생 요청이 성공하였을 때 발생하는 이벤트 |
| pause | 영상이 일시 정지되었을 때 발생하는 이벤트 |
| ready | 플레이어의 재생 준비가 완료되었을 때 발생하는 이벤트 |
| ended | 재생이 끝까지 완료되었을 때 발생하는 이벤트 |
| seeking | seek 동작을 시작할 때 발생하는 이벤트 |
| seeked | seek 동작이 완료되었을 때 발생하는 이벤트 |
| waiting | 버퍼링이 발생하였을 때 발생하는 이벤트 |
| volumechange | 볼륨이 변경될 때 발생하는 이벤트(음소거 포함) |
| controlbarActive | 컨트롤바가 활성화되었을 때 발생하는 이벤트 |
| controlbarDeactive | 컨트롤바가 비활성화되었을 때 발생하는 이벤트 |
| fullscreen | 전체 화면 상태가 변경되었을 때 발생하는 이벤트 |
| fullscreen_on | 전체 화면이 시작되었을 때 발생하는 이벤트 |
| fullscreen_off | 전체 화면이 종료되었을 때 발생하는 이벤트<ul><li>iOS(iPhone) 모바일 웹에서는 사용 불가</li></ul> |
| timeupdate | 현재 재생 시간이 변경될 때 발생하는 이벤트([timeupdate 스크립트](#timeupdate스크립트) 참고) |
| prevTrack | 이전 영상으로 넘어갈 때 발생하는 이벤트([prevTrack 스크립트](#prevTrack스크립트) 참고) |
| nextTrack | 다음 영상으로 넘어갈 때 발생하는 이벤트([nextTrack 스크립트](#nextTrack스크립트) 참고) |

**timeupdate 스크립트** <a name="timeupdate스크립트"></a>
timeupdate 이벤트에 대한 스크립트 및 각 속성에 대한 설명은 다음과 같습니다.

```JavaScript
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 스크립트** <a name="prevTrack스크립트"></a>
prevTrack 이벤트에 대한 스크립트 및 각 속성에 대한 설명은 다음과 같습니다.
```JavaScript
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 스크립트** <a name="nextTrack스크립트"></a>
nextTrack 이벤트에 대한 스크립트 및 각 속성에 대한 설명은 다음과 같습니다.
```JavaScript
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 | 프로필 이미지 |