옵션

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: "영상 제목",                    // 영상 제목
        profile_name: "채널명",                // 채널/프로필명
        profile_image: "https://example.com/profile.png", // 프로필 이미지 URL
        created_at: "2026.01.01",             // 생성 날짜
    },
    vtt: [                                    // 자막 목록
        {
            file: "https://example.com/subtitle.vtt",
            label: "한국어",
            language: "ko",
            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	undefined	CDN 보안 토큰
playbackRate	number	1.0	재생 속도
playRateSetting	number[]	undefined	재생 속도 옵션 리스트

UI 옵션

이름	타입	기본값	설명
ui	string	"auto"	UI 모드 ("auto", "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	true	iOS 전체화면 네이티브 모드 사용

controlBtn 설정

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

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" },
    ],
});

워터마크

이름	타입	기본값	설명
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" },
    ],
});

전체 옵션 예제

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

const player = new ncplayer("player", {
    playlist: [
        {
            file: "https://example.com/video/master.m3u8",
            poster: "https://example.com/poster.jpg",
            description: {
                title: "영상 제목",
                profile_name: "채널명",
            },
            vtt: [
                {
                    file: "https://example.com/subtitle_ko.vtt",
                    label: "한국어",
                    language: "ko",
                    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 페이지에서 모든 옵션을 실시간으로 테스트할 수 있습니다.