既知の制限事項
SDKの使用前に以下の要件と制限事項をご確認ください。
デバイス要件
| 項目 | OpenCL最小 | OpenCL推奨 |
|---|---|---|
| Androidバージョン | 8.0 (API 26) | 12+ (API 31) |
| RAM | 4GB | 6GB以上 |
| ストレージ | 500MB | 1GB以上 |
| GPU | OpenGL ES 2.0 / OpenCL 1.2 | OpenGL ES 3.0+ / OpenCL 2.0+ |
サポートアーキテクチャ (ABI)
| ABI | サポート | 備考 |
|---|---|---|
arm64-v8a | サポート | 大半の最新デバイス |
armeabi-v7a | サポート | 旧型32ビットデバイス |
x86_64 | 非サポート | エミュレータ |
x86 | 非サポート | エミュレータ |
x86/x86_64エミュレータではSDKは動作しません。
テスト方法:
- 実際のAndroidデバイスを使用（推奨）
- ARMベースのエミュレータを使用（例：Apple Silicon Macのデフォルトエミュレータ）
ネットワーク要件
必須条件
- インターネット接続: リアルタイムWebSocket通信に必須
- プロトコル: HTTPS / WSS (TLS 1.2以上)
- ポート: 443
ファイアウォール設定
# 許可が必要なドメイン
*.klleon.io
ネットワーク権限
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
オーディオ関連の制限事項
USBマイク互換性
- MMAPポリシー: MMAPはSDK内部で管理され、デフォルトで無効化されています。MMAP有効化時に一部のUSBマイクでストリームオープンに失敗する場合があります。
- USBデバイス選択: USBマイクが接続されると自動的に検出・選択されます。
- 互換性のないデバイス: 一部のMediaTekベースのTVでUSB複合デバイス（例：DM30RGB）のオーディオストリームオープンに失敗する場合があります。
エコー防止
- アバター発話中は音声認識が自動的にブロックされます。
既知の問題
1. メモリ使用量
ビデオ処理およびAI推論中にメモリ使用量が高くなる場合があります。特に ResourceManager.init() 呼び出し時にYUVフレームバッファとして約1GBのネイティブメモリが割り当てられます。
バッファライフサイクル
finish() はバッファを維持して同一アバター再進入時に即座に再利用します（0ms）。完全なメモリ解放には deinit() を明示的に呼び出す必要があります。
| シナリオ | 動作 |
|---|---|
| 同じアバター再進入 | init(同一avatarId) → バッファ再利用 (0ms) |
| 異なるアバター切り替え | init(新avatarId) → 自動で以前のバッファ解放 + 新規割り当て |
| アプリバックグラウンド遷移 | onTrimMemory → deinit() → バッファ解放 |
| アプリ終了 | CharacterActivity.onDestroy → deinit() → 完全解放 |
| プロセス強制終了 | OSカーネルが自動回収（コード不要） |
必須実装パターン
Applicationクラス — バックグラウンドメモリ自動解放:
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
registerComponentCallbacks(object : ComponentCallbacks2 {
override fun onTrimMemory(level: Int) {
if (level >= ComponentCallbacks2.TRIM_MEMORY_UI_HIDDEN) {
ResourceManager.deinit()
}
}
override fun onConfigurationChanged(newConfig: Configuration) {}
override fun onLowMemory() { ResourceManager.deinit() }
})
}
}
SDK play画面（ChatActivityなど）:
override fun onDestroy() {
super.onDestroy()
// finish()はsuspend関数のためコルーチンで実行
CoroutineScope(Dispatchers.Default).launch {
klleonOndeviceSdk.finish() // バッファ維持（再利用待機）
}
}
アバター選択画面（CharacterActivityなど）:
override fun onDestroy() {
super.onDestroy()
// SDKが再生中でなければ（play前の離脱）手動でメモリ解放
if (!KlleonOndeviceSdk.playing) {
ResourceManager.deinit()
}
}
init(): 同一アバター(avatarId)の再呼び出し時に既存バッファを再利用（重複割り当てなし）deinit(): 複数回呼び出しても安全（冪等性保証）finish(): 内部のplaying状態チェックにより重複呼び出しが安全
2. バックグラウンド制限
アプリがバックグラウンドに遷移すると、ビデオ処理が一時停止されます。
3. 単一インスタンス制限
KlleonOndeviceSdk インスタンスはアプリあたり1つのみ作成する必要があります。
内部コルーチンスコープとスレッドプールがインスタンスごとに割り当てられるため、複数インスタンスを作成するとリソース競合およびメモリリークが発生します。
推奨：objectシングルトンで管理
// アプリ全体で単一インスタンスを共有
object SdkConfig {
val sdk = KlleonOndeviceSdk()
}
// Activityでの使用
class ChatActivity : ComponentActivity() {
private val klleonOndeviceSdk = SdkConfig.sdk // 同一インスタンスを再利用
}
class AnotherActivity : ComponentActivity() {
private val klleonOndeviceSdk = SdkConfig.sdk // 同一インスタンスを再利用
}
Activityフィールドで KlleonOndeviceSdk() を直接生成すると、Activity再生成（画面回転、メモリ不足など）のたびに新しいインスタンスが作成され、以前のインスタンスのスレッドプールが蓄積されます。
// 間違った使い方 - 複数インスタンス
class MainActivity : Activity() {
val sdk1 = KlleonOndeviceSdk() // インスタンス1
val sdk2 = KlleonOndeviceSdk() // インスタンス2 - 競合発生！
}
4. 画面回転
画面回転時にActivityが再生成されると、SDK状態が初期化される場合があります。
解決方法:
<!-- AndroidManifest.xml - 画面回転を直接処理 -->
<activity
android:name=".MainActivity"
android:configChanges="orientation|screenSize|screenLayout" />
5. Android TVの特記事項
- TVプラットフォームではレイアウト変更時に自動フォーカスが最初のfocusable要素に付与され、キーボードが自動表示される場合があります。
focusProperties { canFocus = false }で根本的にブロックし、クリック時にのみ有効化してください。- MediaTekベースのTVで一部USBオーディオデバイスの互換性に問題がある場合があります。
パフォーマンス最適化のヒント
GPUアクセラレーション
SDKは基本的にGPUアクセラレーションを使用します。一部のローエンドデバイスで問題が発生した場合：
// GPU問題発生時のログ確認
adb logcat | grep "Klleon_"
バッテリー最適化
長時間使用時にバッテリー消費が大きくなる場合があります：
- 使用しない時は
finish()を呼び出し - 画面オフ時の処理停止を推奨
enterStandby()/exitStandby()で待機画面モードを活用
サポートへのお問い合わせ
上記の制限事項で解決できない問題は、Klleon Studio を通じてお問い合わせください。