使用 IVS Web 广播 SDK 发布和订阅 | 实时直播功能

本文档将引导您完成使用 IVS 实时直播 Web 广播 SDK 发布和订阅舞台所涉及的步骤。

概念

三个核心概念构成了实时功能的基础：舞台、策略和事件。设计目标是最大限度地减少构建有效产品所需的客户端逻辑量。

舞台

Stage 类是主机应用程序和 SDK 之间交互的主要点。此类表示舞台，用于加入和退出舞台。创建和加入舞台需要控制面板上有效的未过期令牌字符串（表示为 token）。加入和退出舞台很简单：

const stage = new Stage(token, strategy)

try {
   await stage.join();
} catch (error) {
   // handle join exception
}

stage.leave();

策略

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

如果正在订阅远程参与者（请参阅订阅参与者），则 SDK 会询问主机应用程序有关该参与者的自定义订阅配置。此配置是可选的，允许主机应用程序控制订阅用户行为的某些方面。有关可配置内容的信息，请参阅 SDK 参考文档中的 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 中对此进行更详细的介绍。

更新策略

此策略是动态的：可以随时更改从上述任何函数返回的值。例如，如果主机应用程序希望最终用户点击按钮之前不要发布，则可以从 shouldPublishParticipant（类似于 hasUserTappedPublishButton）返回一个变量。当该变量根据最终用户的交互而发生变化时，调用 stage.refreshStrategy() 发送信号到 SDK，表明 SDK 应该查询策略以获取最新值，仅应用已更改的内容。如果 SDK 发现 shouldPublishParticipant 值已更改，则会启动发布流程。如果 SDK 查询和所有函数返回的值与之前相同，则 refreshStrategy 调用不会修改舞台。

如果 shouldSubscribeToParticipant 的返回值从 AUDIO_VIDEO 更改为 AUDIO_ONLY，则如果之前存在视频流，将删除所有返回值已更改的参与者的视频流。

通常，舞台使用该策略来最有效地应用以前和当前策略之间的差异，而主机应用程序无需担心正确管理该策略所需的所有状态。因此，可以将调用 stage.refreshStrategy() 视为一种只需少量计算的操作，因为除非策略发生变化，否则该调用什么都不会做。

事件

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_MUTE_CHANGED, (participant, stream) => {})

对于其中大多数事件，提供相应的 ParticipantInfo。

预计事件提供的信息不会影响策略的返回值。例如，调用 STAGE_PARTICIPANT_PUBLISH_STATE_CHANGED 时，shouldSubscribeToParticipant 的返回值预计不会改变。如果主机应用程序想要订阅特定参与者，则无论该参与者的发布状态如何，它都应返回所需的订阅类型。SDK 负责确保根据舞台状态在正确的时间执行策略的期望状态。

发布媒体流

使用上面从设备检索 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) => {
    const 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，了解有关处于静音状态的是音频还是视频是静音的状态信息：

stage.on(StageEvents.STAGE_STREAM_MUTE_CHANGED, (participant, stream) => {
   if (participant.videoStopped || participant.audioMuted) {
       // handle UI changes for either video or audio
   }
})

获取 WebRTC 统计信息

要获取发布流或订阅流的最新 WebRTC 统计信息，请使用 StageStream 上的 getStats。这是一种异步方法，您可以使用该方法通过 await 或链接承诺来检索统计信息。您将得到 RTCStatsReport，一个包含所有标准统计信息的字典。

try {
   const stats = await stream.getStats();
} catch (error) {
   // Unable to retrieve stats
}

优化媒体

为了获得最佳性能，建议对 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);
})

处理网络问题

本地设备的网络连接中断时，SDK 会内部尝试重新连接，无需用户执行任何操作。在某些情况下，SDK 无法重新连接，则需要用户操作。

一般来说，可以通过 STAGE_CONNECTION_STATE_CHANGED 事件来处理舞台状态：

stage.on(StageEvents.STAGE_CONNECTION_STATE_CHANGED, (state) => {
   switch (state) {
      case StageConnectionState.DISCONNECTED:
         // handle disconnected UI
         break;
      case StageConnectionState.CONNECTING:
         // handle establishing connection UI
         break;
      case StageConnectionState.CONNECTED:
         // SDK is connected to the Stage
         break;
      case StageConnectionState.ERRORED:
         // SDK encountered an error and lost its connection to the stage. Wait for CONNECTED.
         break;
})

通常，您可以忽略成功加入暂存区后遇到的错误状态，因为 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。