에러 대응

재생/라이선스/DRM 오류는 플레이어 위에 i18n 오버레이로 표시됩니다. 컨트롤러 패턴에서는 state.lastError / state.licenseError 를 관찰해 직접 대응할 수 있습니다.

에러 코드

코드	의미
E0001	access_key 무효 / 비결제
E0002	권한 없음
E0003	인증 / 네트워크 실패
E0004	재생 불가 (일반)
E0005	라이선스 무효
E0006	월 무료 사용량 초과
E0007	미지원 포맷 (디코드 실패)
E0009	라이브 오프라인
E0011	DRM 토큰 오류
E0012	DRM 라이선스 통신 실패
E0017	Standard 플랜 필요

재생 실패 매핑 — 네트워크 → E0003, 디코드/포맷 → E0007, DRM → E0012, 그 외 → E0004. iOS 전용 코드(E0010 DASH 미지원, E0013 FairPlay 인증서, E0015/E0016 hls.js/dash.js)는 Android 에서 미해당입니다.

에러 관찰

컨트롤러의 state 에러 상태를 관찰하거나 events: SharedFlow<PlayerEvent> 에서 Error 이벤트를 구독합니다.

// state 관찰
val state by controller.state.collectAsStateWithLifecycle()
state.lastError            // 마지막 재생 오류
state.licenseError         // 라이선스 오류
state.isLicenseValidated   // Bool

// 이벤트 구독
LaunchedEffect(controller) {
    controller.events.collect { event ->
        if (event is PlayerEvent.Error) {
            Log.e("VPE", "재생 오류: ${event}")
        }
    }
}

흔한 실수

공개 API 호출부에 @OptIn(UnstableApi::class) 누락 → 컴파일 경고/에러.
accessKey 누락 / 비결제 → E0001 재생 차단.
state 를 직접 읽기 → collectAsStateWithLifecycle() 로 구독.
토큰/서명 만료(E0011~E0012) → 재생 직전 백엔드에서 최신 옵션 JSON 을 수신해 적용.
Widevine 을 에뮬레이터에서만 검증 → 실기기(L1) 권장.