옵션

VPE 플레이어의 모든 옵션을 설명합니다. 옵션은 new ncplayer()의 두 번째 인자로 전달합니다.

기본 옵션

이름타입기본값설명
playlist
PlaylistItem[]
[]재생 목록 배열. file(영상 URL)과 poster(썸네일) 등을 포함합니다.
autostart
boolean
false페이지 로드 시 자동 재생 여부
muted
boolean
false초기 음소거 상태. autostart와 함께 사용 시 true 필수.
aspectRatio
string
"16/9"플레이어 비율 ("16/9", "4/3", "1/1", "9/16", "auto")
objectFit
string
"contain"영상 채움 방식 ("contain", "cover", "fill", "scale-down", "stretch")
controls
boolean
true컨트롤 UI 표시 여부
lang
string
"auto"UI 언어 설정 ("auto", "ko", "en")

playlist 아이템 구조

// PlaylistItem 구조
{
    file: "https://example.com/video.m3u8",  // 영상 URL (HLS, DASH, MP4)
    poster: "https://example.com/poster.jpg", // 썸네일 이미지 URL
    description: {
        title: "영상 제목",                    // 문자열 또는 다국어 객체
        // title: { ko: "영상 제목", en: "Video Title" },
        profile_name: "채널명",
        profile_image: "https://example.com/profile.png",
        created_at: "2026.01.01",
    },
    vtt: [                                    // 자막 목록
        {
            id: "ko",
            file: "https://example.com/subtitle.vtt",
            label: "한국어",
            default: true,
        },
    ],
    drm: {                                    // DRM 설정 (ncplayerDRM 사용 시)
        "com.widevine.alpha": { ... },
        "com.apple.fps": { ... },
        "com.microsoft.playready": { ... },
    },
}

재생 옵션

이름타입기본값설명
repeat
boolean
false반복 재생 여부
autoPause
boolean
false브라우저 탭 비활성화 시 자동 정지
lowLatencyMode
boolean
false초저지연 모드 (라이브 스트리밍)
setStartTime
string | null
undefined최초 공개 시간 설정 (ISO 8601 형식)
token
string
undefinedCDN 보안 토큰
playRateSetting
number[]
undefined재생 속도 옵션 리스트

UI 옵션

이름타입기본값설명
ui
string
"all"UI 모드 ("all", "pc", "mobile")
controlBtn
object
undefined개별 컨트롤 버튼 표시/숨김 설정
progressBarColor
string
undefined진행 바 색상 (CSS 색상값)
controlActiveTime
number
3000컨트롤 바 자동 숨김 시간 (ms)
keyboardShortcut
boolean
true키보드 단축키 사용 여부
seekingPreview
boolean
true진행 바 탐색 시 미리보기 표시
touchGestures
boolean
true모바일 터치 제스처 사용 여부
startMutedInfoNotVisible
boolean
false음소거 시작 알림 숨김
descriptionNotVisible
boolean
false메타 정보(제목, 채널명) 숨김
iosFullscreenNativeMode
boolean
trueiOS 전체화면 네이티브 모드 사용

controlBtn 설정 (v1 호환용 옵션)

개별 컨트롤 버튼의 표시/숨김을 설정합니다.

const player = new ncplayer("player", {
    controlBtn: {
        play: true,
        fullscreen: true,
        progressBar: true,
        volume: true,
        times: true,
        pictureInPicture: true,
        setting: true,
        subtitle: true,
    },
    playlist: [
        { file: "https://example.com/video/master.m3u8" },
    ],
});

광고 옵션 (IMA)

이름타입기본값설명
ads
AdOptions
undefinedPre-roll 광고 설정 (VAST/VMAP)
ads.tagUrl
string
requiredVAST/VMAP 광고 태그 URL
ads.enabled
boolean
true광고 활성화 여부
const player = new ncplayer("player", {
    playlist: [
        { file: "https://example.com/video/master.m3u8" },
    ],
    autostart: true,
    muted: true,
    ads: {
        tagUrl: "https://pubads.g.doubleclick.net/gampad/ads?...",
    },
});

아이콘 커스터마이징

SVG URL 문자열을 전달하여 플레이어 아이콘을 교체할 수 있습니다. 미지정 시 기본 Material Design 아이콘이 사용됩니다.

이름타입기본값설명
icon
object
undefined플레이어 아이콘 커스터마이징 (SVG URL 문자열)
icon.bigPlay
string
기본 아이콘큰 재생 버튼 아이콘
icon.play
string
기본 아이콘재생 아이콘
icon.pause
string
기본 아이콘일시정지 아이콘
icon.prev
string
기본 아이콘이전 트랙 아이콘
icon.next
string
기본 아이콘다음 트랙 아이콘
icon.replay
string
기본 아이콘다시 재생 아이콘
icon.subtitle
string
기본 아이콘자막 아이콘
icon.subtitleOff
string
기본 아이콘자막 끄기 아이콘
icon.fullscreen
string
기본 아이콘전체화면 아이콘
icon.fullscreenExit
string
기본 아이콘전체화면 해제 아이콘
icon.volumeFull
string
기본 아이콘볼륨 최대 아이콘
icon.volumeMute
string
기본 아이콘음소거 아이콘
icon.volumeMid
string
기본 아이콘볼륨 중간 아이콘
icon.pip
string
기본 아이콘PIP 아이콘
icon.setting
string
기본 아이콘설정 아이콘
const player = new ncplayer("player", {
    playlist: [
        { file: "https://example.com/video/master.m3u8" },
    ],
    icon: {
        play: "/icons/play.svg",
        pause: "/icons/pause.svg",
        fullscreen: "/icons/fullscreen.svg",
        fullscreenExit: "/icons/fullscreen-exit.svg",
    },
});

워터마크

이름타입기본값설명
visibleWatermark
boolean
false텍스트 워터마크 표시 여부
watermarkText
string
undefined워터마크 텍스트 내용
watermarkConfig.randPosition
boolean
true워터마크 위치 랜덤 이동
watermarkConfig.randPositionInterVal
number
3000랜덤 이동 간격 (ms)
watermarkConfig.x
number
10고정 위치 X 좌표 (%)
watermarkConfig.y
number
10고정 위치 Y 좌표 (%)
watermarkConfig.opacity
number
0.5워터마크 투명도 (0~1)
const player = new ncplayer("player", {
    visibleWatermark: true,
    watermarkText: "SAMPLE@example.com",
    watermarkConfig: {
        randPosition: true,
        randPositionInterVal: 3000,
        opacity: 0.5,
    },
    playlist: [
        { file: "https://example.com/video/master.m3u8" },
    ],
});

OTT 특화 옵션

인트로/오프닝/엔딩 스킵, 연령등급 표시, 콘텐츠 경고 기능입니다.start 값은 반드시 "HH:MM:SS" 형식으로 입력해야 합니다.

이름타입기본값설명
playlist[].intro
{ start: string; duration: number }
undefined인트로 스킵 구간 설정
playlist[].opening
{ start: string; duration: number }
undefined오프닝 스킵 구간 설정
playlist[].ending
{ start: string; duration: number }
undefined엔딩 스킵 구간 설정
playlist[].ageRating
"all" | "12" | "15" | "19"
undefined연령등급 오버레이 표시 (재생 시작 후 3초간 노출)
playlist[].contentWarnings
Array<
"sexuality" |
"violence" |
"language" |
"drugs" |
"horror" |
"imitation" |
"provocative" |
string>
undefined콘텐츠 경고 오버레이 표시 (선정성, 폭력성, 언어 등 민감 요소 안내)
const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            intro: { start: "00:00:00", duration: 5 },
            opening: { start: "00:00:30", duration: 90 },
            ending: { start: "00:45:00", duration: 30 },
            ageRating: "15",
            contentWarnings: ["violence", "language"],
        },
    ],
});

고급 옵션

이름타입기본값설명
override
object
undefined이벤트/동작 오버라이드
layout
object
SDK 기본 레이아웃컨트롤바 레이아웃 설정

override

내부 동작을 오버라이드합니다.

const player = new ncplayer("player", {
    playlist: [
        { file: "https://example.com/video/master.m3u8" },
    ],
    override: {
        error: function(error) { console.log(error); },
        nextSource: function() {},
        prevSource: function() {},
        pip: {
            on: function() {},
            off: function() {},
        },
    },
});

layout

레이아웃을 옵션으로 전달해 컨트롤바를 변경합니다. PC/Mobile/FullScreen 상태의 vod/live 구성을 지원하며 일부만 입력하면 기존 레이아웃과 머지되어 동작합니다.

const player = new ncplayer("player", {
    playlist: [
        { file: "https://example.com/video/master.m3u8" },
    ],
    layout: {
        pc: {
            vod: { bottom: [{ key: "play", items: ["PlayBtn"] }] },
            live: { bottom: [{ key: "play", items: ["PlayBtn"] }] },
        },
    },
});

전체 옵션 예제

주요 옵션을 포함한 종합 예제입니다.

const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            poster: "https://example.com/poster.jpg",
            description: {
                title: "영상 제목",
                profile_name: "채널명",
            },
            vtt: [
                {
                    id: "ko",
                    file: "https://example.com/subtitle_ko.vtt",
                    label: "한국어",
                    default: true,
                },
            ],
        },
    ],
    autostart: true,
    muted: true,
    aspectRatio: "16/9",
    objectFit: "contain",
    controls: true,
    controlBtn: {
        play: true,
        fullscreen: true,
        progressBar: true,
        volume: true,
        times: true,
        pictureInPicture: true,
        setting: true,
        subtitle: true,
    },
    progressBarColor: "#2e6ae0",
    controlActiveTime: 3000,
    keyboardShortcut: true,
    touchGestures: true,
    repeat: false,
    playRateSetting: [0.5, 0.75, 1.0, 1.25, 1.5, 2.0],
    lang: "ko",
});
Tip: Options Test 페이지에서 모든 옵션을 실시간으로 테스트할 수 있습니다.
UMD
커스텀 버튼메서드