메서드

ncplayer 인스턴스의 메서드를 사용하여 플레이어를 프로그래밍 방식으로 제어할 수 있습니다.

기본 사용법

new ncplayer()가 반환하는 인스턴스를 변수에 저장한 후, 해당 변수를 통해 메서드를 호출합니다.

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

// 재생
player.play();

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

// 30초 위치로 이동
player.currentTime(30);

재생 제어

메서드	설명
play()	영상을 재생합니다.
pause()	영상을 일시정지합니다.
mute()	음소거합니다.
prev()	이전 플레이리스트 항목으로 이동합니다.
next()	다음 플레이리스트 항목으로 이동합니다.
currentTime(time)	지정한 시간(초)으로 이동합니다.

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

// 재생
player.play();

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

// 음소거
player.mute();

// 30초 위치로 이동
player.currentTime(30);

// 다음 플레이리스트 항목으로 이동
player.next();

// 이전 플레이리스트 항목으로 이동
player.prev();

볼륨 제어

메서드	설명
volume(vol)	볼륨을 설정합니다. (0~1)

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

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

// 음소거
player.mute();

자막 제어

메서드	설명
toggleSubtitle()	자막 표시 여부를 토글합니다.
setSubtitleEnabled(enabled)	자막 표시 여부를 설정합니다.
selectSubTitle(idx)	vtt 배열 인덱스로 자막 트랙을 선택합니다.

// 자막 ON/OFF 토글
player.toggleSubtitle();

// 자막 표시 여부 설정
player.setSubtitleEnabled(true);

// vtt 배열 인덱스로 자막 트랙 선택
player.selectSubTitle(0);

UI 제어

메서드	설명
fullscreen()	전체화면을 토글합니다.
fullscreenOn()	전체화면 모드로 전환합니다.
fullScreenOff()	전체화면 모드를 해제합니다.
pip()	Picture in Picture 모드를 토글합니다.
uiHidden()	플레이어 UI를 숨깁니다.
uiVisible()	플레이어 UI를 표시합니다.
controlBarActive()	컨트롤바를 활성화(표시)합니다.
controlBarDeactive()	컨트롤바를 비활성화(숨김)합니다.
changeUiMode(mode)	UI 모드를 변경합니다. ("pc" \| "mobile" \| "fullscreen" \| null)
layout(nextLayout, merge)	레이아웃을 동적으로 변경합니다. merge가 true(기본값)이면 기존 레이아웃에 병합합니다.

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

// 전체화면 토글
player.fullscreen();

// 전체화면 진입
player.fullscreenOn();

// 전체화면 해제
player.fullScreenOff();

// PIP 모드 토글
player.pip();

// UI 숨김
player.uiHidden();

// UI 표시
player.uiVisible();

// 컨트롤바 활성화
player.controlBarActive();

// 컨트롤바 비활성화
player.controlBarDeactive();

// UI 모드 변경
player.changeUiMode("mobile");

레이아웃 실시간 변경

layout(nextLayout, merge?) — 두 번째 인자 merge의 기본값은 true입니다. Group에 key를 지정하면 같은 key의 Group끼리만 교체되고, 그 외는 base가 유지됩니다. 리마운트 없이 UI가 즉시 전환되며, 자세한 규칙은 레이아웃 시스템 페이지를 참조하세요.

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

// 특정 Group만 교체 — base의 같은 key Group이 교체됨
player.layout({
    bottom: [
        { key: "right", items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"] },
    ],
});

// 새 Group 추가 — 기존 Group 뒤에 append
player.layout({
    bottom: [{ key: "extra", items: ["ShareBtn"] }],
});

// section 전체 교체 — merge: false
player.layout(
    {
        bottom: [
            { items: ["PlayBtn", "TimeBtn"], wrapper: "Group" },
        ],
    },
    false,
);

옵션 / 상태 제어

메서드	설명
changeOptions(nextOptions)	플레이어 옵션을 동적으로 변경합니다.
changePlayMode(mode)	재생 모드를 변경합니다. ("vod" \| "live" \| null)
tokenChange(token)	재생 중 Secure Token을 교체합니다.

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

// 옵션 동적 변경
player.changeOptions({
    muted: true,
    autostart: false,
});

// 재생 모드 변경
player.changePlayMode("live");

// 재생 중 토큰 교체
player.tokenChange("token=st=...~exp=...~acl=...");

플레이리스트 제어

메서드	설명
addNextSource(source)	다음 영상을 플레이리스트에 추가합니다. (단일 또는 배열)
addPrevSource(source)	이전 영상을 플레이리스트에 추가합니다. (단일 또는 배열)

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

// 단일 영상 추가
player.addNextSource({
    file: "https://example.com/new_video.mp4",
    poster: "https://example.com/new_poster.jpg",
    description: { title: "새로운 영상" },
});

// 여러 영상 동시 추가
player.addPrevSource([
    { file: "https://example.com/video_1.mp4" },
    { file: "https://example.com/video_2.mp4" },
]);

이벤트

메서드	설명
on(type, callback)	이벤트 리스너를 등록합니다. 해제 함수를 반환합니다.

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

// 이벤트 리스너 등록
var unsubscribe = player.on("play", function(event) {
    console.log("재생 시작", event);
});

// 모든 이벤트 수신
player.on("*", function(event) {
    console.log(event.type, event);
});

// 이벤트 리스너 해제
unsubscribe();

라이프사이클

메서드	설명
destroy()	플레이어 인스턴스를 제거합니다.

전체 HTML 예제

버튼을 통해 플레이어를 제어하는 완전한 예제입니다.

methods.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 Methods</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 style="margin-top: 16px; text-align: center;">
        <button onclick="player.play()">재생</button>
        <button onclick="player.pause()">일시정지</button>
        <button onclick="player.currentTime(30)">30초로 이동</button>
        <button onclick="player.volume(0.5)">볼륨 50%</button>
        <button onclick="player.mute()">음소거</button>
        <button onclick="player.fullscreen()">전체화면</button>
        <button onclick="player.pip()">PIP</button>
    </div>

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