플레이어 UI

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

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);

그룹 옵션

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