推流
介绍跟推流相关的方法和回调。
enableAutoSwitchAgoraCDN
开启/关闭自动切换媒体资源的 CDN 线路。
- (int)enableAutoSwitchAgoraCDN:(BOOL)enable;
如果你想设置 SDK 根据网络情况自动切换媒体资源 CDN 线路,你可以调用该方法。
请在 openWithAgoraCDNSrc 前调用该方法。
参数
- enable
- 设置是否开启自动切换媒体资源的 CDN 线路:
YES
:开启自动切换媒体资源的 CDN 线路。NO
:(默认) 关闭自动切换媒体资源的 CDN 线路。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getAgoraCDNLineCount
获取媒体资源的 CDN 线路数量。
- (int)getAgoraCDNLineCount;
返回值
- > 0:方法调用成功,返回媒体资源的 CDN 线路数量。
- ≤ 0:方法调用失败。
getCurrentAgoraCDNIndex
获取当前使用的媒体资源的 CDN 线路索引。
- (int)getCurrentAgoraCDNIndex;
返回值
- ≥ 0: 方法调用成功,返回媒体资源的 CDN 线路索引。数值范围为 [0, getAgoraCDNLineCount
()
)。 - < 0: 方法调用失败。
openWithAgoraCDNSrc
打开媒体资源,并通过自研调度中心请求媒体资源的所有 CDN 线路。
- (int)openWithAgoraCDNSrc:(NSString *)src startPos:(NSInteger)startPos;
该方法为异步调用。
如需播放媒体文件,请在收到 didChangedToState 回调报告播放状态为 AgoraMediaPlayerStateOpenCompleted 后再调用 play 方法播放媒体文件。
调用该方法后,Agora 会打开媒体资源并通过自研调度中心请求媒体资源的所有 CDN 线路。Agora 默认使用第一个线路,你也可以通过 switchAgoraCDNLineByIndex 自行切换线路。
query parameter
以更新媒体资源的网路路径。例如:
- 媒体资源网络路径为
rtmp://$domain/$appName/$streamName
- 通过鉴权信息更新过的媒体资源网络路径为
rtmp://$domain/$appName/$streamName?ts=$ts&sign=$sign
- sign : 通过
authKey
+appName
+streamName
+ts
进行 md5 算法加密得出的鉴权字段。你需要联系技术支持咨询你的authKey
字段内容。 - ts : 鉴权过期时间。你可以指定再过多久鉴权过期。例如,
24h
或1h30m20s
。
参数
- src
- 媒体资源的网络路径。
- startPos
- 设置起始播放位置 (毫秒),默认值为 0。如果媒体资源为直播流,则无需赋值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
renewAgoraCDNSrcToken
更新媒体资源网络路径的鉴权信息。
- (int)renewAgoraCDNSrcToken:(NSString *)token ts:(NSInteger)ts;
当鉴权信息过期(超出 ts 时间)时,你可以调用 openWithAgoraCDNSrc 或 switchAgoraCDNSrc 重新打开或切换媒体资源,并传入带新鉴权信息(如更新 ts 字段内容)的媒体资源网络路径。
如果你在切换媒体资源线路 (switchAgoraCDNLineByIndex) 时遇到鉴权信息过期,你需要调用该方法并传入新的鉴权信息,以更新该媒体资源网络路径的鉴权信息。更新鉴权信息后,你还需调用 switchAgoraCDNLineByIndex 才能完成线路切换。
为避免鉴权信息频繁过期,请务必根据场景需求设置合适的 ts 字段内容或联系技术支持。
参数
- token
- 鉴权字段。即鉴权信息中的 sign 字段。
- ts
- 鉴权过期时间。即鉴权信息中的 ts 字段。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDirectCdnStreamingAudioConfiguration
设置主播端直接向 CDN 推流时的音频编码属性。
- (int)setDirectCdnStreamingAudioConfiguration:(AgoraAudioProfile)profile;
该方法仅对麦克风采集或自采集的音频有效,即对在 AgoraDirectCdnStreamingMediaOptions 中设置 publishMicrophoneTrack 或 publishCustomAudioTrack 为 YES
时所采集的音频有效。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。详见 AgoraAudioProfile。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setDirectCdnStreamingVideoConfiguration
设置主播端直接向 CDN 推流时的视频编码属性。
- (int)setDirectCdnStreamingVideoConfiguration:(AgoraVideoEncoderConfiguration * _Nonnull)config;
该方法仅对摄像头采集、屏幕共享或自采集的视频有效。即对在 AgoraDirectCdnStreamingMediaOptions 中设置 publishCameraTrack 或 publishCustomVideoTrack 为 YES
时所采集的视频有效。
如果你设置的视频分辨率超出你的摄像头设备支持的范围,SDK 会根据你的设置进行自适应,取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流。你可以通过 onDirectCdnStreamingStats 回调了解推送的视频流的实际分辨率。
参数
- config
- 视频编码参数配置。详见 AgoraVideoEncoderConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startDirectCdnStreaming
设置主播端开始直接向 CDN 推流。
- (int)startDirectCdnStreaming:(id<AgoraDirectCdnStreamingEventDelegate> _Nonnull)delegate publishUrl:(NSString * _Nonnull)publishUrl mediaOptions:(AgoraDirectCdnStreamingMediaOptions * _Nonnull)options;
Agora 不支持同一时间向同一个 URL 重复推流。
媒体选项说明
Agora 不支持 publishCameraTrack 和 publishCustomVideoTrack 同时为 YES
,也不支持 publishMicrophoneTrack 和 publishCustomAudioTrack 同时为 YES
。你可以根据场景需求设置媒体选项 (AgoraDirectCdnStreamingMediaOptions)。示例如下:
如果你想推送主播端采集的音视频流,请将媒体选项进行如下设置:
- publishCustomAudioTrack 设为
YES
并调用 pushExternalAudioFrameSampleBuffer 或 pushExternalAudioFrameNSData - publishCustomVideoTrack 设为
YES
并调用 pushExternalVideoFrame - 确保 publishCameraTrack 为
NO
(默认值) - 确保 publishMicrophoneTrack 为
NO
(默认值)
参数
- delegate
- 详见 onDirectCdnStreamingStateChanged 及 onDirectCdnStreamingStats。
- publishUrl
- CDN 推流 URL。
- options
- 主播端的媒体选项。详见 AgoraDirectCdnStreamingMediaOptions。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startRtmpStreamWithoutTranscoding
开始非转码推流。
- (int)startRtmpStreamWithoutTranscoding:(NSString* _Nonnull)url;
调用该方法,你可以向指定的旁路推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请确保已开通旁路推流服务。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
startRtmpStreamWithTranscoding
开始旁路推流并设置转码属性。
- (int)startRtmpStreamWithTranscoding:(NSString* _Nonnull)url transcoding:(AgoraLiveTranscoding* _Nullable)transcoding;
调用该方法,你可以向指定的旁路推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
- 请确保已开通旁路推流服务。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding
-
旁路推流的转码属性,详见 AgoraLiveTranscoding 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
stopDirectCdnStreaming
设置主播端停止直接向 CDN 推流。
- (int)stopDirectCdnStreaming;
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopRtmpStream
结束旁路推流。
- (int)stopRtmpStream:(NSString* _Nonnull)url;
调用该方法,你可以结束指定的旁路推流地址上的直播。该方法每次只能结束一个推流地址上的直播,如果你需要结束多个推流地址的直播,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 rtmpStreamingChangedToState 回调,报告推流的状态。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchAgoraCDNLineByIndex
切换媒体资源的 CDN 线路。
- (int)switchAgoraCDNLineByIndex:(int)index;
- 请在 openWithAgoraCDNSrc 后调用该方法。
- 该方法在 play 前后均可调用。如果你在 play 前调用该方法,切换不会立即生效。SDK 会等待播放完成后再切换媒体资源的 CDN 线路。
参数
- index
- CDN 线路索引。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchAgoraCDNSrc
切换媒体资源。
- (int)switchAgoraCDNSrc:(NSString *)src syncPts:(BOOL)syncPts;
如果用户需要自定义播放线路,你可以调用该方法实现媒体资源切换。Agora 会通过自研调度中心支持调度线路,提升观看用户体验。如果用户不需要自定义播放线路,你可以调用 switchSrc 实现媒体资源切换。
- 请在 openWithAgoraCDNSrc 后调用该方法。
- 该方法在 play 前后均可调用。如果你在 play 前调用该方法,SDK 会等你调用 play 后再完成线路切换。
query parameter
以更新媒体资源的网路路径。例如:
- 媒体资源网络路径为
rtmp://$domain/$appName/$streamName
- 通过鉴权信息更新过的媒体资源网络路径为
rtmp://$domain/$appName/$streamName?ts=$ts&sign=$sign
- sign : 通过
authKey
+appName
+streamName
+ts
进行 md5 算法加密得出的鉴权字段。你需要联系技术支持咨询你的authKey
字段内容。 - ts : 鉴权过期时间。你可以指定再过多久鉴权过期。例如,
24h
或1h30m20s
。
参数
- src
- 媒体资源的网络路径。
- syncPts
- 是否同步切换前后的起始播放位置:
YES
:同步。NO
:(默认) 不同步。
如果媒体资源为直播流,你只能将该参数设置为
NO
,否则 SDK 切换媒体资源会失败。如果媒体资源为点播流,你可以根据场景需求对该参数赋值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateChannelMediaRelay
更新媒体流转发的频道。
- (int)updateChannelMediaRelay:(AgoraChannelMediaRelayConfiguration * _Nonnull)config;
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 didReceiveChannelMediaRelayEvent 回调, 并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel (7)。
channelMediaRelayStateDidChange(AgoraChannelMediaRelayStateRunning, AgoraChannelMediaRelayErrorNone)
后调用该方法;否则,方法调用会失败。参数
- config
- 跨频道媒体流转发参数配置。详见 AgoraChannelMediaRelayConfiguration 。
返回值
- 0:方法调用成功
- < 0:方法调用失败
updateRtmpTranscoding
更新旁路推流转码属性。
- (int)updateRtmpTranscoding:(AgoraLiveTranscoding* _Nullable)transcoding;
开启转码推流后,你可以根据场景需求,动态更新转码属性。转码属性更新后,SDK 会触发 rtcEngineTranscodingUpdated 回调。
参数
- transcoding
-
旁路推流的转码属性,详见 AgoraLiveTranscoding 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
onAgoraCDNTokenWillExpire
提示鉴权信息即将过期。
- (void)onAgoraCDNTokenWillExpire;
当你调用 switchAgoraCDNLineByIndex 切换媒体资源的时候,如果 ts 过期,该回调会被触发,提示你更新鉴权信息。你需要调用 renewAgoraCDNSrcToken 传入新的鉴权信息,以更新该媒体资源网络路径的鉴权信息。更新鉴权信息后,你还需要调用 switchAgoraCDNLineByIndex 才能完成线路切换。
onDirectCdnStreamingStateChanged
CDN 推流状态改变回调。
- (void)onDirectCdnStreamingStateChanged:(AgoraDirectCdnStreamingState)state error:(AgoraDirectCdnStreamingError)error message:(NSString *_Nullable)message;
主播端直接向 CDN 推流后,当推流状态改变时,SDK 会触发该回调向你报告新的状态、错误码和信息。你可以据此排查问题。
参数
- state
- 当前推流状态。详见 AgoraDirectCdnStreamingState。
- error
- 推流出错的原因。详见 AgoraDirectCdnStreamingError。
- message
- 状态改变对应的信息。
onDirectCdnStreamingStats
CDN 推流统计数据回调。
- (void)onDirectCdnStreamingStats:(AgoraDirectCdnStreamStats *_Nonnull)stats;
在主播直接向 CDN 推流的过程中,SDK 每隔 1 秒触发一次该回调。
参数
- stats
- 当前推流的统计数据。详见 AgoraDirectCdnStreamingStats。
rtmpStreamingEventWithUrl
旁路推流事件回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine rtmpStreamingEventWithUrl:(NSString* _Nonnull)url eventCode:(AgoraRtmpStreamingEvent)eventCode;
参数
- url
- 旁路推流 URL。
- eventCode
- 旁路推流事件码。详见 AgoraRtmpStreamingEvent。
rtmpStreamingChangedToState
旁路推流状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine rtmpStreamingChangedToState:(NSString* _Nonnull)url state:(AgoraRtmpStreamingState)state errCode:(AgoraRtmpStreamingErrorCode)errCode;
旁路推流状态发生改变时,SDK会触发该回调,并在回调中明确状态发生改变的 URL 地址及当前推流状态。该回调方便推流用户了解当前的推流状态;推流出错时,你可以通过返回的错误码了解出错的原因,方便排查问题。
参数
- engine
- AgoraRtcEngineKit 对象。
- url
-
推流状态发生改变的 URL 地址。
- state
- 当前的推流状态,详见 AgoraRtmpStreamingState。
- errCode
- 推流错误信息,详见 AgoraRtmpStreamingErrorCode。
rtcEngineTranscodingUpdated
旁路推流转码设置已被更新回调。
- (void)rtcEngineTranscodingUpdated:(AgoraRtcEngineKit * _Nonnull)engine;
setLiveTranscoding 方法中的直播参数 AgoraLiveTranscoding 更新时,rtcEngineTranscodingUpdated 回调会被触发并向主播报告更新信息。
参数
- engine
- AgoraRtcEngineKit 对象。