Android SDK

背景ぼかしとバーチャル背景

SkyWay Android SDK は、カメラ映像の背景にぼかしをかける背景ぼかし、および背景を任意の画像に差し替えるバーチャル背景の機能を提供しています。

注意この機能は Android API 24（Android 7.0）以降でのみ利用可能です。

クラス	機能名	効果
`BlurProcessor`	背景ぼかし	背景にぼかし（ブラー）をかける
`VirtualBackgroundProcessor`	バーチャル背景	背景を任意の `Bitmap` 画像に置き換える

どちらのクラスも com.ntt.skyway:video-processors ライブラリに含まれています。

セットアップ

build.gradle に依存関係を追加してください。

dependencies {
    implementation "com.ntt.skyway:video-processors:$video_processors_version"
}

$video_processors_version は、こちらのリンクより最新バージョンを確認してください。

背景ぼかし（BlurProcessor）

BlurProcessor の初期化および適用

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 に追加すると、背景ぼかしが有効になります。映像の送信については、カメラの選択を参照してください。

BlurProcessor API の呼び出し

// 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 の初期化および適用

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 に追加すると、バーチャル背景が有効になります。映像の送信については、カメラの選択を参照してください。

VirtualBackgroundProcessor API の呼び出し

// 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 程度）の使用を推奨します。

// 30fps の映像で推論を 10fps 相当に抑えたい場合
blurProcessor.segmentationIntervalFrames = 3   // 30 / 3 = 10fps

// 60fps の映像でも同じ推論負荷を維持したい場合
blurProcessor.segmentationIntervalFrames = 6   // 60 / 6 = 10fps

`mediaPipeSyncInputSize` はデバイス性能に応じて選択する

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)

バーチャル背景の画像は事前にロードする

// 画像を事前ロードし、切り替え時はプロパティ代入のみ
val backgrounds: List<Bitmap> = 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() を呼び出してリソースを解放してください。

// プロセッサを完全に停止する場合
CameraSource.removeVideoProcessor(blurProcessor)
blurProcessor.dispose()  // GPU リソースを解放

CameraSource.removeVideoProcessor(vbProcessor)
vbProcessor.dispose()    // GPU リソースを解放

Activity や Fragment のライフサイクルに合わせて、onDestroy() / onDestroyView() で呼び出すことを推奨します。

override fun onDestroy() {
    super.onDestroy()
    CameraSource.removeVideoProcessor(blurProcessor)
    blurProcessor.dispose()
}

注意 dispose() 呼び出し後は、同じインスタンスを再利用しないでください。再度使用する場合は新しいインスタンスを作成してください。

API Reference

SkyWay Video Processors for Android

サンプルコード

背景ぼかし/バーチャル背景を利用したカメラ映像のサンプル

発話検知

OpenCVを利用する