플레이어 UI 옵션

이 페이지에서는 플레이어 UI를 구성하고 설정하는 옵션을 안내합니다.

aspectRatio

aspectRatio 속성으로 플레이어의 가로·세로 비율을 지정할 수 있습니다. 플레이어가 고정형 사이즈(width, height)를 가지고 있지 않은 경우에만 적용할 수 있습니다. container의 크기가 변하더라도 설정한 비율이 유지됩니다.

<VpePlayer
    ...
    options={{
        playlist: [
            {
                file: 'https://CDN도메인/example_video_01.mp4'
            },
        ],
        aspectRatio: '16/9', // 화면 비율 설정
    }}
    ...
/>

objectFit

objectFit 속성으로 화면의 채움 방식을 설정할 수 있습니다. 재생 소스의 비율을 유지하고 화면을 꽉 채우도록 설정하는 예제는 다음과 같습니다.

<VpePlayer
    ...
    options={{
        playlist: [
            {
                file: 'https://CDN도메인/example_video_01.mp4'
            },
        ],
        aspectRatio: '16/9',
        objectFit: 'cover', // 화면 채움 설정(비율 맞춤+꽉 채움)
    }}
    ...
/>

controls

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

<VpePlayer
    ...
    options={{
        playlist: [
            {
                file: 'https://CDN도메인/example_video_01.mp4'
            },
        ],
        controls: false // 컨트롤바 표시 안 함(true: 컨트롤바 표시)
    }}
    ...
/>

controlBtn

controlBtn 속성으로 컨트롤바의 버튼 UI 사용 여부를 설정할 수 있습니다.

<VpePlayer
    ...
    options={{
        playlist: [
            {
                file: 'https://CDN도메인/example_video_01.mp4'
            },
        ],
        controls: true,
        controlBtn: {
            play: true,         // 재생
            progressBar: true,  // 재생바 사용 여부
            fullscreen: true,   // 전체 화면 전환
            volume: true,       // 볼륨 컨트롤
            times: true,        // 재생 시간
            setting: true,      // 설정
        },
    }}
    ...
/>

progressBarColor

progressBarColor 속성으로 컨트롤바 영상 탐색 슬라이더의 색상을 설정할 수 있습니다.

<VpePlayer
    ...
    options={{
        playlist: [
            {
                file: 'https://CDN도메인/example_video_01.mp4'
            },
        ],
        progressBarColor: "#ff0000", // 색상 코드(빨간색)
    }}
    ...
/>

controlActiveTime

controlActiveTime 속성으로 컨트롤바가 표시되는 시간을 설정할 수 있습니다.

<VpePlayer
    ...
    options={{
        playlist: [
            {
                file: 'https://CDN도메인/example_video_01.mp4'
            },
        ],
        controlActiveTime: 3000, // 컨트롤바 표시 시간 설정(3000=3초)
    }}
    ...
/>

컨트롤바 UI 동적 수정

영상의 길이에 따라 버튼 UI를 동적으로 수정할 수 있습니다. 예를 들어 영상 길이가 10초 미만일 경우에는 전체 화면, PIP, 설정 버튼을 제공하지 않도록 설정할 수 있습니다.

const playerRef = useRef(null);

return (
    <VpePlayer
        ...
        ref={playerRef}
        events={{
            timeupdate: (res) => {
                if (res.duration < 10) {
                    playerRef.current.controlBarBtnStateUpdate({
                        fullscreen: false,
                        pictureInPicture: false,
                        setting: false,
                    })
                }
            },
        }}
        options={{
            playlist: [
                {
                    file: 'https://CDN도메인/example_video_01.mp4'
                },
            ],
            controlBtn: {
                play: true,
                fullscreen: true,
                volume: true,
                times: true,
                setting: true,
                subtitle: false,
            },
        }}
        ...
    />
)

자막 UI 설정

자막의 크기 및 배경, 스타일을 설정할 수 있습니다.

const playerRef = useRef(null);

return (
    <VpePlayer
        ...
        ref={playerRef}
        options={{
            playlist: [
                {
                    file: 'https://CDN도메인/example_video_01.mp4'
                },
            ],
            captionStyle: {
                fontSize: 12,
                color: '#FFFFFF',
                backgroundColor: 'rgba(0, 0, 0, 0.7)',
                edgeStyle: 'dropshadow', // dropshadow, raised, depressed, uniform
            },
        }}
        ...
    />
)