이벤트

VPE 플레이어에서 발생하는 이벤트를 수신하여 커스텀 로직을 구현할 수 있습니다. UMD 환경에서는 .on() 메서드를 사용합니다.

.on() 메서드로 이벤트 리스닝

player.on(eventName, callback)으로 특정 이벤트를 수신합니다.

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

player.on("play", function () {
    console.log("재생 시작");
});

player.on("pause", function () {
    console.log("일시정지");
});

player.on("ended", function () {
    console.log("재생 완료");
});

player.on("timeupdate", function (e) {
    console.log("현재 시간:", e.state?.currentTime);
});

player.on("error", function (e) {
    console.error("에러 발생:", e);
});

onEvent 콜백 방식

옵션에 onEvent 콜백을 전달하면 모든 이벤트를 한 곳에서 처리할 수 있습니다.

const player = new ncplayer("player", {
    playlist: [
        { file: "https://example.com/video/master.m3u8" },
    ],
    onEvent: function (event) {
        switch (event.type) {
            case "ready":
                console.log("플레이어 준비 완료");
                break;
            case "play":
                console.log("재생 시작");
                break;
            case "pause":
                console.log("일시정지");
                break;
            case "ended":
                console.log("재생 완료");
                break;
            case "timeupdate":
                console.log("현재 시간:", event.state?.currentTime);
                break;
            case "volumechange":
                console.log("볼륨 변경:", event.state?.volume);
                break;
            case "fullscreenchange":
                console.log("전체화면 변경:", event.state?.fullscreen);
                break;
            case "error":
                console.error("에러:", event.data);
                break;
        }
    },
});

재생 이벤트

이벤트설명
ready플레이어가 준비되었을때 발생
play재생이 시작될 때 발생
pause일시정지될 때 발생
ended영상이 끝까지 재생되었을 때 발생
timeupdate재생 시간이 업데이트될 때 주기적으로 발생
seeking탐색(시크)이 시작될 때 발생
seeked탐색(시크)이 완료될 때 발생
ratechange재생 속도가 변경될 때 발생
volumechange볼륨이 변경될 때 발생
loadedmetadata미디어 메타데이터가 로드되었을 때 발생
canplay재생 가능한 상태가 되었을 때 발생

UI 이벤트

이벤트설명
fullscreenchange전체화면 상태가 변경될 때 발생
controlbaractive컨트롤 바가 활성화될 때 발생
controlbarhide컨트롤 바가 숨겨질 때 발생

에러 이벤트

이벤트설명
error재생 에러가 발생했을 때 발생
hlserrorHLS 관련 에러가 발생했을 때 발생
dasherrorDASH 관련 에러가 발생했을 때 발생

광고 이벤트 (IMA)

이벤트설명
adStart광고 재생이 시작될 때 발생
adComplete광고 재생이 완료될 때 발생
adSkip사용자가 광고를 스킵했을 때 발생
adError광고 로드/재생 에러가 발생했을 때 발생

광고 이벤트 (NAM)

이벤트설명
adBreakStart광고 구간 시작 (콘텐츠 일시정지)
adBreakEnd광고 구간 종료 (콘텐츠 재생 재개)
adLoaded광고 로드 완료
adStarted개별 광고 재생 시작
adComplete개별 광고 재생 완료
adSkipped사용자가 광고 스킵
adError광고 로드/재생 에러 (event.data.message에 상세 메시지)

광고 이벤트 예제

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

player.on("adStart", function () {
    console.log("광고 시작");
});

player.on("adComplete", function () {
    console.log("광고 완료");
});

player.on("adSkip", function () {
    console.log("광고 스킵");
});

player.on("adError", function (e) {
    console.log("광고 에러", e.data?.message);
});

// NAM 광고 이벤트
player.on("adBreakStart", function () {
    console.log("NAM 광고 구간 시작");
});

player.on("adBreakEnd", function () {
    console.log("NAM 광고 구간 종료");
});

전체 HTML 예제

events.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 Events</title>
    <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key={YOUR_ACCESS_KEY}"></script>
</head>
<body>
    <div id="player" style="max-width: 800px; margin: 0 auto;"></div>
    <div id="log" style="max-width: 800px; margin: 16px auto; font-family: monospace; font-size: 12px;"></div>

    <script>
        const logEl = document.getElementById("log");

        const player = new ncplayer("player", {
            playlist: [
                {
                    file: "https://example.com/video/master.m3u8",
                    poster: "https://example.com/poster.jpg",
                },
            ],
            autostart: true,
            muted: true,
            aspectRatio: "16/9",
        });

        player.on("ready", function () {
            logEl.innerHTML += "<div>[ready] 플레이어 준비 완료</div>";
        });

        player.on("play", function () {
            logEl.innerHTML += "<div>[play] 재생 시작</div>";
        });

        player.on("pause", function () {
            logEl.innerHTML += "<div>[pause] 일시정지</div>";
        });

        player.on("ended", function () {
            logEl.innerHTML += "<div>[ended] 재생 완료</div>";
        });

        player.on("error", function (e) {
            logEl.innerHTML += "<div>[error] " + JSON.stringify(e.data) + "</div>";
        });
    </script>
</body>
</html>
UMD
메서드OTT 특화 기능