플레이어 UX

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

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 (구간 이동 미리보기)

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

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 (브라우저 비활성화 시 자동 정지)

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

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 (키보드 단축키)

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

기본 단축키

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 (터치 제스처)

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

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 (텍스트 워터마크)

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

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의 네이티브 전체화면 방식을 사용합니다.

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 아이콘이 유지됩니다.

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;        // 설정 아이콘
};

값 유형

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 파일 경로를 문자열로 전달하면 <img> 태그로 렌더링됩니다. 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