最終更新: 2021.03.11_2024.08.28_Review

SDK Libraryの説明

このSDKにはarm64-v8a, armeabi, armeabi-v7a, x86, x86_64系列のNative LibraryとJava Libraryが含まれています。

• kollusplayer_sdk-debug.jar (ログ取得可能な開発用SDK)
• kollusplayer_sdk-release.jar (ログ取得不可のマーケット用SDK)

KollusStorage

いかの役割を遂行します。

• SDK認証の処理
• コンテンツ情報の取得
• コンテンツのダウンロード
• コンテンツの削除
• ストリーミングキャッシュデータの管理

Kollus Storage使用方法

1. getInstance

   • KollusStorageはストレージ別に一つしか生成することができないため、singleton apiを提供します。Kollus PlayerアプリはActivityを相続したBaseActivityから初期化関連作業を遂行し、必要なActivityはBaseActivityを相続して自動で初期化できるように実装してください。

2. Initialize

   • public int initialize(String key, String expireDate, String packageName); SDKの認証を行い、以下の値をリターンします。
     • ErrorCodes.ERROR_OK
     • ErrorCodes.ERROR_INVALID_KEY
     • ErrorCodes.ERROR_EXPIRED_KEY

3. setDevice / setDeviceAsync

   • Sync, ASyncタイプでストレージパスとPlayer IDを設定する関数です。初期化する場合、setDevice関数で初期化しても100msくらいしか掛からないためsetDeviceAsync関数よりsetDevice関数で初期化することを推奨します。
     • 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

   • KollusStorageのリソースを回収する関数: リソースをそれ以上使用しなくなった場合、もしくはストレージパスを変更する場合に使用します。パスを変更委する場合にはfinishしてから1~3の内容を実行してください。

ダウンロードリストの取得

ArrayList contentsList = kollusStorage.getDownloadContentList();

ダウンロードを開始

まずダウンロードリクエストを識別するため、registerOnKollusStorageListenerを登録してください。それ以上使用しなくなった場合にはunregisterOnKollusStorageListenerで解除します。

public interface OnKollusStorageListener {
		void onComplete(int index);
		void onProgress(int index, int percent);
		void onError(int index, int errorCode);
}

1. load

   • public int load(String path, String extraDrmParam, KollusContent content);
     
     • リターンがマイナスの場合エラー発生: ErrorCodesの内容を確認してください。
     • path: ダウンロードするコンテンツのパス

     • extraDrmParam: DRM Callbackに追加するパラメータで、追加しない場合にはnullを入力してください。

       load関数は同時実行ができないため、複数のファイルをダウンロードする場合にはコンテンツのloadが完了してから次のコンテンツをloadしなければなりません。

2. download

   • public int download(String mediaContentKey);
     

     • リターンがマイナスの場合エラー発生: ErrorCodesの内容を確認してください。

       ダウンロードをリクエストする前にcontent.getFileSizeを呼出してディスクの残量がファイルサイズ+150MB以上であるかを確認しなければなりません。

       ディスクの残量が150MB以下の場合にはディスクへの書き込みができないため、既にダウンロードしていたコンテンツを正常に使用できなくなる可能性があります。(OSによって変わりますが、安定性を保つには150MBが必要)

ダウンロードをキャンセル

public int unload(String mediaContentKey);

ダウンロードをキャンセルする場合には該当コンテンツのメディアコンテンツキーでunloadをリクエストします。

ダウンロードしたコンテンツの削除

public int remove(String mediaContentKey);

ダウンロードしたコンテンツを削除する場合には該当コンテンツのメディアコンテンツキーでremoveをリクエストします。

コンテンツ再生

コンテンツ再生の手順

1. Player 生成

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

2. Listener 登録

   • Playerのイベントを取得するするまてにはリスナーを登録しなければなりません。以下のリスナーは出来るだけ登録することを推奨します。
     • OnPreparedListener
     • OnCompletionListener
     • OnErrorListener
     • OnVideoSizeChangedListener
   • Player関連のリスナーは以下のリストを確認してください。

     • 再生準備完了を取得するリスナー
       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<BandwidthItem> list);
       	void onChangedBandwidth(MediaPlayer mp, BandwidthItem item);
       }
       

     • DRM関連リスナー (widevineなど)
       void setOnCencDrmListener(OnCencDrmListener listener);

       public interface OnCencDrmListener
       {
       	void onProxyError(int nErrorCode, String strErrorMessage);
       }

     • シーク完了有無を取得するリスナー
       setOnSeekCompleteListener(OnSeekCompleteListener listener);

       public interface OnSeekCompleteListener
       {
       	public void onSeekComplete(MediaPlayer mp);
       }

     • コンテンツのresolution情報が変更された際に取得するリスナー
       setOnSeekCompleteListener(OnSeekCompleteListener listener); 初期resolution情報を取得する際にも使用します。

       public interface OnVideoSizeChangedListener
       {
       	public void onVideoSizeChanged(MediaPlayer mp, 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 {
       	/**
       	 * リクエストしたLMSデータの内容
       	 * @param request サーバーにリクエストしたメッセージ
       	 * @param response サーバーからレスポンスされたメッセージ
       	 */
       	void onLMS(String request, String response);
       }

     • ブックマーク関連リスナー
       setKollusPlayerBookmarkListener(KollusPlayerBookmarkListener listener);

       public interface KollusPlayerBookmarkListener {
       	/**
       	 * Indexブックマークまたはユーザーブックマークがあるとリスニングされます。 
       	 * @param bookmark ブックマークリスト
       	 * @param bWritable false の場合、ユーザーブックマークを使用しようすることができないコンテンツ
       	 */
       	void onBookmark(List<KollusBookmark> 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);
       }

     • Emulatorで再生を試した際に発生するリスナー
       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);
       • path : コンテンツパス
       • extraDrmParam : Play Callbackに追加するパラメータでない場合にはnullを入力してください。
     • ダウンロードコンテンツ
       • public void setDataSourceByKey(String mediaContentKey, String extraDrmParam);
       • mediaContentKey: ダウンロードされているコンテンツのメディアコンテンツキー
       • extraDrmParam : DRM Callbackに追加するパラメータでない場合にはnullを入力してください。
     • SurfaceViewの生成が完了した際に実行
       • ストリーミングコンテンツを再生する場合
         • mediaPlayer. setDataSourceByUrl(path, extraDrmParam);
       • ダウンロードコンテンツを再生する場合
         • mediaPlayer. setDataSourceByKey (mck, extraDrmParam);

5. 再生準備完了

   • public void prepareAsync();
     prepareAsyncをリクエストすると、コンテンツの再生準備が完了された際に発生するOnPreparedListenerのonPreparedがリスニングされます。この段階からコンテンツ情報の取得と再生が可能になります。
     続き再生をさせるためにはstart前にseekToまたはseekToExactを実行してください。
     
     • onPrepared(MediaPlayer mp)が発生した際の作業
       
       • getKollusContent(KollusContent content)をリクエストしてコンテンツ情報を取得します。スクリーンショット情報は以下のように取得します。
         1. String screenShotPath = content.getScreenShotPath();
         2. ネーミングルールは、「ファイル名.{width}x{height}x{count}.拡張子」となり、ここでCountの一番前の3枚は無意味な値になるので注意してください。
       • 続き再生をする場合、以下のどちらかの関数をリクエストしてください。
         1. mMediaPlayer.seekTo(int msec); //フレーム基準でシーク
         2. mMediaPlayer.seekToExact(int msec); //時間基準でシーク

6. 再生終了

   • 再生を終了させる場合、または再生が完了されてOnCompletionListenerのonCompletionがリスニングされた場合には以下の関数を順番通りにリクエストしてください。
     1. public void stop();
     2. public void release();

ブックマーク管理

ブックマーク管理は再生途中に行い、KollusPlayerBookmarkListenerを登録した場合にリストを取得することができます。登録または削除はネットワーク経由で作業が行われるため環境によっては時間が掛かる可能性がありますので、関数をリクエストしてから直ちにUIに反映されるように実装することを推奨します。

ブックマークリストの取得

on Bookmarkがリスニングされた際にブックマーク情報の登録/削除可能可否を取得することができます。

ブックマーク登録/更新

public void updateKollusBookmark(int position, String label);

• position : 登録する位置のミリ秒
• label : 登録する位置のタイトルで、ない場合には“”をリクエストします。
• updateKollusBookmarkをリクエストするとonBookmarkUpdatedがリスニングされます。新しい項目なら新規登録され、既存項目なら更新されます。

ブックマーク削除

public void deleteKollusBookmark(int position);

• position : 削除するブックマークのミリ秒
• deleteKollusBookmarkをリクエストするとonBookmarkDeletedがリスニングされます。