KSYGPUStreamerKit Class Reference

Inherits from NSObject
Declared in KSYGPUStreamerKit.h

Overview

KSY 直播推流工具类

  • kit类将直播推流SDK中提供的各种组件进行组合串联, 功能覆盖了绝大部分秀场直播场景的需求
  • 可以直接使用Kit类来开发基础功能的推流APP

  • 亦可以参考kit类的代码, 了解每个组件API的使用方法, 自行开发进阶需求的功能

  • 本 kit 类中, 演示了3个图层内容和2个音频通道的叠加直播

  • 图像通道: ([]中的数字为图层编号) vCapDev –> cropFilter –> filters[0] –>| vPreMixer |-> preview logo picture[1] –>| logo text label[2] –>| vStrMixer |-> picOutput –> streamer

  • 音频通道: ([]中的数字为音轨编号) aCapDev [0] –>| bgmplayer [1] –>| aMixer –> streamer

Other Methods

– initWithDefaultCfg

初始化方法

- (instancetype)initWithDefaultCfg

Discussion

创建带有默认参数的 kit，不会打断其他后台的音乐播放

Warning: kit只支持单实例推流，构造多个实例会出现异常

Declared In

KSYGPUStreamerKit.h

– initWithInterruptCfg

初始化方法

- (instancetype)initWithInterruptCfg

Discussion

创建带有默认参数的 kit，会打断其他后台的音乐播放

Warning: kit只支持单实例推流，构造多个实例会出现异常

Declared In

KSYGPUStreamerKit.h

– getKSYVersion

获取SDK版本号

- (NSString *)getKSYVersion

Declared In

KSYGPUStreamerKit.h

  vCapDev

视频采集设备

@property (nonatomic, readonly) KSYAVFCapture *vCapDev

Discussion

通过该指针可以对摄像头进行操作 (操作接口参见GPUImage)

Declared In

KSYGPUStreamerKit.h

  filter

获取当前使用的滤镜

@property (nonatomic, readonly) GPUImageOutput<GPUImageInput> *filter

Discussion

通过此指针可以对滤镜参数进行设置 @waning 请确保外部保留了filter的真实类型的指针, 否则会出现奔溃

Declared In

KSYGPUStreamerKit.h

  vPreviewMixer

图像混合器 for 预览

@property (nonatomic, readonly) KSYGPUPicMixer *vPreviewMixer

Discussion

将多图层的内容叠加

Declared In

KSYGPUStreamerKit.h

  vStreamMixer

图像混合器 for 推流

@property (nonatomic, readonly) KSYGPUPicMixer *vStreamMixer

Discussion

将多图层的内容叠加

Declared In

KSYGPUStreamerKit.h

  preview

预览视图

@property (nonatomic, readonly) KSYGPUView *preview

Discussion

通过此指针可以对预览视图进行操作

Declared In

KSYGPUStreamerKit.h

  capToGpu

采集到的图像上传GPU

@property (nonatomic, readonly) KSYGPUPicInput *capToGpu

Discussion

用于衔接GPU和capture

Declared In

KSYGPUStreamerKit.h

  gpuToStr

获取渲染的图像

@property (nonatomic, readonly) KSYGPUPicOutput *gpuToStr

Discussion

用于衔接GPU和streamer

Declared In

KSYGPUStreamerKit.h

  aCapDev

音频采集设备 Audio Unit 音频采集

@property (nonatomic, readonly) KSYAUAudioCapture *aCapDev

Declared In

KSYGPUStreamerKit.h

  bgmPlayer

背景音乐播放器

@property (nonatomic, readonly) KSYBgmPlayer *bgmPlayer

Declared In

KSYGPUStreamerKit.h

  aMixer

音频混合器

@property (nonatomic, readonly) KSYAudioMixer *aMixer

Discussion

用于将多路音频进行混合,将混合后的音频送入streamerBase

Declared In

KSYGPUStreamerKit.h

  audioCaptureType

音频采集模式

@property (nonatomic, assign) KSYAudioCapType audioCaptureType

Discussion

推荐使用AudioUnit模式

Declared In

KSYGPUStreamerKit.h

  msgStreamer

消息通道

@property (nonatomic, readonly) KSYMessage *msgStreamer

Discussion

用于采集消息，并将数据送入streamerBase

Declared In

KSYGPUStreamerKit.h

  streamerBase

获取初始化时创建的底层推流工具

@property (nonatomic, readonly) KSYStreamerBase *streamerBase

Discussion

  1. 通过它来设置推流参数
  1. 通过它来启动，停止推流

Declared In

KSYGPUStreamerKit.h

  maxAutoRetry

自动重连次数 关闭(0), 开启(>0), 默认为0

@property (nonatomic, assign) int maxAutoRetry

Discussion

当内部发现推流错误后, 会在一段时间后尝试重连 自动重连不会重新获取推流地址, 仍然使用上次推流的地址

Warning: 如果在推流地址有过期时间, 请勿开启

Declared In

KSYGPUStreamerKit.h

  autoRetryDelay

自动重连延时, 发现连接错误后, 重试的延时

@property (nonatomic, assign) double autoRetryDelay

Discussion

单位为秒, 默认为2s, 最小值为0.1s

Declared In

KSYGPUStreamerKit.h

  cameraLayer

摄像头图层

@property (nonatomic, readonly) NSInteger cameraLayer

Declared In

KSYGPUStreamerKit.h

  logoPicLayer

logo 图片的图层

@property (nonatomic, readonly) NSInteger logoPicLayer

Declared In

KSYGPUStreamerKit.h

  logoTxtLayer

logo 文字的图层

@property (nonatomic, readonly) NSInteger logoTxtLayer

Declared In

KSYGPUStreamerKit.h

  aeLayer

贴纸的图层

@property (nonatomic, readonly) NSInteger aeLayer

Declared In

KSYGPUStreamerKit.h

  micTrack

麦克风通道

@property (nonatomic, readonly) int micTrack

Declared In

KSYGPUStreamerKit.h

  bgmTrack

背景音乐通道

@property (nonatomic, readonly) int bgmTrack

Declared In

KSYGPUStreamerKit.h

  captureState

当前采集设备状况

@property (nonatomic, readonly) KSYCaptureState captureState

Discussion

可以通过该属性获取采集设备的工作状况

通知： * KSYCaptureStateDidChangeNotification 当采集设备工作状态发生变化时提供通知 * 收到通知后，通过本属性查询新的状态，并作出相应的动作

Declared In

KSYGPUStreamerKit.h

– getCaptureStateName:

获取采集状态对应的字符串

- (NSString *)getCaptureStateName:(KSYCaptureState)stat

Declared In

KSYGPUStreamerKit.h

– getCurCaptureStateName

获取当前采集状态对应的字符串

- (NSString *)getCurCaptureStateName

Declared In

KSYGPUStreamerKit.h

– startPreview:

启动预览

- (void)startPreview:(UIView *)view

Parameters

view

预览画面作为subview，插入到 view 的最底层

Discussion

设置完成采集参数之后，按照设置值启动预览，启动后对采集参数修改不会生效

需要访问摄像头和麦克风的权限，若授权失败，其他API都会拒绝服务

@warning: 开始推流前必须先启动预览

See Also

Declared In

KSYGPUStreamerKit.h

– startVideoCap

开启视频配置和采集

- (BOOL)startVideoCap

Discussion

设置完成视频采集参数之后，按照设置值启动视频预览，启动后对视频采集参数修改不会生效

需要访问摄像头的权限，若授权失败，其他API都会拒绝服务

视频采集成功返回YES，不成功返回NO

Declared In

KSYGPUStreamerKit.h

– startAudioCap

开始音频配置和采集

- (BOOL)startAudioCap

Discussion

设置完成音频采集参数之后，按照设置值启动音频预览，启动后对音频采集参数修改不会生效

需要访问麦克风的权限，若授权失败，其他API都会拒绝服务

音频采集成功返回YES，不成功返回NO

Declared In

KSYGPUStreamerKit.h

– stopPreview

停止预览，停止采集设备，并清理会话

- (void)stopPreview

Discussion

若推流未结束，则先停止推流

Declared In

KSYGPUStreamerKit.h

– appEnterBackground

进入后台: 暂停图像采集

- (void)appEnterBackground

Discussion

暂停图像采集和预览, 中断旁路录制

如果需要释放mic资源请直接调用停止采集

kit内部在收到UIApplicationDidEnterBackgroundNotification 或采集被打断等事件时,会主动调用本接口

Declared In

KSYGPUStreamerKit.h

– appBecomeActive

回到前台: 恢复采集

- (void)appBecomeActive

Discussion

恢复图像采集和预览

恢复音频采集

kit内部在收到UIApplicationDidBecomeActiveNotification等事件时,会主动调用本接口

Declared In

KSYGPUStreamerKit.h

  capPreset

采集分辨率 (仅在开始采集前设置有效)

@property (nonatomic, assign) NSString *capPreset

Discussion

参见iOS的 AVCaptureSessionPresetXXX的定义

https://developer.apple.com/reference/avfoundation/avcapturesession/1669314-video_input_presets?language=objc

透传到 KSYGPUCamera. 默认值为AVCaptureSessionPreset640x480

不同设备支持的预设分辨率可能不同, 请尽量与预览分辨率一致

Declared In

KSYGPUStreamerKit.h

– captureDimension

查询实际的采集分辨率

- (CGSize)captureDimension

Discussion

参见iOS的 AVCaptureSessionPresetXXX的定义

Declared In

KSYGPUStreamerKit.h

  previewDimension

预览分辨率 (仅在开始采集前设置有效)

@property (nonatomic, assign) CGSize previewDimension

Discussion

内部始终将较大的值作为宽度 (若需要竖屏，请设置 videoOrientation）

宽高都会向上取整为4的整数倍

有效范围: 宽度[160, 1920] 高度[ 90, 1080], 超出范围会取边界有效值

当预览分辨率与采集分辨率不一致时: 若宽高比不同, 先进行裁剪, 再进行缩放 若宽高比相同, 直接进行缩放

默认值为(640, 360)

Declared In

KSYGPUStreamerKit.h

  streamDimension

用户定义的视频 推流 分辨率

@property (nonatomic, assign) CGSize streamDimension

Discussion

有效范围: 宽度[160, 1280] 高度[ 90, 720], 超出范围会取边界有效值

其他与previewDimension限定一致,

当与previewDimension不一致时, 同样先裁剪到相同宽高比, 再进行缩放

默认值为(640, 360)

See Also

Declared In

KSYGPUStreamerKit.h

  capturePixelFormat

采集模块输出的像素格式 (默认:kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)

@property (nonatomic, assign) OSType capturePixelFormat

Discussion

目前只支持 kCVPixelFormatType_32BGRA 和 kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange

仅在开始推流前设置有效

Declared In

KSYGPUStreamerKit.h

  gpuOutputPixelFormat

gpu output pixel format (默认:kCVPixelFormatType_32BGRA)

@property (nonatomic, assign) OSType gpuOutputPixelFormat

Discussion

目前支持 BGRA , NV12 和 I420

仅在开始推流前设置有效

Declared In

KSYGPUStreamerKit.h

  videoFPS

采集及编码视频帧率 (开始采集前设置有效)

@property (nonatomic, assign) int videoFPS

Discussion

video frame per seconds 有效范围[1~30], 超出范围会取边界有效值

默认值为15

Declared In

KSYGPUStreamerKit.h

  cameraPosition

摄像头位置 (仅在开始采集前设置有效)

@property (nonatomic, assign) AVCaptureDevicePosition cameraPosition

Discussion

前后摄像头, 默认值为前置

Declared In

KSYGPUStreamerKit.h

  videoOrientation

摄像头朝向, 只在启动采集前设置有效

@property (nonatomic, readwrite) UIInterfaceOrientation videoOrientation

Discussion

参见UIInterfaceOrientation

竖屏时: width < height

横屏时: width > height

需要与UI方向一致

Declared In

KSYGPUStreamerKit.h

  bStereoAudioStream

是否用双声道推流 (默认为NO)

@property (nonatomic, assign) BOOL bStereoAudioStream

Discussion

使用KSYAUAudioCapture采集的声音目前只支持单声道(主播说话的声音为单声道)

背景音乐如果是双声道的音频,通过修改bStereoStream, 可以让观众听到双声道的音乐

只能在开始推流前修改本属性, 开始推流后, 修改无效

Declared In

KSYGPUStreamerKit.h

– switchCamera

切换摄像头

- (BOOL)switchCamera

Return Value

TRUE: 成功切换摄像头， FALSE：当前参数，下一个摄像头不支持，切换失败

Discussion

在前后摄像头间切换，从当前的摄像头切换到另一个，切换成功则修改cameraPosition的值

开始预览后开始有效，推流过程中也响应切换请求

See Also

Declared In

KSYGPUStreamerKit.h

– isTorchSupported

当前采集设备是否支持闪光灯

- (BOOL)isTorchSupported

Return Value

YES / NO

Discussion

通常只有后置摄像头支持闪光灯

Declared In

KSYGPUStreamerKit.h

– toggleTorch

开关闪光灯

- (void)toggleTorch

Discussion

切换闪光灯的开关状态 开 <–> 关

Declared In

KSYGPUStreamerKit.h

– setTorchMode:

设置闪光灯

- (void)setTorchMode:(AVCaptureTorchMode)mode

Parameters

mode

AVCaptureTorchModeOn/Off

Discussion

设置闪光灯的开关状态

开始预览后开始有效

Declared In

KSYGPUStreamerKit.h

– getCurrentCameraDevices

获取当前采集设备的指针

- (AVCaptureDevice *)getCurrentCameraDevices

Return Value

AVCaptureDevice* 预览开始前调用返回为nil，开始预览后，返回当前正在使用的摄像头

Discussion

开放本指针的目的是开放类似下列添加到AVCaptureDevice的 categories： - AVCaptureDeviceFlash - AVCaptureDeviceTorch - AVCaptureDeviceFocus - AVCaptureDeviceExposure - AVCaptureDeviceWhiteBalance - etc.

Warning: 请勿修改摄像头的像素格式，帧率，分辨率等参数，修改后会导致推流工作异常或崩溃

Declared In

KSYGPUStreamerKit.h

  videoProcessingCallback

视频处理回调接口

@property (nonatomic, copy) void ( ^ ) ( CMSampleBufferRef sampleBuffer ) videoProcessingCallback

Parameters

sampleBuffer

原始采集到的视频数据

Discussion

对sampleBuffer内的图像数据的修改将传递到观众端

请注意本函数的执行时间，如果太长可能导致不可预知的问题

请参考 CMSampleBufferRef

Declared In

KSYGPUStreamerKit.h

  audioProcessingCallback

音频处理回调接口

@property (nonatomic, copy) void ( ^ ) ( CMSampleBufferRef sampleBuffer ) audioProcessingCallback

Discussion

sampleBuffer 原始采集到的音频数据

对sampleBuffer内的pcm数据的修改将传递到观众端

请注意本函数的执行时间，如果太长可能导致不可预知的问题

当audioDataType 为KSYAudioData_CMSampleBuffer时才会被触发回调

请参考 CMSampleBufferRef

See Also

Declared In

KSYGPUStreamerKit.h

  pcmProcessingCallback

音频处理回调接口

@property (nonatomic, copy) void ( ^ ) ( uint8_t **pData , int len , const AudioStreamBasicDescription *fmt , CMTime timeInfo ) pcmProcessingCallback

Discussion

pData len为原始采集到的音频数据

当audioDataType 为KSYAudioData_RawPCM时才会被触发回调

请注意本函数的执行时间，如果太长可能导致不可预知的问题

See Also

Declared In

KSYGPUStreamerKit.h

  audioDataType

音频处理通路数据类型 (默认为 KSYAudioData_CMSampleBuffer)

@property (nonatomic, assign) KSYAudioDataType audioDataType

Discussion

音频数据转为 CMSampleBuffer时有格式开销, 使用RawPCM资源消耗会少一些

内部组件对KSYAudioData_RawPCM可能不完善, 目前仅保证基本通路能工作

Declared In

KSYGPUStreamerKit.h

  interruptCallback

摄像头采集被打断的消息通知

@property (nonatomic, copy) void ( ^ ) ( BOOL bInterrupt ) interruptCallback

Discussion

bInterrupt 为YES, 表明被打断, 摄像头采集暂停

bInterrupt 为NO, 表明恢复采集

Declared In

KSYGPUStreamerKit.h

– setupFilter:

设置当前使用的滤镜

- (void)setupFilter:(GPUImageOutput<GPUImageInput> *)filter

Discussion

若filter 为nil， 则关闭滤镜

若filter 为GPUImageFilter的实例，则使用该滤镜做处理

filter 也可以是GPUImageFilterGroup的实例，可以将多个滤镜组合

Declared In

KSYGPUStreamerKit.h

  previewMirrored

预览设置成镜像模式，默认为NO

@property (nonatomic, assign) BOOL previewMirrored

Declared In

KSYGPUStreamerKit.h

  streamerMirrored

推流设置成镜像模式,默认为NO

@property (nonatomic, assign) BOOL streamerMirrored

Declared In

KSYGPUStreamerKit.h

  streamerFreezed

推流的画面是否冻结 (默认为NO)

@property (nonatomic, assign) BOOL streamerFreezed

Discussion

通过本属性可以主动将推流的画面固定为当前帧

Declared In

KSYGPUStreamerKit.h

  previewOrientation

预览图像朝向, 如果UI能够旋转,需要保持和UI的朝向一致

@property (nonatomic, assign) UIInterfaceOrientation previewOrientation

Declared In

KSYGPUStreamerKit.h

  streamOrientation

推流图像朝向, 如果UI能够旋转, 可以跟随旋转,也可以不修改

@property (nonatomic, assign) UIInterfaceOrientation streamOrientation

Declared In

KSYGPUStreamerKit.h

– rotatePreviewTo:

根据UI的朝向旋转预览视图, 保证预览视图全屏铺满窗口

- (void)rotatePreviewTo:(UIInterfaceOrientation)orie

Parameters

orie

旋转到目标朝向, 需要从demo中获取UI的朝向传入

Discussion

采集到的图像的朝向还是和启动时的朝向一致

此函数与 previewOrientation的set函数功能一样

Declared In

KSYGPUStreamerKit.h

– rotateStreamTo:

根据UI的朝向旋转推流画面, 这个是可以选的,可以不跟随旋转

- (void)rotateStreamTo:(UIInterfaceOrientation)orie

Parameters

orie

旋转到目标朝向, 需要从demo中获取UI的朝向传入

Discussion

此函数与 streamOrientation 的set函数功能一样

Declared In

KSYGPUStreamerKit.h

  logoPic

水印logo的图片

@property (nonatomic, readwrite) KSYGPUPicture *logoPic

Discussion

设置为nil为清除水印图片

请注意背景图片的尺寸, 太大的图片会导致内存占用过高

Declared In

KSYGPUStreamerKit.h

– setLogoOrientaion:

设置水印图片的朝向

- (void)setLogoOrientaion:(UIImageOrientation)orien

Parameters

orien

图片的朝向

Declared In

KSYGPUStreamerKit.h

– setOrientaion:ofLayer:

设置指定图层的朝向

- (void)setOrientaion:(UIImageOrientation)orien ofLayer:(NSInteger)idx

Parameters

orien

目标朝向
idx

图层的index

Declared In

KSYGPUStreamerKit.h

– setRect:ofLayer:

设置指定图层的大小和位置

- (void)setRect:(CGRect)rect ofLayer:(NSInteger)idx

Parameters

rect

位置+大小
idx

指定图层的index

Declared In

KSYGPUStreamerKit.h

  textPic

文字内容的图片

@property (nonatomic, readwrite) KSYGPUPicture *textPic

Discussion

设置为nil为清除内容图片

Declared In

KSYGPUStreamerKit.h

  aePic

贴纸的图片

@property (nonatomic, readwrite) GPUImageUIElement *aePic

Discussion

设置为nil为清除贴纸图片

Declared In

KSYGPUStreamerKit.h

  logoRect

水印logo的图片的位置和大小

@property (nonatomic, readwrite) CGRect logoRect

Discussion

位置和大小的单位为预览视图的百分比, 左上角为(0,0), 右下角为(1.0, 1.0)

如果宽为0, 则根据图像的宽高比, 和设置的高度比例, 计算得到宽度的比例

如果高为0, 方法同上

Declared In

KSYGPUStreamerKit.h

  logoAlpha

水印logo的图片的位置

@property (nonatomic, readwrite) CGFloat logoAlpha

Discussion

alpha为透明度(0-1),0完全透明，1完全不透明

Declared In

KSYGPUStreamerKit.h

  textLabel

水印文字的label

@property (nonatomic, readwrite) UILabel *textLabel

Discussion

借用UILabel来指定文字的颜色,字体, 透明度, 对齐方式等属性

请注意保证背景图片的尺寸, 太大的图片会导致内存占用过高

Warning: 如果使用非等宽字体, 可能导致闪烁(默认为Courier)

Warning: picMixer和UILabel都有alpha属性, 建议只选用其中一个, 固定另一个为1.0, 为了减少接口, 建议直接使用UILabel的属性, 如果两者同时使用, 最终图层的alpha为两者乘积

See Also

Declared In

KSYGPUStreamerKit.h

  textRect

水印文字的图片的位置和大小

@property (nonatomic, readwrite) CGRect textRect

Discussion

位置和大小的单位为预览视图的百分比, 左上角为(0,0), 右下角为(1.0, 1.0)

如果宽为0, 则根据文字图像的宽高比, 和设置的高度比例, 计算得到宽度的比例

如果高为0, 方法同上

Declared In

KSYGPUStreamerKit.h

– updateTextLabel

刷新水印文字的内容

- (void)updateTextLabel

Discussion

先修改文字的内容或格式,调用该方法后生效

Declared In

KSYGPUStreamerKit.h

– focusAtPoint:

当前采集设备是否支持自动变焦 @param point相机对焦的位置

- (BOOL)focusAtPoint:(CGPoint)point

Return Value

YES / NO

Discussion

通常只有后置摄像头支持自动变焦

Declared In

KSYGPUStreamerKit.h

– exposureAtPoint:

当前采集设备是否支持自动曝光 @param point相机曝光的位置

- (BOOL)exposureAtPoint:(CGPoint)point

Return Value

YES / NO

Discussion

通常前后置摄像头都支持自动曝光

Declared In

KSYGPUStreamerKit.h

  pinchZoomFactor

触摸缩放因子

@property (nonatomic, assign) CGFloat pinchZoomFactor

Declared In

KSYGPUStreamerKit.h

  stabilizationMode

摄像头防抖模式，切换摄像头后需要进行重新设置

@property (nonatomic, assign) AVCaptureVideoStabilizationMode stabilizationMode

Discussion

(iPhone前置摄像头不支持防抖功能)

Declared In

KSYGPUStreamerKit.h

  streamerProfile

采集和推流配置参数

@property (nonatomic, assign) KSYStreamerProfile streamerProfile

Discussion

选择profile类型后, 采集和编码参数会自动配置进去, 默认的profile类型是KSYStreamerProfile_540p_3

Declared In

KSYGPUStreamerKit.h

– processMessageData:

用户待发送的消息 @param messageData待发送的消息

- (BOOL)processMessageData:(NSDictionary *)messageData

Return Value

YES / NO

Declared In

KSYGPUStreamerKit.h

bgp Methods

  bgPic

@property (nonatomic, retain) KSYGPUPicture *bgPic

– updateBgpImage:

更新背景图片

- (void)updateBgpImage:(UIImage *)img

Parameters

img

新的背景图片

Declared In

KSYGPUStreamerKit+bgp.h

– startBgpPreview:

开始背景图预览

- (BOOL)startBgpPreview:(UIView *)bgView

Parameters

bgView

预览视图的背景图, 预览视图会填满背景视图 结束预览仍然使用之前的 stopPreview

Declared In

KSYGPUStreamerKit+bgp.h

– startBgpStream:

开始背景图推流

- (BOOL)startBgpStream:(NSURL *)url

Parameters

url

推流地址

Return Value

当前状态是否能开始推流

Declared In

KSYGPUStreamerKit+bgp.h

– stopBgpStream

停止背景图推流

- (void)stopBgpStream

Declared In

KSYGPUStreamerKit+bgp.h