本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 为 Amazon Chime SDK 将背景筛选器添加到您的应用程序
<a name="add-filters"></a>

添加背景筛选器的过程要遵循以下主要步骤：
+ 检查是否有支持的浏览器。
+ 使用您要使用的配置创建 `VideoFxConfig` 对象。
+ 使用配置对象创建 `VideoFxProcessor` 对象。
+ 将 `VideoFxProcessor` 对象包含在 `VideoTransformDevice`。
+ 使用 `VideoTransformDevice` 启动视频输入。

**注意**  
要完成这些步骤，您必须先执行以下操作：  
创建 `Logger`。
选择 `MediaDeviceInfo` 类视频设备。
成功加入 `MeetingSession`。

以下部分介绍如何完成流程的每个步骤。

**Topics**
+ [为 Amazon Chime SDK 在提供筛选器之前先检查是否受支持](support-check.md)
+ [为 Amazon Chime SDK 创建 VideoFxConfig 对象](create-videofxconfig.md)
+ [为 Amazon Chime SDK 创建 VideoFxProcessor 对象](create-videofxprocessor.md)
+ [为 Amazon Chime SDK 配置 VideoFxProcessor 对象](configure-videofxprocessor.md)
+ [为 Amazon Chime SDK 创建 VideoTransformDevice 对象](create-video-transform.md)
+ [为 Amazon Chime SDK 开始视频输入](start-video-input.md)
+ [为 Amazon Chime SDK 微调资源利用率](tuning.md)

# 为 Amazon Chime SDK 在提供筛选器之前先检查是否受支持
<a name="support-check"></a>

Amazon Chime SDK 提供了一种异步静态方法，用于检查受支持的浏览器并尝试下载所需资产。但是，它不检查设备性能。作为最佳实践，在提供筛选器之前，始终确保用户的浏览器和设备可以支持筛选器。

```
import {
    VideoFxProcessor
} from 'amazon-chime-sdk-js';

if (!await VideoFxProcessor.isSupported(logger)) {     
    // logger is optional for isSupported
}
```

# 为 Amazon Chime SDK 创建 VideoFxConfig 对象
<a name="create-videofxconfig"></a>

您可以在同一个对象中为 `backgroundBlur` 和 `backgroundReplacement` 定义配置。但是，不能同时为两个筛选器将 `isEnabled` 设置为 `true`。这是一个无效配置。

`VideoFxConfig` 类本身不进行验证。验证将在下一步骤中进行。

以下示例显示有效的 `VideoFxConfig`。

```
const videoFxConfig: VideoFxConfig = {
    backgroundBlur: {
        isEnabled: false,
        strength: 'medium'
    },
    backgroundReplacement: {
        isEnabled: false,
        backgroundImageURL: 'space.jpg',
        defaultColor: undefined,
    }
}
```

下表列出了您可以在 `VideoFxConfig` 对象中指定的 `VideoFxProcessor` 属性。

**背景模糊筛选器属性**


| 属性 | Type | 说明 | 
| --- | --- | --- | 
| `isEnabled` | `boolean` |  当为 `true` 时，筛选器会模糊背景。 | 
| `strength` | `string` | 确定模糊程度。有效值：`low` \$1 `medium` \$1 `high`。 | 

**背景替换筛选器属性**


| 属性 | Type | 说明 | 
| --- | --- | --- | 
| `isEnabled` | `boolean` |  当为 `true` 时，筛选器会替换背景。 | 
| `backgroundImageURL` | `string` | 背景图片的 URL。筛选器根据当前屏幕的尺寸动态调整图像大小。您可以使用诸如 `https://...` 等字符串或诸如 `data:image/jpeg;base64` 等 URL。 | 
| `defaultColor` | `string` | 十六进制颜色字符串，例如 `000000` 或 `FFFFFF`，或 `black` 或 `white` 等字符串。如果未指定图像 URL，则处理器会使用 `defaultColor` 作为背景。如果未指定 `defaultColor`，则处理器默认为黑色。 | 

# 为 Amazon Chime SDK 创建 VideoFxProcessor 对象
<a name="create-videofxprocessor"></a>

创建`VideoFxProcessor`对象时， AWS 服务器会下载运行时资源，或者浏览器缓存加载资源。如果网络或 CSP 配置阻止访问资产，则 `VideoFx.create` 操作会引发异常。结果 VideoFxProcessor 被配置为无操作处理器，这不会影响视频流。

```
let videoFxProcessor: VideoFxProcessor | undefined = undefined;
try {
  videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig);
} catch (error) {
  logger.warn(error.toString());
}
```

`VideoFxProcessor.create` 还会尝试从 `backgroundReplacement.backgroundImageURL` 中加载图像。如果图像加载失败，处理器会抛出异常。处理器还会出于其他原因抛出异常，例如配置无效、浏览器不受支持或硬件性能不足。

# 为 Amazon Chime SDK 配置 VideoFxProcessor 对象
<a name="configure-videofxprocessor"></a>

下表列出可以配置的 `VideoFxProcessor` 属性。表下方的示例显示典型的运行时系统配置。

**背景模糊**  
背景模糊具有以下属性：


| 属性 | Type | 说明 | 
| --- | --- | --- | 
| `isEnabled` | `boolean` | 当为 `true` 时，筛选器会模糊背景。 | 
| `strength` | `string` | 确定模糊程度。有效值：`low` \$1`medium` \$1`high`. | 

**背景替换**  
背景替换使用以下参数：


| 属性 | Type | 说明 | 
| --- | --- | --- | 
| `isEnabled` | `boolean` | 当为 `true` 时，筛选器会替换背景。 | 
| `backgroundImageURL` | `string` | 背景图片的 URL。筛选器根据当前屏幕的尺寸动态调整图像大小。您可以使用诸如 `https://...` 等字符串或诸如 `data:image/jpeg;base64` 等 URL。 | 
| `defaultColor` | `string` | 十六进制颜色字符串，例如 `000000` 或 `FFFFFF`，或 `black` 或 `white` 等字符串。如果未指定图像 URL，则处理器会使用 `defaultColor` 作为背景。如果未指定 `defaultColor`，则处理器默认为黑色。 | 

**运行时更改配置**  
您可以使用 `videoFxProcessor.setEffectConfig` 参数在运行时更改 `VideoFxProcessor` 配置。以下示例显示如何启用背景替换和禁用背景模糊。

**注意**  
一次只能指定一种类型的背景替换。指定 `backgroundImageURL` 或 `defaultColor` 的值，但不能同时指定两者。

```
videoFxConfig.backgroundBlur.isEnabled = false;
videoFxConfig.backgroundReplacement.isEnabled = true;
try {
  await videoFxProcessor.setEffectConfig(videoFxConfig);
} catch(error) {
  logger.error(error.toString())
}
```

如果 `setEffectConfig` 抛出异常，则之前的配置仍然有效。`setEffectConfig` 会在与导致 `VideoFxProcessor.create` 抛出异常的类似条件下抛出异常。

以下示例显示如何在视频运行时更改背景图像。

```
videoFxConfig.backgroundReplacement.backgroundImageURL = "https://my-domain.com/my-other-image.jpg";
try {
  await videoFxProcessor.setEffectConfig(videoFxConfig);
} catch(error) {
  logger.error(error.toString())
}
```

# 为 Amazon Chime SDK 创建 VideoTransformDevice 对象
<a name="create-video-transform"></a>

以下示例显示如何创建包含 `VideoFxProcessor` 的 `VideoTransformDevice` 对象。

```
// assuming that logger and videoInputDevice have already been set    
const videoTransformDevice = new DefaultVideoTransformDevice(
  logger,
  videoInputDevice,
  [videoFxProcessor]
);
```

# 为 Amazon Chime SDK 开始视频输入
<a name="start-video-input"></a>

以下示例演示如何使用 `VideoTransformDevice` 对象开始视频输入。

```
// assuming that meetingSession has already been created
await meetingSession.audioVideo.startVideoInput(videoTransformDevice);
meetingSession.audioVideo.start();
meetingSession.audioVideo.startLocalVideoTile();
```

# 为 Amazon Chime SDK 微调资源利用率
<a name="tuning"></a>

创建 `VideoFxProcessor` 时，您可以提供可选 `processingBudgetPerFrame` 参数并控制筛选器占用 CPU 和 GPU 量。

```
let videoFxProcessor: VideoFxProcessor | undefined = undefined;
const processingBudgetPerFrame = 50;
try {
  videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig, processingBudgetPerFrame);
} catch (error) {
  logger.warn(error.toString());
}
```

`VideoFxProcessor` 需要时间处理帧。时间长短取决于设备、浏览器以及浏览器或设备上正在运行的其他程序。处理器使用*预算*的概念确定处理和渲染每帧所用的时间。

处理时间以毫秒为单位。举个如何使用预算的示例，1 秒有 1000 毫秒。将每秒 15 帧的视频捕获作为目标，总预算为 1000 毫秒/15fps = 66 毫秒。通过在 `processingBudgetPerFrame` 参数中提供值 `50`，您可以将预算设置为其中的 50% 或 33ms，如上例所示。

然后 `VideoFxProcessor` 尝试在指定的预算范围内处理帧。如果处理超出预算，处理器会降低视觉质量使其保持在预算范围内。处理器继续将视觉质量降低到最低限度后，它会停止降低。这种处理持续时间是持续测量的，因此，如果有更多资源可用，例如关闭另一个应用程序并释放 CPU，处理器会再次提高视觉质量，直到达到预算或者达到最高的视觉质量。

如果您未向 `processingBudgetPerFrame` 提供值，则 `VideoFxProcessor` 默认为 `50`。