--- lang: ja path: cookbook/android-sdk/video-processor labels: クックブック/Android SDK/背景ぼかしとバーチャル背景 metaTitle: 背景ぼかし | バーチャル背景 | Android SDK | クックブック | SkyWay（スカイウェイ） --- # 背景ぼかしとバーチャル背景 SkyWay Android SDK は、カメラ映像の背景にぼかしをかける**背景ぼかし**、および背景を任意の画像に差し替える**バーチャル背景**の機能を提供しています。 > **注意** この機能は Android API 24（Android 7.0）以降でのみ利用可能です。 | クラス | 機能名 | 効果 | |--------|--------|------| | `BlurProcessor` | 背景ぼかし | 背景にぼかし（ブラー）をかける | | `VirtualBackgroundProcessor` | バーチャル背景 | 背景を任意の `Bitmap` 画像に置き換える | どちらのクラスも `com.ntt.skyway:video-processors` ライブラリに含まれています。 --- ## セットアップ `build.gradle` に依存関係を追加してください。 ```groovy dependencies { implementation "com.ntt.skyway:video-processors:$video_processors_version" } ``` $video_processors_version は、 [こちらのリンク](https://central.sonatype.com/artifact/com.ntt.skyway/video-processors) より最新バージョンを確認してください。 --- ## 背景ぼかし（BlurProcessor） ### BlurProcessor の初期化および適用 ```kotlin import com.ntt.skyway.videoprocessors.BlurProcessor import com.ntt.skyway.videoprocessors.BlurProcessingConfig import com.ntt.skyway.core.content.local.source.CameraSource // 1. 背景ぼかしプロセッサを作成 val blurProcessor = BlurProcessor( config = BlurProcessingConfig(blurStrength = 60), context = applicationContext ) // 2. CameraSource にプロセッサを追加 CameraSource.addVideoProcessor(blurProcessor) ``` `BlurProcessor` を `CameraSource` に追加すると、背景ぼかしが有効になります。 映像の送信については、[カメラの選択](https://skyway.ntt.com/ja/docs/cookbook/android-sdk/select-devices/) を参照してください。 ### BlurProcessor API の呼び出し ```kotlin // 3. 背景ぼかし実行中に強度を変更（0〜100） blurProcessor.blurStrength = 80 // 4. 前景判定しきい値を変更（0f〜1f） blurProcessor.foregroundThreshold = 0.6f // 5. 境界の滑らかさを変更（0f〜1f） blurProcessor.edgeSoftness = 0.12f // 6. セグメンテーション実行間隔を変更（1〜100） blurProcessor.segmentationIntervalFrames = 2 // 2フレームごとに推論 // 7. 背景ぼかしを一時停止 blurProcessor.isActive = false // 8. 背景ぼかしを再開 blurProcessor.isActive = true // 9. 背景ぼかしを完全に停止する CameraSource.removeVideoProcessor(blurProcessor) blurProcessor.dispose() ``` --- ## バーチャル背景（VirtualBackgroundProcessor） ### VirtualBackgroundProcessor の初期化および適用 ```kotlin import android.graphics.Bitmap import com.ntt.skyway.videoprocessors.VirtualBackgroundProcessor import com.ntt.skyway.videoprocessors.VirtualBackgroundProcessingConfig import com.ntt.skyway.core.content.local.source.CameraSource // 1. 背景画像付きで初期化 val bgBitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.virtual_background) val vbProcessor = VirtualBackgroundProcessor( config = VirtualBackgroundProcessingConfig( backgroundImage = bgBitmap ), context = applicationContext ) // 2. CameraSource にプロセッサを追加 CameraSource.addVideoProcessor(vbProcessor) ``` `VirtualBackgroundProcessor` を `CameraSource` に追加すると、バーチャル背景が有効になります。 映像の送信については、[カメラの選択](https://skyway.ntt.com/ja/docs/cookbook/android-sdk/select-devices/) を参照してください。 ### VirtualBackgroundProcessor API の呼び出し ```kotlin // 3. 実行中に背景画像を変更 vbProcessor.backgroundImage = BitmapFactory.decodeResource(resources, R.drawable.beach_background) // 4. 背景なし（元映像）に戻す vbProcessor.backgroundImage = null // 5. 前景判定しきい値を変更（0f〜1f） vbProcessor.foregroundThreshold = 0.6f // 6. 境界の滑らかさを変更（0f〜1f） vbProcessor.edgeSoftness = 0.12f // 7. セグメンテーション実行間隔を変更（1〜100） vbProcessor.segmentationIntervalFrames = 2 // 2フレームごとに推論 // 8. バーチャル背景を一時停止 vbProcessor.isActive = false // 9. プロセッサ削除・リソース解放 CameraSource.removeVideoProcessor(vbProcessor) vbProcessor.dispose() ``` ## ベストプラクティス ### `segmentationIntervalFrames` でフレームレートに応じた負荷調整をする `segmentationIntervalFrames` を増やすと MediaPipe の推論頻度が下がり、CPU/GPU 負荷を削減できます。 前フレームのセグメンテーション結果をキャッシュして再利用するため、映像品質への影響は軽微です。 > **注意** 値を大きくするほど、セグメンテーション結果の更新が遅れるため、人物が動いた際に背景ぼかし・バーチャル背景の境界が映像に対してズレて見える場合があります。動きの激しい映像では小さい値（1〜3 程度）の使用を推奨します。 ```kotlin // 30fps の映像で推論を 10fps 相当に抑えたい場合 blurProcessor.segmentationIntervalFrames = 3 // 30 / 3 = 10fps // 60fps の映像でも同じ推論負荷を維持したい場合 blurProcessor.segmentationIntervalFrames = 6 // 60 / 6 = 10fps ``` ### `mediaPipeSyncInputSize` はデバイス性能に応じて選択する ```kotlin val am = context.getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager val isLowRam = am.isLowRamDevice val cores = Runtime.getRuntime().availableProcessors() val inputSize = when { isLowRam || cores <= 4 -> 192 // 低スペック端末（高速優先） cores <= 6 -> 256 // 中程度の端末（バランス） else -> 320 // 高スペック端末（精度優先） } val config = BlurProcessingConfig(mediaPipeSyncInputSize = inputSize) ``` ### バーチャル背景の画像は事前にロードする ```kotlin // 画像を事前ロードし、切り替え時はプロパティ代入のみ val backgrounds: List = listOf("bg1", "bg2", "bg3").mapNotNull { val resId = resources.getIdentifier(it, "drawable", packageName) if (resId != 0) BitmapFactory.decodeResource(resources, resId) else null } vbProcessor.backgroundImage = backgrounds[selectedIndex] ``` `BitmapFactory.decodeResource()` を毎回切り替えのたびに呼び出すと、画像デコード処理が都度発生するため避けてください。 ### `isActive` と `addVideoProcessor` / `removeVideoProcessor` の使い分け | 手法 | プロセッサインスタンスの維持 | MediaPipe 初期化コスト | 推奨タイミング | |------|-----------------|--------------|---------------| | `isActive = false` | 維持される | 再発生しない | 頻繁な ON/OFF | | `CameraSource.removeVideoProcessor()` | 参照を保持していれば維持 | 再 `add` 時に発生しない（インスタンスを再利用する場合） | 完全に無効化したい場合 | 頻繁に ON/OFF する場合は `isActive` の切り替えを推奨します。 ### プロセッサのリソースを適切に解放する `BlurProcessor` / `VirtualBackgroundProcessor` はどちらも内部で GPU リソースを保持しています。使用を終えたら必ず `dispose()` を呼び出してリソースを解放してください。 ```kotlin // プロセッサを完全に停止する場合 CameraSource.removeVideoProcessor(blurProcessor) blurProcessor.dispose() // GPU リソースを解放 CameraSource.removeVideoProcessor(vbProcessor) vbProcessor.dispose() // GPU リソースを解放 ``` Activity や Fragment のライフサイクルに合わせて、`onDestroy()` / `onDestroyView()` で呼び出すことを推奨します。 ```kotlin override fun onDestroy() { super.onDestroy() CameraSource.removeVideoProcessor(blurProcessor) blurProcessor.dispose() } ``` > **注意** `dispose()` 呼び出し後は、同じインスタンスを再利用しないでください。再度使用する場合は新しいインスタンスを作成してください。 ## API Reference - [SkyWay Video Processors for Android](https://android-sdk.api-reference.skyway.ntt.com/video-processors/) ## サンプルコード - [背景ぼかし/バーチャル背景を利用したカメラ映像のサンプル](https://github.com/skyway/android-sdk/tree/main/examples/JetpackCompose/SkyWayComposeExamples/app/src/main/java/com/ntt/skyway/compose/examples/VideoProcessorsViewModel.kt)