AgoraStreamingKit 类

Inherits from NSObject
Declared in AgoraStreamingKit.h

概览

AgoraStreamingKit 接口。

该接口是 Agora Streaming Kit 主要接口。请调用该类的方法实现 Agora Streaming Kit 提供的功能。

+ sharedStreamingKitWithContext:

创建一个 AgoraStreamingKit 实例。

+ (instancetype)sharedStreamingKitWithContext:(AgoraStreamingContext *)context

参数

context

Context,详见 AgoraStreamingContext

返回

  • 方法调用成功,返回 AgoraStreamingKit 实例。
  • 方法调用失败,返回错误码。

详情

调用该方法创建一个 AgoraStreamingKit 实例,初始化 Agora Streaming Kit 服务。

Note

  • 请确保调用其他 API 之前,你已调用该方法初始化 AgoraStreaming Kit。
  • Streaming Kit 只支持单实例。为避免其余进程占用摄像头和麦克风,Agora 推荐你开发一个 app 时仅使用一个进程。你仅需要为每个 app 创建一个 AgoraStreamingKit 实例。

Declared In

AgoraStreamingKit.h

– releaseStreamingKit

释放 AgoraStreamingKit 使用的所有资源。

- (void)releaseStreamingKit

详情

该方法释放 Agora Streaming Kit 使用的所有资源。调用该方法后,你将无法再使用 Kit 提供的其他 API。 如果你需要重新使用 Kit,你需要调用 sharedStreamingKitWithContext 方法,重新创建一个 AgoraStreamingKit 实例。

Warning: 请确保同时将 AgoraStreamingKit 实例传空。

Note

  • 该方法为同步调用。为避免死锁,Agora 建议你不要在 Kit 产生的回调中调用该接口。
  • 如果你需要在销毁后再次创建 AgoraStreamingKit 实例,请等待 releaseStreamingKit 方法执行结束后再创建。

Declared In

AgoraStreamingKit.h

– startStreaming:

开始向 CDN 推送媒体流。

- (int)startStreaming:(NSString *)publishUrl

参数

publishUrl

CDN 推流 URL 地址。必须为有效的 RTMP 地址。字符长度不能超过 1024 字节。URL 不支持中文等特殊字符。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

调用该方法后,Agora Streaming Kit 会自动采集音视频,并将采集到音视频推送到指定的一个 CDN URL 地址上,以开始直播推流。

Kit 只支持同一时间向一个 CDN URL 地址推流。如果你再次调用该方法向第二个地址推流,Kit 会返回错误码 StartStreamingErrAlreadyStarted (3)

调用该方法开始推流后,如果你需要修改 CDN URL 地址,请先调用 stopStreaming 方法结束旧地址上的推流后, 再调用该方法并传入新的 CDN URL 地址。

Note: - 多主播连麦直播推流时,你需要同时使用 Agora Native SDK 和 Agora Streaming Kit。Agora Native SDK 的 channel profile 必须设为直播。 - 为避免观众端看到花屏等异常现象,请不要在推流过程中调用 switchResolution。 - 如果你需要切换视频流的来源,比如将摄像头采集的视频流切换为自采集的屏幕共享流,请务必在推流开始前完成切换。

Declared In

AgoraStreamingKit.h

– stopStreaming

停止向 CDN 推送媒体流。

- (int)stopStreaming

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

调用 startStreaming 向指定的一个 CDN 推流 URL 地址开始推送媒体流后,调用 stopStreaming 方法可以停止推送该媒体流,结束直播推流。

Declared In

AgoraStreamingKit.h

– enableAudioRecording:

开启或关闭音频采集。

- (int)enableAudioRecording:(BOOL)enabled

参数

enabled

是否开启音频采集:

  • YES:(默认)开启音频采集。
  • NO: 关闭音频采集。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

Declared In

AgoraStreamingKit.h

– enableVideoCapturing:

开启或关闭视频采集。

- (int)enableVideoCapturing:(BOOL)enabled

参数

enabled

是否开启视频采集:

  • YES:(默认)开启视频采集。
  • NO: 关闭视频采集。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

Declared In

AgoraStreamingKit.h

– muteAudioStream:

停止或恢复发送音频流。

- (int)muteAudioStream:(BOOL)muted

参数

muted

是否停止发送音频流:

  • YES: 停止发送音频流。
  • NO: (默认)发送音频流。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

Declared In

AgoraStreamingKit.h

– muteVideoStream:

停止或恢复发送视频流。

- (int)muteVideoStream:(BOOL)muted

参数

muted

是否停止发送视频流:

  • YES: 停止发送视频流。
  • NO: (默认)发送视频流。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

Declared In

AgoraStreamingKit.h

– getCameraCapturer

获取管理摄像头采集行为的对象。(仅适用于 iOS 平台)

- (AgoraCameraCapturer *)getCameraCapturer

返回

详情

调用该方法,获取 AgoraCameraCapturer 对象,该对象提供管理摄像头采集行为的方法。

Declared In

AgoraStreamingKit.h

– switchCamera

切换前置和后置摄像头。(仅适用于 iOS 平台)

- (int)switchCamera

返回

  • 0: 方法调用成功
  • < 0: 方法调用失败

详情

Streaming Kit 的初始状态为使用前置摄像头。

Declared In

AgoraStreamingKit.h

– addVideoFilter:

添加 video filter。

- (BOOL)addVideoFilter:(id<AgoraVideoFilter>)videoFilter

参数

videoFilter

video filter,详见 AgoraVideoFilter

返回

  • YES: 添加 video filter 成功。
  • NO: 添加 video filter 失败。

详情

调用该方法可以向 video track 添加一个 video filter,以进行视频前处理,如美颜。

Declared In

AgoraStreamingKit.h

– removeVideoFilter:

移除 video filter。

- (BOOL)removeVideoFilter:(id<AgoraVideoFilter>)videoFilter

参数

videoFilter

video filter,详见 AgoraVideoFilter

返回

  • YES: 移除 video filter 成功。
  • NO: 移除 video filter 失败。

详情

调用 addVideoFilter 方法添加 video filter 后,你可以调用该方法移除 video filter。

Declared In

AgoraStreamingKit.h

– adjustRecordingSignalVolume:

调节音量。

- (int)adjustRecordingSignalVolume:(int)volume

参数

volume

音量。取值范围可为 [0,400]。为避免回声并提升直播质量,Agora 建议取值 为 [0,100]。如果超出该范围,请先联系技术支持

  • 0: 静音。
  • 100: 原始音量。
  • 400: 原始音量的 4 倍(自带溢出保护)。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

Streaming Kit 会将采集到的音频输出并推送到 CDN URL 地址。调用该方法,你可以调节 Streaming Kit 的输出音量。

Declared In

AgoraStreamingKit.h

– getVideoPreviewRenderer

获取视频预览渲染器对象。

- (AgoraVideoPreviewRenderer *)getVideoPreviewRenderer

返回

详情

调用该方法,获取 AgoraVideoPreviewRenderer 对象,该对象提供管理视频本地渲染的方法。

Declared In

AgoraStreamingKit.h

– switchResolution:

切换分辨率。

- (int)switchResolution:(CGSize)resolution

参数

resolution

视频分辨率。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

如果创建 AgoraStreamingKit 时设置的视频分辨率无法满足你当前需求,你可以调用本方法切换分辨率。 该方法影响本地用户和远端用户所见。

Note: 请不要在推流过程中更改分辨率。即,本方法必须在 startStreaming 前调用。

Declared In

AgoraStreamingKit.h

– snapshot:

对设备屏幕截图。

- (void)snapshot:(ASKImageBlock)completion

参数

completion

(输出参数)详见 ASKImageBlock 回调。

详情

截图成功后,Streaming Kit 会触发 ASKImageBlock 回调并报告图像数据 ASKImage。你需要自行处理该图像。

Declared In

AgoraStreamingKit.h

– setExternalAudioSource:sampleRate:channels:

设置外部音频源。

- (int)setExternalAudioSource:(BOOL)enabled sampleRate:(AgoraAudioSampleRate)sampleRate channels:(AgoraAudioSoundType)channels

参数

enabled

是否开启音频自采集:

  • YES: 开启音频自采集。
  • NO:(默认)关闭音频自采集。
sampleRate

外部音频源的采样率 (Hz)。详见 AgoraAudioSampleRate

channels

外部音频源的声道数。详见 AgoraAudioSoundType

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

Declared In

AgoraStreamingKit.h

– setExternalVideoSource:

设置外部视频源。

- (int)setExternalVideoSource:(BOOL)enable

参数

enable

是否开启视频自采集

  • YES: 开启视频自采集。
  • NO:(默认)关闭视频自采集。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

Declared In

AgoraStreamingKit.h

– pushExternalVideoFrame:

推送外部视频帧。

- (int)pushExternalVideoFrame:(CVPixelBufferRef)frame

参数

frame

外部视频数据 CVPixelBufferRef。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

开启视频自采集后,你可以调用该方法将视频数据 CVPixelBufferRef 推送给 Streaming Kit。

Note: 调用该方法前,请确保你已调用 setExternalVideoSource 方法。

Declared In

AgoraStreamingKit.h

– pushExternalAudioFrame:

推送外部音频帧。

- (int)pushExternalAudioFrame:(CMSampleBufferRef)frame

参数

frame

外部音频数据 CMSampleBufferRef。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

开启音频自采集后,你可以调用该方法将采集的音频推送给 Streaming Kit。

Note

Declared In

AgoraStreamingKit.h

– pushExternalAudioFrameRawData:samples:timestamp:

推送外部音频帧。

- (BOOL)pushExternalAudioFrameRawData:(void *)data samples:(NSUInteger)samples timestamp:(NSTimeInterval)timestamp

参数

data

外部音频帧。

samples

音频帧的样本数量。

timestamp

音频帧的 Unix 时间戳 (ms)。必填参数。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助你实现音视频同步。

返回

  • YES: 方法调用成功。
  • NO: 方法调用失败。

详情

开启音频自采集后,你可以调用该方法将采集的音频推送给 Streaming Kit。

Note

  • 调用该方法前,请确保你已调用 setExternalAudioSource 方法。
  • 相比 pushExternalAudioFrame 方法,本方法推送的音频数据为编码前的原始数据,因此本方法更适用于同时推送应用音频和麦克风音频的场景。

Declared In

AgoraStreamingKit.h

– setLogFile:

设置日志文件路径。

- (int)setLogFile:(NSString *)filePath

参数

filePath

日志文件的完整路径。该日志文件为 UTF-8 编码。请确保该路径存在且可写。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

Agora Streaming Kit 运行时产生的所有 log 都写入日志文件。日志文件会存储至默认路径,即 App Sandbox/Library/Caches/streaming-kit.log。如果你需要修改日志文件路径,请调用该方法设置日志文件路径。

Note: 如果你需要调用该方法,请在调用 sharedStreamingKitWithContext 方法创建 AgoraStreamingKit 实例后立即调用,以保证日志内容的完整性。

Declared In

AgoraStreamingKit.h

– setLogFilter:

设置日志文件过滤等级。

- (int)setLogFilter:(AgoraLogFilterType)filter

参数

filter

日志文件的过滤等级,详见 AgoraLogFilterType

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

设置 Agora Streaming Kit 输出日志的过滤等级。过滤等级从低到高分别为 OFF,DEBUG,INFO,WARN, ERROR,CRITICAL。指定一个过滤等级后,Kit 会输出该等级和高于该等级的所有日志信息。详见 filter

Declared In

AgoraStreamingKit.h

– setLogFileSize:

设置每个日志文件大小。

- (int)setLogFileSize:(unsigned int)fileSizeInKBytes

参数

fileSizeInKBytes

每个日志文件的大小(KB)。取值范围为 [128,20480]。取值小于 128 KB 时,Agora 会自动调整为 128 KB。

返回

  • 0: 方法调用成功。
  • < 0: 方法调用失败。

详情

Agora Streaming Kit 会输出两个日志文件,每个文件大小都默认为 512 KB。如果你使用默认的文件大小,当输出的日志内容超过 1024 KB 时, 新输出的日志内容会覆盖旧的日志内容。如果你需要修改日志文件大小,请调用该方法设置每个日志文件的大小。

Declared In

AgoraStreamingKit.h

+ getSdkVersion

获取 Streaming Kit 的版本号。

+ (NSString *)getSdkVersion

返回

Streaming Kit 版本号,如 "1.1.0"

Declared In

AgoraStreamingKit.h