옵션

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

기본 옵션

이름	타입	기본값	설명
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")
lang	string	"auto"	UI 언어 설정 ("auto", "ko", "en")
controls	boolean	true	컨트롤 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;    // 생성 날짜
    };

    // 연령등급
    ageRating?: "all" | "12" | "15" | "19" | string;

    // OTT 스킵 구간
    intro?: { start: string; duration: number };
    opening?: { start: string; duration: number };
    ending?: { start: string; duration: number };

    // 콘텐츠 경고
    contentWarnings?: Array<
        "sexuality" | "violence" | "language" | "drugs" |
        "horror" | "imitation" | "provocative" | string
    >;
}

재생 옵션

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

UI 옵션

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

controlBtn 설정

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

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

광고 옵션 (IMA)

이름	타입	기본값	설명
ads	AdOptions	undefined	Pre-roll 광고 설정 (VAST/VMAP)
ads.tagUrl	string	required	VAST/VMAP 광고 태그 URL
ads.enabled	boolean	true	광고 활성화 여부

광고 옵션 (NAM)

이름	타입	기본값	설명
namAds	NamAdOptions	undefined	NAM Instream 광고 설정
namAds.adScheduleId	string	required	NAM 광고 스케줄 ID
namAds.adSchedulePolicy	object	{ pre: true }	광고 스케줄 정책 (pre/mid/post)
namAds.adPlayerType	string	undefined	광고 플레이어 타입 ("HTML5_PC" \| "HTML5_MO" \| "SMART_TV")
namAds.contentDuration	number	auto	콘텐츠 길이(초). 미지정 시 자동 감지
namAds.customParam	Record	undefined	광고 타겟팅 파라미터
namAds.sdkUrl	string	undefined	gfp-instream.js SDK URL 오버라이드
namAds.phase	string	"production"	NAM SDK 환경 ("test" \| "production")

워터마크

이름	타입	기본값	설명
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)

{
    "visibleWatermark": true,
    "watermarkText": "Sample Watermark",
    "watermarkConfig": {
        "randPosition": true,
        "randPositionInterVal": 3000,
        "opacity": 0.5
    }
}

OTT 특화 옵션

인트로/오프닝/엔딩 스킵, 연령등급 표시, 콘텐츠 경고 기능입니다. 자세한 사용법은 OTT 특화 기능 페이지를 참조하세요.

이름	타입	기본값	설명
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	콘텐츠 경고 오버레이 표시 (선정성, 폭력성, 언어 등 민감 요소 안내)

고급 옵션

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

옵션별 예제

모든 예제는 공통으로 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,
    }}
/>

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,
        },
    }}
/>

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 페이지에서 모든 옵션을 실시간으로 테스트할 수 있습니다.