接口定义

本文介绍创建引擎、初始化引擎、引擎创建/销毁会话、获取引擎版本号和监听引擎事件的相关接口,以及会话相关的接口,包括创建一个房间、加入已有的房间、发布和订阅音视频流等。

引擎相关

创建引擎

enum EventType {
    INIT = 0,                         //引擎类:初始化结果
    WSS_LINK,                         //引擎类:和房间服务器的 WebSocket 的连接状态
    CREATE_ROOM,                      //会话类:创建房间
    JOIN_ROOM,                        //会话类:加入房间
    PUBLISH,                          //会话类:发布
    SUBSCRIBE,                        //会话类:订阅
    EXIT_ROOM,                        //会话类:退出房间
    ICE_LINK,                         //会话类:音视频数据通道联调状态
    START_RECORD                      //会话类:启动录制的结果
};
struct RtcEvent {
    std::string uid;                  //事件关联的用户 ID,目前 uid 只支持英文字母、数字、下划线的组合,且长度不超过 128 个字符。
    EventType type;                   //事件类型
    int32_t code;                     //事件结果,小于 0 表示错误,等于 0 表示正常
    std::string ext = "";             //扩展字段,格式和事件类型相关,参考问题列表章节
};
struct MRtcEngineListener {
    MRtcEngineListener() {};
    virtual ~MRtcEngineListener(){};
    virtual void OnEngineEvent(RtcEvent event) = 0;
};
static MRtcEngine* Create(MRtcEngineListener* engineListener);

初始化引擎

enum RtcVideoCodec {
    VIDEO_CODEC_YUV420P,        //视频输入输出是未编码的 YUV 数据(I420P)
    VIDEO_CODEC_H264,           //视频输入输出是编码好的 H264 数据
};
enum RtcAudioCodec {
    AUDIO_CODEC_PCM,            //音频当前只支持 PCM 格式的输入和输出
};
struct RtcVideoData {
    const uint8_t *dataY;      //引擎初始化为 VIDEO_CODEC_YUV420P 时为 Y 分量缓存,其他情况为编码后视频帧缓存地址
    const uint8_t *dataU;      //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    const uint8_t *dataV;      //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t strideY;           //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t strideU;           //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t strideV;           //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t length;            //视频数据长度,引擎初始化为 VIDEO_CODEC_H264 必填,其他情况无需关注
    int32_t width;             //视频宽
    int32_t height;            //视频高
    int64_t timestamp;         //视频时间戳,必填
};
struct RtcAudioFormat {
    RtcAudioFormat():channels(1),sampleRate(16000),bytesPerSample(2),audioCodec(AUDIO_CODEC_PCM){}
    int32_t            channels;               //音频声道数
    int32_t            sampleRate;             //音频采样率
    int32_t            bytesPerSample;         //单个样本点字节数
    RtcAudioCodec      audioCodec;
};
struct MRtcEngineInitParam {
    std::string roomUrl;             //房间服务器的接入地址
    RtcVideoFormat videoFormat;      //视频输入输出格式
    RtcAudioFormat audioFormat;      //音频输入输出格式
    std::string logLevel = "debug";  //日志级别,none|error|warn|info|debug 中的某一个,none 表示不打印日志
    int32_t maxSessionNum = 20;      //运行并发的最大会话数量,大于 0 时配置生效
    bool enableRelay = false;        //如果服务器没有公网 IP,可以考虑打开该开关,使用数据中转模式
    bool enableDataChannel = false;  //是否开启 DataChannel 功能
};
int32_t Init(const MRtcEngineInitParam& param);

引擎创建⼀个会话

/**
 *  会话监听器,可以侦听会话中产生的一些事件,比如发布成功,订阅成功等
 *  当有新的发布者加入或者离开会话,会得到通知,告知该发布者的一些信息,包括使用的流 ID,用户 ID 等
 *  如果订阅了某个发布者的流数据,那么还会收到其相应的音视频数据
**/
struct MRtcSessionListener {
    MRtcSessionListener() {};
    virtual ~MRtcSessionListener(){};
    //会话事件回调
    virtual void OnSessionEvent(RtcEvent event) = 0;
    //房间里面有人发布了一条新流,可供订阅
    virtual void OnNewPublisher(StreamInfo info) = 0;
    //房间里面某条流取消了发布,离开了房间
    virtual void OnStreamGone(StreamInfo info) = 0;
    //有新的订阅者订阅了某条流
    virtual void OnNewSubscriber(StreamInfo info) = 0;
    //混音后的音频数据,该接口保留,两人场景下没有用到
    virtual void OnMixedAudio(const RtcAudioData& audio) = 0;
    //收到某条流的音频数据
    virtual void OnAudio(const RtcAudioData& audio,const std::string& streamId) = 0;
    //收到某条流的视频数据
    virtual void OnVideo(const RtcVideoData& video,const std::string& streamId) = 0;

    //H264-NALU 对接的场景下,需要反馈一些信息 给到编码器做实时调节
    //请求本地编码器下一帧编码关键帧
    virtual void OnKeyFrameRequest() {}
    //实时控制编码器的一些编码参数,比如输出帧率和码率
    virtual void OnEncoderQosRequest(const MRtcEncoderQosParams& params) {}
};
/**
 *  根据底层网络状态的反馈情况以及订阅方视频解码的情况,
 *  实时调节上次业务方编码器的输出帧率和码率
 *  业务方可以根据编码器的特性,尽可能的做出对应的调整
**/
struct MRtcEncoderQosParams {
    int target_kbps;
    int target_fps;
};
MRtcSession* CreateSession(MRtcSessionListener* sessionListener);

引擎销毁⼀个会话

void DestroySession(MRtcSession* session);

获取引擎的版本号

std::string GetVersion();

监听引擎事件

void OnEngineEvent(RtcEvent event);

会话相关

创建⼀个房间

struct CreatRoomParam {
    std::string uid;                    //用户 ID,作为房间里某个用户的唯一标识
    std::string sign;                   //房间服务器需要验证该通话业务的合法性
    std::string bizName;                //业务类型,比如 Bank(银行类业务)、Stock(证券类业务)
    std::string subBiz;                 //子业务类型,比如上海银行,平安证券等
    std::string workspaceId;            //MPaaS 类业务需要填写,其他业务不需要该字段
    bool autoSubscribe;                 //当房间里面有新人进入,发布了新的流,SDK 是否自动订阅
    EngineType engine = ENGINE_ALIPAY;  //媒体数据使用 P2P 模式还是 SFU 模式,默认使用 SFU 模式(中转)
    std::string ext;                    //留作扩展,可用来配置录制相关的特性,参见问题列表
};
void CreateRoom(const CreatRoomParam& createParam);

加入已有房间

struct JoinRoomParam {
    std::string roomId;
    std::string uid;
    std::string sign;
    std::string bizName;
    std::string subBiz;
    std::string token;                 //加入房间的凭证
    std::string workspaceId;           //MPaaS 类业务需要填写,其他业务不需要该字段
    bool autoSubscribe;                //是否自动订阅房间里面发布者发布的音视频流
    EngineType engine = ENGINE_ALIPAY; //媒体数据使用 P2P 模式还是 SFU 模式,默认使用 SFU 模式(中转)
    std::string ext;                   //留作扩展,暂时未用
};
void JoinRoom(const JoinRoomParam& joinParam);

发布音视频流

struct PublishParam {
    PublishParam():enableVideo(false),enableAudio(true){}
    bool enableVideo;                //是否发布本地视频到视频服务器
    bool enableAudio;                //是否发布本地音频到视频服务器
};
void Publish(const PublishParam& pubParam);

订阅音视频流

struct SubscribeParam {
    SubscribeParam():enableVideo(false),enableAudio(true){}
    bool enableVideo;               //手动订阅的场景下,是否订阅视频
    bool enableAudio;               //手动订阅的场景下,是否订阅音频
    std::string streamId;           //房间里面的每个发布者都有唯一的一个流标识,这个标识指明去订阅哪个参与者的音视频流
};
void Subscribe(const SubscribeParam& subParam);

从服务端输入音频数据发送到客户端

struct RtcAudioData {
    const uint8_t *data;           //必填,音频数据缓存
    int32_t length;                //必填,音频数据长度
    int64_t timestamp;             //必填,音频时间戳
};
void FeedAudio(const RtcAudioData& audio);

从服务端输入视频数据发送到客户端

struct RtcVideoData {
    const uint8_t *dataY;      //引擎初始化为 VIDEO_CODEC_YUV420P 时为 Y 分量缓存,其他情况为编码后视频帧缓存地址
    const uint8_t *dataU;      //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    const uint8_t *dataV;      //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t strideY;           //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t strideU;           //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t strideV;           //引擎初始化为 VIDEO_CODEC_YUV420P 时必填,其他情况无需关注
    int32_t length;            //视频数据长度,引擎初始化为 VIDEO_CODEC_H264 必填,其他情况无需关注
    int32_t width;             //视频宽
    int32_t height;            //视频高
    int64_t timestamp;         //视频时间戳,必填
};
void FeedVideo(const RtcVideoData& video);

发送文本消息

peers 存放接收端的 UID,文本消息底层使用 WSS 协议通过 Room 中转。

void SendText(const std::string& text,const std::list<std::string> peers);

发送文本消息

与 SendText 的区别在于,底层是采用的 WebRtc 的 DataChannel 传输通道。

void SendData(const std::string& data);

离开房间

void LeaveRoom();

清除音频发送队列

这些数据将不会发送到客户端,实现打断的功能。

void ClearAudio();

音频发送队列大小

获取音频发送队列当前剩余的数据量,用于判断当前所有后台产生的语音包是否已经发送到端。

int32_t AudioQueueSize();