クイックスタート: ビデオ通話にビデオ効果を追加する

[アーティクル]
07/26/2023

ビデオ効果機能を使用すると、ビデオ通話においてビデオに効果を追加できます。この機能を使用すると、開発者はバックグラウンドの視覚効果とバックグラウンドビデオの置き換えを通話エクスペリエンスに組み込むことができます。背景ぼかしにより、ユーザーは、参加者の背後にある気を散らすものを取り除くメカニズムを利用できます。これにより、参加者はバックグラウンドに破壊的なアクティビティや機密情報が示されることなく通信できます。これは、医療提供者または患者が機密情報や個人を特定できる情報を保護するために自分の周囲を隠したいという、遠隔医療のコンテキストで特に役立ちます。背景ぼかしは、ユーザーのプライバシーを保護するために、テレバンクや仮想ヒアリングを含むすべての仮想予定シナリオに適用できます。機密性の向上に加えて、背景ぼかしを使用すると、表現の創造性が向上し、ユーザーはカスタム背景をアップロードして、より楽しくパーソナライズされた通話エクスペリエンスをホストできます。

Note

通話効果ライブラリはスタンドアロンでは使用できず、WebJS (https://www.npmjs.com/package/@azure/communication-calling) 用の Azure Communication Calling クライアントライブラリで使用する場合にのみ機能します。

ビデオ効果の使用

パッケージをインストールする

JavaScript 用の Azure Communication Services SMS SDK をインストールするには、npm install コマンドを使用します。

重要

このクイックスタートでは、1.13.1 またはそれ以上のバージョンの Azure Communication Services Calling SDK、および 1.0.1 より新しいまたは同等のバージョンの Azure Communication Services Calling Effects SDK を使用します。

npm install @azure/communication-calling-effects --save

通話通信効果 npm パッケージページの詳細については、こちらをご覧ください。

Note

現在、ビデオの背景効果を作成するためのブラウザーのサポートは、Chrome、Edge Desktop Browser (Windows および Mac)、Mac Safari Desktop 上でのみ対応しています。

Note

現在、使用可能なビデオ効果は 2 つあります。

背景ぼかし
背景を画像に置き換える (縦横比は 16:9 で互換性があること)

Azure Communication Calling SDK でビデオ効果を使用するには、LocalVideoStream を作成したら、LocalVideoStream の VideoEffects 機能 API を取得してビデオ効果を開始または停止する必要があります。

import * as AzureCommunicationCallingSDK from '@azure/communication-calling'; 

import { BackgroundBlurEffect, BackgroundReplacementEffect } from '@azure/communication-calling-effects'; 

// Get the video effects feature api on the LocalVideoStream 
// (here, localVideoStream is the LocalVideoStream object you created while setting up video calling)
const videoEffectsFeatureApi = localVideoStream.feature(AzureCommunicationCallingSDK.Features.VideoEffects); 


// Subscribe to useful events 
videoEffectsFeatureApi.on(‘effectsStarted’, () => { 
    // Effects started
});

videoEffectsFeatureApi.on(‘effectsStopped’, () => { 
    // Effects stopped
}); 

videoEffectsFeatureApi.on(‘effectsError’, (error) => { 
    // Effects error
});

背景ぼかし

// Create the effect instance 
const backgroundBlurEffect = new BackgroundBlurEffect(); 

// Recommended: Check support by using the isSupported method on the feature API
const backgroundBlurSupported = await videoEffectsFeatureApi.isSupported(backgroundBlurEffect);

if (backgroundBlurSupported) { 
    // Use the video effects feature api we created to start effects
    await videoEffectsFeatureApi.startEffects(backgroundBlurEffect); 
}

背景をイメージに置き換える

この効果の背景として必要なイメージの URL を指定する必要があります。

重要

URL がイメージではない場合、あるいは到達できない、または読み取れない場合、startEffects メソッドは失敗します。

Note

現在サポートされているイメージ形式は、png、jpg、jpeg、tiff、bmp です。

現在サポートされている縦横比は 16:9 です。

const backgroundImage = 'https://linkToImageFile'; 

// Create the effect instance 
const backgroundReplacementEffect = new BackgroundReplacementEffect({ 
    backgroundImageUrl: backgroundImage
}); 

// Recommended: Check support by using the isSupported method on the feature API
const backgroundReplacementSupported = await videoEffectsFeatureApi.isSupported(backgroundReplacementEffect);

if (backgroundReplacementSupported) { 
    // Use the video effects feature api as before to start/stop effects 
    await videoEffectsFeatureApi.startEffects(backgroundReplacementEffect); 
}

この効果のイメージを変更するには、それを、configure メソッドを介して渡します。

const newBackgroundImage = 'https://linkToNewImageFile'; 

await backgroundReplacementEffect.configure({ 
    backgroundImageUrl: newBackgroundImage
});

切り替え効果は、ビデオ効果機能 API 上で同じ方法を使用して実行できます。

// Switch to background blur 
await videoEffectsFeatureApi.startEffects(backgroundBlurEffect); 

// Switch to background replacement 
await videoEffectsFeatureApi.startEffects(backgroundReplacementEffect);

アクティブな効果をチェックする場合はいつでも、activeEffects プロパティを使用できます。 activeEffects プロパティを使用すると、現在アクティブな効果の名前を持つ配列が返され、アクティブな効果がない場合は空の配列が返されます。

// Using the video effects feature api
const currentActiveEffects = videoEffectsFeatureApi.activeEffects;

効果を停止するには:

await videoEffectsFeatureApi.stopEffects();

Note

iOS Calling SDK でビデオ効果を使用するために、機械学習モデルがお客様のデバイスにダウンロードされます。アプリケーションのプライバシーに関する注記を確認し、必要に応じて更新することをお勧めします。

ビデオ効果機能を使用すると、ビデオ通話のビデオに効果を追加できます。背景ぼかしにより、ユーザーは、参加者の背後にある気を散らすものを取り除くメカニズムを利用できます。これにより、参加者はバックグラウンドに破壊的なアクティビティや機密情報が示されることなく通信できます。この機能は遠隔医療のコンテキストで特に役立ちます。医療提供者や患者が、機密情報や個人データを保護するために自分の周囲をぼかすことができるからです。背景ぼかしは、ユーザーのプライバシーを保護するために、テレバンクや仮想ヒアリングを含むすべての仮想予定シナリオに適用できます。

ビデオ効果の使用

注意

iOS 版でのビデオエフェクトのサポートは、最近の iOS メジャーバージョン 2 つに限定されます。たとえば、iOS の新しいメジャーバージョンがリリースされたとき、iOS の要件は、その最新バージョンと直近のバージョン 1 つになります。

現在使用できるビデオ効果は、背景ぼかしの 1 つです。

LocalVideoEffectsFeature オブジェクトには、次の API 構造があります。

enable: LocalVideoStream インスタンスのビデオ効果を有効にします。
disable: LocalVideoStream インスタンスのビデオ効果を無効にします。
isSupported: LocalVideoStream インスタンスで Video Effect がサポートされているかどうかを示します。
onVideoEffectEnabled: ビデオ効果が正常に有効化されたときにトリガーされるイベント。
onVideoEffectDisabled: ビデオ効果が正常に無効化されたときにトリガーされるイベント。
onVideoEffectError: ビデオ効果の操作が失敗したときにトリガーされるイベント。

LocalVideoEffectsFeature オブジェクトを取得したら、イベントをサブスクライブできます。イベントには、didEnableVideoEffect、didDisableVideoEffect、didReceiveVideoEffectError というデリゲートがあります。

Azure Communication Calling SDK でビデオ効果を使用するには、LocalVideoStream の作成後、LocalVideoStream の VideoEffects 機能 API を取得してビデオ効果を有効または無効にする必要があります。

// Obtain the Video Effects feature from the LocalVideoStream object that is sending the video.
@State var localVideoEffectsFeature: LocalVideoEffectsFeature?
localVideoEffectsFeature = self.localVideoStreams.first.feature(Features.localVideoEffects)

// Subscribe to the events
public func localVideoEffectsFeature(_ videoEffectsLocalVideoStreamFeature: LocalVideoEffectsFeature, didEnableVideoEffect args: VideoEffectEnabledEventArgs) {
        os_log("Video Effect Enabled, VideoEffectName: %s", log:log, args.videoEffectName)
    }
public func localVideoEffectsFeature(_ videoEffectsLocalVideoStreamFeature: LocalVideoEffectsFeature, didDisableVideoEffect args: VideoEffectDisabledEventArgs) {
    os_log("Video Effect Disabled, VideoEffectName: %s", log:log, args.videoEffectName)
}
public func localVideoEffectsFeature(_ videoEffectsLocalVideoStreamFeature: LocalVideoEffectsFeature, didReceiveVideoEffectError args: VideoEffectErrorEventArgs) {
    os_log("Video Effect Error, VideoEffectName: %s, Code: %s, Message: %s", log:log, args.videoEffectName, args.code, args.message)
}

API の使用を開始して、ビデオ効果を有効または無効にします。

localVideoEffectsFeature.enable(effect: backgroundBlurVideoEffect)
localVideoEffectsFeature.disable(effect: backgroundBlurVideoEffect)

背景ぼかし

背景ぼかしは、人物の背景をぼかすことができるビデオ効果です。背景ぼかしのビデオ効果を使用するには、有効な LocalVideoStream から LocalVideoEffectsFeature 機能を取得する必要があります。

新しい背景ぼかしのビデオ効果オブジェクトを作成します。

@State var backgroundBlurVideoEffect: BackgroundBlurEffect?

BackgroundBlurEffect がサポートされているかどうかを確認し、videoEffectsFeature オブジェクトで Enable を呼び出します。

if((localVideoEffectsFeature.isSupported(effect: backgroundBlurVideoEffect)) != nil)
{
    localVideoEffectsFeature.enable(effect: backgroundBlurVideoEffect)
}

背景ぼかしのビデオ効果を無効にするには:

localVideoEffectsFeature.disable(effect: backgroundBlurVideoEffect)

注意

Android Calling SDK でビデオ効果を使用できるように、機械学習モデルがお客様のデバイスにダウンロードされます。アプリケーションのプライバシーに関する注記を確認し、必要に応じて更新することをお勧めします。

このクイックスタートは、Android 用の「クイックスタート: アプリに 1 対 1 のビデオ通話を追加する」に基づいています。

ビデオ効果の使用

注意

Android 版でのビデオエフェクトのサポートは、最近の Android メジャーバージョン 4 つに限定されます。たとえば、Android の新しいメジャーバージョンがリリースされたとき、Android の要件は、その最新バージョンと直近のバージョン 3 つになります。

現在使用できるビデオ効果は、背景ぼかしの 1 つです。

VideoEffectsLocalVideoStreamFeature オブジェクトには、次の API 構造があります。

enableEffect: LocalVideoStream インスタンスのビデオ効果を有効にします。
disableEffect: LocalVideoStream インスタンスのビデオ効果を無効にします。
OnVideoEffectEnabledListener: ビデオ効果が正常に有効化されたときにトリガーされるイベント。
OnVideoEffectDisabledListener: ビデオ効果が正常に無効化されたときにトリガーされるイベント。
OnVideoEffectErrorListener: ビデオ効果の操作が失敗したときにトリガーされるイベント。

VideoEffectEnabledEvent、VideoEffectDisabledEvent、VideoEffectErrorEvent の各オブジェクトには、次の API 構造があります。

getVideoEffectName: イベントをトリガーしたビデオ効果の名前を取得します。

VideoEffectsLocalVideoStreamFeature オブジェクトを取得したら、イベントをサブスクライブできます。

// Obtain the Video Effects feature from the LocalVideoStream object that is sending the video.
VideoEffectsLocalVideoStreamFeature videoEffectsFeature = currentVideoStream.feature(Features.LOCAL_VIDEO_EFFECTS);

// Create event handlers for the events
private void handleOnVideoEffectEnabled(VideoEffectEnabledEvent args) {
}
private void handleOnVideoEffectDisabled(VideoEffectDisabledEvent args) {
}
private void handleOnVideoEffectError(VideoEffectErrorEvent args) {
}
 
// Subscribe to the events
videoEffectsFeature.addOnVideoEffectEnabledListener(this::handleOnVideoEffectEnabled);
videoEffectsFeature.addOnVideoEffectDisabledListener(this::handleOnVideoEffectDisabled);
videoEffectsFeature.addOnVideoEffectErrorListener(this::handleOnVideoEffectError);

API の使用を開始して、ビデオ効果を有効または無効にします。

videoEffectsFeature.enableEffect( {{VIDEO_EFFECT_TO_DISABLE}} );
videoEffectsFeature.disableEffect( {{VIDEO_EFFECT_TO_DISABLE}} );

背景ぼかし

背景ぼかしは、人物の背景をぼかすことができるビデオ効果です。背景ぼかしのビデオ効果を使用するには、有効な LocalVideoStream から VideoEffectsLocalVideoStreamFeature 機能を取得する必要があります。

背景ぼかしのビデオ効果を有効にするには:

VideoEFfects 機能を取得し、イベントをサブスクライブするメソッドを作成します。

private void handleOnVideoEffectEnabled(VideoEffectEnabledEvent args) {
   Log.i("VideoEfects", "Effect enabled for effect " + args.getVideoEffectName());
}
private void handleOnVideoEffectDisabled(VideoEffectDisabledEvent args) {
   Log.i("VideoEfects", "Effect disabled for effect " + args.getVideoEffectName());
}
private void handleOnVideoEffectError(VideoEffectErrorEvent args) {
   Log.i("VideoEfects", "Error " + args.getCode() + ":" + args.getMessage()
           + " for effect " + args.getVideoEffectName());
}

VideoEffectsLocalVideoStreamFeature videoEffectsFeature;
public void createVideoEffectsFeature() {
    videoEffectsFeature = currentVideoStream.feature(Features.LOCAL_VIDEO_EFFECTS);
    videoEffectsFeature.addOnVideoEffectEnabledListener(this::handleOnVideoEffectEnabled);
    videoEffectsFeature.addOnVideoEffectDisabledListener(this::handleOnVideoEffectDisabled);
    videoEffectsFeature.addOnVideoEffectErrorListener(this::handleOnVideoEffectError);
}

新しい背景ぼかしのビデオ効果オブジェクトを作成します。

BackgroundBlurEffect backgroundBlurVideoEffect = new BackgroundBlurEffect();

videoEffectsFeature オブジェクトで EnableEffect を呼び出します。

public void enableBackgroundBlur() {
    videoEffectsFeature.enableEffect(backgroundBlurEffect);
}

背景ぼかしのビデオ効果を無効にするには:

public void disableBackgroundBlur() {
    videoEffectsFeature.disableEffect(backgroundBlurEffect);
}

注意

Windows Calling SDK でビデオ効果を使用するために、機械学習モデルが顧客のデバイスにダウンロードされます。アプリケーションのプライバシーに関する注記を確認し、必要に応じて更新することをお勧めします。

このクイックスタートは、Windows 用の「クイックスタート: アプリに 1 対 1 のビデオ通話を追加する」に基づいています。

ビデオ効果の使用

現在使用できるビデオ効果は、背景ぼかしの 1 つです。

VideoEffectsLocalVideoStreamFeature オブジェクトには、次の API 構造があります。

EnableEffect: LocalVideoStream インスタンスのビデオ効果を有効にします。
DisableEffect: LocalVideoStream インスタンスのビデオ効果を無効にします。
VideoEffectEnabled: ビデオ効果が正常に有効化されたときにトリガーされるイベント。
VideoEffectDisabledListener: ビデオ効果が正常に無効化されたときにトリガーされるイベント。
VideoEffectErrorListener: ビデオ効果の操作が失敗したときにトリガーされるイベント。

VideoEffectEnabledEvent、VideoEffectDisabledEvent、VideoEffectErrorEvent の各オブジェクトには、次の API 構造があります。

VideoEffectName: イベントをトリガーしたビデオ効果の名前を取得します。

VideoEffectsLocalVideoStreamFeature オブジェクトを取得したら、イベントをサブスクライブできます。

Azure Communication Calling SDK でビデオ効果を使用するために、変数を MainPage に追加します。

public sealed partial class MainPage : Page
{
    private LocalVideoEffectsFeature localVideoEffectsFeature;
}

LocalVideoStream を作成したら、ビデオ効果の有効/無効を切り替える、LocalVideoStream の VideoEffects 機能 API を取得する必要があります。

private async void CameraList_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    var selectedCamerea = CameraList.SelectedItem as VideoDeviceDetails;
    cameraStream = new LocalOutgoingVideoStream(selectedCamerea);
    InitVideoEffectsFeature(cameraStream);
    
    var localUri = await cameraStream.StartPreviewAsync();
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
    {
        LocalVideo.Source = MediaSource.CreateFromUri(localUri);
    });
}

public void InitVideoEffectsFeature(LocalOutgoingVideoStream videoStream){
    localVideoEffectsFeature = videoStream.Features.VideoEffects;
    localVideoEffectsFeature.VideoEffectEnabled += LocalVideoEffectsFeature_VideoEffectEnabled;
    localVideoEffectsFeature.VideoEffectDisabled += LocalVideoEffectsFeature_VideoEffectDisabled;
    localVideoEffectsFeature.VideoEffectError += LocalVideoEffectsFeature_VideoEffectError;
}

// Create event handlers for the events
private void LocalVideoEffectsFeature_VideoEffectEnabled(object sender, VideoEffectEnabledEventArgs args)
{
}

private void LocalVideoEffectsFeature_VideoEffectDisabled(object sender, VideoEffectDisabledEventArgs args)
{
}

private void LocalVideoEffectsFeature_VideoEffectError(object sender, VideoEffectErrorEventArgs args)
{
}
 
// Subscribe to the events
videoEffectsFeature.VideoEffectEnabled += VideoEffectsFeature_OnVideoEffectEnabled;
videoEffectsFeature.VideoEffectDisabled += VideoEffectsFeature_OnVideoEffectDisabled;
videoEffectsFeature.VideoEffectError += VideoEffectsFeature_OnVideoEffectError;

API の使用を開始して、ビデオ効果を有効または無効にします。

videoEffectsLocalVideoStreamFeature.EnableEffect( {{VIDEO_EFFECT_TO_ENABLE}} );
videoEffectsLocalVideoStreamFeature.DisableEffect( {{VIDEO_EFFECT_TO_DISABLE}} );

背景ぼかし

背景ぼかしのビデオ効果を有効にするには:

BackgroundBlurEffect インスタンスを MainPage に追加します。

public sealed partial class MainPage : Page
{
    private BackgroundBlurEffect backgroundBlurVideoEffect = new BackgroundBlurEffect();
}

VideoEFfects 機能を取得し、イベントをサブスクライブするメソッドを作成します。

private async void LocalVideoEffectsFeature_VideoEffectEnabled(object sender, VideoEffectEnabledEventArgs e)
{
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, async () =>
    {
        BackgroundBlur.IsChecked = true;
    });
}

private async void LocalVideoEffectsFeature_VideoEffectDisabled(object sender, VideoEffectDisabledEventArgs e)
{
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, async () =>
    {
        BackgroundBlur.IsChecked = false;
    });
}

private void LocalVideoEffectsFeature_VideoEffectError(object sender, VideoEffectErrorEventArgs e)
{
    String effectName = args.VideoEffectName;
    String errorCode = args.Code;
    String errorMessage = args.Message;

    Trace.WriteLine("VideoEffects VideoEffectError on effect " + effectName + "with code "
        + errorCode + "and error message " + errorMessage);
}

次のように背景ぼかし効果を有効または無効にします。

private async void BackgroundBlur_Click(object sender, RoutedEventArgs e)
{
    if (localVideoEffectsFeature.IsEffectSupported(backgroundBlurVideoEffect))
    {
        var backgroundBlurCheckbox = sender as CheckBox;
        if (backgroundBlurCheckbox.IsChecked.Value)
        {
            localVideoEffectsFeature.EnableEffect(backgroundBlurVideoEffect);
        }
        else
        {
            localVideoEffectsFeature.DisableEffect(backgroundBlurVideoEffect);
        }
    }
}

次のステップ

詳細については、次の記事を参照してください。

通話のヒーローサンプルを確認する
UI ライブラリを使ってみる
Calling SDK の機能について確認する
通話のしくみの詳細について確認する

クイック スタート: ビデオ通話にビデオ効果を追加する

ビデオ効果の使用

パッケージをインストールする

背景ぼかし

背景をイメージに置き換える

ビデオ効果の使用

背景ぼかし

ビデオ効果の使用

背景ぼかし

ビデオ効果の使用

背景ぼかし

次のステップ

その他のリソース

クイックスタート: ビデオ通話にビデオ効果を追加する