메서드

PlayerHandle ref를 사용하여 플레이어를 프로그래밍 방식으로 제어할 수 있습니다.

PlayerHandle ref 사용법

"use client";

import Hls from "hls.js";
import { VpePlayer, type PlayerHandle } from "@sgrsoft/vpe-react-sdk";
import { useRef } from "react";

export default function PlayerPage() {
    const playerRef = useRef<PlayerHandle>(null);

    const handlePlay = () => {
        playerRef.current?.play();
    };

    const handleSeek = () => {
        playerRef.current?.seek(30); // 30초 위치로 이동
    };

    return (
        <div>
            <VpePlayer
                ref={playerRef}
                hls={Hls}
                accessKey="YOUR_ACCESS_KEY"
                options={{
                    playlist: [{
                        file: "https://example.com/video/master.m3u8",
                    }],
                }}
            />
            <div>
                <button onClick={handlePlay}>Play</button>
                <button onClick={handleSeek}>Seek to 30s</button>
            </div>
        </div>
    );
}

재생 제어

메서드	설명
play()	영상을 재생합니다.
pause()	영상을 일시정지합니다.
seek(time: number)	지정한 시간(초)으로 이동합니다.
stop()	영상을 정지하고 처음으로 돌아갑니다.
getDuration()	영상의 전체 길이(초)를 반환합니다.
getCurrentTime()	현재 재생 위치(초)를 반환합니다.

볼륨 제어

메서드	설명
setVolume(vol: number)	볼륨을 설정합니다. (0~1)
getVolume()	현재 볼륨 값을 반환합니다.
setMuted(muted: boolean)	음소거 상태를 설정합니다.
getMuted()	음소거 상태를 반환합니다.

UI 제어

메서드	설명
setLayout(layout: object)	레이아웃을 동적으로 변경합니다. 리마운트 없이 UI가 전환됩니다.
controlBarActive()	컨트롤 바를 활성화(표시)합니다.
enterFullscreen()	전체 화면 모드로 전환합니다.
exitFullscreen()	전체 화면 모드를 해제합니다.

실시간 레이아웃 전환 예제

// 레이아웃을 런타임에 변경
const switchLayout = () => {
    playerRef.current?.layout({
        pc: {
            vod: {
                order: ["center", "bottom"],
                center: [{ items: ["BigPlayBtn"], align: "center" }],
                bottom: [
                    { items: ["ProgressBar"] },
                    {
                        items: ["PlayBtn", "TimeDisplay"],
                        align: "left",
                    },
                    {
                        items: ["FullscreenBtn"],
                        align: "right",
                    },
                ],
            },
        },
    });
};

UMD 메서드 예제

<script>
    const player = new ncplayer("player", {
        playlist: [{ file: "https://example.com/video/master.m3u8" }],
    });

    // 재생
    player.play();

    // 일시정지
    player.pause();

    // 30초로 이동
    player.seek(30);

    // 볼륨 설정 (0~1)
    player.setVolume(0.8);

    // 전체화면 진입
    player.enterFullscreen();
</script>

UMD 레이아웃 변경 + 이벤트 예제

<script>
    const player = new ncplayer("player", {
        playlist: [{ file: "https://example.com/video/master.m3u8" }],
    });

    // 레이아웃 실시간 변경
    player.layout({
        bottom: [{ items: ["PlayBtn", "TimeBtn", "FullscreenBtn"], wrapper: "Group" }],
    });

    // 이벤트 리스닝
    player.on("play", function() {
        console.log("재생 시작");
    });
</script>