옵션

VPE 플레이어의 모든 옵션을 설명합니다. 옵션은 options prop으로 전달합니다.

기본 옵션

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

playlist 아이템 구조

interface PlaylistItem {
    file: string;           // 영상 URL (HLS, DASH, MP4)
    poster?: string;        // 썸네일 이미지 URL
    description?: {
        title?: string;         // 영상 제목
        profile_name?: string;  // 채널/프로필명
        profile_image?: string; // 프로필 이미지 URL
        created_at?: string;    // 생성 날짜
    };
}

재생 옵션

이름타입기본값설명
repeatbooleanfalse반복 재생 여부
autoPausebooleanfalse브라우저 탭 비활성화 시 자동 정지
lowLatencyModebooleanfalse초저지연 모드 (라이브 스트리밍)
setStartTimestring | nullundefined최초 공개 시간 설정 (ISO 8601 형식)
tokenstringundefinedCDN 보안 토큰

UI 옵션

이름타입기본값설명
uistring"auto"UI 모드 ("auto", "pc", "mobile")
controlBtnobjectundefined개별 컨트롤 버튼 표시/숨김 설정
progressBarColorstringundefined진행 바 색상 (CSS 색상값)
controlActiveTimenumber3000컨트롤 바 자동 숨김 시간 (ms)
playRateSettingnumber[]undefined재생 속도 옵션 리스트
keyboardShortcutbooleantrue키보드 단축키 사용 여부
seekingPreviewbooleantrue진행 바 탐색 시 미리보기 표시
touchGesturesbooleantrue모바일 터치 제스처 사용 여부
startMutedInfoNotVisiblebooleanfalse음소거 시작 알림 숨김
descriptionNotVisiblebooleanfalse메타 정보(제목, 채널명) 숨김
iosFullscreenNativeModebooleantrueiOS 전체화면 네이티브 모드 사용

controlBtn 설정

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

{
    "controlBtn": {
        "play": true,
        "fullscreen": true,
        "progressBar": true,
        "volume": true,
        "times": true,
        "pictureInPicture": true,
        "setting": true,
        "subtitle": true
    }
}

광고 옵션 (IMA)

이름타입기본값설명
adsAdOptionsundefinedPre-roll 광고 설정 (VAST/VMAP)
ads.tagUrlstringrequiredVAST/VMAP 광고 태그 URL
ads.enabledbooleantrue광고 활성화 여부

광고 옵션 (NAM)

이름타입기본값설명
namAdsNamAdOptionsundefinedNAM Instream 광고 설정
namAds.adScheduleIdstringrequiredNAM 광고 스케줄 ID
namAds.adSchedulePolicyobject{ pre: true }광고 스케줄 정책 (pre/mid/post)
namAds.adPlayerTypestringundefined광고 플레이어 타입 ("HTML5_PC" | "HTML5_MO" | "SMART_TV")
namAds.contentDurationnumberauto콘텐츠 길이(초). 미지정 시 자동 감지
namAds.customParamRecord<string, string | string[] | number>undefined광고 타겟팅 파라미터
namAds.sdkUrlstringundefinedgfp-instream.js SDK URL 오버라이드
namAds.phasestring"production"NAM SDK 환경 ("test" | "production")

워터마크

이름타입기본값설명
visibleWatermarkbooleanfalse텍스트 워터마크 표시 여부
watermarkTextstringundefined워터마크 텍스트 내용
watermarkConfig.randPositionbooleantrue워터마크 위치 랜덤 이동
watermarkConfig.randPositionInterValnumber3000랜덤 이동 간격 (ms)
watermarkConfig.xnumber10고정 위치 X 좌표 (%)
watermarkConfig.ynumber10고정 위치 Y 좌표 (%)
watermarkConfig.opacitynumber0.5워터마크 투명도 (0~1)
{
    "visibleWatermark": true,
    "watermarkText": "Sample Watermark",
    "watermarkConfig": {
        "randPosition": true,
        "randPositionInterVal": 3000,
        "opacity": 0.5
    }
}

고급 옵션

이름타입기본값설명
devTestAppIdstringundefined개발 테스트용 AppId
overrideobjectundefined이벤트/동작 오버라이드
layoutobjectSDK 기본 레이아웃컨트롤바 레이아웃 설정

옵션별 예제

모든 예제는 공통으로 accessKey와 playlist를 포함합니다.

playlist

재생에 필요한 기본 항목입니다. file은 영상 URL, poster는 썸네일을 의미합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [
            {
                file: "https://CDN_DOMAIN/example_video_01.mp4",
                poster: "https://CDN_DOMAIN/example_video_01.png",
                description: {
                    title: "영상 제목",
                    profile_name: "채널명",
                    profile_image: "https://CDN_DOMAIN/profile.png",
                    created_at: "2026.02.03",
                },
            },
        ],
    }}
/>

autostart

자동 재생 여부를 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        autostart: true,
    }}
/>

muted

시작 시 음소거를 적용합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        muted: true,
    }}
/>

ads

Pre-roll 광고를 설정합니다. VAST/VMAP 태그 URL을 전달하면 콘텐츠 재생 전에 광고가 자동으로 재생됩니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.m3u8" }],
        autostart: true,
        muted: true,
        ads: {
            tagUrl: "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_preroll_skippable&sz=640x480&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=",
        },
    }}
/>

namAds

NAM Instream Pre-roll 광고를 설정합니다. NAM 광고 스케줄 ID를 전달하면 콘텐츠 재생 전에 광고가 자동으로 재생됩니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.m3u8" }],
        autostart: true,
        muted: true,
        namAds: {
            adScheduleId: "YOUR_AD_SCHEDULE_ID",
        },
    }}
/>

aspectRatio

플레이어 비율을 지정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        aspectRatio: "16/9",
    }}
/>

objectFit

비디오 표시 방식을 설정합니다. cover | contain | fill | stretch

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        objectFit: "cover",
    }}
/>

controls

기본 컨트롤 표시 여부를 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        controls: true,
    }}
/>

keyboardShortcut

키보드 단축키를 활성화합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        keyboardShortcut: true,
    }}
/>

seekingPreview

시킹 프리뷰 표시 여부를 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        seekingPreview: true,
    }}
/>

touchGestures

터치 제스처 사용 여부를 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        touchGestures: true,
    }}
/>

startMutedInfoNotVisible

시작 음소거 안내 문구 표시 여부를 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        startMutedInfoNotVisible: true,
    }}
/>

lang

UI 언어를 설정합니다. 설정하지 않거나 auto로 설정되면 브라우저/기기 설정을 따라갑니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        lang: "ko",
    }}
/>

ui

UI 모드/스킨 키를 설정합니다. 설정하지 않거나 auto로 설정되면 브라우저 가로폭이나 기기를 따라갑니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        ui: "auto",
    }}
/>

controlBtn

컨트롤 버튼 표시 여부를 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        controlBtn: {
            play: true,
            fullscreen: true,
            progressBar: true,
            volume: true,
            times: true,
            pictureInPicture: true,
            setting: true,
            subtitle: true,
        },
    }}
/>

progressBarColor

진행바 색상을 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        progressBarColor: "#00E0FF",
    }}
/>

controlActiveTime

컨트롤 자동 숨김 시간을 설정합니다(ms).

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        controlActiveTime: 3000,
    }}
/>

playRateSetting

재생 속도 옵션을 설정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        playRateSetting: [0.5, 1, 1.5, 2],
    }}
/>

autoPause

탭 전환/창 최소화 시 자동 정지를 설정합니다. 인앱 웹뷰 상황에서는 정상 동작하지 않습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        autoPause: true,
    }}
/>

repeat

반복 재생을 설정합니다. 플레이리스트가 여러 개면 마지막 재생 후 처음 영상으로 돌아갑니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        repeat: true,
    }}
/>

setStartTime

시작 시간을 지정합니다(문자열). 기본적으로 UTC 시간을 지원하며 로컬 포맷도 사용할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        setStartTime: "2026-02-03T09:00:00Z",
    }}
/>

lowLatencyMode

저지연 모드를 활성화합니다. LL-HLS를 제대로 재생하려면 해당 옵션이 필수입니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        lowLatencyMode: true,
    }}
/>

descriptionNotVisible

메타 설명 표시 여부를 설정합니다. 기본값은 false이며 true로 설정 시 화면에 표시되지 않습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        descriptionNotVisible: true,
    }}
/>

iosFullscreenNativeMode

iOS 네이티브 전체화면 모드를 사용합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        iosFullscreenNativeMode: true,
    }}
/>

visibleWatermark

워터마크 표시 여부를 설정합니다. 이 옵션은 콘솔에서만 적용 가능하며 코드에서 수정할 수 없습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        visibleWatermark: true,
    }}
/>

watermarkText

워터마크 텍스트를 지정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        watermarkText: "SAMPLE@example.com",
    }}
/>

watermarkConfig

워터마크 상세 설정을 지정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        watermarkConfig: {
            randPosition: true,
            randPositionInterVal: 5000,
            x: 10,
            y: 10,
            opacity: 0.4,
        },
    }}
/>

devTestAppId

개발 테스트용 AppId를 지정합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        devTestAppId: "YOUR_DEV_APP_ID",
    }}
/>

token

스트림 URL에 자동으로 붙일 토큰을 설정합니다. HLS/DASH의 하위 TS 파일까지 함께 적용됩니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        token: "token=...",
    }}
/>

override

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

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        override: {
            error: (error) => console.log(error),
            nextSource: () => {},
            prevSource: () => {},
            pip: {
                on: () => {},
                off: () => {},
            },
        },
    }}
/>

layout

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

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: "https://CDN_DOMAIN/example_video_01.mp4" }],
        layout: {
            pc: {
                vod: { bottom: [{ key: "play", items: ["PlayBtn"] }] },
                live: { bottom: [{ key: "play", items: ["PlayBtn"] }] },
            },
        },
    }}
/>
Tip: Options Test 페이지에서 모든 옵션을 실시간으로 테스트할 수 있습니다.
커스텀 버튼메서드