본문으로 건너뛰기

개발 가이드

이 문서는 Android SDK를 활용한 앱 개발 지침을 제공합니다.
본 SDK는 콘텐츠 재생 및 관리를 위한 핵심 API를 제공하며, 플레이어 UI는 개발자가 직접 구현해야 합니다.

Android SDK API 레퍼런스​

SDK에 포함된 전체 API 명세는 아래 문서를 참고하세요.

지원 아키텍처 및 라이브러리 구성​

SDK는 다양한 기기 환경과의 호환성을 위해 다음 CPU 아키텍처용 Native 라이브러리와 Java 라이브러리를 포함합니다.

  • 지원 환경: arm64-v8a, armeabi, armeabi-v7a, x86, x86_64
  • 라이브러리
    • kollusplayer_sdk-debug.jar: 개발용(로그 포함)
    • kollusplayer_sdk-release.jar: 마켓 배포용(로그 없음)

KollusStorage​

KollusStorage는 SDK의 핵심 요소로, 다음과 같은 주요 라이프사이클 관리 및 데이터 처리를 담당합니다.

  • SDK 인증
  • 콘텐츠 정보 조회
  • 콘텐츠 다운로드 및 삭제
  • 스트리밍 캐시 데이터 관리

인스턴스 초기화 및 해제 절차​

kollusStorage 사용 흐름

1. 인스턴스 획득 (getInstance)​

KollusStorage는 하나의 스토리지에 대해 단일 인스턴스(Singleton)만 생성되어야 합니다.
공통 BaseActivity에서 초기화하여 하위 모든 Activity가 동일한 인스턴스를 상속받도록 설계하는 것을 권장합니다.

2. SDK 인증 (initialize)​

발급받은 키를 사용하여 SDK의 유효성을 검증합니다.

public int initialize(String key, String expireDate, String packageName);
  • 반환 코드
    • ErrorCodes.ERROR_OK: 정상
    • ErrorCodes.ERROR_INVALID_KEY: 잘못된 키
    • ErrorCodes.ERROR_EXPIRED_KEY: 만료

3. 경로 및 기기 설정 (setDevice/setDeviceAsync)​

스토리지 경로와 기기 식별자를 설정합니다.

비동기(Async) 방식인 setDeviceAsync보다 안정성을 위해 동기(Sync) 방식인 setDevice 사용을 강력히 권장합니다.(평균 소요 시간: 약 100ms)

// 동기 방식 (권장)
public int setDevice(String storagePath, String deviceSha1, String deviceGUIDMd5, boolean bTablet); 
// 비동기 방식
public void setDeviceASync(String storagePath, String deviceSha1, String deviceGUIDMd5, boolean bTablet, OnKollusStorageDeviceListener listener);

4. 자원 해제 및 재설정 (finish)​

사용 중인 리소스를 정리하거나 스토리지 경로를 변경해야 할 때 호출합니다.

finish() 호출 후 다시 스토리지를 사용하려면 반드시 1~3번의 초기화 과정을 다시 수행해야 합니다.

콘텐츠 다운로드​

다운로드 목록 조회​

다운로드된 콘텐츠 목록를 가져옵니다.

ArrayList<KollusContent> contentsList = kollusStorage.getDownloadContentList();

다운로드​

다운로드 프로세스를 제어하기 위해서는 OnKollusStorageListener를 등록하여 이벤트(진행률, 완료, 오류 등)를 수신해야 합니다.
더 이상 이벤트 수신이 필요하지 않은 경우 unregisterOnKollusStorageListener를 통해 해제할 수 있습니다.

이벤트 리스너 인터페이스​

public interface OnKollusStorageListener {
    void onComplete(int index);               // 완료
    void onProgress(int index, int percent);  // 진행률
    void onError(int index, int errorCode);   // 오류
}
콘텐츠 다운로드 흐름

1. 다운로드 준비 (load)​

다운로드 대상 콘텐츠의 정보를 로드하고 준비합니다.

  • 주의 사항: load는 동시 호출을 지원하지 않습니다. 한 콘텐츠의 로드가 완전히 끝난 후 다음 콘텐츠를 호출해야 합니다.
  • 반환값: 음수 값 반환 시 오류 상태이므로 ErrorCodes를 참조하여 예외 처리를 수행하세요.
public int load(String path, String extraDrmParam, KollusContent content);
파라미터타입설명
pathString다운로드할 콘텐츠 경로
extraDrmParamStringDRM 다운로드 콜백에 전달할 추가 파라미터
기본값은 null입니다.

2. 다운로드 시작 (download)​

준비된 콘텐츠의 실제 데이터 전송을 시작합니다.

  • 저장 공간 검증: 사전에 content.getFileSize()를 호출하여 콘텐츠 파일의 크기를 확인하세요. 기기의 남은 저장 공간이 파일 크기 + 150MB보다 커야 안정적인 다운로드와 재생이 가능합니다.
  • 반환값: 음수 값 반환 시 오류 상태이므로 ErrorCodes를 참조하여 예외 처리를 수행하세요.
public int download(String mediaContentKey);
파라미터타입설명
mediaContentKeyString다운로드할 콘텐츠의 미디어 콘텐츠 키

다운로드 취소​

현재 진행 중인 다운로드 작업을 중단하고 세션을 종료합니다.

다운로드 취소 흐름 
public int unload(String mediaContentKey);
파라미터타입설명
mediaContentKeyString다운로드를 취소할 콘텐츠의 미디어 콘텐츠 키

다운로드 콘텐츠 삭제​

다운로드가 완료된 로컬 콘텐츠 파일을 스토리지에서 삭제합니다.

다운로드 콘텐츠 삭제 흐름 
public int remove(String mediaContentKey);
파라미터타입설명
mediaContentKeyString삭제할 콘텐츠의 미디어 콘텐츠 키

콘텐츠 재생​

콘텐츠 재생 흐름

1. MediaPlayer 인스턴스 생성​

MediaPlayer 객체(플레이어)를 생성합니다.

public MediaPlayer(Context context, KollusStorage storage, int port);

2. 이벤트 리스너 등록​

플레이어의 상태 변화 및 예외 상황을 감지하기 위해 아래 리스너들을 반드시 구현해야 합니다.

필수 등록 리스너​

  • OnPreparedListener: 재생 준비 완료
  • OnCompletionListener: 재생 완료
  • OnErrorListener: 재생 중 오류 발생
  • OnVideoSizeChangedListener: 콘텐츠 해상도 변경
이벤트 리스너 목록
재생 준비 완료​

setOnPreparedListener(OnPreparedListener listener);

public interface OnPreparedListener{
    void onPrepared(MediaPlayer mp);
}
재생 완료​

setOnCompletionListener(OnCompletionListener listener);

public interface OnCompletionListener{
    void onCompletion(MediaPlayer mp);
}
재생 중 오류 발생​

setOnErrorListener(OnErrorListener listener);

public interface OnErrorListener{
    boolean onError(MediaPlayer mp, int what, int extra);
}
정보 알림​

setOnInfoListener(OnInfoListener listener);

public interface OnInfoListener{
    boolean onInfo(MediaPlayer mp, int what, int extra); 
    void onBufferingStart(MediaPlayer mp);
    void onBufferingEnd(MediaPlayer mp); 
    void onFrameDrop(MediaPlayer mp);
    void onDownloadRate(MediaPlayer mp, int downloadRate);
    void onDetectBandwidthList(MediaPlayer mp, List list); 
    void onChangedBandwidth(MediaPlayer mp, BandwidthItem item);
}
DRM(Widevine 등) 오류​

void setOnCencDrmListener(OnCencDrmListener listener);

public interface OnCencDrmListener{
    void onProxyError(int nErrorCode, String strErrorMessage);
}
seek 완료​

setOnSeekCompleteListener(OnSeekCompleteListener listener);

public interface OnSeekCompleteListener{
    public void onSeekComplete(MediaPlayer mp);
}
콘텐츠 해상도 변경​

setOnVideoSizeChangedListener(OnVideoSizeChangedListener listener);

public interface OnVideoSizeChangedListener{
    public void onVideoSizeChanged(MediaPlayer mp, int width, int height);
}
ℹ️참고

이 리스너는 최초 해상도 정보를 받을 때에도 호출됩니다.

자막 표시​

setOnTimedTextListener(OnTimedTextListener listener);

public interface OnTimedTextListener{
    public void onTimedText(MediaPlayer mp, String text);
    public void onTimedImage(MediaPlayer mp, byte[] image, int width, int height);
}
외부 디스플레이 연결 감지​

setOnExternalDisplayDetectListener(OnExternalDisplayDetectListener listener);

public interface OnExternalDisplayDetectListener{
    public void onExternalDisplayDetect(int type, boolean plugged);
}
LMS 전송 확인​
  • registerKollusPlayerLMSListener(KollusPlayerLMSListener listener);
  • unregisterKollusPlayerLMSListener(KollusPlayerLMSListener listener);
public interface KollusPlayerLMSListener {
    /**
     * 진도율 데이터를 서버에 전송했을 때 관련 데이터를 전달합니다.
     * @param request 서버로 전송된 메시지
     * @param response 서버로부터 응답받은 메시지
     */
    void onLMS(String request, String response);
}
북마크​

setKollusPlayerBookmarkListener(KollusPlayerBookmarkListener listener);

public interface KollusPlayerBookmarkListener {
    /**
     * 공식 북마크 또는 내 북마크가 있을 경우 호출됩니다.
     * @param bookmark   북마크 목록
     * @param bWritable  false: 내 북마크 추가/삭제 불가
     */
    void onBookmark(List bookmark, boolean bWritable);

    /*
     * 다음 상황에서 호출됩니다.
     * - 네트워크 전송 오류
     * - JSON 데이터 파싱 오류
     * - JSON 내 error 필드 값이 0이 아닌 다른 상태 코드를 반환한 경우
     */
    void onGetBookmarkError(int nErrorCode);

    /**
     * 북마크가 추가되거나 업데이트되었을 때 호출됩니다.
     * @param position   업데이트된 북마크 위치(단위: 초)
     * @param bUpdated   업데이트 성공 여부
     */
    void onBookmarkUpdated(int position, boolean bUpdated);

    /**
     * 북마크가 삭제되었을 때 호출됩니다.
     * @param position   삭제된 북마크 위치(단위: 초)
     * @param bDeleted   삭제 성공 여부
     */
    void onBookmarkDeleted(int position, boolean bDeleted);
}
에뮬레이터 재생 시도 감지​

setEmulatorCheckerListener(EmulatorCheckerListener listener);

public interface EmulatorCheckerListener {
    public void onRunningEmulator();
}

3. 비디오 출력 영역 설정​

영상 데이터가 렌더링될 출력 창을 설정합니다.

public void setSurface(Surface surface);
public void setDisplay(SurfaceHolder sh);

4. 콘텐츠 경로 설정​

재생 방식(스트리밍/다운로드)에 따라 적절한 메서드를 선택합니다.

스트리밍 콘텐츠​

public void setDataSourceByUrl(String path, String extraDrmParam);
파라미터타입설명
pathString콘텐츠 경로
extraDrmParamString플레이 콜백 추가 파라미터(값이 없을 경우 null 입력)

다운로드 콘텐츠​

public void setDataSourceByKey(String mediaContentKey, String extraDrmParam);
파라미터타입설명
mediaContentKeyString다운로드된 콘텐츠의 미디어 콘텐츠 키
extraDrmParamStringDRM 다운로드 콜백 추가 파라미터(값이 없을 경우 null 입력)
contentKollusContent다운로드할 콘텐츠 정보

5~6. 준비 및 데이터 획득​

리소스 로딩을 시작합니다. 재생 준비가 완료되면 onPrepared()가 호출됩니다.

public void prepareAsync();

onPrepared 수신 후 처리 권장 사항​

  • 콘텐츠 정보 조회: getKollusContent(KollusContent content)를 호출하여 콘텐츠 정보를 가져올 수 있습니다.
  • 스크린샷 경로: 파일명.{width}x{height}x{count}.확장자
    • count의 초기 3장은 의미 없는 값입니다.
String screenShotPath = content.getScreenShotPath();

이어보기 구현​

start() 호출 전 재생 시점 이동(Seek)을 통해 이어보기를 구현합니다.

  • seekTo: 가장 가까운 키 프레임(I-Frame)으로 이동합니다.
mMediaPlayer.seekTo(int msec);
  • seekToExact: 지정한 시점으로 이동합니다.
mMediaPlayer.seekToExact(int msec);

7. 재생 시작​

재생을 시작합니다.

public void start();

8~9. 재생 종료​

재생이 완료되었거나 종료하고 싶을 때 아래 메서드를 순서대로 호출합니다.

public void stop();
public void release();

북마크 관리​

북마크 관리는 콘텐츠 재생 중에 수행할 수 있습니다.

KollusPlayerBookmarkListener를 등록하면 북마크 목록을 수신할 수 있습니다.
북마크 추가 및 삭제 작업은 네트워크 상태에 따라 지연될 수 있으므로, 반드시 리스너의 콜백 수신 후 UI를 업데이트해야 합니다.

북마크 목록 조회​

onBookmark가 호출되면, 현재 북마크 목록을 수신합니다.
이때 내 북마크(시청자 개인용 북마크)의 추가/삭제 가능 여부를 확인할 수 있습니다.

북마크 추가 및 수정​

특정 시점에 새로운 북마크를 추가하거나 기존 내용을 수정합니다.

  • 동작 원리: 해당 위치(position)에 데이터가 없으면 신규 생성, 이미 존재하면 기존 내용을 덮어씁니다.
  • 완료 확인: 작업이 서버에 반영되면 onBookmarkUpdated가 호출됩니다.
public void updateKollusBookmark(int position, String label);
파라미터타입설명
positionint추가 또는 수정할 북마크 위치(단위: 밀리초)
labelString북마크 제목
미지정 시 기본값은 빈 문자열("")입니다.

북마크 삭제​

저장된 북마크를 제거합니다.

  • 완료 확인: 삭제 처리가 완료되면 onBookmarkDeleted가 호출됩니다.
public void deleteKollusBookmark(int position);
파라미터타입설명
positionint삭제할 북마크 위치(단위: 밀리초)