实现媒体推流

本页介绍如何集成声网 Media Streaming Server SDK 并调用 API 实现服务端媒体推流。

前提条件

环境要求

请确保满足以下环境要求：

• 服务器运行环境（物理或虚拟）：
  • Ubuntu Linux 14.04+ LTS 64 位。
  • CentOS 6.5+（推荐 7.0）64 位。
• 安装编译器 gcc 4.4 或以上版本（推荐 4.8）。
• 安装 FFmpeg 组件。推荐 FFmpeg 4.2 及之后版本。声网 Media Streaming Server SDK 包内附带了静态编译的 FFmpeg 4.2，可以匹配大部分 Linux 发行版本。
• 白名单：将域名 .agora.io 和 .agoralab.co 设为白名单。
• 端口：每个频道建议使用 4 个端口。你可在加入频道时设置 lowUdpPort 和 highUdpPort 参数指定端口范围。SDK 会在指定范围内给每个频道分配端口，并避免端口冲突。如端口冲突，将无法加入频道。

参考配置

我们测试了以下云主机配置下的推流并发性能：

• AWS：Intel(R) Xeon(R) Platinum 8124M CPU @ 3.00 GHz
• 8 虚拟核 CPU，32 GB 内存
• 磁盘 I/O: 412 MB/s

测试条件：推流视频分辨率为 320 × 240 ，帧率设为 15 fps 。

并发频道数为 1224 时，测试数据如下：

• CPU 占用：68% - 70.4%
• 内存占用：16.7% - 18.4%
• CPU 平均负载：6.9 - 7.9

你可参考上述云主机配置和对应的录制性能，根据实际需要选择和配置云主机。

准备媒体文件

声网 Media Streaming Server SDK 支持推送以下类型的 MP4 文件：

• 纯音频文件。
• 音视频文件。

接收端

请确保接收端（Android、iOS、Windows 或 macOS 平台）已集成声网 RTC SDK（2.3.3 及以上版本）。

集成 SDK

1. 点击此处获取声网 Media Streaming Server SDK 包。SDK 包结构如下：

2. 通过以下步骤将 SDK 集成到你的项目中：

   1). 将 include 文件夹添加到你的项目里，并确保其加入头文件搜索目录。
   2). 将 libs 文件夹添加到你的项目里，确保库的链接和依赖关系。libmedia_streaming_server.so 是 Media Streaming Server SDK 的主库，libagora_rtc_sdk.so 为其依赖的基础库。示例如下：

   ldd libmedia_streaming_server.so 
   linux-vdso.so.1 => (0x00007ffdae3fa000)
   libagora_rtc_sdk.so => /opt/agora/ServerSDK-Video/build/proj.cmake/../../../prebuilt/lib/linux/x64_agora_sdk/libagora_rtc_sdk.so (0x00007fe5b49c5000)
   librt.so.1 => /lib/x86_64-linux-gnu/librt.so.1 (0x00007fe5b479f000)
   libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fe5b4580000)
   libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fe5b427a000)
   libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007fe5b4062000)
   libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fe5b3c98000)
   /lib64/ld-linux-x86-64.so.2 (0x000055f4c36eb000)

3. 为调试方便，建议你设置 ulimit -c unlimited，打开系统的 core dump 功能以记录可能产生的程序崩溃信息。

至此你已经集成了声网 Media Streaming Server SDK。

推流预处理

由于媒体文件容器格式和编码格式多种多样，为了更好地适配接收端的声网 RTC SDK，我们对推流的媒体文件编码格式有如下要求：

• 视频：YUV420，编码参考帧为 1，无 B 帧 的 H.264 格式。
• 音频：采样率 48 kHz，双声道，首选 Opus 编码格式，同时支持 AAC。(AAC 不支持与 web 客户端互通）

在推流之前，你需要使用转码脚本 mediaConvert，对文件进行转码处理。

打开终端，进入 samples/demo/mediaConvert 目录，运行以下命令即可实现一键转码：

./streaming_convert.sh ${INPUT} ${OUTPUT}

说明：

• INPUT 为待转码 MP4 文件的路径。
• OUTPUT 为转码后 MP4 文件的路径。

转码后文件名将变为 agora-xxx.mp4。

如果你需要对视频文件进行降噪、AI 补帧，请参阅推流预处理。

实现推流

本节介绍如何实现服务端推流。API 时序图如下：

1.创建实例

首先，调用 createAgoraMediaStreamingEngine 方法创建一个 IMediaStreamingEngine 实例。

在该方法中，你需要：

• 设置 appId 参数，传入你的 App ID。这个 App ID 与接收端的声网 RTC SDK 使用的 App ID 相同。
• 设置 eventHandler 参数。SDK 通过 IMediaStreamingEngineEventHandler 类中的回调通知事件。

示例代码如下，仅供参考：

class YourMediaStreamingEngineEventHandler : virtual public agora::mediaserver::IMediaStreamingEngineEventHandler {
    virtual void onError(int error, agora::linuxsdk::STAT_CODE_TYPE stat_code) override {
        // Handle errors here(Generally speaking, SDK can not automatically recover from it)
    };
    virtual void onWarning(int warn) override {
        // Warnings
    };

    ...

    virtual void onMediaStreamingStateChanged(const char *url, int state, int error) override {
        // Check state change during streaming
    };
    virtual void onMediaStreamingProgress(agora::linuxsdk::StreamingStateInfo stateInfo) override {
        // Check progress during streaming
    };
    virtual void onMediaStreamingStats(agora::linuxsdk::RtcChannelStats rtcStats) override {
        // Check stats of this RtcChannel
    };
}

YourMediaStreamingEngineEventHandler *m_streaming_engine_event_handler = new YourMediaStreamingEngineEventHandler();

agora::mediaserver::IMediaStreamingEngine *m_streaming_engine = agora::mediaserver::IMediaStreamingEngine::createAgoraMediaStreamingEngine(your_app_id, m_streaming_engine_event_handler);

2.加入频道

创建实例后，调用 joinChannel 方法使 IMediaStreamingEngine 实例加入接收端的声网 RTC SDK 所在的频道。

频道场景必须为直播场景。

加入频道时，你需要：

• 设置 channelKey 参数，传入能标识用户角色和权限的动态密钥，详见校验用户权限。我们建议：

  • 测试阶段，你可以在控制台里生成一个临时 Token。临时 Token 服务有效期为 24 小时。详见获取临时 Token。
  • 项目正式上线阶段，你需要在你的服务器端生成的 Token，详见生成 Token。

• 设置 channelId 参数，传入接收端的声网 RTC SDK 所在频道的名称。

• 设置 IMediaStreamingEngine 实例的 uid。该实例相当于一个特殊的用户加入频道，因此也必须有一个 uid。有以下两种设置方法:

  • 设置为 0，系统将自动分配一个 UID。
  • 设置一个唯一的 UID，不能与现在频道内的任何 UID 重复。字符串格式，只能为 0 到 9 的数字字符，如 "133122"。取值范围: 1 到 (2³²-1)。

• 设置推流具体参数 config。详见 MediaStreamingEngineConfig。

示例代码如下，仅供参考：

agora::mediaserver::MediaStreamingEngineConfig config;
config.lowUdpPort = lowUdpPort;
config.highUdpPort = highUdpPort;
config.idleLimitSec = 300;
config.channelProfile = agora::linuxsdk::CHANNEL_PROFILE_TYPE::CHANNEL_PROFILE_LIVE_BROADCASTING;

m_streaming_engine->joinChannel(token, channel, uid, config);

3.管理推流

加入频道后，先调用 openStreamingUrl 方法打开指定的推流文件。在该方法中，你需要设置 url 参数，指定待推流文件的本地路径。

目前仅支持本地 MP4 文件推流，且需要满足一定格式，详见上文推流预处理。

然后调用 startStreaming 方法开始播放推流文件。

示例代码如下，仅供参考：

m_streaming_engine->openStreamingUrl(file);

m_streaming_engine->startStreaming();

m_streaming_engine->pauseStreaming();

m_streaming_engine->resumeStreaming();

m_streaming_engine->stopStreaming();

开始推流后，你可以调用 pauseStreaming，resumeStreaming 和 stopStreaming 方法暂停推流、恢复推流和停止推流。控制推流播放状态。

调用 stopStreaming 方法停止推流后，如果要再次开始推流，需要重新调用 openStreamingUrl 和 startStreaming。

4.监听播放进度

推流过程中，你可以通过 onMediaStreamingStateChanged 和 onMediaStreamingProgress 回调监听播放进度。示意图如下：

如上图所示，开始推流时，SDK 会触发 onMediaStreamingStateChanged 回调，上报 STREAMING_CLIP_SET（开始播放当前文件）。

此后，SDK 每 1 秒触发一次 onMediaStreamingProgress 回调，报告推流进度，直至 SDK 触发 onMediaStreamingStateChanged 回调中上报 STREAMING_CLIP_EOF（当前文件播放结束）。

示例代码如下，仅供参考：

// 参照初始化部分

5.管理播放列表

推流过程中，你可以多次调用 appendStreamingUrl 方法，指定本地路径，添加一个视频文件至播放列表。最多可以添加 256 个视频文件。

当前文件播放完毕后，如果播放列表中存在待播放文件，会按照播放列表中的顺序自动播放后面的推流文件。

你也可以调用 removeStreamingUrl 方法，从播放列表中移除文件。

示例代码如下，仅供参考：

m_streaming_engine->appendStreamingUrl(file);

m_streaming_engine->removeStreamingUrl(file);

6.离开频道

调用 leaveChannel 方法离开频道。如果离开频道的时候正在推流，推流会被停止。

示例代码如下，仅供参考：

m_streaming_engine->leaveChannel();

7.释放资源

调用 release 方法销毁 IMediaStreamingEngine 实例，释放该实例所占用的资源。

示例代码如下，仅供参考：

m_streaming_engine->release();

开发注意事项

• 由于加入频道就会产生计费，因此我们建议你通过 MediaStreamingEngineConfig 的 idleLimitSec 参数设置空闲频道退出时间，从而避免由于集成问题或者其他误操作而导致的非预期的频道长时间占用。举例来说，你将 idleLimitSec 设为 600 后，如果 600 秒内 SDK 在该频道没有推送音视频数据，就会自动退出频道。注意，这段时间也会纳入计费。
• IMediaStreamingEngine 实例资源管理：
  • joinChannel 与 leaveChannel 是用于进入/退出频道的 API，createAgoraMediaStreamingEngine 与 release 是用于分配/释放资源的 API。建议成对匹配调用以避免资源无法正确释放而影响系统性能。
  • release 会释放 IMediaStreamingEngine 实例。请确保在调用 release 方法后不要再引用该实例。
• 对于信号量处理过程，可以参考命令行演示 demo 中的 Ctrl+C 示例，主动监听信号，然后调用 leaveChannel 和 release 方法释放资源。