자막

VPEPlayer Android SDK 는 두 종류의 자막을 지원합니다 — ① 외부 사이드카(vtt / srt URL)와 ② 매니페스트 내장 자막(HLS / DASH). 두 종류 모두 ExoPlayer 텍스트 트랙으로 인식되어 state.availableSubtitles 한 목록에 함께 노출되고 같은 방식으로 선택합니다. 기본은 OFF 이며, on/off·언어 선택은 로컬에 영속되어 다음 재생 시 복원됩니다.

외부 사이드카 자막 (VTT / SRT)

playlist 아이템에 vtt / srt 배열로 트랙을 정의합니다. 각 트랙은 { id, file, label, default } 구조입니다(둘 다 있으면 vtt 우선).

options = mapOf(
    "playlist" to listOf(mapOf(
        "file" to "https://.../master.m3u8",
        "vtt" to listOf(
            mapOf("id" to "ko", "file" to "https://.../ko.vtt", "label" to "한국어", "default" to true)
        ),
        "srt" to listOf(
            mapOf("id" to "en", "file" to "https://.../en.srt", "label" to "English")
        )
    ))
)

default: true 인 트랙이 초기 선택됩니다. 기본은 OFF 이며, 사용자가 자막을 켜면 선택이 로컬에 저장되어 다음 재생 시 복원됩니다.

매니페스트 내장 자막 (HLS / DASH)

HLS / DASH 매니페스트에 포함된 자막은 playlist 옵션이 전혀 필요 없습니다. ExoPlayer 가 텍스트 트랙으로 자동 인식해 state.availableSubtitles 에 합류시키고, 외부 자막과 동일한 자막/설정 버튼에서 선택할 수 있습니다. 기본은 OFF 입니다.

컨트롤러로 제어

외부·내장 구분 없이 한 목록에서 명령형으로 자막을 전환합니다.

controller.setSubtitle("ko")     // 트랙 id 로 선택, null 이면 끄기
controller.toggleSubtitle()       // 켜기/끄기 토글

// 관찰 상태 (state: StateFlow<PlayerState>)
state.availableSubtitles          // 외부 + 내장 합산
state.activeSubtitleId            // String?
state.currentSubtitleText         // String

자막 스타일

captionStyle 옵션은 Android 에서 무시됩니다(의도된 divergence). 자막 스타일(글꼴, 색상, 배경, 크기)은 설정 ▸ 접근성 ▸ 자막(CaptioningManager)을 따르며 실시간 반영됩니다. 글자 크기는 컨테이너 너비 기준으로 계산되어 세로 9:16 비율에서도 넘치지 않습니다.