音频外部采集与渲染

---

1 使用场景

1.1 外部采集

以下情况时，建议使用音频外部采集功能：

1. 客户需要从现有音频流、音频文件、或者定制的采集系统中获得采集后输入，交给 SDK 传输。
2. 客户有自己对 PCM 输入源做特殊的音效处理的需求，在音效处理后输入，交给 SDK 传输。

1.2 外部渲染

当客户有自己渲染的需求，例如对拉取到的原始 PCM 数据做特殊应用或者处理后再渲染，建议使用 SDK 的音频外部渲染功能。

2 相关接口

音频外部采集和渲染的相关接口都位于 zego-api-external-audio-device.h 文件中，如下所示：

zego-api-external-audio-device.h

    /**
     推流通道音频采集源类别
     */
    typedef enum ZegoExternalAudioDeviceSourceType
    {
        kZegoExternalAudioDeviceSourceTypeNone                     = -1,   /**< 关闭外部音源 */
        kZegoExternalAudioDeviceSourceTypeSameAsMainPublishChannel = 0,    /**< 和主推流通道一样 */
        kZegoExternalAudioDeviceSourceTypeExternalCapture          = 1,    /**< 使用外部采集 */
        kZegoExternalAudioDeviceSourceTypePlayer                   = 2,    /**< 使用媒体播放器的音源 */
    } ZegoAudioDeviceSrcType;

    /**
     设置推流通道的音源

     @param publish_channel_index 选定推流通道
     @param source_type 音频来源, 详见 ZegoExternalAudioDeviceSourceType 定义
     @return 详见 enum ZegoErrorCode
     @note 必须在开启预览或者启动推流/拉流 前调用才有效
     @note 开发者采用外部采集和渲染后，SDK 内部不负责声音增强、噪音抑制、回音消除等功能，需要用户自己实现
     @note 当 publish_channel_index = 0 时表示主通道, 只支持外部采集方式
     @note 当 publish_channel_index = 1 时表示辅助通道, 支持三种音源模式, 和主推流通道一样, 使用外部采集, 使用媒体播放器的音源
     @note 当 publish_channel_index > 1 时, 当前只支持外部采集方式
     @note 当 source_type 选择 kZegoExternalAudioDeviceSourceTypeNone 时表示关闭外部音源, 主通道使用内部采集音源, 其他通道无音源
     */
    ZEGOAVKIT_API int zego_external_audio_device_set_audio_source(int publish_channel_index, ZegoExternalAudioDeviceSourceType source_type);

    /**
     开始外部音频采集（通知 SDK）

     @param publish_channel_index 选定推流通道
     @return 详见 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_external_audio_device_start_capture(int publish_channel_index);

    /**
     结束外部音频采集（通知 SDK）

     @param publish_channel_index 选定推流通道
     @return 详见 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_external_audio_device_stop_capture(int publish_channel_index);

    /**
     把采集到的音频数据(AAC 或者 PCM） 塞给 SDK。

     @param publish_channel_index 选定推流通道
     @param audio_frame 采集到的音频帧
     @return 详见 enum ZegoErrorCode
     @note 必须在启动推流以后，且已经调用了 zego_external_audio_device_start_capture API，此接口调用才有效
     @note 必须在反初始化 SDK 之前停止调用
     */
    ZEGOAVKIT_API int zego_external_audio_device_on_record_audio_frame(int publish_channel_index, struct ZegoAudioFrame* audio_frame);

    /**
     开始外部音频播放（通知 SDK）

     @return 详见 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_external_audio_device_start_render();

    /**
     结束外部音频播放（通知 SDK）

     @return 详见 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_external_audio_device_stop_render();

    /**
     从 SDK 取音频渲染数据(PCM)

     @param audio_frame 得到的音频数据
     @return 详见 enum ZegoErrorCode
     @note 必须在启动拉流以后，且已经调用了 zego_external_audio_device_start_render API，此接口调用才有效
     @note 必须在反初始化 SDK 之前停止调用
     */
    ZEGOAVKIT_API int zego_external_audio_device_on_playback_audio_frame(struct ZegoAudioFrame* audio_frame);

其中，ZegoAudioFrame 表示音频帧，具体使用方式为：

zego-api-audio-frame.h

    /** 音频帧类型 */
    typedef enum ZegoAudioFrameType
    {
        kZegoAudioFrameTypePCM          = 0x1001,   /** PCM 数据 */
        kZegoAudioFrameTypeAACStream    = 0x1003,   /** AAC 编码数据流 */
    } ZegoAudioFrameType;

    /** 音频帧结构 */
    struct ZegoAudioFrame;

    /**
     创建音频帧对象

     @return 返回创建的对象，使用完毕后必须调用 zego_audio_frame_destroy() 接口释放
     */
    ZEGOAVKIT_API struct ZegoAudioFrame* zego_audio_frame_create();

    /**
     释放音频帧对象

     @param audio_frame 所有释放的对象
     */
    ZEGOAVKIT_API void zego_audio_frame_destroy(struct ZegoAudioFrame* audio_frame);

    /**
     设置帧数据类型

     @param audio_frame 音频帧
     @param frame_type 帧数据类型，参考 enum ZegoAudioFrameType，默认 kZegoAudioFrameTypePCM
     @return 参考 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_audio_frame_set_frame_type(struct ZegoAudioFrame* audio_frame, enum ZegoAudioFrameType frame_type);

    /**
     获取帧数据类型

     @param audio_frame 音频帧
     @param frame_type 帧数据类型，参考 enum ZegoAudioFrameType，默认 kZegoAudioFrameTypePCM
     @return 参考 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_audio_frame_get_frame_type(/* in */struct ZegoAudioFrame* audio_frame, /* out */enum ZegoAudioFrameType& frame_type);

    /**
     设置采集/渲染配置

     @param audio_frame 音频帧
     @param channels 通道数，支持 1(单声道) 或 2(立体声)
     @param sample_rate 采样率
     @return 参考 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_audio_frame_set_frame_config(struct ZegoAudioFrame* audio_frame, int channels, int sample_rate);

    /**
     获取采集/渲染配置

     @param audio_frame 音频帧
     @param channels 通道数，支持 1(单声道) 或 2(立体声)
     @param sample_rate 采样率
     @return 参考 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_audio_frame_get_frame_config(/* in */struct ZegoAudioFrame* audio_frame, /* out */int& channels, /* out */int& sample_rate);

    /**
     设置采集到/待渲染的数据

     @param audio_frame 音频帧
     @param samples 采样数
     @param data 音频数据，注意：内部不会拷贝数据，需要由调用方管理其生命周期
     @return 参考 enum ZegoErrorCode
     @attention 仅支持 16 比特量化深度
     */
    ZEGOAVKIT_API int zego_audio_frame_set_frame_data(struct ZegoAudioFrame* audio_frame, int samples, unsigned char* data);

    /**
     获取采集到/待渲染的数据

     @param audio_frame 音频帧
     @param samples 采样数
     @param data 音频数据，注意：内部不会拷贝数据，需要由调用方管理其生命周期
     @return 参考 enum ZegoErrorCode
     @attention 仅支持 16 比特量化深度
     */
    ZEGOAVKIT_API int zego_audio_frame_get_frame_data(/* in */struct ZegoAudioFrame* audio_frame, /* out */int& samples, /* out */unsigned char** data);

    /**
     设置 AAC 编码数据属性

     @param audio_frame 音频帧
     @param timestamp 时间戳，如果数据中只有 AAC 配置信息，填 0
     @param data_length 总数据长度，注意 data_length = AAC编码结果长度 + special_config_length
     @param special_config_length AAC 配置信息长度
     @return 参考 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_audio_frame_set_aac_properties(struct ZegoAudioFrame* audio_frame, double timestamp, int data_length, int special_config_length);

    /**
     获取 AAC 编码数据属性

     @param audio_frame 音频帧
     @param timestamp 时间戳，如果数据中只有 AAC 配置信息，填 0
     @param data_length 总数据长度，注意 data_length = AAC编码结果长度 + special_config_length
     @param special_config_length AAC 配置信息长度
     @return 参考 enum ZegoErrorCode
     */
    ZEGOAVKIT_API int zego_audio_frame_get_aac_properties(/* in */struct ZegoAudioFrame* audio_frame, /* out */double& timestamp, /* out */int& data_length, /* out */int& special_config_length);

• 当 frameType 为 TYPE_PCM 时，各参数的含义说明：

• 当 frameType 为 TYPE_AAC_STREAM 时，各参数的含义说明如下。

下文将详细讲述如何使用实现音频外部采集和渲染。

2.1 开启外部音频设备

使用音频外部采集和外部渲染之前，必须先启用外部音频设备，调用如下接口：

zego-api-external-audio-device.h

    /**
     设置推流通道的音源

     @param publish_channel_index 选定推流通道
     @param source_type 音频来源, 详见 ZegoExternalAudioDeviceSourceType 定义
     @return 详见 enum ZegoErrorCode
     @note 必须在开启预览或者启动推流/拉流 前调用才有效
     @note 开发者采用外部采集和渲染后，SDK 内部不负责声音增强、噪音抑制、回音消除等功能，需要用户自己实现
     @note 当 publish_channel_index = 0 时表示主通道, 只支持外部采集方式
     @note 当 publish_channel_index = 1 时表示辅助通道, 支持三种音源模式, 和主推流通道一样, 使用外部采集, 使用媒体播放器的音源
     @note 当 publish_channel_index > 1 时, 当前只支持外部采集方式
     @note 当 source_type 选择 kZegoExternalAudioDeviceSourceTypeNone 时表示关闭外部音源, 主通道使用内部采集音源, 其他通道无音源
     */
    ZEGOAVKIT_API int zego_external_audio_device_set_audio_source(int publish_channel_index, ZegoExternalAudioDeviceSourceType source_type);

2.2 音频外部采集

音频外部采集的接口调用步骤如下图所示：(要换成对应函数)

2.3 音频外部渲染

音频外部渲染的接口调用步骤如下图所示：(要换成对应函数)

• 当 audioFrame 作为输入参数时，外部渲染模块参数需要按照如下方式填写：

• 当 audioFrame 作为输出参数时，SDK 会按照外部渲染要求填充好 buffer 中的数据，会修改 bufLen = 2 x samples x channels，其他字段不变。