从本地发送媒体流至 SD-RTN™

本文以发送 PCM 格式的音频流和 YUV 格式的视频流为例，介绍从声网的 SD-RTN™ 发送媒体流的基本流程以及集成过程中的注意事项。

架构图

下图分别展示了发送本地音频和视频数据的数据处理和流转过程：

音频

视频

其中：

• 箭头指代音视频流流向。蓝色方框为你需要创建的对象，虚线为可选项，黄色方框为 SDK 内置模块。
• 你可以加多个 filter，用于美颜、超分辨率算法、变声等。
• 你可以使用 IVideoSinkBase 或 IVideoRenderer 实现本地预览。IVideoRenderer 为 IVideoSinkBase 的派生类，提供默认渲染功能。如需自定义渲染，请使用 IVideoSinkBase。
• 你可以使用 SDK 内置的 Audio Device Module (ADM) 直接播放本地音频。

实现方法

API 时序图

发送原始音视频数据

发送编码后音视频数据

实现步骤

1. 全局初始化

首先，你需要在你的应用程序里调用 createAgoraService 和 initialize 进行全局初始化，创建并初始化 AgoraService 对象。

这个操作只需要进行一次，AgoraService 对象的生命期和应用程序的生命期保持一致，只要应用程序没有退出，AgoraService 可以一直存在。

auto service = createAndInitAgoraService(false, true, true);

2. 建立连接

初始化后，根据以下步骤让本地 AgoraService 对象与声网服务器建立连接。

1. 调用 createRtcConnection 创建 IRtcConnection 对象，用于与声网服务器建立连接。
2. 创建 IRtcConnectionObserver 对象（即示例代码中的 SampleConnectionObserver 对象），用于监测连接事件。然后通过 registerObserver 方法将 IRtcConnectionObserver 对象和 IRtcConnection 对象关联起来。
3. 调用 connect 与声网服务器建立连接。

// Create声网connection
  agora::rtc::RtcConnectionConfiguration ccfg;
  ccfg.autoSubscribeAudio = false;
  ccfg.autoSubscribeVideo = false;
  ccfg.clientRoleType = agora::rtc::CLIENT_ROLE_BROADCASTER;


  agora::agora_refptr<agora::rtc::IRtcConnection> connection = service->createRtcConnection(ccfg);
  if (!connection) {
    AG_LOG(ERROR, "Failed to creating声网connection!");
    return -1;
  }

  // Register connection observer to monitor connection event
  auto connObserver = std::make_shared<SampleConnectionObserver>();
  connection->registerObserver(connObserver.get());

  // Connect to声网channel
  if (connection->connect(options.appId.c_str(), options.channelId.c_str(),
                          options.userId.c_str())) {
    AG_LOG(ERROR, "Failed to connect to声网channel!");
    return -1;
  }

3. 媒体流发送准备

1. 创建 IMediaNodeFactory 对象。
2. 创建 IAudioPcmDataSender 对象和 IVideoFrameSender对象，分别用于发送 PCM 格式的音频流和 YUV 格式的视频流。
3. 创建 ILocalAudioTrack 对象和 ILocalVideoTrack 对象，分别对应即将发布至频道内的本地音频轨道和本地视频轨道。
4. 通过 ILocalUser 对象的 publish 相关方法发布上一步创建的本地音频轨道和视频轨道。

 // Create media node factory
  agora::agora_refptr<agora::rtc::IMediaNodeFactory> factory = service->createMediaNodeFactory();
  if (!factory) {
    AG_LOG(ERROR, "Failed to create media node factory!");
  }


  // Create audio data sender
  agora::agora_refptr<agora::rtc::IAudioPcmDataSender> audioPcmDataSender =
      factory->createAudioPcmDataSender();
  if (!audioPcmDataSender) {
    AG_LOG(ERROR, "Failed to create audio data sender!");
    return -1;
  }

  // Create audio track
  agora::agora_refptr<agora::rtc::ILocalAudioTrack> customAudioTrack =
      service->createCustomAudioTrack(audioPcmDataSender);
  if (!customAudioTrack) {
    AG_LOG(ERROR, "Failed to create audio track!");
    return -1;
  }

  // Create video frame sender
  agora::agora_refptr<agora::rtc::IVideoFrameSender> videoFrameSender =
      factory->createVideoFrameSender();
  if (!videoFrameSender) {
    AG_LOG(ERROR, "Failed to create video frame sender!");
    return -1;
  }

  // Create video track
  agora::agora_refptr<agora::rtc::ILocalVideoTrack> customVideoTrack =
      service->createCustomVideoTrack(videoFrameSender);
  if (!customVideoTrack) {
    AG_LOG(ERROR, "Failed to create video track!");
    return -1;
  }

  // Configure video encoder
  agora::rtc::VideoEncoderConfiguration encoderConfig(
      options.video.width, options.video.height, options.video.frameRate,
      options.video.targetBitrate, agora::rtc::ORIENTATION_MODE_ADAPTIVE);
  customVideoTrack->setVideoEncoderConfiguration(encoderConfig);

  // Publish audio & video track
  customAudioTrack->setEnabled(true);
  connection->getLocalUser()->publishAudio(customAudioTrack);
  customVideoTrack->setEnabled(true);
  connection->getLocalUser()->publishVideo(customVideoTrack);

4. 发送媒体流

一般情况下，当音频编码器和视频编码器完成一帧数据的编码后，会以回调的方式通知应用程序。你需要在提示编码完成的回调函数中添加发送媒体流的逻辑。每次收到提示编码完成的回调，都需要触发 sendAudioPcmData 和 sendEncodedVideoImage 方法的调用，分别用于发送音频帧和视频帧。换言之，你不需要单独创建一个线程用于发流，直接在编码器的输出回调里进行发流即可。

对于音频帧，调用 sendAudioPcmData 方法时，你需要传入 samplesPer10ms（每 10 毫秒的 sample 个数）、sampleSize（每个 sample 的大小）、numOfChannels 和 sampleRate 这四个参数。目前 Linux SDK 每次只能发送 10 毫秒的 PCM 数据。

// Send one PCM frame
  if (audioPcmDataSender->sendAudioPcmData(frameBuf, 0, samplesPer10ms, sampleSize,
                                           options.audio.numOfChannels,
                                           options.audio.sampleRate) < 0) {
    AG_LOG(ERROR, "Failed to send audio frame!");
  }

  // Send one YUV frame
  if (videoFrameSender->sendVideoFrame(videoFrame) < 0) {
    AG_LOG(ERROR, "Failed to send video frame!");
  }

5. 断开连接

媒体流传输完成后，你可以通过以下步骤退出频道并断开与声网服务器的连接：

1. 调用 unpublish相关方法取消发布音频流和视频流。
2. 调用 disconnect 断开与声网服务器的连接。
3. 释放 IRtcConnection 对象相关的资源。
   你必须严格按照示例代码中的顺序释放相关资源。

// Unpublish audio & video track
  connection->getLocalUser()->unpublishAudio(customAudioTrack);
  connection->getLocalUser()->unpublishVideo(customVideoTrack);


  // Unregister connection observer
  connection->unregisterObserver(connObserver.get());

  // Disconnect from声网channel
  if (connection->disconnect()) {
    AG_LOG(ERROR, "Failed to disconnect from声网channel!");
    return -1;
  }
  AG_LOG(INFO, "Disconnected from声网channel successfully");

  // Destroy声网connection and related resources
  connObserver.reset();
  audioPcmDataSender = nullptr;
  videoFrameSender = nullptr;
  customAudioTrack = nullptr;
  customVideoTrack = nullptr;
  factory = nullptr;
  connection = nullptr;

6. 全局注销

当你的应用程序退出时，可以调用如下逻辑，注销整个 AgoraService。

// Destroy声网 Service
  service->release();
  service = nullptr;

进阶功能

使用 String 型用户 ID

Linux SDK 支持使用 String 型用户 ID 加入频道。使用时，你需要注意以下限制：

• 在调用 createAndInitAgoraService 时，需要将 enableuseStringUid 设为 true。
• String 型用户 ID 能且只能与 String 型用户 ID 互通。如果一个频道内同时存在 String 型用户 ID 和 Int 型用户 ID，会导致未知的错误。
• 和 Int 型用户 ID 不同，在调用 connect 方法时，你必须给 userId 赋值。设置为 null 会收到报错。
• String 型用户 ID 必须是频道内唯一的。

具体代码可参考 sample_stringuid_send.cpp 示例项目。

发送加密后的媒体流

你可以使用 encryptionMode参数设置加密算法以及加密密钥。具体代码可参考 sample_send_encrypted_h264.cpp 示例项目。

// Set the encryption mode
  if (options.encryptionMode == true) {
    agora::rtc::EncryptionConfig Config;
    Config.encryptionMode = agora::rtc::SM4_128_ECB;
    Config.encryptionKey = options.encryptionKey.c_str();
    if (connection->enableEncryption(options.encryptionMode, Config) < 0) {
      AG_LOG(ERROR, "Failed to enable encryption!");
    }
    AG_LOG(INFO, "Enable encryption successfully");
  }

其他注意事项

• 以上所有接口函数，如无特殊说明，都是异步调用，无需担心阻塞用户线程。
• 在声网 SDK 和 Linux SDK 互通的场景中，请确保将 RTC SDK 的频道场景设置为 LIVE_BROADCASTING。
• SDK 发送 AAC 格式的音频数据时，不支持 44.1 Kbps 的采样率。

示例项目

我们在 SDK 中提供了一系列发送媒体流的示例项目，供你参考：