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

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

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