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

Prev Next

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 <img src="...">로 렌더링
미지정 - 기본 Material Design 아이콘 사용

이미지 경로로 아이콘 교체

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

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>
사업자등록번호: 129-86-31394 통신판매업신고번호:제2009-경기성남-0510호
대표이사: 김유원 주소: 경기도 성남시 분당구 불정로 6 네이버 그린팩토리 17~26층, 13561 고객지원 대표전화: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.