플레이어 UI

Classic/VPC 환경에서 이용 가능합니다.

플레이어 UI를 구성하고 설정하는 옵션과 선언적 레이아웃 시스템을 안내합니다.

controls

controls 속성으로 컨트롤바 표시 여부를 설정할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: false, // 컨트롤바 숨김
    }}
    onBack={() => navigation.goBack()}
/>

controlBtn

controlBtn 속성으로 개별 버튼의 표시 여부를 설정할 수 있습니다. TV SDK에서는 fullscreen, pictureInPicture 속성이 없습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: true,
        controlBtn: {
            play: true,
            progressBar: true,
            volume: true,
            times: true,
            setting: true,
            subtitle: true,
        },
    }}
    onBack={() => navigation.goBack()}
/>

progressBarColor

progressBarColor 속성으로 진행바의 색상을 설정할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        progressBarColor: '#00E0FF',
    }}
    onBack={() => navigation.goBack()}
/>

controlActiveTime

• controlActiveTime 속성으로 컨트롤바가 자동으로 숨겨지는 시간을 설정합니다. 기본값은 3000ms(3초)입니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controlActiveTime: 5000, // 5초 후 자동 숨김
    }}
    onBack={() => navigation.goBack()}
/>

lang

lang 속성으로 UI 언어를 설정할 수 있습니다.

리모컨 이벤트

TV SDK는 리모컨 D-pad 입력을 자동으로 처리합니다.

레이아웃 시스템

TV SDK의 선언적 레이아웃 시스템을 사용하여 컨트롤바 UI를 커스터마이징할 수 있습니다.

레이아웃 구조

5개 섹션(top, upper, center, lower, bottom)과 seekbar로 구성된 선언적 레이아웃입니다.

사용 가능한 아이템

컨트롤바에 배치할 수 있는 아이템은 다음과 같습니다.

TV에서 제거된 아이템은 FullscreenBtn, PipBtn, ShareBtn이며, 레이아웃에 포함해도 무시됩니다.

커스텀 레이아웃 예제

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        top: [
            { items: ['BackBtn'], wrapper: 'Group' },
            { items: ['MetaDesc'] },
            { wrapper: 'Blank', items: [] },
        ],
        center: [
            { items: ['BigPlayBtn'], align: 'center' },
        ],
        lower: [
            { wrapper: 'Blank', items: ['SeekBar'], align: 'center' },
        ],
        bottom: [
            { items: ['PlayBtn'], wrapper: 'Group' },
            { items: ['NextPrevBtn'], wrapper: 'Group' },
            { items: ['MuteBtn'], wrapper: 'Group' },
            { items: ['TimeBtn'], wrapper: 'Group' },
            { wrapper: 'Blank', items: [] },
            { items: ['SubtitleBtn', 'SettingBtn'], wrapper: 'Group' },
        ],
    }}
    onBack={() => navigation.goBack()}
/>

VOD/Live 변형

VOD와 Live에서 서로 다른 레이아웃을 사용할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        vod: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['SettingBtn'], wrapper: 'Group' },
            ],
        },
        live: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['MuteBtn'], wrapper: 'Group' },
            ],
        },
    }}
    onBack={() => navigation.goBack()}
/>

런타임 레이아웃 변경

ref 메서드를 통해 런타임에 레이아웃을 변경할 수 있습니다.

const playerRef = useRef<PlayerHandle>(null);

// 부분 업데이트 (merge=true, 기본값)
playerRef.current?.layout(
    { bottom: [{ items: ['PlayBtn'], wrapper: 'Group' }] },
    true
);

// 전체 교체 (merge=false)
playerRef.current?.layout(newLayout, false);

그룹 옵션

각 그룹에 설정할 수 있는 속성은 다음과 같습니다.