5. オフライン再生

お知らせ

このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。

ローカルディスクへのダウンロードが完了したコンテンツを再生する方法について説明します。 オフライン状態では、オンラインストリーミング再生時に使用するリモート URL の代わりに、メディアコンテンツキー（MediaContentKey、mck）ベースのデータソースを使用します。

このドキュメントのすべてのサンプルコードは、公式サンプルアプリ kollus_player_v2_android をもとに作成されています。

---

オフライン再生

ストリーミング再生時に使用する setDataSourceByUrl の代わりに、ローカルメディアキーを指定する setDataSourceByKey メソッドを使用してオフライン再生を開始します。

// VideoView.openVideo()
String extraDrmParam = null;
if (mUri != null) {
    // Streaming playback (online environment)
    mMediaPlayer.setDataSourceByUrl(mUri.toString(), extraDrmParam);
} else if (mKollusContent != null) {
    // Offline playback (downloaded content)
    mMediaPlayer.setDataSourceByKey(
        mKollusContent.getKollusContent().getMediaContentKey(),
        extraDrmParam);
}
mMediaPlayer.prepareAsync();

全体の連携フロー

1. multiStorage.getDownloadKollusContent(localPath) または getDownloadList() メソッドを通じて MultiKollusContent オブジェクトを取得します。
2. VideoView コンポーネントに setKollusContent(content) メソッドで取得したオブジェクトをアタッチします。
3. 内部的に setDataSourceByKey(mck, extraDrmParam) と prepareAsync() が順次呼び出されます。
4. 再生準備の過程で SDK がローカル DRM 検証を自動的に実行します。ライセンスが失効しているか権限がない場合はプレイヤーが停止し、onDRMInfo コールバックでエラーコードが通知されます。（参考文書: 8. ダウンロードイベント/コールバック）

---

オフライン DRM 検証条件

ネットワークに接続されていないオフライン環境でも DRM 検証を通過するには、ダウンロードファイル内部に注入された以下の 3 つの DRM セキュリティ制限条件をすべて満たす必要があります。

• 失効日時 (DRMExpireDate): デバイスの現在時刻がライセンスに指定された失効日時より前である必要があります。
• 再生回数 (DRMExpireCount): これまでの実際の再生回数が設定された最大制限回数(DRMExpireCountMax)未満である必要があります。
• 残余時間 (DRMExpirePlayTime): 残余再生許可時間が 0 より大きい必要があります。

上記 3 つの条件のうち 1 つでも違反した場合はローカル再生が失敗し、正常動作のためには再度ネットワークに接続してライセンスを更新する必要があります。（参考文書: 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 から該当インデックスを削除します。（アプリ再起動後のダウンロード復元パイプライン 参考）
ファイルが破損している場合	ERROR_WRITE_FILE エラーが返されるか、再生時にプレイヤーエラーが発生します。ユーザーにファイルの不具合を案内し、再ダウンロードを促すメッセージを表示します。