자막

VPEPlayer iOS SDK 는 두 종류의 자막을 지원합니다 — ① 외부 사이드카(vtt / srt URL)와 ② HLS 매니페스트 내장 자막(EXT-X-MEDIA). 두 종류 모두 controller.availableSubtitles 한 목록에 함께 노출되고 같은 방식으로 선택합니다.

종류	옵션 정의	로딩 방식
외부 사이드카 (VTT/SRT)	`vtt` / `srt` 명시	SDK 가 URL 다운로드·파싱 후 오버레이 렌더
HLS 내장 자막	옵션 불필요	매니페스트에서 자동 인식 (AVMediaSelectionGroup)

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

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

options: [
    "playlist": [
        [
            "file": "https://.../master.m3u8",
            "vtt": [
                ["id": "ko", "file": "https://.../ko.vtt", "label": "한국어", "default": true]
            ],
            "srt": [
                ["id": "en", "file": "https://.../en.srt", "label": "English"]
            ]
        ]
    ]
]

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

HTTP 자막 URL 주의 — http 사이드카 URL 은 ATS(App Transport Security) 예외 설정(Info.plist)이 필요할 수 있습니다. 가급적 https 를 사용하세요.

HLS 내장 자막 (EXT-X-MEDIA)

HLS 매니페스트에 EXT-X-MEDIA TYPE=SUBTITLES 로 포함된 자막은 playlist 옵션이 전혀 필요 없습니다. 재생 준비 후 SDK 가 AVMediaSelectionGroup 을 자동으로 로드해 availableSubtitles 에 합류시키고, 외부 자막과 동일한 자막/설정 버튼에서 선택할 수 있습니다(강제 자막은 제외). 기본은 OFF 입니다.

코드로 내장 자막 목록을 받으려면 events 에서 .embeddedSubtitlesAvailable([SubtitleTrack]) 를 구독합니다. 각 트랙은 kind == .embedded 이며 embeddedOptionID 를 보유합니다.

import Combine

player.events
    .sink { event in
        if case let .embeddedSubtitlesAvailable(tracks) = event {
            // tracks: [SubtitleTrack]  (kind == .embedded, embeddedOptionID 보유)
            print("내장 자막", tracks.map(\.label))
        }
    }
    .store(in: &cancellables)

주의 — 내장 자막은 시뮬레이터에서 렌더가 제한될 수 있으므로 실기기에서 확인하는 것을 권장합니다. 또한 HLS 내장 자막은 옵션에 따로 추가하지 마세요(자동 인식).

컨트롤러로 제어

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

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

// 관찰 상태
player.availableSubtitles     // [SubtitleTrack]  (외부 + 내장 합산)
player.activeSubtitleID       // String?
player.currentSubtitleText    // String

자막 스타일

captionStyle 옵션은 iOS 에서 무시됩니다. 모든 자막(외부·내장) 의 스타일(글꼴 크기, 색상 등)은 iOS 설정 ▸ 손쉬운 사용 ▸ 자막 및 캡션 ▸ 스타일 의 접근성 자막 설정을 따르며, 코드로 강제할 수 없습니다. 가독성 배경 박스는 항상 표시됩니다.