재생 설정

플레이어의 재생 관련 옵션을 설정하는 방법을 안내합니다.

Android TVtvOSFire TV

기본 설정 - playlist

재생할 영상을 설정합니다. 재생 소스는 MP4, HLS, DASH 형식을 지원합니다.

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

여러 영상 재생

playlist 속성으로 여러 개의 재생 소스를 전달하여 연속 재생할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [
            {
                file: 'https://example.com/video1.m3u8',
                poster: 'https://example.com/poster1.jpg',
                description: { title: '첫 번째 영상' },
            },
            {
                file: 'https://example.com/video2.m3u8',
                description: { title: '두 번째 영상' },
            },
        ],
        autostart: true,
    }}
    onBack={() => navigation.goBack()}
/>

동적 플레이리스트 구성

영상 재생 완료 후 다음에 재생할 영상을 동적으로 추가할 수 있습니다.

const playerRef = useRef<PlayerHandle>(null);

// 단일 영상 추가
playerRef.current?.addNextSource({
    file: 'https://example.com/new_video.m3u8',
    description: { title: '새로운 영상' },
});

// 여러 영상 동시 추가
playerRef.current?.addPrevSource([
    { file: 'https://example.com/video_1.mp4' },
    { file: 'https://example.com/video_2.mp4' },
]);

autostart

autostart 속성으로 영상을 자동 재생할 수 있습니다. 기본값은 true입니다.

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

muted

muted 속성으로 처음 재생 시 음소거 상태로 시작할 수 있습니다.

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

playRateSetting

playRateSetting 속성으로 사용자가 재생 속도를 선택할 수 있는 UI를 제공합니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playRateSetting: [0.5, 0.75, 1, 1.5, 2],
        playlist: [{
            file: 'https://example.com/video.m3u8',
        }],
    }}
    onBack={() => navigation.goBack()}
/>

repeat

repeat 속성으로 영상을 반복 재생할 수 있습니다.

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

자막 설정

playlist.vtt 속성으로 자막을 제공할 수 있습니다. VTT 및 SMI 형식을 지원하며, SMI 파일의 EUC-KR 인코딩은 자동 디코딩됩니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{
            file: 'https://example.com/video.m3u8',
            vtt: [
                { label: '한국어', src: 'https://example.com/ko.vtt', default: true },
                { label: 'English', src: 'https://example.com/en.vtt' },
                { label: '日本語', src: 'https://example.com/ja.smi' },
            ],
        }],
    }}
    onBack={() => navigation.goBack()}
/>

lowLatencyMode (라이브)

lowLatencyMode 속성으로 LL-HLS 저지연 모드를 활성화할 수 있습니다. 라이브 스트림은 자동으로 감지됩니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        lowLatencyMode: true,
        playlist: [{
            file: 'https://example.com/live.m3u8',
            description: { title: '라이브 방송' },
        }],
    }}
    onBack={() => navigation.goBack()}
/>

라이브 감지 시 자동 동작: TimeBtn에 빨간 dot + "LIVE" 표시, 재생속도 메뉴 숨김, SeekBar 시킹 비활성화

lowLatencyMode 플랫폼별 동작

플랫폼	동작
Android TV	ExoPlayer targetOffsetMs: 2000 (라이브 엣지 2초 목표)
tvOS	AVPlayer preferredForwardBufferDuration: 2

5초 이상 뒤처지면 라이브 엣지로 자동 복귀합니다.

메타데이터 설정

playlist.description 속성으로 영상의 메타 정보를 표시할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{
            file: 'https://example.com/video.m3u8',
            description: {
                title: '네이버클라우드 소개',
                created_at: '2024.01.01',
                profile_name: '네이버클라우드',
                profile_image: 'https://example.com/profile.png',
            },
        }],
    }}
    onBack={() => navigation.goBack()}
/>

OTT 설정

OTT 서비스에 필요한 인트로/오프닝/엔딩 스킵, 연령등급 표시, 콘텐츠 경고 기능을 playlist 아이템 단위로 설정합니다.

자세한 사용법은 OTT 특화 기능 페이지를 참조하세요.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        autostart: true,
        playlist: [
            {
                file: "https://CDN_DOMAIN/episode_01.m3u8",
                poster: "https://CDN_DOMAIN/episode_01.jpg",
                description: {
                    title: "드라마 시즌1 EP.01",
                    profile_name: "OTT 채널",
                },
                ageRating: "15",
                contentWarnings: ["violence", "language"],
                intro: {
                    start: "00:00:00",
                    duration: 5,
                },
                opening: {
                    start: "00:00:05",
                    duration: 90,
                },
                ending: {
                    start: "00:45:00",
                    duration: 60,
                },
            },
        ],
    }}
    onBack={() => navigation.goBack()}
/>

워터마크

visibleWatermark 속성으로 워터마크를 표시할 수 있습니다.

<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{
            file: 'https://example.com/video.m3u8',
        }],
        visibleWatermark: true,
        watermarkText: 'SAMPLE@example.com',
        watermarkConfig: {
            randPosition: true,
            randPositionInterVal: 5000,
            opacity: 0.4,
        },
    }}
    onBack={() => navigation.goBack()}
/>