5. 오프라인 재생

로컬 디스크에 다운로드가 완료된 콘텐츠를 재생하는 방법을 설명합니다. 오프라인 상태에서는 온라인 스트리밍 재생 시 사용하는 원격 URL 대신 미디어 콘텐츠 키(MediaContentKey, mck) 기반 데이터 소스를 사용합니다.

이 문서의 모든 예제 코드는 공식 샘플 앱인 kollus_player_v2_android를 바탕으로 작성되었습니다.

오프라인 재생

스트리밍 재생 시 사용하는 setDataSourceByUrl 대신, 로컬 미디어 키를 지정하는 setDataSourceByKey 메서드를 사용하여 오프라인 재생을 시작합니다.

// VideoView.openVideo()
String extraDrmParam = null;
if (mUri != null) {
    // 스트리밍 재생 (온라인 환경)
    mMediaPlayer.setDataSourceByUrl(mUri.toString(), extraDrmParam);
} else if (mKollusContent != null) {
    // 오프라인 재생 (다운로드된 콘텐츠)
    mMediaPlayer.setDataSourceByKey(
        mKollusContent.getKollusContent().getMediaContentKey(),
        extraDrmParam);
}
mMediaPlayer.prepareAsync();

전체 연동 흐름

1. multiStorage.getDownloadKollusContent(localPath) 또는 getDownloadList() 메서드를 통해 MultiKollusContent 객체를 획득합니다.
2. VideoView 컴포넌트에 setKollusContent(content) 메서드로 획득한 객체를 연결(Attach)합니다.
3. 내부적으로 setDataSourceByKey(mck, extraDrmParam)와 prepareAsync()가 순차적으로 호출됩니다.
4. 재생 준비 과정에서 SDK가 로컬 DRM 검증을 자동으로 수행합니다. 만약 라이선스가 만료되었거나 권한이 없다면 플레이어가 정지되며 onDRMInfo 콜백으로 에러 코드를 통지합니다. (참고: 8. 다운로드 이벤트/콜백)

오프라인 DRM 검증 조건

네트워크가 연결되지 않은 오프라인 환경에서도 DRM 검증을 통과하려면, 다운로드 파일 내부에 주입된 아래 3가지 DRM 보안 제한 조건을 모두 만족해야 합니다.

• 만료 일시 (DRMExpireDate): 디바이스의 현재 시각이 라이선스에 지정된 만료 일시 이전이어야 합니다.
• 재생 횟수 (DRMExpireCount): 현재까지의 실제 재생 횟수가 설정된 최대 제한 횟수(DRMExpireCountMax) 미만이어야 합니다.
• 잔여 시간 (DRMExpirePlayTime): 잔여 재생 허용 시간이 0보다 커야 합니다.

위 3가지 조건 중 단 하나라도 위반될 경우 로컬 재생이 실패하며, 정상 작동을 위해서는 다시 네트워크를 연결하여 라이선스를 갱신해야 합니다. (참고: 6. DRM 라이선스 갱신)

만료 콘텐츠 처리

DRM 검증 단계에서 라이선스 임계치를 초과하여 만료가 감지되었을 때, 플레이어 재생 단계에서 반환되는 주요 에러 코드 규격입니다.

만료 유형	에러 코드 (ErrorCode)
만료 일시 초과	ERROR_EXPIRATION_DATE
재생 횟수 초과	ERROR_EXPIRATION_COUNT
재생 시간 초과	ERROR_EXPIRATION_PLAY_TIME
강제 삭제 (DRM 콜백)	ERROR_FORCE_DELETE (이어서 onDRMInfo 콜백 내 DCB_INFO_DELETE 신호가 함께 트리거됩니다.)

만료 콘텐츠 UX 권장 사항

위 에러 코드들이 감지되면 화면에 "라이선스가 만료되었습니다. 네트워크를 연결하여 라이선스를 갱신한 후 다시 재생해 주세요."라는 안내 팝업을 띄우고, 백그라운드 환경에서 라이선스 동적 갱신 API 프로세스를 시도하도록 로직을 설계하는 것이 좋습니다.

파일 삭제 및 손상된 파일 예외 처리

사용자가 로컬 미디어 파일을 임의로 변형하거나 강제로 지웠을 때의 안전한 방어 코드 구현 패턴입니다.

상황	SDK 판단 및 권장 처리 방식
DB 레코드는 존재하지만 실제 파일이 없는 경우	KollusContent.isLoaded() == false 조건을 판별하여 DB에서 해당 인덱스를 제거합니다. (DownloadService.onCreate 시점의 정리 파이프라인 참고)
파일이 손상된 경우	ERROR_WRITE_FILE 에러가 반환되거나 재생 시 플레이어 에러가 발생합니다. 사용자에게 파일 결함을 안내하고 재다운로드를 권유하는 메시지를 표시합니다.