快速接入

1.初始化SDK

步骤：

1. 实现EngineEventHandlerInterface类，该类型包含RTC所需回调，收到数据或状态变更，其中的回调函数将被触发

2. 创建EngineEventListener实例

3. 调用AliRTCEngine.CreateAliRTCEngine函数创建AliRTCEngine实例，过程中会将EngineEventListener实例注册为engine的回调对象。后面只需要调用AliRTCEngine实例的各方法完成推拉流设置

4. 若需要向多个房间推流，请创建多个AliRTCEngine实例，每个实例对应一个房间内的虚拟用户

示例如下：

# 实现EngineEventHandlerInterface类
...

# 初始化SDK
eventHandler = EngineEventListener()
coreServicePath = '/path/AliRtcCoreService' # AliRtcCoreService路径
extra_jobj = {
    "user_specified_disable_audio_ranking": "true"
}
extra = json.dumps(extra_jobj)
linuxEngine = AliRTCEngine.CreateAliRTCEngine(eventHandler, 42000, 45000, "/tmp", coreServicePath, True, extra)

CreateAliRTCEngine函数被调用后，将启动一个AliRtcCoreService进程，函数参数如下：

• eventHandler:EngineEventHandlerInterface：回调对象，负责处理回调逻辑

• lowPort:int：端口号下限，lowPort~highPort之间的端口将被随机选择用于进程间通信

• highPort:int：端口号上限

• logPath:str：Linux SDK运行过程中，日志文件的保存路径

• coreServicePath:str：AliRtcCoreService的实际路径

• h5mode:bool：h5兼容模式，若要与Web端互通请务必设置为True，其他场景一般为False即可

• extra:str：对SDK进行额外配置时传入的JSON格式字符串

2.入会

请先参考官网文档了解阿里云RTC鉴权过程：Token鉴权

步骤：

1. 设置用户名、房间号等基本信息，从appserver请求获取单参数token

2. 配置JoinChannelConfig，设置推拉流模式等参数

3. 调用JoinChannel成员方法以入会

4. EngineEventListener实例的OnJoinChannelResult函数将被触发，以告知入会结果

# -------- 获取入会所需基本信息 --------
authInfo = AuthInfo()
authInfo.appid = ''      # appid，业务方传入
authInfo.userid = ''     # 用户名，房间内各用户的唯一标识，若有重复将被踢出房间
authInfo.username = ''   # 用户昵称，可与userid一致，也可自行设置
authInfo.channel = ''    # 入会房间号
# ...向appserver请求，获取单参数入会token
authInfo.token = ''      # appserver响应的入会token

# -------- 配置JoinChannelConfig --------
joinConfig = JoinChannelConfig()
joinConfig.channelProfile = ChannelProfile.ChannelProfileInteractiveLive # 互动模式
joinConfig.publishAvsyncMode = PublishAvsyncMode.PublishAvysncWithPts      # 推流音画同步模式
joinConfig.subscribeAudioFormat = AudioFormat.AudioFormatPcmBeforMixing  # 音频订阅格式
joinConfig.subscribeVideoFormat = VideoFormat.VideoFormatH264            # 视频订阅格式
joinConfig.isAudioOnly = False                                           # 仅音频模式，一般为False
joinConfig.subscribeMode = SubscribeMode.SubscribeAutomatically          # 订阅模式
joinConfig.publishMode = PublishMode.PublishAutomatically                # 推流模式

# -------- 调用JoinChannel入会 --------
linuxEngine.JoinChannel(authInfo.token, authInfo.channel, authInfo.userid, authInfo.username, joinConfig)

JoinChannelConfig参数说明：

1. 推流模式：支持自动和手动推流模式。前者入会后自动开启音视频推流，后者则需要手动调用API后才能进行推流。

2. 订阅模式：支持自动订阅和手动订阅模式。前者当房间内有主播入会后，便会自动订阅该主播的音视频流，后者需要手动调用API，指定要订阅的主播uid。在仅订阅音频或视频的场景下，建议使用SubscribeAudioAutoAndOnly或SubscribeCameraAutoAndOnly，以降低解码器带来的CPU占用。

3. 音频订阅格式：AudioFormatMixedPcm表示合流，房间内所有远端用户的音频被订阅后，会混合为一路音频数据回调；而AudioFormatPcmBeforMixing表示分流，每位远端用户的音频数据，将会被单独回调。

4. 视频订阅格式：设置为VideoFormatH264，当收到数据后，会触发OnRemoteVideoSample回调，否则即使收到数据也不会触发回调。

5. 音画同步模式：选择PublishAvysncWithPts后，在推送音视频数据时将根据API传入的timestamp进行音画同步，否则将不参考时间戳，按照实际调用的频率进行推送

重要

在未离会时，请勿重复调用JoinChannel

Demo中演示了用GenerateToken模拟appserver生成入会参数的过程，该接口是专为简化开发、测试过程而提供的，生产环境中，请通过与app server的交互获取token，避免appkey泄漏。

3.手动开启与关闭推流

'''
    * @brief 是否推送本地视频(摄像头)流
    * @param enabled 是否开启/关闭本地视频流推送
    - true: 开启视频流推送
    - false: 关闭视频流推送
    * @return
    - 0: 设置成功
    - <0: 设置失败，返回错误码
    * @note SDK默认设置推送视频流，在加入频道前也可以调用此接口修改默认值，并在加入频道成功时生效
'''
def PublishLocalVideoStream(enabled:bool) -> int

'''
    * @brief 是否推送本地音频流
    * @param enabled 是否开启/关闭本地音频流推送
    - true: 开启音频流推送
    - false: 关闭音频流推送
    * @return
    - 0: 设置成功
    - <0: 设置失败，返回错误码
    * @note SDK默认设置推送音频流，在加入频道前也可以调用此接口修改默认值，并在加入频道成功时生效
'''
def PublishLocalAudioStream(enabled:bool) -> int

若数据发送已结束，但不立即离会，建议调用上述两接口关闭推流

4.推送外部视频数据

'''
    * @brief 启用外部视频输入源
    * @param enable true 开启, false 关闭
    * @param type 流类型
    * @note 启用后使用PushExternalVideoFrame接口输入视频数据
'''
def SetExternalVideoSource(enable:bool, sourceType:VideoSource, renderMode:RenderMode) -> int

'''
     * @brief 输入外部输视频, 暂不支持2k及以上的视频输入
     * @param frame 帧数据
     * @param type 流类型
     * @param 支持多种输入视频帧类型，如YUV、RGB24等
'''
def PushExternalVideoFrame(frame:VideoDataSample, sourceType:VideoSource) -> int

5.推送外部音频数据

不调用SetExternalAudioPublishVolume默认按100音量推音频

'''
     * @brief 设置是否启用外部音频输入推流
     * @param enable true 开启，false 关闭
     * @param sampleRate 采样率 16k 48k...
     * @param channelsPerFrame 通道数 1 2...
     * @return >=0表示成功， <0表示失败
     * @note 可通过SetExternalAudioPublishVolume设置输入音频推流音量
'''
def SetExternalAudioSource(enable:bool, sampleRate:int, channelsPerFrame:int) -> int

'''
     * @brief 输入外部音频数据推流
     * @param audioSamples 音频数据
     * @param sampleLength 音频数据长度
     * @param timestamp 时间戳
     * @return <0表示失败，返回值为ERR_AUDIO_BUFFER_FULL时，需要在间隔投递数据时间长度后再次重试投递
'''
def PushExternalAudioFrameRawData(audioSamples:bytes, sampleLength:int, timestamp:int) -> int

'''
     * @brief 设置外部输入音频推流混音音量
     * @param vol 音量 0-100
'''
def SetExternalAudioPublishVolume(volume:int) -> int

'''
     * @brief 获取外部输入音频推流混音音量
     * @return vol 音量
'''
def GetExternalAudioPublishVolume() -> int

6.手动订阅

在自动订阅的模式下，无需调用这部分接口拉流

'''
     * @brief 停止/恢复订阅特定远端用户的音频流, 用于会中调用, 会前调用无效
     * @param uid 用户ID，从App server分配的唯一标示符
     * @param sub 是否订阅远端用户的音频流
     * - true:订阅指定用户的音频流
     * - false:停止订阅指定用户的音频流
     * @return
     * - 0: 成功
     * - 非0: 失败
'''
def SubscribeRemoteAudioStream(uid:str, sub:bool) -> int:

'''
     * @brief 停止/恢复订阅远端用户的视频流, 用于会中调用, 会前调用无效
     * @param uid 用户ID，从App server分配的唯一标示符
     * @param track 视频流类型
     * - AliEngineVideoTrackNo: 无效参数，设置不会有任何效果
     * - AliEngineVideoTrackCamera: 相机流
     * - AliEngineVideoTrackScreen: 屏幕共享流
     * - AliEngineVideoTrackBoth: 相机流和屏幕共享流
     * @param sub 是否订阅远端用户的视频流
     * - true:订阅指定用户的视频流
     * - false:停止订阅指定用户的视频流
     * @return
     * - 0:设置成功
     * - <0:设置失败
     * @note
'''
def SubscribeRemoteVideoStream(uid:str, videoTrack:VideoTrack, sub:bool) -> int

7.数据回调

'''
     * @brief 本地订阅音频数据回调
     * @details 远端所有用户混音后待播放的音频数据 对应AliRTCSdk::Linux::AudioFormatMixedPcm
     * @param frame 音频数据，详见{@link AliRTCSdk::Linux::AudioFrame}
'''
def OnSubscribeMixAudioFrame(self, frame:AudioFrame) -> None

'''
     * @brief 本地订阅音频数据回调
     * @details 远端所有用户混音后待播放的音频数据 对应AliRTCSdk::Linux::AudioFormatMixedPcm
     * @param frame 音频数据，详见{@link AliRTCSdk::Linux::AudioFrame}
'''
def OnSubscribeMixAudioFrame(self, frame:AudioFrame) -> None

'''
     * @brief 订阅的远端视频数据回调
     * @param uid 用户ID
     * @param frame 视频裸数据
     * @return
'''
def OnRemoteVideoSample(self, uid:str, frame:VideoFrame) -> None

8.离会

# 结束推流
linuxEngine.PublishLocalVideoStream(False)
linuxEngine.PublishLocalAudioStream(False)

若要在停止推流后，仍在会中，请手动调用此接口；直接离会也具有停止推流的效果

linuxEngine.LeaveChannel()

9.销毁SDK

linuxEngine.Release()
linuxEngine = None

1. Data Channel

请调用SetParameter以开启Data Channel：linuxEngine.SetParameter("{\"data\":{\"enablePubDataChannel\":true,\"enableSubDataChannel\":true}}")

通过SendDataChannelMessage发送消息：

dataChannelMsg = AliEngineDataChannelMsg()
message = "This is data channel message".encode('utf-8')
dataChannelMsg.data = message
dataChannelMsg.dataLen = len(message)
dataChannelMsg.networkTime = t0; // 网络时间字段，也可以自定义取值，不影响消息收发
dataChannelMsg.progress = 0; // 保留字段
dataChannelMsg.type = AliEngineDataMsgType.AliEngineDataChannelCustom

linuxEngine.SendDataChannelMessage(dataChannelMsg)

当接收到Data Channel消息后，会触发回调：

'''
     * @brief 获得dataChannel远端数据
     * @param msg 远端传来的消息
'''
def OnDataChannelMsg(self, uid:str, msg:AliEngineDataChannelMsg) -> None

2. SEI

/**
 * @brief 发送 媒体扩展信息(SEI)， 最大长度为4*1024字节，用于业务的少量数据传输
 * @param message 扩展信息内容，可以传递4K Bytes数据
 * @param length 扩展信息长度，单位:字节
 * @param repeatCount 重复次数，用于防止网络丢包导致的消息丢失
 * @param delay 延迟多久发出去，单位:毫秒
 * @param isKeyFrame 是否只在关键帧上增加SEI
 * @return <0: 成功，-1: SDK内部错误>
*/
int SendMediaExtensionMsg(const char* message,
                          size_t length,
                          int repeatCount,
                          uint32_t delay,
                          bool isKeyFrame);

通过SendMediaExtensionMsg发送消息：

seiMsg = "This is SEI message".encode('utf-8')
linuxEngine.SendMediaExtensionMsg(seiMsg, len(seiMsg), 3, 0 , False)

由于关键帧间隔较长，若需要高频收发SEI消息，建议isKeyFrame设置为false。同时为保证消息有效送达，建议重复次数大于1。

当接收到SEI消息后，会触发回调：

'''
     * @brief 收到媒体扩展信息回调
     * @param uid 发送用户userId
     * @param message 扩展信息内容
     * @param size 扩展信息长度
     * @note 当一端通过 {@link SendMediaExtensionMsg} 发送信息后，其他端通过该回调接收数据
'''
def OnMediaExtensionMsgReceived(self, userid:str, message:bytes, size:int) -> None:

1. 关闭Audio Ranking

Audio Ranking是多人语聊房中，仅订阅音量较大几路音频流的功能，使听众听到的声音更为清晰，默认为开启状态。若场景需要订阅全部音频流，需要通过如下字段关闭Audio Ranking功能：

{"user_specified_disable_audio_ranking" : "true"}

2. 开启订阅音频时的转码AAC功能

对于有拉流存档需求的场景，SDK提供将订阅到的远端音频转码至AAC编码的能力。您可通过AudioTranscodingCodec中的各项选择以何种格式获取远端音频（PCM、AAC或二者皆要），若开启AAC转码功能，还可选择是否进行重采样以降低CPU和存储占用。当user_specified_audio_observer_resample_rate设置为0表示不进行重采样。

{"user_specified_audio_observer_codec" : 
    AudioTranscodingCodec.AudioTranscodingCodecBothPcmAndAac.value}
{"user_specified_audio_observer_codec_format" : 0} // 目前只支持adts格式
{"user_specified_audio_observer_resample_rate" : 16000} // 重采样率
{"user_specified_audio_observer_codec_bitrate" : 64000} // 转码的目标码率

3. 开启订阅视频时直接获取H264码流功能

对于有拉流存档需求的场景，SDK提供直接获取远端视频H264码流的能力。您可通过VideoTranscodingCodec的各项，选择以何种格式获取远端视频（YUV、H264码流或二者皆要）。

{"user_specified_video_observer_codec" :
    VideoTranscodingCodec.VideoTranscodingCodecBothYuvAndH264.value}
{"user_specified_video_observer_codec_format" : 0} // 目前只支持annexb格式