# IVS 服务器端合成 \$1 实时直播功能 服务器端合成使用 IVS 服务器混合所有舞台参与者的音频和视频，然后将此混合视频发送到 IVS 频道（例如，为了服务于更多观众）或 S3 存储桶。服务器端合成通过舞台主区域的 IVS 控制面板操作调用。 使用服务器端合成广播或录制舞台有很多好处，对于寻求高效而可靠的云端视频工作流程的用户来说，是一个有吸引力的选择。 **Topics** + [IVS 服务器端合成概述](ssc-overview.md) + [IVS 服务器端合成入门](ssc-getting-started.md) + [自定义参与者排序](ssc-getting-started-custom-participant-ordering.md) + [在 IVS 服务器端合成中启用屏幕共享](ssc-getting-started-screen-share.md) + [已知问题和解决方法](ssc-known-issues.md) # IVS 服务器端合成概述 下图演示了服务器端合成的工作原理： ![\[使用服务器端合成广播舞台。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/ssc_Intro_Composite_Recording.png) ## 优势 与客户端合成相比，服务器端合成具有以下优点： + **减少客户端负载** — 通过服务器端合成，处理和组合音频和视频源的负担从单个客户端设备转移到服务器本身。服务器端合成使客户端设备无需使用其 CPU 和网络资源来合成视图并将其传输到 IVS。这意味着观众无需自己的设备处理资源密集型任务即可观看广播，从而延长电池寿命并获得更流畅的观看体验。 + **质量稳定** — 服务器端合成允许精确控制最终流的质量、分辨率和比特率。这样可确保所有观众都能获得一致的观看体验，而与其个人设备的功能无关。 + **弹性** — 通过将合成过程集中到服务器上，广播变得更加强大。即使发布者设备遇到技术限制或波动，服务器也可以进行调整，为所有受众成员提供更流畅的流。 + **带宽效率** — 由于服务器负责合成，因此舞台发布者不必花费额外的带宽将视频广播到 IVS。 或者，要向 IVS 频道广播舞台，可以在客户端进行合成；请参阅 *IVS Low-Latency Streaming User Guide* 中的 [Enabling Multiple Hosts on an IVS Stream](https://docs.aws.amazon.com//ivs/latest/LowLatencyUserGuide/multiple-hosts.html)。 ## 合成生命周期 使用下图来了解合成的状态转换： ![\[服务器端合成资源的生命周期。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/ssc_Composition_Lifecycle.png) 概括来说，合成的生命周期如下所示： 1. 合成资源在用户调用 StartComposition 操作时创建。 1. IVS 成功开始合成之后，就会发送“IVS 合成状态更改（会话开始）”EventBridge 事件。有关事件的详细信息，请参阅[将 EventBridge 与 IVS 实时直播功能结合使用](eventbridge.md)。 1. 合成处于活动状态后，就会发生以下情况： + 用户停止合成：如果调用 StopComposition 操作，IVS 会启动合成的正常关闭，发送“目标结束”事件，然后发送“会话结束”事件。 + 合成执行自动关闭 — 如果 IVS 舞台被删除或 60 秒内没有参与者主动发布到 IVS 舞台，则合成将自动完成，并发送 EventBridge 事件。 + 目标故障 — 如果目标意外失败（例如，IVS 频道被删除），则目标将转换为 `RECONNECTING` 状态并发送“目标重新连接”事件。如果无法恢复，IVS 会将目标转换为 `FAILED` 状态并发送“目标故障”事件。如果至少有一个目标处于活动状态，IVS 会使合成保持活动状态。 1. 一旦合成处于 `STOPPED` 或 `FAILED` 状态，就会在五分钟后自动将其清除。（然后，ListCompositions 或 GetComposition 将不再对其进行检索。） ## IVS API 服务器端合成使用以下关键 API 元素： + *EncoderConfiguration* 对象允许您自定义要生成的视频的格式（高度、宽度、比特率和其他流式传输参数）。每次调用 StartComposition 操作时，都可以重复使用 EncoderConfiguration。 + *Composition* 操作跟踪视频合成并输出到 IVS 频道。 + *StorageConfiguration* 会跟踪录制合成内容的 S3 存储桶。 要使用服务器端合成，您需要创建一个 EncoderConfiguration 并在调用 StartComposition 操作时将其附上。在此示例中，SquareVideo EncoderConfiguration 用于两个合成： ![\[服务器端合成使用两个关键 API 元素。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/ssc_IVS_API_Composite_Recording.png) 如需完整信息，请参阅 [IVS Real-Time Streaming API Reference](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/Welcome.html)。 ## Layouts StartComposition 操作提供两个布局选项：网格和 pip（画中画）。 ### 网格布局 网格布局在由大小相等的槽位组成的网格中排列暂存区参与者。它提供了几个可自定义的属性： + `videoAspectRatio` 设置参与者显示模式以控制视频磁贴的宽高比。 + `videoFillMode` 定义视频内容如何适应参与者磁贴。 + `gridGap` 指定参与者磁贴之间的间距（以像素为单位）。 + `omitStoppedVideo` 允许从合成中排除已停止的视频流。 + `featuredParticipantAttribute` 标识精选槽位。设置此选项后，精选参与者在主屏幕上较大的槽位中显示，其他参与者在其下方显示。 + `participantOrderAttribute` 可基于参与者令牌中的属性值实现自定义参与者排序。指定此参数后，系统将按参与者属性值的数值大小对其进行排序，缺少该属性的参与者将重新按到达时间排序。这提供了可选的确定性定位功能，可实现基于角色的布局。 有关网格布局的详细信息（包括所有字段的有效值和默认值），请参阅 [GridConfiguration](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_GridConfiguration.html) 数据类型。 ![\[服务器端合成网格布局\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/ssc_Grid_Layout.png) ### 画中画（PiP）布局 PiP 布局允许在大小、位置和行为均可配置的叠加窗口中显示参与者。关键属性包括： + `pipParticipantAttribute` 指定 PiP 窗口的参与者。 + `pipPosition` 确定 PiP 窗口的角落位置。 + `pipWidth` 和 `pipHeight` 配置 PiP 窗口的宽度和高度。 + `pipOffset` 设置 PiP 窗口距离最近边缘的偏移位置（以像素为单位）。 + `pipBehavior` 定义所有其他参与者都离开时的 PiP 行为。 与网格布局类似，PiP 布局支持 `featuredParticipantAttribute`、`omitStoppedVideo`、`videoFillMode`、`gridGap` 和 `participantOrderAttribute`，可用来进一步自定义合成。`participantOrderAttribute` 支持为 PiP 窗口选中参与者，并同时根据参与者令牌中的属性值对参与者进行网格定位，从而实现自定义的参与者排序。 有关 PiP 布局的详细信息（包括所有字段的有效值和默认值），请参阅 [PipConfiguration](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_PipConfiguration.html) 数据类型。 ![\[服务器端合成画中画（PiP）布局\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/ssc_PiP_Layout.png) **注意**：舞台发布者在服务器端合成中支持的最大分辨率为 1080p。如果发布者发送的视频高于 1080p，则发布者将呈现为纯音频参与者。 **重要提示**：确保您的应用程序不依赖于当前布局的特定功能，例如磁贴的大小和位置。*可以随时对布局进行视觉改进*。 # IVS 服务器端合成入门 本文档将引导您完成 IVS 服务器端合成入门所涉及的步骤。 ## 先决条件 要使用服务器端合成，您必须有一个包含活跃发布者的舞台，并使用 IVS 频道和/或 S3 存储桶作为合成目标。 要创建 S3 存储桶，请参阅有关[如何创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)的 S3 文档。必须在与 IVS 暂存区相同的 AWS 区域中创建 S3 存储桶。 **重要**：如果使用现有 S3 存储桶： + **对象所有权**设置必须为**强制存储桶拥有者**或**首选存储桶拥有者**。 + **默认加密**设置必须是**具有 Amazon S3 托管密钥的服务器端加密 (SSE-S3)**。 有关详细信息，请参阅有关[控制对象所有权](https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html)和[使用加密保护数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingEncryption.html)的 S3 文档。 ## API 说明 下面，我们将介绍一种可能的工作流程，它使用 EventBridge 事件来开始合成，当参与者发布时，该合成将舞台广播到 IVS 频道。或者，您可以根据自己的应用程序逻辑开始和停止合成。请参阅[合成录制](rt-composite-recording.md)以获得另一个示例，它展示了如何使用服务器端合成将舞台直接录制到 S3 存储桶。 1. 创建 IVS 频道。请参阅 [Amazon IVS 低延迟直播功能入门](https://docs.aws.amazon.com//ivs/latest/LowLatencyUserGuide/getting-started.html)。 1. 为每个发布者创建 IVS 舞台和参与者令牌。 1. 创建 [EncoderConfiguration](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_EncoderConfiguration.html)。 1. 加入舞台并发布到该舞台。（请参阅实时流式广播 SDK 指南的“发布和订阅”部分：[Web](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/web-publish-subscribe.html)、[Android](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/android-publish-subscribe.html) 和 [iOS](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/ios-publish-subscribe.html)。） 1. 当您收到参与者发布的 EventBridge 事件时，使用所需的布局配置调用 [StartComposition](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_StartComposition.html)。 1. 等待几秒钟，然后在频道回放中观看合成视图。 ![\[服务器端合成工作流程，在参与者发布时使用 EventBridge 事件开始合成。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/ssc_Workflow.png) **注意**：发布者参与者在舞台上处于非活动状态 60 秒后，合成执行自动关闭。此时，合成终止，并转换到 `STOPPED` 状态。合成处于 `STOPPED` 状态几分钟后将自动删除。 ## CLI 说明 使用 Amazon CLI 是一个高级选项，需要先在计算机上下载并配置 CLI。有关详细信息，请参阅 [Amazon 命令行界面用户指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)。 现在，您可以使用 CLI 创建和管理资源。合成操作位于 `ivs-realtime` 命名空间下。 ### 创建 EncoderConfiguration 资源 EncoderConfiguration 是一个对象，允许您自定义生成的视频的格式（高度、宽度、比特率和其他流式传输参数）。每次调用合成操作时，您都可以重复使用 EncoderConfiguration，如下一步中所述。 下面的命令创建 EncoderConfiguration 资源，用于配置服务器端视频合成参数，例如视频比特率、帧速率和分辨率： ``` aws ivs-realtime create-encoder-configuration --name "MyEncoderConfig" --video "bitrate=2500000,height=720,width=1280,framerate=30" ``` 响应如下： ``` { "encoderConfiguration": { "arn": "arn:aws:ivs:us-east-1:927810967299:encoder-configuration/9W59OBY2M8s4", "name": "MyEncoderConfig", "tags": {}, "video": { "bitrate": 2500000, "framerate": 30, "height": 720, "width": 1280 } } } ``` ### 开始合成 使用上面响应中提供的 EncoderConfiguration ARN，创建您的合成资源： **网格布局示例** ``` aws ivs-realtime start-composition --stage-arn "arn:aws:ivs:us-east-1:927810967299:stage/8faHz1SQp0ik" --destinations '[{"channel": {"channelArn": "arn:aws:ivs:us-east-1:927810967299:channel/DOlMW4dfMR8r", "encoderConfigurationArn": "arn:aws:ivs:us-east-1:927810967299:encoder-configuration/9W59OBY2M8s4"}}]' --layout '{"grid":{"participantOrderAttribute":"order","featuredParticipantAttribute":"isFeatured","videoFillMode":"COVER","gridGap":0}}' ``` **PiP 布局示例** ``` aws ivs-realtime start-composition --stage-arn "arn:aws:ivs:us-east-1:927810967299:stage/8faHz1SQp0ik" --destinations '[{"channel": {"channelArn": "arn:aws:ivs:us-east-1:927810967299:channel/DOlMW4dfMR8r", "encoderConfigurationArn": "arn:aws:ivs:us-east-1:927810967299:encoder-configuration/DEkQHWPVaOwO"}}]' --layout '{"pip":{"participantOrderAttribute":"priority","pipParticipantAttribute":"isPip","pipOffset":10,"pipPosition":"TOP_RIGHT"}}' ``` **注意**：您可以使用[此工具](https://composition.ivsdemos.com/)更轻松地根据您选择的布局生成 `--layout` 配置。 响应将显示该合成使用 `STARTING` 状态创建。一旦合成开始发布合成，状态就会转换为 `ACTIVE`。（您可以通过调用 ListCompositions 或 GetComposition 操作来查看状态。） 合成处于 `ACTIVE` 后，可以使用 ListCompositions 在 IVS 频道上看到 IVS 舞台的合成视图： ``` aws ivs-realtime list-compositions ``` 响应如下： ``` { "compositions": [ { "arn": "arn:aws:ivs:us-east-1:927810967299:composition/YVoaXkKdEdRP", "destinations": [ { "id": "bD9rRoN91fHU", "startTime": "2023-09-21T15:38:39+00:00", "state": "ACTIVE" } ], "stageArn": "arn:aws:ivs:us-east-1:927810967299:stage/8faHz1SQp0ik", "startTime": "2023-09-21T15:38:37+00:00", "state": "ACTIVE", "tags": {} } ] } ``` **注意**：您需要让发布者参与者主动发布到舞台上，以使合成保持活动状态。有关更多信息，请参阅实时流式广播 SDK 指南的“发布和订阅”部分：[Web](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/web-publish-subscribe.html)、[Android](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/android-publish-subscribe.html) 和 [iOS](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/ios-publish-subscribe.html)。您必须为每位参与者创建不同的舞台令牌。 # 自定义参与者排序 借助自定义参与者排序功能，您可以根据参与者令牌中的自定义属性值控制参与者在网格和 PiP 布局中的定位，包括特写参与者的定位和 PiP 窗口中的参与者选择。这提供了确定性定位功能，可实现基于角色的布局。 ## 自定义排序的工作原理 在布局配置中指定 `participantOrderAttribute` 后，系统将根据以下规则对参与者进行排序： + 令牌中包含指定排序属性的参与者排在最前，按其属性值的数值大小进行排序。 + 缺少排序属性的参与者将重新按到达时间排序，并排在已排序的参与者之后。 + 如有多个参与者的排序值相同，则按其进入舞台的时间再次排序。 + 排序按数值大小（不是字典顺序）进行，因此“10”排在“9”之后，而不是在“1”之后。 + 支持负值。负值应排于正值之前。 + 非整数值（例如“abc”、“1.5”）将视为无效，这些参与者会重新按到达时间排序。 **重要提示：**参与者排序（无论是基于到达时间还是自定义）将在合成开始后生效。对于在合成开始之前进入舞台的参与者，无法保证参与者的正确排序。 ## 创建具有排序属性的令牌 要使用自定义参与者排序功能，请在创建参与者令牌时将排序属性包含在其中： ``` aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=1 aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=2 aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=3 ``` 您可以将自定义参与者排序属性与用于为精选槽位和 PiP 窗口选择参与者的属性相结合： ``` aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=2,isFeatured=true aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=3,isFeatured=true aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=4,isPip=true ``` ## 使用案例示例 示例使用案例包括： + 一致的定位：参与者使用相同的令牌重新连接时会保持原来的位置。 + 基于角色的定位：例如，您可以指定教师的顺序为 1，学生的顺序为 2。 + 基于优先级的布局：顺序值较低的 VIP 参与者将首先出现。 + 动态布局：您可以将自定义排序与 `featuredParticipantAttribute` 和 `pipParticipantAttribute` 组合使用，以满足复杂场景的需要。 + 跨舞台互动：在 VS 模式竞赛等场景中使用参与者复制功能时，来自不同舞台的主播将进行互动，您可以通过覆盖排序属性来控制目标舞台合成中的定位。 **注意：**对于参与者复制使用案例，您可以在开始复制时根据需要覆盖参与者属性（包括排序属性），以在目标舞台中实现所需的布局。 ## 向后兼容 自定义参与者排序是一项可选功能，并且完全向后兼容。没有 `participantOrderAttribute` 属性的现有合成会继续正常运行，按到达时间排序。将 `participantOrderAttribute` 设置为空字符串时，系统将完全忽略自定义排序并回退到默认行为。 # 在 IVS 服务器端合成中启用屏幕共享 要使用固定的屏幕共享布局，请执行以下步骤。 ## 创建 EncoderConfiguration 资源 下面的命令创建 EncoderConfiguration 资源，用于配置服务器端合成参数（视频比特率、帧速率和分辨率）。 ``` aws ivs-realtime create-encoder-configuration --name "test-ssc-with-screen-share" --video={bitrate=2000000,framerate=30,height=720,width=1280} ``` 使用 `screen-share` 属性创建舞台参与者令牌。由于我们将指定 `screen-share` 作为 `featured` 槽位的名称，因此我们需要创建一个 `screen-share` 属性设置为 `true` 的舞台令牌： ``` aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes screen-share=true ``` 响应如下： ``` { "participantToken": { "attributes": { "screen-share": "true" }, "expirationTime": "2023-08-04T05:26:11+00:00", "participantId": "E813MFklPWLF", "token": "eyJhbGciOiJLTVMiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2OTExMjY3NzEsImlhdCI6MTY5MTA4MzU3MSwianRpIjoiRTgxM01Ga2xQV0xGIiwicmVzb3VyY2UiOiJhcm46YXdzOml2czp1cy1lYXN0LTE6OTI3ODEwOTY3Mjk5OnN0YWdlL3U5T2lFMjliVDdYcCIsInRvcGljIjoidTlPaUUyOWJUN1hwIiwiZXZlbnRzX3VybCI6IndzczovL3VzLWVhc3QtMS5ldmVudHMubGl2ZS12aWRlby5uZXQiLCJ3aGlwX3VybCI6Imh0dHBzOi8vYjJlYTVjMmZmMzU1Lmdsb2JhbC53aGlwLmxpdmUtdmlkZW8ubmV0IiwiYXR0cmlidXRlcyI6eyJzY3JlZW4tc2hhcmUiOiJ0cnVlIn0sImNhcGFiaWxpdGllcyI6eyJhbGxvd19wdWJsaXNoIjp0cnVlLCJhbGxvd19zdWJzY3JpYmUiOnRydWV9LCJ2ZXJzaW9uIjoiMC4zIn0.MGUCMFvMzv35O4yVzM9tIWZl7n3mmFQhleqsRSBx_G2qT2YUDlWSNg6H1vL7sAWQMeydSAIxAIvdfqt3Fh1MLiyelc9NnTjI5hL3YPKqDX6J3NDH1fksh8_5y1jztoPDy4yVA5OmtA" } } ``` ## 开始合成 要使用屏幕共享功能开始合成，我们使用以下命令： ``` aws ivs-realtime start-composition --stage-arn "arn:aws:ivs:us-east-1:927810967299:stage/8faHz1SQp0ik" --destinations '[{"channel": {"channelArn": "arn:aws:ivs:us-east-1:927810967299:channel/DOlMW4dfMR8r", "encoderConfigurationArn": "arn:aws:ivs:us-east-1:927810967299:encoder-configuration/DEkQHWPVaOwO"}}]' --layout '{"grid":{"featuredParticipantAttribute":"screen-share"}}' ``` 响应如下： ``` { "composition" : { "arn" : "arn:aws:ivs:us-east-1:927810967299:composition/B19tQcXRgtoz", "destinations" : [ { "configuration" : { "channel" : { "channelArn" : "arn:aws:ivs:us-east-1:927810967299:channel/DOlMW4dfMR8r", "encoderConfigurationArn" : "arn:aws:ivs:us-east-1:927810967299:encoder-configuration/DEkQHWPVaOwO" }, "name" : "" }, "id" : "SGmgBXTULuXv", "state" : "STARTING" } ], "layout" : { "grid" : { "featuredParticipantAttribute" : "screen-share", "gridGap": 2, "omitStoppedVideo": false, "videoAspectRatio": "VIDEO" } }, "stageArn" : "arn:aws:ivs:us-east-1:927810967299:stage/8faHz1SQp0ik", "startTime" : "2023-09-27T21:32:38Z", "state" : "STARTING", "tags" : { } } } ``` 当舞台参与者 `E813MFklPWLF` 加入舞台时，该参与者的视频将显示在精选槽位中，所有其他舞台发布者将在呈现在该槽位下方： ![\[使用屏幕共享功能开始合成。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/ssc_StartComposition.png) ## 停止合成 要随时停止合成，请调用 StopComposition 操作： ``` aws ivs-realtime stop-composition --arn arn:aws:ivs:us-east-1:927810967299:composition/B19tQcXRgtoz ``` # 已知问题和解决方法 此部分列出了使用 IVS 服务器端合成时可能遇到的已知问题，并提出了可能的解决方法。 + 有些合成在静音一段时间后可能会出现短暂的音频卡顿。 **解决办法：**尚无。