你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：向视频通话添加视频效果

可以使用视频效果功能在视频通话中向视频添加效果。 此功能使开发人员能够在通话体验中生成背景视觉效果和背景视频替换。 背景模糊为用户提供了一种消除参与者身后干扰的机制，这样参与者就可以在后台进行无干扰活动或机密信息的通信。 这在远程医疗环境中特别有用，在此环境中提供商或患者可能希望模糊其周围环境以保护敏感信息或个人身份信息。 背景模糊可以应用于所有虚拟约会场景，包括网上银行和虚拟听证会，以保护用户隐私。 除了增强保密性外，背景模糊还可提供更多的表达创意，使用户可以上传自定义背景，以提供更有趣、更具个性化的通话体验。

注意

调用效果库不能单独使用，只能与用于 WebJS (https://www.npmjs.com/package/@azure/communication-calling) 的 Azure 通信通话客户端库一起使用。

使用视频效果

安装包

使用 npm install 命令安装适用于 JavaScript 的 Azure 通信服务效果 SDK。

重要

本快速入门使用版本为 1.13.1（或更高）的 Azure 通信服务通话 SDK 和版本高于或等于 1.0.1 的 Azure 通信服务通话效果 SDK。

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

有关通话通信效果 npm 包页面的更多详细信息，请参阅此处。

注意

目前，仅 Chrome 和 Edge 桌面浏览器（Windows 和 Mac）以及 Mac Safari 桌面版支持创建视频背景效果。

注意

目前有两种可用的视频效果：

• 背景模糊
• 用图像替换背景（纵横比应为 16:9 才能兼容）

若要通过 Azure 通信通话 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 方法将失败。

注意

当前支持的图像格式为：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); 
}

可以通过以下配置方法传递图像来更改此效果的图像：

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、didDisableVideoEffect、didReceiveVideoEffectError。

若要通过 Azure 通信通话 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 通话 SDK 上使用视频效果，请将机器学习模型下载到客户的设备。 我们鼓励查看应用程序中的隐私声明，并在必要时进行相应更新。

可以使用视频效果功能在视频通话中向视频添加效果。 背景模糊为用户提供了一种消除参与者身后干扰的机制，这样参与者就可以在后台进行无干扰活动或机密信息的通信。 此功能在远程医疗环境中特别有用，在此环境中提供商或患者可能希望模糊其周围环境以保护敏感信息或个人数据。 背景模糊可以应用于所有虚拟约会场景，包括网上银行和虚拟听证会，以保护用户隐私。

本快速入门是基于适用于 Android 的快速入门：在应用中添加 1:1 视频通话制作的。

使用视频效果

注意

Android 上的视频效果支持仅限于 Android 的四个最新主要版本。 例如，当发布新的 Android 主版本时，Android 要求是新版本和之前的三个最新版本。

目前有一个可用的视频效果：背景模糊。

VideoEffectsLocalVideoStreamFeature 对象具有以下 API 结构：

• enableEffect：在 LocalVideoStream 实例上启用视频效果。
• disableEffect：在 LocalVideoStream 实例上禁用视频效果。
• OnVideoEffectEnabledListener：成功启用视频效果时触发的事件。
• OnVideoEffectDisabledListener：成功禁用视频效果时触发的事件。
• OnVideoEffectErrorListener：视频效果操作失败时触发的事件。

VideoEffectEnabledEvent、VideoEffectDisabledEvent 和 VideoEffectErrorEvent 对象具有以下 API 结构：

• getVideoEffectName：获取触发事件的视频效果的名称。

获得 VideoEffectsLocalVideoStreamFeature 对象后，可以订阅事件：

若要通过 Azure 通信通话 SDK 使用视频效果，创建 LocalVideoStream 后，需要获取 LocalVideoStream 的 VideoEffects 功能 API 来启用/禁用视频效果：

// 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 上使用视频效果，请将机器学习模型下载到客户的设备。 我们鼓励查看应用程序中的隐私声明，并在必要时进行相应更新。

可以使用视频效果功能在视频通话中向视频添加效果。 背景模糊为用户提供了一种消除参与者身后干扰的机制，这样参与者就可以在后台进行无干扰活动或机密信息的通信。 此功能在远程医疗环境中特别有用，在此环境中提供商或患者可能希望模糊其周围环境以保护敏感信息或个人数据。 背景模糊可以应用于所有虚拟约会场景，包括网上银行和虚拟听证会，以保护用户隐私。

本快速入门是基于适用于 Windows 的快速入门：在应用中添加 1:1 视频通话制作的。

使用视频效果

目前有一个可用的视频效果：背景模糊。

VideoEffectsLocalVideoStreamFeature 对象具有以下 API 结构：

• EnableEffect：在 LocalVideoStream 实例上启用视频效果。
• DisableEffect：在 LocalVideoStream 实例上禁用视频效果。
• VideoEffectEnabled：成功启用视频效果时触发的事件。
• VideoEffectDisabledListener：成功禁用视频效果时触发的事件。
• VideoEffectErrorListener：视频效果操作失败时触发的事件。

VideoEffectEnabledEvent、VideoEffectDisabledEvent 和 VideoEffectErrorEvent 对象具有以下 API 结构：

• VideoEffectName：获取触发事件的视频效果的名称。

获得 VideoEffectsLocalVideoStreamFeature 对象后，可以订阅事件：

若要将视频效果与 Azure 通信呼叫 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}} );

背景模糊

背景模糊是一种视频效果，可用于模糊用户的背景。 若要使用背景视频效果，需要从有效的 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);
        }
    }
}

后续步骤

有关详细信息，请参阅以下文章：

• 查看我们的出色呼叫示例
• UI 库入门
• 了解如何调用 SDK 功能
• 了解有关呼叫工作原理的详细信息