# 使用 IVS Web 广播 SDK 发布和订阅 \| 实时直播功能
本文档将引导您完成使用 IVS 实时直播 Web 广播 SDK 发布和订阅舞台所涉及的步骤。
## 概念
三个核心概念构成了实时功能的基础：[舞台](#web-publish-subscribe-concepts-stage)、[策略](#web-publish-subscribe-concepts-strategy)和[事件](#web-publish-subscribe-concepts-events)。设计目标是最大限度地减少构建有效产品所需的客户端逻辑量。
### 暂存区
`Stage` 类是主机应用程序和 SDK 之间交互的主要点。此类表示舞台，用于加入和退出舞台。创建和加入舞台需要控制面板上有效的未过期令牌字符串（表示为 `token`）。加入和退出舞台很简单：
```
const stage = new Stage(token, strategy)
try {
await stage.join();
} catch (error) {
// handle join exception
}
stage.leave();
```
### Strategy
`StageStrategy` 接口为主机应用程序提供了一种方法，可以将所需的舞台状态传递给 SDK。需要实现三项函数：`shouldSubscribeToParticipant`、`shouldPublishParticipant` 和 `stageStreamsToPublish`。下面将进行详述。
要使用已定义的策略，请将该策略传递给 `Stage` 构造函数。以下是应用程序的完整示例，该应用程序使用策略将参与者的网络摄像头发布到舞台并订阅所有参与者。以下部分详细说明了每个必需策略函数的用途。
```
const devices = await navigator.mediaDevices.getUserMedia({
audio: true,
video: {
width: { max: 1280 },
height: { max: 720 },
}
});
const myAudioTrack = new LocalStageStream(devices.getAudioTracks()[0]);
const myVideoTrack = new LocalStageStream(devices.getVideoTracks()[0]);
// Define the stage strategy, implementing required functions
const strategy = {
audioTrack: myAudioTrack,
videoTrack: myVideoTrack,
// optional
updateTracks(newAudioTrack, newVideoTrack) {
this.audioTrack = newAudioTrack;
this.videoTrack = newVideoTrack;
},
// required
stageStreamsToPublish() {
return [this.audioTrack, this.videoTrack];
},
// required
shouldPublishParticipant(participant) {
return true;
},
// required
shouldSubscribeToParticipant(participant) {
return SubscribeType.AUDIO_VIDEO;
}
};
// Initialize the stage and start publishing
const stage = new Stage(token, strategy);
await stage.join();
// To update later (e.g. in an onClick event handler)
strategy.updateTracks(myNewAudioTrack, myNewVideoTrack);
stage.refreshStrategy();
```
#### 订阅参与者
```
shouldSubscribeToParticipant(participant: StageParticipantInfo): SubscribeType
```
当远程参与者加入舞台，SDK 会向主机应用程序查询该参与者的所需订阅状态。选项为 `NONE`、`AUDIO_ONLY` 和 `AUDIO_VIDEO`。为该函数返回值时，主机应用程序无需担心发布状态、当前订阅状态或舞台连接状态。如果返回 `AUDIO_VIDEO`，则 SDK 会等到远程参与者发布后再订阅，并在整个过程中通过发射事件来更新主机应用程序。
以下是实施示例：
```
const strategy = {
shouldSubscribeToParticipant: (participant) => {
return SubscribeType.AUDIO_VIDEO;
}
// ... other strategy functions
}
```
完整实施此功能，适用于始终希望所有参与者都能看到对方的主机应用程序；例如，视频聊天应用程序。
也可以进行更高级的实施。例如，假设应用程序在使用 CreateParticipantToken 创建令牌时提供一个 `role` 属性。根据服务器提供的属性，该应用程序可使用 `StageParticipantInfo` 上的 `attributes` 属性有选择地订阅参与者：
```
const strategy = {
shouldSubscribeToParticipant(participant) {
switch (participant.attributes.role) {
case 'moderator':
return SubscribeType.NONE;
case 'guest':
return SubscribeType.AUDIO_VIDEO;
default:
return SubscribeType.NONE;
}
}
// . . . other strategies properties
}
```
此操作用于创建舞台，在该舞台中，监管人可以监视所有来宾，而不会被来宾看见或听见。主机应用程序可以使用其他业务逻辑，让监管人看到彼此，但对来宾不可见。
#### 订阅参与者的配置
```
subscribeConfiguration(participant: StageParticipantInfo): SubscribeConfiguration
```
如果正在订阅远程参与者（请参阅[订阅参与者](#web-publish-subscribe-concepts-strategy-participants)），则 SDK 会询问主机应用程序有关该参与者的自定义订阅配置。此配置是可选的，允许主机应用程序控制订阅用户行为的某些方面。有关可配置内容的信息，请参阅 SDK 参考文档中的 [SubscribeConfiguration](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/SubscribeConfiguration)。
以下是一个实现示例：
```
const strategy = {
subscribeConfiguration: (participant) => {
return {
jitterBuffer: {
minDelay: JitterBufferMinDelay.MEDIUM
}
}
// ... other strategy functions
}
```
此实现将所有已订阅参与者的抖动缓冲区最小延迟更新为预设的 `MEDIUM`。
与 `shouldSubscribeToParticipant` 一样，可以实现更高级的实现。给定的 `ParticipantInfo` 可用于有选择地更新特定参与者的订阅配置。
建议使用默认行为。仅在需要更改特定行为时指定自定义配置。
#### 发布
```
shouldPublishParticipant(participant: StageParticipantInfo): boolean
```
连接到舞台后，SDK 会查询主机应用程序以查看特定参与者是否应该发布。仅对有权根据提供的令牌进行发布的本地参与者调用此操作。
以下是实施示例：
```
const strategy = {
shouldPublishParticipant: (participant) => {
return true;
}
// . . . other strategies properties
}
```
适用于用户总想发布的标准视频聊天应用程序。用户可以将音频和视频静音或取消静音，以便立即隐藏或被看见/听见。（他们也可以使用发布/取消发布，但这要慢得多。对于经常需要更改可见性的使用场景，静音/取消静音更可取。）
#### 选择要发布的流
```
stageStreamsToPublish(): LocalStageStream[];
```
这项操作用于在发布时确定应发布的音频和视频流。稍后将在 [Publish a Media Stream](#web-publish-subscribe-publish-stream) 中对此进行更详细的介绍。
#### 更新策略
此策略是动态的：可以随时更改从上述任何函数返回的值。例如，如果主机应用程序希望最终用户点击按钮之前不要发布，则可以从 `shouldPublishParticipant`（类似于 `hasUserTappedPublishButton`）返回一个变量。当该变量根据最终用户的交互而发生变化时，调用 `stage.refreshStrategy()` 发送信号到 SDK，表明 SDK 应该查询策略以获取最新值，仅应用已更改的内容。如果 SDK 发现 `shouldPublishParticipant` 值已更改，则会启动发布流程。如果 SDK 查询和所有函数返回的值与之前相同，则 `refreshStrategy` 调用不会修改舞台。
如果 `shouldSubscribeToParticipant` 的返回值从 `AUDIO_VIDEO` 更改为 `AUDIO_ONLY`，则如果之前存在视频流，将删除所有返回值已更改的参与者的视频流。
通常，舞台使用该策略来最有效地应用以前和当前策略之间的差异，而主机应用程序无需担心正确管理该策略所需的所有状态。因此，可以将调用 `stage.refreshStrategy()` 视为一种只需少量计算的操作，因为除非策略发生变化，否则该调用什么都不会做。
### Events
`Stage` 实例是事件发射器。使用 `stage.on()`，将舞台状态传递给主机应用程序。事件完全可以支持主机应用程序界面的更新。事件如下所示：
```
stage.on(StageEvents.STAGE_CONNECTION_STATE_CHANGED, (state) => {})
stage.on(StageEvents.STAGE_PARTICIPANT_JOINED, (participant) => {})
stage.on(StageEvents.STAGE_PARTICIPANT_LEFT, (participant) => {})
stage.on(StageEvents.STAGE_PARTICIPANT_PUBLISH_STATE_CHANGED, (participant, state) => {})
stage.on(StageEvents.STAGE_PARTICIPANT_SUBSCRIBE_STATE_CHANGED, (participant, state) => {})
stage.on(StageEvents.STAGE_PARTICIPANT_STREAMS_ADDED, (participant, streams) => {})
stage.on(StageEvents.STAGE_PARTICIPANT_STREAMS_REMOVED, (participant, streams) => {})
stage.on(StageEvents.STAGE_STREAM_ADAPTION_CHANGED, (participant, stream, isAdapting) => ())
stage.on(StageEvents.STAGE_STREAM_LAYERS_CHANGED, (participant, stream, layers) => ())
stage.on(StageEvents.STAGE_STREAM_LAYER_SELECTED, (participant, stream, layer, reason) => ())
stage.on(StageEvents.STAGE_STREAM_MUTE_CHANGED, (participant, stream) => {})
stage.on(StageEvents.STAGE_STREAM_SEI_MESSAGE_RECEIVED, (participant, stream) => {})
```
对于其中大多数事件，提供相应的 `ParticipantInfo`。
预计事件提供的信息不会影响策略的返回值。例如，调用 `STAGE_PARTICIPANT_PUBLISH_STATE_CHANGED` 时，`shouldSubscribeToParticipant` 的返回值预计不会改变。如果主机应用程序想要订阅特定参与者，则无论该参与者的发布状态如何，它都应返回所需的订阅类型。SDK 负责确保根据舞台状态在正确的时间执行策略的期望状态。
## 发布媒体流
使用上面[从设备检索 MediaStream](broadcast-web-getting-started.md#broadcast-web-retrieve-mediastream)中概述的步骤来检索本地设备（如麦克风和摄像头）。在示例中，我们使用 `MediaStream` 创建用于 SDK 发布的 `LocalStageStream` 对象列表：
```
try {
// Get stream using steps outlined in document above
const stream = await getMediaStreamFromDevice();
let streamsToPublish = stream.getTracks().map(track => {
new LocalStageStream(track)
});
// Create stage with strategy, or update existing strategy
const strategy = {
stageStreamsToPublish: () => streamsToPublish
}
}
```
## 发布屏幕共享
除了用户的网络摄像头外，应用程序通常还需要发布屏幕共享。发布屏幕共享需要为暂存区创建一个额外的令牌，专门用于发布屏幕共享的媒体。使用 `getDisplayMedia` 并将分辨率限制为最大 720p。之后的步骤类似于将相机发布到暂存区。
```
// Invoke the following lines to get the screenshare's tracks
const media = await navigator.mediaDevices.getDisplayMedia({
video: {
width: {
max: 1280,
},
height: {
max: 720,
}
}
});
const screenshare = { videoStream: new LocalStageStream(media.getVideoTracks()[0]) };
const screenshareStrategy = {
stageStreamsToPublish: () => {
return [screenshare.videoStream];
},
shouldPublishParticipant: (participant) => {
return true;
},
shouldSubscribeToParticipant: (participant) => {
return SubscribeType.AUDIO_VIDEO;
}
}
const screenshareStage = new Stage(screenshareToken, screenshareStrategy);
await screenshareStage.join();
```
## 显示并删除参与者
订阅完成后，您将通过 `STAGE_PARTICIPANT_STREAMS_ADDED` 事件接收一组 `StageStream` 对象。该活动还为您提供参与者信息，以在显示媒体流时提供帮助：
```
stage.on(StageEvents.STAGE_PARTICIPANT_STREAMS_ADDED, (participant, streams) => {
let streamsToDisplay = streams;
if (participant.isLocal) {
// Ensure to exclude local audio streams, otherwise echo will occur
streamsToDisplay = streams.filter(stream => stream.streamType === StreamType.VIDEO)
}
// Create or find video element already available in your application
const videoEl = getParticipantVideoElement(participant.id);
// Attach the participants streams
videoEl.srcObject = new MediaStream();
streamsToDisplay.forEach(stream => videoEl.srcObject.addTrack(stream.mediaStreamTrack));
})
```
当参与者停止发布或取消订阅流时，将使用已删除的流来调用 `STAGE_PARTICIPANT_STREAMS_REMOVED` 函数。主机应用程序应将其用作信号，从 DOM 中删除参与者的视频流。
在所有可能删除流的场景中都会调用 `STAGE_PARTICIPANT_STREAMS_REMOVED`，包括：
+ 远程参与者停止发布。
+ 本地设备取消订阅或将订阅从 `AUDIO_VIDEO` 更改为 `AUDIO_ONLY`。
+ 远程参与者退出舞台。
+ 本地参与者退出舞台。
由于在所有场景中都会调用 `STAGE_PARTICIPANT_STREAMS_REMOVED`，因此在远程或本地退出操作期间，从用户界面中删除参与者无需自定义业务逻辑。
## 静音和取消静音媒体流
`LocalStageStream` 对象具有控制流是否静音的 `setMuted` 函数。可以在 `stageStreamsToPublish` 策略函数返回之前或之后在流上调用此函数。
**重要提示**：如果在调用 `refreshStrategy` 后 `stageStreamsToPublish` 返回了新的 `LocalStageStream` 对象实例，将对舞台应用新流对象的静音状态。创建新 `LocalStageStream` 实例时要小心，务必保持预期的静音状态。
## 监控远程参与者媒体静音状态
当参与者更改其视频或音频的静音状态时，已更改的流列表会触发 `STAGE_STREAM_MUTE_CHANGED` 事件。使用 `StageStream` 上的 `isMuted` 属性相应地更新您的用户界面：
```
stage.on(StageEvents.STAGE_STREAM_MUTE_CHANGED, (participant, stream) => {
if (stream.streamType === 'video' && stream.isMuted) {
// handle UI changes for video track getting muted
}
})
```
此外，您可以查看 [StageParticipantInfo](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference#stageparticipantinfo)，了解有关处于静音状态的是音频还是视频是静音的状态信息：
```
stage.on(StageEvents.STAGE_STREAM_MUTE_CHANGED, (participant, stream) => {
if (participant.videoStopped || participant.audioMuted) {
// handle UI changes for either video or audio
}
})
```
## 获取 WebRTC 统计信息
使用 `requestQualityStats()` 方法可以访问本地和远程流的详细 WebRTC 统计数据。该方法适用于 LocalStageStream 和 RemoteSageStream 对象。它将返回全面的质量指标，包括网络质量、数据包统计数据、比特率信息和帧相关指标。
这是一种异步方法，您可以使用该方法通过 await 或链接承诺来检索统计信息。当统计数据不可用时，则会返回 `undefined`；例如，流未处于活动状态或内部统计数据不可用。如果统计数据可用，该方法将返回 [LocalVideoStats](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/LocalVideoStats)、[LocalAudioStats](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/LocalAudioStats)、[RemoteVideoStats](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/RemoteVideoStats) 或 [RemoteAudioStats](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/interfaces/RemoteAudioStats) 对象，具体取决于流类型（远程、本地、视频还是音频）。
请注意，对于联播视频流，该阵列会包含多个统计对象（每层一个）。
**最佳实践**
+ 轮询频率：以合理的间隔时间（1-5 秒）调用 `requestQualityStats()` 以免影响性能
+ 错误处理：始终在处理之前检查返回的值是否为 `undefined`
+ 内存管理：不再需要流时清除间隔时间/超时
+ 网络质量：针对网络导致的性能下降问题，使用 `networkQuality` 收集用户反馈。有关详细信息，请参阅[网络质量](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference/enumerations/NetworkQuality)。
**示例用法**
```
// For local streams
const localStats = await localVideoStream.requestQualityStats();
const audioStats = await localAudioStream.requestQualityStats();
// For remote streams
const remoteVideoStats = await remoteVideoStream.requestQualityStats();
const remoteAudioStats = await remoteAudioStream.requestQualityStats();
// Example: Monitor stats every 10 seconds
const statsInterval = setInterval(async () => {
const stats = await localVideoStream.requestQualityStats();
if (stats) {
// Note: If simulcast is enabled, you may receive multiple
// stats records for each layer
stats.forEach(layer => {
const rid = layer.rid || 'default';
console.log(`Layer ${rid}:`, {
active: layer.active,
networkQuality: layer.networkQuality,
packetsSent: layer.packetsSent,
bytesSent: layer.bytesSent,
resolution: `${layer.frameWidth}x${layer.frameHeight}`,
fps: layer.framesPerSecond
});
});
}
}, 10000);
```
## 优化媒体
为了获得最佳性能，建议对 `getUserMedia` 和 `getDisplayMedia` 调用采取以下限制：
```
const CONSTRAINTS = {
video: {
width: { ideal: 1280 }, // Note: flip width and height values if portrait is desired
height: { ideal: 720 },
framerate: { ideal: 30 },
},
};
```
您可以通过传递给 `LocalStageStream` 构造函数的附加选项进一步约束媒体：
```
const localStreamOptions = {
minBitrate?: number;
maxBitrate?: number;
maxFramerate?: number;
simulcast: {
enabled: boolean
}
}
const localStream = new LocalStageStream(track, localStreamOptions)
```
在以上代码中：
+ `minBitrate` 设置浏览器应使用的最小比特率。但是，低复杂度的视频流可能会导致编码器低于此比特率。
+ `maxBitrate` 设置浏览器不应超过的此流的最大比特率。
+ `maxFramerate` 设置浏览器不应超过的此流的最大帧率。
+ `simulcast` 选项仅在基于 Chromium 的浏览器上可用。它允许发送流的三个渲染层。
+ 这允许服务器根据网络限制选择发送给其他参与者的版本。
+ `simulcast` 与 `maxBitrate` 和/或 `maxFramerate` 值一起指定时，预计会根据这些值配置最高渲染层，前提是 `maxBitrate` 不低于内部 SDK 第二最高层 900 kbps 的默认 `maxBitrate` 值。
+ 如果与第二最高层的默认值相比，`maxBitrate` 被定过低，将禁用 `simulcast`。
+ 如果不通过让 `shouldPublishParticipant` 返回 `false`、调用 `refreshStrategy`、让 `shouldPublishParticipant` 返回 `true` 并再次调用 `refreshStrategy` 的组合操作来重新发布媒体，则无法打开和关闭 `simulcast`。
## 获取参与者属性
如果您在 `CreateParticipantToken` 操作请求中指定属性，则可以在 `StageParticipantInfo` 属性中看到这些属性：
```
stage.on(StageEvents.STAGE_PARTICIPANT_JOINED, (participant) => {
console.log(`Participant ${participant.id} info:`, participant.attributes);
})
```
## 获取补充增强信息（SEI）
补充增强信息（SEI）NAL 单元用于在视频旁存储帧对齐的元数据。它可以在发布和订阅 H.264 视频流时使用。无法保证 SEI 有效载荷一定会到达订阅者手中，尤其是在网络条件不佳的情况下。由于 SEI 有效载荷直接在 H.264 帧结构中存储数据，因此这一功能无法用于纯音频流。
### 插入 SEI 有效载荷
发布客户端可以通过将其视频的 LocalStageStream 配置为启用 `inBandMessaging` 并随后调用 `insertSeiMessage` 方法来将 SEI 有效载荷插入正在发布的 Stage 流。请注意，启用 `inBandMessaging` 会增加 SDK 内存使用量。
有效载荷必须为 [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) 类型。有效载荷的大小必须大于 0 KB 且小于 1KB。每秒插入的 SEI 消息数量不得超过每秒 10KB。
```
const config = {
inBandMessaging: { enabled: true }
};
const vidStream = new LocalStageStream(videoTrack, config);
const payload = new TextEncoder().encode('hello world').buffer;
vidStream.insertSeiMessage(payload);
```
#### 重复 SEI 有效载荷
可选择提供一个 `repeatCount`，以便在接下来发送的 N 个帧中重复插入 SEI 有效载荷。这将有助于减少因用于发送视频的底层 UDP 传输协议而可能造成的固有损耗。请注意，该值必须在 0 到 30 之间。接收客户端必须有删除重复消息的逻辑。
```
vidStream.insertSeiMessage(payload, { repeatCount: 5 }); // Optional config, repeatCount must be between 0 and 30
```
### 读取 SEI 有效载荷
通过将订阅用户 `SubscribeConfiguration` 配置为启用 `inBandMessaging` 并侦听 `StageEvents.STAGE_STREAM_SEI_MESSAGE_RECEIVED` 事件，订阅客户端可以从发布 H.264 视频的发布者（如果存在）那里读取 SEI 有效载荷，如以下示例所示：
```
const strategy = {
subscribeConfiguration: (participant) => {
return {
inBandMessaging: {
enabled: true
}
}
}
// ... other strategy functions
}
stage.on(StageEvents.STAGE_STREAM_SEI_MESSAGE_RECEIVED, (participant, seiMessage) => {
console.log(seiMessage.payload, seiMessage.uuid);
});
```
## 联播分层编码
“联播分层编码”是一项 IVS 实时流媒体功能，允许发布者发送多个不同质量的视频层，也允许订阅用户动态或手动更改这些层。[直播优化](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/real-time-streaming-optimization.html)部分会对该功能作详细介绍。
### 配置分层编码（发布者）
要以发布者身份启用“联播分层编码”，请在实例化时将以下配置添加到 `LocalStageStream`：
```
// Enable Simulcast
let cameraStream = new LocalStageStream(cameraDevice, {
simulcast: { enabled: true }
})
```
根据相机设备的输入分辨率，系统会按照“直播优化”**部分[默认层、质量和帧速率](real-time-streaming-optimization.md#real-time-streaming-optimization-default-layers)小节中的定义，对一定数量的层进行编码和发送。
此外，您还可以选择在联播配置中配置各个层：
```
import { SimulcastLayerPresets } from ‘amazon-ivs-web-broadcast’
// Enable Simulcast
let cameraStream = new LocalStageStream(cameraDevice, {
simulcast: {
enabled: true,
layers: [
SimulcastLayerPresets.DEFAULT_720,
SimulcastLayerPresets.DEFAULT_360,
SimulcastLayerPresets.DEFAULT_180,
}
})
```
或者，您可以创建最多三层的自定义层配置。如果您提供空数组或不提供任何值，则使用上面描述的默认值。层通过以下必需属性进行描述：
+ `height: number;`
+ `width: number;`
+ `maxBitrateKbps: number;`
+ `maxFramerate: number;`
从预设开始，您可以覆盖单个属性，也可以创建全新的配置：
```
import { SimulcastLayerPresets } from ‘amazon-ivs-web-broadcast’
const custom720pLayer = {
...SimulcastLayerPresets.DEFAULT_720,
maxFramerate: 15,
}
const custom360pLayer = {
maxBitrateKbps: 600,
maxFramerate: 15,
width: 640,
height: 360,
}
// Enable Simulcast
let cameraStream = new LocalStageStream(cameraDevice, {
simulcast: {
enabled: true,
layers: [
custom720pLayer,
custom360pLayer,
}
})
```
有关配置单个层时可能触发的最大值、限制和错误，请参阅 SDK 参考文档。
### 配置分层编码（订阅用户）
订阅用户无需执行任何操作来启用分层编码。如果发布者正发送联播层，则服务器默认会在各层之间动态调整，根据订阅用户的设备和网络状况选择最佳质量。
或者，要选择发布者正发送的显式层，有几个选项可用，如下所述。
### 选项 1：初始层质量偏好
使用 `subscribeConfiguration` 策略可以选择作为订阅用户要接收的初始层：
```
const strategy = {
subscribeConfiguration: (participant) => {
return {
simulcast: {
initialLayerPreference: InitialLayerPreference.LOWEST_QUALITY
}
}
}
// ... other strategy functions
}
```
默认情况下，系统总是先向订阅用户发送质量最低的层，而后慢慢增加到质量最高的层。这可以优化最终用户的带宽消耗，提供最佳的视频播放时间，从而减少网络较弱的用户的初始视频冻结。
以下选项适用于 `InitialLayerPreference`：
+ `LOWEST_QUALITY`：服务器首先会提供质量最低的视频层。这会优化带宽消耗以及媒体播放时间。质量定义为视频大小、比特率和帧速率的组合。例如，720p 视频的质量低于 1080p 视频的质量。
+ `HIGHEST_QUALITY`：服务器首先会提供质量最高的视频层。这会优化质量，也可能会增加媒体播放时间。质量定义为视频大小、比特率和帧速率的组合。例如，1080p 视频的质量优于 720p 视频的质量。
**注意：**要使初始层首选项（`initialLayerPreference` 调用）生效，必须重新订阅，因为这些更新不适用于有效订阅。
### 选项 2：首选直播层
直播开始后，您可以使用 `preferredLayerForStream ` 策略方法。这种策略方法会公开参与者和直播信息。
该策略方法可以返回以下内容：
+ 直接基于 `RemoteStageStream.getLayers` 返回内容的层对象
+ 基于 `StageStreamLayer.label` 的层对象标签字符串
+ “未定义”或 null，表示不应选择任何层，优先选择动态自适应
例如，以下策略会始终让用户选择质量最低的可用视频层：
```
const strategy = {
preferredLayerForStream: (participant, stream) => {
return stream.getLowestQualityLayer();
}
// ... other strategy functions
}
```
要重置层选择并返回动态自适应，则在策略中返回 null 或“未定义”。在本示例中，`appState` 是虚拟变量，表示可能的应用程序状态。
```
const strategy = {
preferredLayerForStream: (participant, stream) => {
if (appState.isAutoMode) {
return null;
} else {
return appState.layerChoice
}
}
// ... other strategy functions
}
```
### 选项 3：RemoteSageStream 层帮助程序
`RemoteStageStream` 有几种帮助程序，可用于做出有关层选择的决定并向最终用户显示相应的选择：
+ **层事件**：除了 `RemoteStageStream` 之外，`StageEvents` 对象本身还有传达层和联播自适应变更的事件：
+ `stream.on(RemoteStageStreamEvents.ADAPTION_CHANGED, (isAdapting) => {})`
+ `stream.on(RemoteStageStreamEvents.LAYERS_CHANGED, (layers) => {})`
+ `stream.on(RemoteStageStreamEvents.LAYER_SELECTED, (layer, reason) => {})`
+ **层方法**：`RemoteStageStream` 有几种帮助程序方法，可用于获取有关流和正在呈现之层的信息。这些方法适用于 `preferredLayerForStream ` 策略中提供的远程流，以及通过 `StageEvents.STAGE_PARTICIPANT_STREAMS_ADDED` 公开的远程流。
+ `stream.getLayers`
+ `stream.getSelectedLayer`
+ `stream.getLowestQualityLayer`
+ `stream.getHighestQualityLayer`
有关详细信息，请参阅 [SDK 参考文档](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference)中的 `RemoteStageStream` 类。出于 `LAYER_SELECTED` 原因，如果返回 `UNAVAILABLE`，则表示无法选择请求的层。尽量在其所在位置选择，通常是质量较低的层，以保持流稳定性。
## 处理网络问题
本地设备的网络连接中断时，SDK 会内部尝试重新连接，无需用户执行任何操作。在某些情况下，SDK 无法重新连接，则需要用户操作。
一般来说，可以通过 `STAGE_CONNECTION_STATE_CHANGED` 事件来处理舞台状态：
```
stage.on(StageEvents.STAGE_CONNECTION_STATE_CHANGED, (state) => {
switch (state) {
case StageConnectionState.DISCONNECTED:
// handle disconnected UI
return;
case StageConnectionState.CONNECTING:
// handle establishing connection UI
return;
case StageConnectionState.CONNECTED:
// SDK is connected to the Stage
return;
case StageConnectionState.ERRORED:
// SDK encountered an error and lost its connection to the stage. Wait for CONNECTED.
return;
}
})
```
通常，您可以忽略成功加入暂存区后遇到的错误状态，因为 SDK 将尝试在内部恢复。如果 SDK 报告 `ERRORED` 状态，并且该暂存区在很长一段时间（例如 30 秒或更长时间）内保持 `CONNECTING` 状态，则您可能已断开与网络的连接。
## 将舞台广播到 IVS 通道
要广播舞台，请创建一个单独的 `IVSBroadcastClient` 会话，然后按照上述用 SDK 进行广播的常规说明进行操作。通过 `STAGE_PARTICIPANT_STREAMS_ADDED` 公开的 `StageStream` 列表可用于检索参与者媒体流，这些媒体流可以应用于广播流的构成，如下所示：
```
// Setup client with preferred settings
const broadcastClient = getIvsBroadcastClient();
stage.on(StageEvents.STAGE_PARTICIPANT_STREAMS_ADDED, (participant, streams) => {
streams.forEach(stream => {
const inputStream = new MediaStream([stream.mediaStreamTrack]);
switch (stream.streamType) {
case StreamType.VIDEO:
broadcastClient.addVideoInputDevice(inputStream, `video-${participant.id}`, {
index: DESIRED_LAYER,
width: MAX_WIDTH,
height: MAX_HEIGHT
});
break;
case StreamType.AUDIO:
broadcastClient.addAudioInputDevice(inputStream, `audio-${participant.id}`);
break;
}
})
})
```
或者，您可以合成舞台并将其广播到 IVS 低延迟通道，以覆盖更多的观众。请参阅 IVS Low-Latency Streaming User Guide 中的 [Enabling Multiple Hosts on an Amazon IVS Stream](https://docs.aws.amazon.com//ivs/latest/LowLatencyUserGuide/multiple-hosts.html)。