이벤트

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컨트롤 바가 숨겨질 때 발생
subtitleChange자막이 켜지거나 변경될 때 발생 — data: { isSubtitle: boolean, subTitleIdx: number }

에러 이벤트

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

광고 이벤트 (IMA)

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

DRM 라이선스 이벤트

DRM 보호 콘텐츠 재생 시 라이선스 요청/응답을 추적할 수 있습니다. HLS(Widevine/PlayReady/FairPlay via hls.js), DASH(Widevine/PlayReady via dash.js), FairPlay native(Safari WebKitMediaKeys) 모두 동일한 통일 스키마로 발화됩니다.

이벤트설명
licenseRequestDRM 라이선스 요청 시작 시 발생
licenseSuccessDRM 라이선스 응답이 성공적으로 수신되었을 때 발생
licenseErrorDRM 라이선스 요청이 실패했을 때 발생
const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.mpd",
            drm: { /* DRM 설정 */ },
        },
    ],
    onEvent: function (event) {
        switch (event.type) {
            case "licenseRequest":
                // { keySystem, url, requestSize, sessionId?, contentId? }
                console.log("DRM 요청:", event.data);
                break;
            case "licenseSuccess":
                // { keySystem, url, status?, durationMs, responseSize?, messageType?, contentId? }
                console.log("DRM 성공:", event.data);
                break;
            case "licenseError":
                // { keySystem, url?, status?, durationMs?, reason: "http"|"network"|"abort"|"key", error?, code? }
                console.warn("DRM 실패:", event.data);
                break;
        }
    },
});

// 또는 .on() 메서드 사용
player.on("licenseRequest", function (e) {
    console.log("DRM 요청:", e.data);
});

player.on("licenseSuccess", function (e) {
    console.log("DRM 성공:", e.data);
});

player.on("licenseError", function (e) {
    console.warn("DRM 실패:", e.data);
});

페이로드 필드

필드설명
keySystem"com.widevine.alpha" | "com.microsoft.playready" | "com.apple.fps" | "com.apple.fps.1_0" | "unknown"
url라이선스 서버 URL
requestSize요청 페이로드(SPC 등) 바이트 수
responseSize응답 라이선스 바이트 수 (HLS/FairPlay에서 측정, DASH는 registerLicenseResponseFilter로 측정)
durationMs요청 시작 ~ 응답까지 경과 시간
statusHTTP status code
reason실패 원인 (http | network | abort | key)
messageTypeDASH 전용: "license-request" 등 EME 메시지 타입
contentIdFairPlay 전용: SPC를 처리한 contentId

광고 이벤트 예제

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);
});

전체 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>
    <!-- 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="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 특화 기능