---
title: "플레이어 UX"
slug: "vpe-react-player-ux"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-react-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 (음소거 상태 표시)

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        autostart: true,
        muted: true,
        startMutedInfoNotVisible: true,
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

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

참고

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(VOD)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        seekingPreview: true,
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

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

참고

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(VOD)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        autoPause: true,
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## keyboardShortcut (키보드 단축키)

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

참고

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

**기본 단축키**

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        keyboardShortcut: true,
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## touchGestures (터치 제스처)

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

참고

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        touchGestures: true,
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

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

참고

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        visibleWatermark: true,
        watermarkText: "Sample watermark",
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

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

**랜덤 이동**

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4) - 랜덤 이동
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        watermarkConfig: {
          randPosition: true,          // 워터마크 랜덤 이동 여부
          randPositionInterVal: 5000,  // 랜덤 이동 간격(ms)
          opacity: 0.4,                // 워터마크 투명도
        },
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

**고정 위치**

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4) - 고정 위치
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        watermarkConfig: {
          randPosition: false, // 워터마크 랜덤 이동 여부
          x: 10,               // 좌측 상단 x 좌표(% 단위)
          y: 10,               // 좌측 상단 y 좌표(% 단위)
          opacity: 0.4,        // 워터마크 투명도
        },
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

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

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

참고

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        iosFullscreenNativeMode: true,
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## 커스텀 버튼

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

참고

UMD 환경(정적 HTML/PHP/JSP)에서는 React 컴포넌트를 사용할 수 없으며, SVG 또는 PNG 이미지 경로(string)만 사용 가능합니다.

### IconOverrides 타입

각 키에 `string` 또는 `ReactNode`를 전달할 수 있습니다.

```
type IconOverrides = {
  bigPlay?: string | ReactNode;        // 큰 재생 버튼 아이콘
  play?: string | ReactNode;           // 재생 아이콘
  pause?: string | ReactNode;          // 일시정지 아이콘
  prev?: string | ReactNode;           // 이전 트랙 아이콘
  next?: string | ReactNode;           // 다음 트랙 아이콘
  replay?: string | ReactNode;         // 다시 재생 아이콘
  subtitle?: string | ReactNode;       // 자막 켜기 아이콘
  subtitleOff?: string | ReactNode;    // 자막 끄기 아이콘
  fullscreen?: string | ReactNode;     // 전체화면 아이콘
  fullscreenExit?: string | ReactNode; // 전체화면 해제 아이콘
  volumeFull?: string | ReactNode;     // 볼륨 최대 아이콘
  volumeMute?: string | ReactNode;     // 음소거 아이콘
  volumeMid?: string | ReactNode;      // 볼륨 중간 아이콘
  pip?: string | ReactNode;            // PIP 아이콘
  setting?: string | ReactNode;        // 설정 아이콘
};
```

### 값 유형

| 유형 | 예시 | 렌더링 방식 |
| --- | --- | --- |
| string | `"/icons/play.svg"` | `&lt;img src={url}&gt;`로 렌더링 |
| ReactNode | `&lt;FaPlay /&gt;` | React 컴포넌트/JSX를 그대로 렌더링 |
| 미지정 | - | 기본 Material Design 아이콘 사용 |

### React 컴포넌트로 아이콘 교체

커스텀 SVG 컴포넌트나 `react-icons` 등의 아이콘 라이브러리를 활용하여 JSX로 아이콘을 교체할 수 있습니다.

```
"use client";
import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 커스텀 SVG 컴포넌트 정의
function PlayIcon() {
  return (
    <svg viewBox="0 0 24 24" width="1.5em" height="1.5em" fill="#ffffff">
      <polygon points="6,3 20,12 6,21" />
    </svg>
  );
}

function PauseIcon() {
  return (
    <svg viewBox="0 0 24 24" width="1.5em" height="1.5em" fill="#ffffff">
      <rect x="5" y="3" width="4" height="18" />
      <rect x="15" y="3" width="4" height="18" />
    </svg>
  );
}

function FullscreenIcon() {
  return (
    <svg viewBox="0 0 24 24" width="1.5em" height="1.5em" fill="none" stroke="#ffffff" strokeWidth="2">
      <polyline points="15,3 21,3 21,9" />
      <polyline points="9,21 3,21 3,15" />
      <polyline points="21,15 21,21 15,21" />
      <polyline points="3,9 3,3 9,3" />
    </svg>
  );
}

export default function CustomIconPlayer() {
  return (
    <VpePlayer
      hls={Hls}
      accessKey="YOUR_ACCESS_KEY"
      options={{
        playlist: [
          { file: "https://example.com/video/master.m3u8" },
        ],
        autostart: true,
        muted: true,
        aspectRatio: "16/9",
        icon: {
          play: <PlayIcon />,
          pause: <PauseIcon />,
          bigPlay: <PlayIcon />,
          fullscreen: <FullscreenIcon />,
          fullscreenExit: <FullscreenExitIcon />,
          setting: <SettingIcon />,
          volumeFull: <VolumeIcon />,
          volumeMute: <VolumeMuteIcon />,
          volumeMid: <VolumeIcon />,
        },
      }}
    />
  );
}
```

`app/player/page.tsx`

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

SVG 또는 PNG 파일 경로를 문자열로 전달하면 `&lt;img&gt;` 태그로 렌더링됩니다. React와 UMD 환경 모두에서 사용 가능합니다.

```
"use client";
import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export default function SvgUrlIconPlayer() {
  return (
    <VpePlayer
      hls={Hls}
      accessKey="YOUR_ACCESS_KEY"
      options={{
        playlist: [
          { file: "https://example.com/video/master.m3u8" },
        ],
        autostart: true,
        muted: true,
        aspectRatio: "16/9",
        icon: {
          play: "/icons/play.svg",
          pause: "/icons/pause.svg",
          bigPlay: "/icons/big-play.svg",
          fullscreen: "/icons/fullscreen.svg",
          fullscreenExit: "/icons/fullscreen-exit.svg",
        },
      }}
    />
  );
}
```

### 혼합 사용

이미지 경로와 React 컴포넌트를 함께 사용할 수 있습니다. 필요한 아이콘만 지정하면 나머지는 기본 아이콘이 유지됩니다.

```
"use client";
import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";
import { FaPlay, FaPause } from "react-icons/fa";

export default function MixedIconPlayer() {
  return (
    <VpePlayer
      hls={Hls}
      accessKey="YOUR_ACCESS_KEY"
      options={{
        playlist: [
          { file: "https://example.com/video/master.m3u8" },
        ],
        autostart: true,
        muted: true,
        aspectRatio: "16/9",
        icon: {
          // React 컴포넌트
          play: <FaPlay style={{ fontSize: "1.2rem", color: "#fff" }} />,
          pause: <FaPause style={{ fontSize: "1.2rem", color: "#fff" }} />,
          // 이미지 경로
          bigPlay: "/icons/big-play.svg",
          fullscreen: "/icons/fullscreen.svg",
          fullscreenExit: "/icons/fullscreen-exit.svg",
        },
      }}
    />
  );
}
```

`app/player/page.tsx`