플레이어 UI

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

플레이어 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 (컨트롤바 버튼 UI)

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 설정

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

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

레이아웃 시스템

지원 플랫폼: Android iOS

VPE React Native SDK는 웹 SDK에서 포팅된 layout-driven ControlBar 시스템을 제공합니다. JSON 선언으로 컨트롤 버튼의 배치, 그룹화, 화면 환경별(PC/모바일/전체화면)과 콘텐츠 유형별(VOD/Live) 구성을 정의할 수 있습니다.

개요

layout prop에 레이아웃 객체를 전달하여 ControlBar의 모든 영역을 사용자 정의할 수 있습니다. layout prop이 없을 경우 기본 반응형 레이아웃이 사용됩니다.

• 5개 섹션: top, upper, center, lower, bottom
• 환경별 분리: pc / mobile / fullscreen
• 콘텐츠 유형 분리: vod / live
• 모바일 판정 breakpoint: 기본 768
• 사용자 layout × 디폴트 layout 자동 병합 (섹션 단위 replace)

구성 구조

최상위 키는 pc, mobile, fullscreen으로 나뉘며, 각 환경 내부에 vod와 live 레이아웃을 정의합니다.

{
  "pc": {
    "vod": {},
    "live": {}
  },
  "mobile": {
    "vod": {},
    "live": {}
  },
  "fullscreen": {
    "vod": {},
    "live": {}
  },
  "breakpoint": 768
}

layout.json

각 variant 내부는 5개 섹션의 순서와 그룹/아이템 정렬로 구성됩니다.

{
  "order": ["top", "upper", "center", "lower", "bottom"],
  "top": [
    { "wrapper": "Group", "items": ["BackBtn"] },
    { "wrapper": "Blank" },
    { "wrapper": "Group", "items": ["ShareBtn", "SettingBtn"] }
  ],
  "center": [
    { "wrapper": "Blank", "items": ["BigPlayBtn"] }
  ],
  "bottom": {
    "seekbar": ["SeekBar"],
    "left": [
      { "wrapper": "Group", "items": ["PlayBtn", "VolumeBtn"] },
      { "wrapper": "Group", "items": ["TimeBtn"] }
    ],
    "right": [
      { "wrapper": "Group", "items": ["SubtitleBtn", "FullscreenBtn"] }
    ]
  }
}

variant.json

사용 가능한 컨트롤 아이템

items 배열에 다음 이름들을 사용할 수 있습니다.

wrapper 종류

• Group — 기본 알약 모양 그룹 (반투명 배경, borderRadius 999). 단일 자식이면 원형(aspectRatio: 1) 처리, TimeBtn은 단독일 때 우회.
• Blank — 자식이 없으면 spacer, 자식이 있으면 align 적용 row.

기본 사용 예제

import { VpePlayer } from 'vpe-react-native';

const myLayout = {
  pc: {
    vod: {
      order: ['top', 'center', 'bottom'],
      top: [
        { wrapper: 'Group', items: ['BackBtn'] },
        { wrapper: 'Blank' },
        { wrapper: 'Group', items: ['ShareBtn', 'SettingBtn'] },
      ],
      center: [{ wrapper: 'Blank', items: ['BigPlayBtn'] }],
      bottom: {
        seekbar: ['SeekBar'],
        left: [
          { wrapper: 'Group', items: ['PlayBtn', 'VolumeBtn'] },
          { wrapper: 'Group', items: ['TimeBtn'] },
        ],
        right: [
          { wrapper: 'Group', items: ['SubtitleBtn', 'FullscreenBtn'] },
        ],
      },
    },
    live: { /* ... */ },
  },
  mobile: {
    vod: { /* ... */ },
    live: { /* ... */ },
  },
  fullscreen: {
    vod: { /* ... */ },
    live: { /* ... */ },
  },
  breakpoint: 768,
};

export default function MyPlayer() {
  return (
    <VpePlayer
      accessKey={'YOUR_ACCESS_KEY'}
      layout={myLayout}
      options={{
        playlist: [{ file: 'https://CDN도메인/master.m3u8' }],
        aspectRatio: '16/9',
      }}
    />
  );
}

레이아웃 병합 동작

사용자가 전달한 layout은 디폴트 layout과 자동 병합됩니다. 일부 환경(예: pc만) 또는 일부 섹션만 정의해도 나머지는 디폴트가 사용됩니다. 단, 섹션 단위 replace 방식이므로 한 섹션을 정의하면 디폴트의 같은 섹션은 완전히 대체됩니다.

개발(__DEV__) 모드에서는 잘못된 아이템 이름, 누락된 필수 섹션 등에 대해 콘솔 경고가 출력됩니다.

터치 제스처

ControlBar는 단일/더블탭 제스처를 처리합니다. 화면을 좌/중/우 1/3 영역으로 나누어 더블탭 시 10초씩 누적 seek가 발생하며, 단일탭은 컨트롤바 토글입니다.

• 단일탭 토글은 300ms 지연 (그동안 두 번째 탭이 들어오면 더블탭으로 처리되어 컨트롤 깜빡임 방지)
• 더블탭 좌/우 → 10초 누적 seek (500ms 후 실제 seek 실행)
• options.touchGestures: false 시 더블탭 비활성화 (단일탭 토글만 동작)

관련 가이드

• 커스텀 아이콘 (IconOverrides)
• 플레이어 UI 옵션
• 플레이어 UX 옵션