この記事では公式ドキュメントのUse the Virtual Background Extensionを翻訳した内容になります。

概要

このagora-extension-virtual-background拡張機能は、バーチャル背景機能を実装するためにAgora Web SDK（v4.10.0以降）と一緒に使用されます。
この機能により、ユーザーは実際の背景をぼかしたり、単色または画像に置き換えたりすることができます。
この拡張機能は、オンライン会議、オンラインクラス、ライブストリーミングなどのシナリオに適用できます。
個人のプライバシーを保護し、視聴者が気を散らすのを減らすのに役立ちます。

次の図は、拡張機能がどのように機能するかを示しています。

2022/7/5追記
WebSDK　v4.12.0から背景に動画を設定する事ができるようになりました。

注意事項

この拡張機能は、カメラでキャプチャされたビデオにユーザーが1人しかいない場合に最適に機能します。
バーチャル背景拡張機能のブラウザサポートは次のとおりです。
- より優れたバーチャル背景を実現するために、Agoraは最新バージョンのデスクトップChromeでこの機能を使用することをお勧めします。
- Agoraは、FirefoxおよびSafariブラウザでバーチャル背景機能を有効にすることを推奨していません。FirefoxでWebアプリをバックグラウンド処理すると、ビデオがフリーズする可能性がありますが、Safariでのパフォーマンスは、ブラウザー自体のパフォーマンスの問題のために低下する可能性があります。
- Agoraは、モバイルブラウザでバーチャル背景機能を有効にすることを推奨していません。
バーチャル背景機能には、高いパフォーマンス要件があります。コンピュータが次の要件を満たしていることを確認してください。
- CPU：Intel Corei5 4コア以上
- 8GRAM以上
- 64 Bit OS

処理概要

Agora Web SDKの一般的な送信パイプラインは、キャプチャ、前処理、エンコード、送信、デコード、後処理、再生などの一連の手順で構成されています。前処理段階で、拡張機能はパイプラインのオーディオおよびビデオデータを変更して、バーチャル背景やノイズキャンセルなどの機能を実装できます。

実装方法

以下のようにバーチャル背景拡張機能を組み込みます。

クイックスタートガイドを参照して、Web SDK（v4.10.0以降）を組み込み、プロジェクトに基本的なビデオ通話機能を実装してください。
npmを介してバーチャル背景拡張機能をプロジェクトに組み込みます。
拡張機能をインストールするには、次のコマンドを実行します。

npm install agora-extension-virtual-background

拡張機能をインポートするには、次のいずれかの方法を使用します。

方法1：JavaScriptファイルに次のコードを追加します。

import {VirtualBackgroundExtension} from "agora-extension-virtual-background";

方法2：HTMLファイルでScriptタグを使用します。インポートすると、VirtualBackgroundExtensionオブジェクトをJavaScriptファイルで直接使用できます。

<script src="./agora-extension-virtual-background.js"></script>

Wasm依存ファイルを動的にロードする：バーチャル背景拡張機能はWasmファイルに依存します。node_modules/agora-extension-virtual-background/wasms以下にWasmファイルがあります。WasmファイルをCDNまたは静的リソースサーバーに公開する必要があります。以降の手順で呼び出すときは、WasmファイルのURLを渡す必要があります。拡張機能は、Wasmファイルを動的にロードします。

注意事項
WasmファイルのホストURLがWebアプリケーションのホストURLと同じでない場合は、CORSポリシーを有効にします。
HTTPSドメインへのHTTPリソースのロードはブラウザのセキュリティポリシーによってブロックされているため、WasmファイルをHTTPサービスに配置しないでください。

バーチャル背景拡張機能を登録します。

// Create a client object
var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"});
// Create a VirtualBackgroundExtension instance
const extension = new VirtualBackgroundExtension();
// Register the extension
AgoraRTC.registerExtensions([extension]);

バーチャル背景拡張機能を初期化します。

processor = extension.createProcessor();

拡張機能を初期化するために呼び出します。この方法では、WasmモジュールのURLを渡す必要があります。リソースのロードまたは拡張機能の初期化が失敗した場合、このメソッドは例外をスローします。この例外をキャッチし、それに応じて処理します。

await processor.init("./assets/wasms");

ローカルカメラトラックを作成した後、videoTrack.pipeでvideoTrack.processorDestination拡張機能をSDKのメディア処理パイプラインに挿入します。

localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination);

processor.setOptionsで仮想背景タイプを選択し、設定を行います。Agoraは次の設定をサポートしています。

背景として単色を設定

processor.setOptions({type: 'color', color: '#00ff00'});

画像を背景として設定

processor.setOptions({type: 'img', source: HTMLImageElement});

元の背景をぼかす(低:1、中:2、高:3)

processor.setOptions({type: 'blur', blurDegree: 2});

processor.enableで、仮想バックグラウンド機能を有効にします。

await processor.enable();

setOptionsをコールしない場合、デフォルトで元の背景をぼかす（低)になります。切り替えはsetOptionsを呼び出すだけです。

サンプルコード

import AgoraRTC from "agora-rtc-sdk-ng";
import {VirtualBackgroundExtension} from "agora-extension-virtual-background";

// Create a client object
var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"});
// Create a VirtualBackgroundExtension instance
const extension = new VirtualBackgroundExtension();
// Register the extension
AgoraRTC.registerExtensions([extension]);

let processor = null;
var localTracks = {
  videoTrack: null,
  audioTrack: null
};

// Initialization
async function getProcessorInstance() {
  if (!processor && localTracks.videoTrack) {
    // Create a VirtualBackgroundProcessor instance
    processor = extension.createProcessor();

      try {
        // Initialize the extension and pass in the URL of the Wasm file
        await processor.init("./assets/wasms");
        } catch(e) {
          console.log("Fail to load WASM resource!");return null;
          }
    // Inject the extension into the video processing pipeline in the SDK
    localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination);
  }
  return processor;
}

// Join a channel
async function join() {
  // Add event listeners
  client.on("user-published", handleUserPublished);
  client.on("user-unpublished", handleUserUnpublished);

  [options.uid, localTracks.audioTrack, localTracks.videoTrack] = await Promise.all([
    // Join a channel
    client.join(options.appid, options.channel, options.token || null),
    // Create a local microphone track and camera track
    localTracks.audioTrack || AgoraRTC.createMicrophoneAudioTrack(),
    localTracks.videoTrack || AgoraRTC.createCameraVideoTrack({encoderConfig: '720p_4'})
  ]);

  // Play local tracks
  localTracks.videoTrack.play("local-player");
}

// Set a solid color as the background
async function setBackgroundColor() {
  if (localTracks.videoTrack) {
    document.getElementById("loading").style.display = "block";

    let processor = await getProcessorInstance();

    try {
      processor.setOptions({type: 'color', color: '#00ff00'});
      await processor.enable();
    } finally {
      document.getElementById("loading").style.display = "none";
    }

    virtualBackgroundEnabled = true;
  }
}

// Blur the user's actual background
async function setBackgroundBlurring() {
  if (localTracks.videoTrack) {
    document.getElementById("loading").style.display = "block";

    let processor = await getProcessorInstance();

    try {
      processor.setOptions({type: 'blur', blurDegree: 2});
      await processor.enable();
    } finally {
      document.getElementById("loading").style.display = "none";
    }

    virtualBackgroundEnabled = true;
  }
}

// Set an image as the background
async function setBackgroundImage() {
    const imgElement = document.createElement('img');

    imgElement.onload = async() => {
      document.getElementById("loading").style.display = "block";

      let processor = await getProcessorInstance();

      try {
        processor.setOptions({type: 'img', source: imgElement});
        await processor.enable();
      } finally {
        document.getElementById("loading").style.display = "none";
      }

      virtualBackgroundEnabled = true;
    }
    imgElement.src = '/images/background.png';
}

Agoraは多くのサンプルコードをGitHubに公開しています。
このバーチャル背景のサンプルも公開されています。

最後に

agora.ioに関するお問い合わせはこちらから