快速入門：將視訊效果新增至您的視訊通話

文章
08/18/2023

您可以使用影片效果功能，在視訊通話中將效果新增至您的視訊。此功能可讓開發人員在通話體驗中建置背景視覺效果和背景視訊取代。背景模糊可讓使用者在參與者後方移除干擾，讓參與者在背景中不具干擾性活動或機密資訊的情況下進行通訊。這特別適用于遠端醫療的內容，其中提供者或病患可能會想要遮蔽其周圍，以保護敏感性資訊或個人識別資訊。背景模糊可以套用到所有虛擬約會案例中，包括電話銀行和虛擬聽聽程式，以保護使用者隱私權。除了增強的機密性之外，背景模糊也允許更多運算式的創意，讓使用者上傳自訂背景來裝載更有趣的個人化通話體驗。

注意

呼叫效果程式庫無法獨立使用，而且只能在與適用于 WebJS (的 Azure 通訊通話用戶端程式庫搭配使用時使用) https://www.npmjs.com/package/@azure/communication-calling 。

使用視訊效果

安裝套件

npm install使用命令來安裝 Azure 通訊服務 Effects SDK for JavaScript。

重要

本快速入門使用Azure 通訊服務呼叫 SDK 版本的 1.13.1 (或更新) ，以及大於或等於 1.0.1 的Azure 通訊服務呼叫效果 SDK 版本。

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

如需呼叫 commmunication 效果 npm 套件頁面的詳細資訊，請參閱這裡。

注意

目前只有 Chrome 和 Edge Desktop Browser (Windows 和 Mac) 和 Mac Safari Desktop 才支援建立視訊背景效果的瀏覽器支援。

注意

目前有兩個可用的視訊效果：

背景模糊
以影像取代背景， (外觀比例應該是 16：9 才能相容)

若要搭配 Azure 通訊通話 SDK 使用視訊效果，建立之後 LocalVideoStream ，您需要取得 VideoEffects 的功能 API LocalVideoStream ，才能啟動/停止視訊效果：

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 將會失敗。

注意

目前支援的影像格式包括：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();

注意

為了在 iOS 呼叫 SDK 上使用影片效果，機器學習模型會下載至客戶的裝置。建議您檢閱應用程式中的隱私權注意事項，並視需要加以更新。

您可以使用影片效果功能，在視訊通話中將效果新增至您的視訊。背景模糊可讓使用者在參與者後方移除干擾，讓參與者在背景中不具干擾性活動或機密資訊的情況下進行通訊。這項功能特別適用于遠端醫療的內容，其中提供者或病患可能會想要遮蔽其周圍，以保護機密資訊或個人資料。背景模糊可以套用到所有虛擬約會案例中，包括電話銀行和虛擬聽聽程式，以保護使用者隱私權。

使用視訊效果

注意

iOS 上的視訊效果支援僅限於 iOS 的兩 個最新主要版本。例如，當發行新的主要 iOS 版本時，iOS 需求是新版本，以及之前的最新版本。

目前有一個可用的視訊效果：背景模糊。

物件 LocalVideoEffectsFeature 具有下列 API 結構：

enable：在實例上 LocalVideoStream 啟用視訊效果。
disable：停用實例上的 LocalVideoStream 視訊效果。
isSupported：指出實例是否支援 LocalVideoStream 視訊效果。
onVideoEffectEnabled：成功啟用視訊效果時所觸發的事件。
onVideoEffectDisabled：成功停用影片效果時所觸發的事件。
onVideoEffectError：視訊效果作業失敗時所觸發的事件。

擁有 LocalVideoEffectsFeature 物件之後，您可以訂閱事件，事件具有下列委派： didEnableVideoEffect 、、 didDisableVideoEffectdidReceiveVideoEffectError 。

若要搭配 Azure 通訊通話 SDK 使用視訊效果，建立之後 LocalVideoStream ，您必須取得 VideoEffects 的功能 API LocalVideoStream ，才能啟用/停用視訊效果：

// 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 通話 SDK 上使用影片效果，機器學習模型會下載至客戶的裝置。建議您檢閱應用程式中的隱私權注意事項，並視需要加以更新。

本快速入門是以快速入門為基礎：將 1：1 視訊通話新增至適用于 Android 的應用程式。

使用視訊效果

注意

Android 上的視訊效果支援僅限於 最後四 個主要版本的 Android。例如，當新的主要 Android 版本發行時，Android 需求是新版本，以及前面三個最新版本。

目前有一個可用的視訊效果：背景模糊。

物件 VideoEffectsLocalVideoStreamFeature 具有下列 API 結構：

enableEffect：在實例上 LocalVideoStream 啟用視訊效果。
disableEffect：停用實例上的 LocalVideoStream 視訊效果。
OnVideoEffectEnabledListener：成功啟用視訊效果時所觸發的事件。
OnVideoEffectDisabledListener：成功停用影片效果時所觸發的事件。
OnVideoEffectErrorListener：視訊效果作業失敗時所觸發的事件。

VideoEffectEnabledEvent和 VideoEffectDisabledEventVideoEffectErrorEvent 物件具有下列 API 結構：

getVideoEffectName：取得觸發事件的視訊效果名稱。

擁有 VideoEffectsLocalVideoStreamFeature 物件之後，您可以訂閱事件：

若要搭配 Azure 通訊通話 SDK 使用視訊效果，建立之後 LocalVideoStream ，您必須取得 VideoEffects 的功能 API LocalVideoStream ，才能啟用/停用視訊效果：

// 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 通話 SDK 上使用視訊效果，機器學習模型會下載至客戶的裝置。建議您檢閱應用程式中的隱私權注意事項，並視需要加以更新。

本快速入門以快速入門為基礎：將 1：1 視訊通話新增至適用于 Windows 的應用程式。

使用視訊效果

目前有一個可用的視訊效果：背景模糊。

物件 VideoEffectsLocalVideoStreamFeature 具有下列 API 結構：

EnableEffect：在實例上 LocalVideoStream 啟用視訊效果。
DisableEffect：停用實例上的 LocalVideoStream 視訊效果。
VideoEffectEnabled：成功啟用視訊效果時所觸發的事件。
VideoEffectDisabledListener：成功停用影片效果時所觸發的事件。
VideoEffectErrorListener：視訊效果作業失敗時所觸發的事件。

VideoEffectEnabledEvent和 VideoEffectDisabledEventVideoEffectErrorEvent 物件具有下列 API 結構：

VideoEffectName：取得觸發事件的視訊效果名稱。

擁有 VideoEffectsLocalVideoStreamFeature 物件之後，您可以訂閱事件：

若要搭配 Azure 通訊通話 SDK 使用視訊效果，請將變數新增至 MainPage。

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

建立 LocalVideoStream 之後，您必須取得 VideoEffects 的功能 LocalVideoStream 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}} );

背景模糊

背景模糊是一種視訊效果，可讓人員的背景模糊。若要使用背景視訊效果，您必須從有效的 LocalVideoStream 取得 VideoEffectsLocalVideoStreamFeature 功能。

若要啟用背景模糊視訊效果：

將 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);
        }
    }
}

後續步驟

如需詳細資訊，請參閱下列文章：

查看我們的通話 Hero 範例
開始使用 UI 程式庫
瞭解通話 SDK 功能
深入了解通話的運作方式

快速入門：將視訊效果新增至您的視訊通話

使用視訊效果

安裝套件

背景模糊

以影像取代背景

使用視訊效果

背景模糊

使用視訊效果

背景模糊

使用視訊效果

背景模糊

後續步驟

更多資源