---
title: "플레이어 UX"
slug: "vpe-umd-player-ux"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-umd-player-ux"
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.

# 플레이어 UX

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

스크립트 코드를 수정하여 UX와 관련된 옵션을 설정하는 방법을 설명합니다.

참고

- 옵션을 설정하는 속성에 대한 설명은 플레이어 설정을 참고해 주십시오.
- 이용 중인 요금제에 따라 설정 가능한 옵션이 다를 수 있습니다.

## startMutedInfoNotVisible (음소거 상태 표시)

음소거 상태를 표시할 수 있습니다.

```
// 동영상(MP4)
const player = new ncplayer("video1", {
  autostart: true,
  muted: true,
  startMutedInfoNotVisible: true,
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## seekingPreview (구간 이동 미리보기)

구간 이동 시 섬네일 이미지를 제공합니다.

참고

- Standard 요금제에서만 사용할 수 있습니다.
- VOD에서만 지원합니다.

```
// 동영상(VOD)
const player = new ncplayer("video1", {
  seekingPreview: true,
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## autoPause (브라우저 비활성화 시 자동 정지)

탭이 비활성화되면 자동으로 재생을 정지합니다.

참고

- Standard 요금제에서만 사용할 수 있습니다.
- 모바일에서는 동작하지 않습니다.
- Webapp/Webview 환경에서는 동작하지 않습니다.

```
// 동영상(VOD)
const player = new ncplayer("video1", {
  autoPause: true,
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## keyboardShortcut (키보드 단축키)

키보드 단축키 사용 여부를 설정합니다.

참고

Standard 요금제에서만 사용할 수 있습니다.

**기본 단축키**

| 키 | 기능 |
| --- | --- |
| Space | 재생 / 일시정지 |
| ← → | 5초 전 / 후로 이동 |
| ↑ ↓ | 볼륨 5% 조절 |
| M | 음소거 |
| F | 전체 화면 |

```
// 동영상(MP4)
const player = new ncplayer("video1", {
  keyboardShortcut: true,
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## touchGestures (터치 제스처)

터치 제스처 사용 여부를 설정합니다.

참고

Standard 요금제에서만 사용할 수 있습니다.

```
// 동영상(MP4)
const player = new ncplayer("video1", {
  touchGestures: true,
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## visibleWatermark/watermarkText (텍스트 워터마크)

워터마크를 활성화하거나 표시 텍스트를 설정합니다.

참고

- Standard 요금제에서만 사용할 수 있습니다.
- 해당 옵션은 콘솔 설정을 통해서만 적용됩니다.
- 코드에서 값을 바꿀 수 없습니다. (스크립트 코드에서만 확인 가능)

```
// 동영상(MP4)
const player = new ncplayer("video1", {
  visibleWatermark: true,
  watermarkText: "Sample watermark",
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## watermarkConfig (텍스트 워터마크 상세 설정)

워터마크 이동, 위치, 투명도 등을 설정합니다.

```
// 동영상(MP4) - 랜덤 이동
const player = new ncplayer("video1", {
  watermarkConfig: {
    randPosition: true,         // 워터마크 랜덤 이동 여부
    randPositionInterVal: 5000, // 랜덤 이동 간격(ms)
    opacity: 0.4,               // 워터마크 투명도
  },
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

```
// 동영상(MP4) - 고정 위치
const player = new ncplayer("video1", {
  watermarkConfig: {
    randPosition: false, // 워터마크 랜덤 이동 여부
    x: 10,               // 좌측 상단 x 좌표(% 단위)
    y: 10,               // 좌측 상단 y 좌표(% 단위)
    opacity: 0.4,        // 워터마크 투명도
  },
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## iosFullscreenNativeMode (iOS 웹 전체 화면 방식)

iOS Safari의 네이티브 전체화면 방식을 사용합니다.

참고

- Basic/Standard 요금제에서 사용할 수 있습니다.
- iOS Safari에서만 동작합니다.
- Player 버전 1.1.5 이상에서 지원합니다.
- 기본값은 `true`입니다.

```
// 동영상(MP4)
const player = new ncplayer("video1", {
  iosFullscreenNativeMode: true,
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
    },
  ],
});
```

## 전체 UMD 예제

```
<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE Player - UX 옵션</title>

  <!-- hls.js / dash.js를 VPE 스크립트보다 먼저 로드 -->
  <script src="https://player.vpe.naverncp.com/lib/js/hls.min.js"></script>
  <script src="https://player.vpe.naverncp.com/lib/js/dash.all.min.js"></script>
  <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
  <div id="video1" style="max-width: 800px; margin: 0 auto;"></div>

  <script>
    const player = new ncplayer("video1", {
      playlist: [
        {
          file: "https://CDN도메인/example_video_01.mp4",
        },
      ],
      autostart: true,
      muted: true,
      startMutedInfoNotVisible: true,
      autoPause: true,
      keyboardShortcut: true,
      touchGestures: true,
      seekingPreview: true,
      iosFullscreenNativeMode: true,
      visibleWatermark: true,
      watermarkText: "Sample watermark",
      watermarkConfig: {
        randPosition: true,
        randPositionInterVal: 5000,
        opacity: 0.4,
      },
    });
  </script>
</body>
</html>
```

## 커스텀 버튼

`options.icon`을 사용하면 플레이어 컨트롤바의 기본 아이콘을 원하는 이미지로 교체할 수 있습니다. 지정하지 않은 아이콘은 기본 Material Design 아이콘이 유지됩니다.

참고

UMD 환경(정적 HTML/PHP/JSP)에서는 SVG 또는 PNG 이미지 경로(string)만 사용 가능합니다. React 컴포넌트(JSX)를 사용하려면 React SDK를 사용해 주십시오.

### 사용 가능한 아이콘 키

`bigPlay` `play` `pause` `prev` `next` `replay` `subtitle` `subtitleOff` `fullscreen` `fullscreenExit` `volumeFull` `volumeMute` `volumeMid` `pip` `setting`

### 값 유형

| 유형 | 예시 | 렌더링 방식 |
| --- | --- | --- |
| string (URL) | `/icons/play.svg` | `&lt;img src="..."&gt;`로 렌더링 |
| 미지정 | - | 기본 Material Design 아이콘 사용 |

### 이미지 경로로 아이콘 교체

SVG 또는 PNG 파일 경로를 문자열로 전달하면 `&lt;img&gt;` 태그로 렌더링됩니다. 필요한 아이콘만 지정하면 나머지는 기본 아이콘이 유지됩니다.

```
const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDN_DOMAIN/example.m3u8",
    },
  ],
  autostart: true,
  muted: true,
  icon: {
    play: "/icons/play.svg",
    pause: "/icons/pause.svg",
    bigPlay: "/icons/big-play.svg",
    fullscreen: "/icons/fullscreen.svg",
    fullscreenExit: "/icons/fullscreen-exit.svg",
  },
});
```

### 외부 SVG URL 활용

Iconify 등의 SVG API를 활용하여 외부 URL로 아이콘을 제공할 수도 있습니다.

```
const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDN_DOMAIN/example.m3u8",
    },
  ],
  autostart: true,
  muted: true,
  icon: {
    play: "https://api.iconify.design/mdi/play-circle-outline.svg?color=%23ffffff&width=24&height=24",
    pause: "https://api.iconify.design/mdi/pause-circle-outline.svg?color=%23ffffff&width=24&height=24",
    bigPlay: "https://api.iconify.design/mdi/play-circle-outline.svg?color=%23ffffff&width=48&height=48",
    fullscreen: "https://api.iconify.design/mdi/arrow-expand-all.svg?color=%23ffffff&width=24&height=24",
    fullscreenExit: "https://api.iconify.design/mdi/arrow-collapse-all.svg?color=%23ffffff&width=24&height=24",
    setting: "https://api.iconify.design/mdi/cog-outline.svg?color=%23ffffff&width=24&height=24",
    volumeFull: "https://api.iconify.design/mdi/volume-high.svg?color=%23ffffff&width=24&height=24",
    volumeMute: "https://api.iconify.design/mdi/volume-off.svg?color=%23ffffff&width=24&height=24",
    volumeMid: "https://api.iconify.design/mdi/volume-medium.svg?color=%23ffffff&width=24&height=24",
    pip: "https://api.iconify.design/mdi/picture-in-picture-bottom-right.svg?color=%23ffffff&width=24&height=24",
  },
});
```

### 전체 HTML 예제

```
<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE Player - 커스텀 아이콘</title>

  <!-- hls.js / dash.js를 VPE 스크립트보다 먼저 로드 -->
  <script src="https://player.vpe.naverncp.com/lib/js/hls.min.js"></script>
  <script src="https://player.vpe.naverncp.com/lib/js/dash.all.min.js"></script>
  <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
  <div id="video" style="max-width: 800px; margin: 0 auto;"></div>

  <script>
    const player = new ncplayer("video", {
      playlist: [
        {
          file: "https://CDN_DOMAIN/example.m3u8",
          poster: "https://CDN_DOMAIN/poster.jpg",
        },
      ],
      autostart: true,
      muted: true,
      icon: {
        play: "/icons/play.svg",
        pause: "/icons/pause.svg",
        bigPlay: "/icons/big-play.svg",
        fullscreen: "/icons/fullscreen.svg",
        fullscreenExit: "/icons/fullscreen-exit.svg",
        setting: "/icons/setting.svg",
        volumeFull: "/icons/volume.svg",
        volumeMute: "/icons/volume-mute.svg",
      },
    });
  </script>
</body>
</html>
```