TXLivePush

最近更新时间:2020-07-09 11:15:11

功能

直播推流类。

介绍

主要负责将本地的音视频画面进行编码和 RTMP 推送,包含如下技术特点:

  • 针对腾讯云的推流地址,会采用 QUIC 协议进行加速,配合改进后的 BBR2 带宽测算方案,可以最大限度的利用主播的上行带宽,降低直播卡顿率。
  • 内嵌套的 Qos 流量控制技术具备上行网络自适应能力,可以根据主播端网络的具体情况实时调节音视频数据量。
  • 内嵌多套美颜磨皮算法(自然&光滑)和多款色彩空间滤镜(支持自定义滤镜),可以根据需要自行选择。
  • 企业版 SDK 包含了大眼、瘦脸以及隆鼻等功能,配合高级美颜动效素材,可快速地完成功能集成。
  • 支持自定义的音视频采集和渲染,让您可以根据项目需要选择自己的音视频数据源。

SDK 基础函数

config

设置 TXLivePushConfig 推流配置项,见TXLivePushConfig.h文件中的详细定义。

@property (nonatomic, copy) TXLivePushConfig * config

delegate

设置推流回调接口,见TXLivePushListener.h文件中的详细定义。

@property (nonatomic, weak) id< TXLivePushListener > delegate

initWithConfig

创建 TXLivePusher 示例。

- (id)initWithConfig:(TXLivePushConfig *)config 

参数

参数 类型 含义
config TXLivePushConfig * TXLivePushConfig 推流配置项,见TXLivePushConfig.h文件中的详细定义。

推流基础接口

rtmpURL

获取当前推流的 RTMP 地址。

@property (nonatomic, readonly, assign) NSString * rtmpURL

startPreview

启动摄像头预览。

- (int)startPreview:(TXView *)view 

参数

参数 类型 含义
view TXView * 承载视频画面的控件。

介绍

启动预览后并不会立刻开始 RTMP 推流,需要调用 startPush 才能真正开始推流。


stopPreview

停止摄像头预览。

- (void)stopPreview

startPush

启动 RTMP 推流。

- (int)startPush:(NSString *)rtmpURL 

参数

参数 类型 含义
rtmpURL NSString * 推流地址,请参见 获取推流地址

返回

0:启动成功;-1:启动失败;-5:license 校验失败。

介绍

针对腾讯云的推流地址,会采用 QUIC 协议进行加速,配合改进后的 BBR2 带宽测算方案,可以最大限度的利用主播的上行带宽,降低直播卡顿率。

说明:

-5返回码代表 license 校验失败,TXLivePusher 需要 license校验通过才能工作。


stopPush

停止 RTMP 推流。

- (void)stopPush

pausePush

暂停摄像头采集并进入垫片推流状态。

- (void)pausePush

介绍

SDK 会暂时停止摄像头采集,并使用 TXLivePushConfig.pauseImg 中指定的图片作为替代图像进行推流,也就是所谓的“垫片”。 这项功能常用于 App 被切到后台运行的场景,尤其是在 iOS 系统中,当 App 切到后台以后,操作系统不会再允许该 App 继续使用摄像头。 此时就可以通过调用 pausePush 进入垫片状态。
对于绝大多数推流服务器而言,如果超过一定时间不推视频数据,服务器会断开当前的推流链接。
TXLivePushConfig 您可以指定:

  • pauseImg 设置后台推流的默认图片,默认为黑色背景。
  • pauseFps 设置后台推流帧率,最小值为5,最大值为20,默认为10。
  • pauseTime 设置后台推流持续时长,单位秒,默认300秒。
说明:

请注意调用顺序:startPush => ( pausePush => resumePush ) => stopPush,错误的调用顺序会导致 SDK 表现异常。


resumePush

恢复摄像头采集并结束垫片推流状态。

- (void)resumePush

isPublishing

查询是否正在推流。

- (bool)isPublishing

返回

YES:推流中;NO:没有在推流。


视频相关接口

frontCamera

查询当前是否为前置摄像头。

@property (nonatomic, readonly, assign) BOOL frontCamera

setVideoQuality

设置视频编码质量。

- (void)setVideoQuality:(TX_Enum_Type_VideoQuality)quality adjustBitrate:(BOOL)adjustBitrate adjustResolution:(BOOL)adjustResolution 

参数

参数 类型 含义
quality TX_Enum_Type_VideoQuality 画质类型(标清,高清,超高清)。
adjustBitrate BOOL 动态码率开关。
adjustResolution BOOL 动态切分辨率开关。

介绍

推荐设置:秀场直播 quality:HIGH_DEFINITION;adjustBitrate:NO;adjustResolution:NO。请参见 设定清晰度

说明:

adjustResolution 早期被引入是为了让 TXLivePusher 能够满足视频通话这一封闭场景下的一些需求,现已不推荐使用。 如果您有视频通话的需求,可以使用我们专门为视频通话打造的 TRTC 服务。 由于目前很多 H5 播放器不支持分辨率动态变化,所以开启分辨率自适应以后,会导致 H5 播放端和录制文件的很多兼容问题。


switchCamera

切换前后摄像头(iOS)。

- (int)switchCamera

selectCamera

选择摄像头(macOS)。

- (void)selectCamera:(AVCaptureDevice *)camera 

setMirror

设置视频镜像效果。

- (void)setMirror:(BOOL)isMirror 

参数

参数 类型 含义
isMirror BOOL YES:播放端看到的是镜像画面;NO:播放端看到的是非镜像画面。

介绍

由于前置摄像头采集的画面是取自手机的观察视角,如果将采集到的画面直接展示给观众,是完全没有问题的。 但如果将采集到的画面也直接显示给主播,则会跟主播照镜子时的体验完全相反,会让主播感觉到很奇怪。 因此,SDK 会默认开启本地摄像头预览画面的镜像效果,让主播直播时跟照镜子时保持一个体验效果。
setMirror 所影响的则是观众端看到的视频效果,如果想要保持观众端看到的效果跟主播端保持一致,需要开启镜像; 如果想要让观众端看到正常的未经处理过的画面(如主播弹吉他的时候有类似需求),则可以关闭镜像。


setRenderRotation

设置本地摄像头预览画面的旋转方向。

- (void)setRenderRotation:(int)rotation 

参数

参数 类型 含义
rotation int 取值为0、90、180和270(其他值无效),表示主播端摄像头预览视频的顺时针旋转角度。

介绍

该接口仅能够改变主播本地预览画面的方向,而不会改变观众端的画面效果。 如果希望改变观众端看到的视频画面的方向,例如原来是540 × 960,希望变成960 × 540,则可以通过设置 TXLivePushConfig 中的 homeOrientation 来实现。

// 竖屏推流(HOME 键在下)
_config.homeOrientation = HOME_ORIENTATION_DOWN;
[_txLivePublisher setConfig:_config];
[_txLivePublisher setRenderRotation:0];
// 横屏推流(HOME 键在右)
_config.homeOrientation = HOME_ORIENTATION_RIGHT;
[_txLivePublisher setConfig:_config];
[_txLivePublisher setRenderRotation:90];

toggleTorch

打开后置摄像头旁边的闪关灯。

- (BOOL)toggleTorch:(BOOL)bEnable 

参数

参数 类型 含义
bEnable BOOL YES:打开;NO:关闭。

返回

YES:打开成功;NO:打开失败。

介绍

此操作对于前置摄像头是无效的,因为绝大多数手机都没有给前置摄像头配置闪光灯。


setZoom

调整摄像头的焦距。

- (void)setZoom:(CGFloat)distance 

参数

参数 类型 含义
distance CGFloat 焦距大小,取值范围:1 - 5,默认值建议设置为1即可。
说明:

当 distance 为1的时候为最远视角(正常镜头),当为5的时候为最近视角(放大镜头),最大值不要超过5,超过5后画面会模糊不清。


setFocusPosition

设置手动对焦区域。

- (void)setFocusPosition:(CGPoint)touchPoint 

介绍

SDK 默认使用摄像头自动对焦功能,您也可以通过 TXLivePushConfig 中的 touchFocus 选项关闭自动对焦,改用手动对焦。 改用手动对焦之后,需要由主播自己单击摄像头预览画面上的某个区域,来手动指导摄像头对焦。

说明:

早期 SDK 版本仅仅提供了手动和自动对焦的选择开关,并不支持设置对焦位置,3.0版本以后,手动对焦的接口才开放出来。


美颜相关接口

getBeautyManager

获取美颜管理对象 TXBeautyManager

- (TXBeautyManager *)getBeautyManager 

通过美颜管理,您可以使用以下功能:

  • 设置”美颜风格”、”美白”、“红润”、“大眼”、“瘦脸”、“V脸”、“下巴”、“短脸”、“小鼻”、“亮眼”、“白牙”、“祛眼袋”、“祛皱纹”、“祛法令纹”等美容效果。
  • 调整“发际线”、“眼间距”、“眼角”、“嘴形”、“鼻翼”、“鼻子位置”、“嘴唇厚度”、“脸型”。
  • 设置人脸挂件(素材)等动态效果。
  • 添加美妆。
  • 进行手势识别。

音频相关接口

setMute

开启静音。

- (void)setMute:(BOOL)bEnable 

参数

参数 类型 含义
bEnable BOOL 是否开启静音。

介绍

开启静音后,SDK 并不会继续采集麦克风的声音,但是会用非常低(5kbps左右)的码率推送伪静音数据, 这样做的目的是为了兼容 H5 上的 video 标签,并让录制出来的 MP4 文件有更好的兼容性。


playBGM

播放背景音乐。

- (BOOL)playBGM:(NSString *)path 

参数

参数 类型 含义
path NSString * 本地音乐文件路径。

返回

YES:成功;NO:失败。

介绍

SDK 会将背景音乐和麦克风采集的声音进行混合并一起推送到云端。


playBGM

播放背景音乐(高级版本)。

- (BOOL)playBGM:(NSString *)path withBeginNotify:(void(^)(NSInteger errCode))beginNotify withProgressNotify:(void(^)(NSInteger progressMS, NSInteger durationMS))progressNotify andCompleteNotify:(void(^)(NSInteger errCode))completeNotify 

参数

参数 类型 含义
path NSString * 本地音乐文件路径。
beginNotify void(^)(NSInteger errCode) 播放开始的回调。
progressNotify void(^)(NSInteger progressMS, NSInteger durationMS) 播放进度回调。
completeNotify void(^)(NSInteger errCode) 播放完毕回调。

返回

YES:成功;NO:失败。


stopBGM

停止播放背景音乐。

- (BOOL)stopBGM

pauseBGM

暂停播放背景音乐。

- (BOOL)pauseBGM

resumeBGM

继续播放背景音乐。

- (BOOL)resumeBGM

getMusicDuration

获取背景音乐文件的总时长,单位是毫秒。

- (int)getMusicDuration:(NSString *)path 

参数

参数 类型 含义
path NSString * 音乐文件路径,如果 path 为空,那么返回当前正在播放的背景音乐的时长。

setBGMVolume

设置混音时背景音乐的音量大小,仅在播放背景音乐混音时使用。

- (BOOL)setBGMVolume:(float)volume 

参数

参数 类型 含义
volume float 音量大小,1为正常音量,范围是0 - 1之间的浮点数。

返回

YES:成功;NO:失败。


setMicVolume

设置混音时麦克风音量大小,仅在播放背景音乐混音时使用。

- (BOOL)setMicVolume:(float)volume 

参数

参数 类型 含义
volume float 音量大小,1为正常音量,范围是0 - 1之间的浮点数。

返回

YES:成功;NO:失败。


setBgmPitch

调整背景音乐的音调高低。

- (BOOL)setBgmPitch:(float)pitch 

参数

参数 类型 含义
pitch float 音调,默认值是0.0f,范围是-1 - 1之间的浮点数。

返回

YES:成功;NO:失败。


setReverbType

设置混响效果。

- (BOOL)setReverbType:(TXReverbType)reverbType 

参数

参数 类型 含义
reverbType TXReverbType 混响类型,详见TXLiveSDKTypeDef.h中的 TXReverbType 定义。

返回

YES:成功;NO:失败。


setVoiceChangerType

设置变声类型。

- (BOOL)setVoiceChangerType:(TXVoiceChangerType)voiceChangerType 

参数

参数 类型 含义
voiceChangerType TXVoiceChangerType 混响类型,详见TXLiveSDKTypeDef.h中的 voiceChangerType 定义。

返回

YES:成功;NO:失败。


本地录制接口

recordDelegate

录制回调接口,详见TXLiveRecordTypeDef.h中的 TXLiveRecordListener 定义。

@property (nonatomic, weak) id< TXLiveRecordListener > recordDelegate

startRecord

开始录制短视频。

- (int)startRecord:(NSString *)videoPath 

参数

参数 类型 含义
videoPath NSString * 视频录制后存储路径。

返回

0:成功;-1:videoPath 为空;-2:上次录制尚未结束,请先调用 stopRecord;-3:推流尚未开始。

说明:

  1.  只有启动推流后才能开始录制,非推流状态下启动录制无效。
  2.  出于安装包体积的考虑,仅专业版和商业版两个版本的 LiteAVSDK 支持该功能,直播精简版仅定义了接口但并未实现。
  3.  录制过程中请勿动态切换分辨率和软硬编,会有很大概率导致生成的视频异常。

stopRecord

- (int)stopRecord

返回

0:成功;-1:不存在录制任务。


snapshot

推流过程中本地截图。

- (void)snapshot:(void(^)(TXImage *))snapshotCompletionBlock 

参数

参数 类型 含义
snapshotCompletionBlock void(^)(TXImage *) 截图完成的回调函数。

自定义采集和处理

videoProcessDelegate

自定义视频处理回调。

@property (nonatomic, weak) id< TXVideoCustomProcessDelegate > videoProcessDelegate

介绍

自定义视频采集和自定义视频处理不能同时开启,与自定义视频采集不同,自定义视频处理依然是由 SDK 采集摄像头的画面, 但 SDK 会通过 TXVideoCustomProcessDelegate(见TXVideoCustomProcessDelegate.h)回调将数据回调给您的 App 进行二次加工。
如果要开启自定义视频处理,需要给 TXLivePushConfig 中的 customModeType 属性增加 CUSTOM_MODE_VIDEO_PREPROCESS 选项。

说明:

出于性能和稳定性考虑,一般不建议开启此特性。


audioProcessDelegate

自定义音频处理回调。

@property (nonatomic, weak) id< TXAudioCustomProcessDelegate > audioProcessDelegate

介绍

自定义音频采集和自定义音频处理不能同时开启,与自定义音频采集不同,自定义音频处理依然是由 SDK 采集麦克风的声音, 但 SDK 会通过 TXAudioCustomProcessDelegate(见TXAudioCustomProcessDelegate.h)回调将数据回调给您的 App 进行二次加工。
如果要开启自定义音频处理,需要给 TXLivePushConfig 中的 customModeType 属性增加 CUSTOM_MODE_AUDIO_PREPROCESS 选项。

说明:

出于性能和稳定性考虑,一般不建议开启此特性。


sendVideoSampleBuffer

自定义视频采集,向 SDK 发送自己采集的视频数据。

- (void)sendVideoSampleBuffer:(CMSampleBufferRef)sampleBuffer 

参数

参数 类型 含义
sampleBuffer CMSampleBufferRef 向 SDK 发送的 SampleBuffer。

介绍

在自定义视频采集模式下,SDK 不再继续从摄像头采集图像,只保留编码和发送能力,您需要定时地发送自己采集的 SampleBuffer。 要开启自定义视频采集,需要完成如下两个步骤:

  1. 开启自定义采集:给 TXLivePushConfig 中的 customModeType 属性增加 CUSTOM_MODE_VIDEO_CAPTURE 选项,代表开启自定义视频采集。
  2. 设定视频分辨率:将 TXLivePushConfig 中的 sampleBufferSize 属性设置为您期望的分辨率。 如果期望编码分辨率跟采集分辨率一致,可以不设置 sampleBufferSize 属性,而是将 autoSampleBufferSize 设置为 YES。
说明:

  1. 开启自定义视频采集后,即无需再调用 startPreview 来开启摄像头采集。
  2. SDK 内部有简单的帧率控制,如果发送太快时 SDK 会自动丢弃多余的帧率;如果超时不发送,SDK 会不断地重复发送最后一帧。

sendCustomPCMData

自定义音频采集,向 SDK 发送自己采集的音频 PCM 数据。

- (void)sendCustomPCMData:(unsigned char *)data len:(unsigned int)len 

参数

参数 类型 含义
data unsigned char * 要发送的 PCM buffer。
len unsigned int 数据长度。

介绍

在自定义音频采集模式下,SDK 不再继续从麦克风采集声音,只保留编码和发送能力,您需要定时地发送自己采集的声音数据(PCM 格式) 要开启自定义音频采集,需要完成如下两个步骤:

  1. 开启自定义采集:给 TXLivePushConfig 中的 customModeType 属性增加 CUSTOM_MODE_AUDIO_CAPTURE 选项,代表开启自定义音频采集。
  2. 设定音频采样率:将 TXLivePushConfig 中的 audioSampleRate 属性设置为您期望的音频采样率,audioChannels 设置为期望的声道数,默认值:1(单声道)。
说明:

SDK 对每次传入的 PCM buffer 大小有严格要求,每一个采样点要求是16位宽。 如果是单声道,请保证传入的 PCM 长度为2048;如果是双声道,请保证传入的 PCM 长度为4096。


sendAudioSampleBuffer

自定义音频采集,向 SDK 发送自己采集的音频数据。

- (void)sendAudioSampleBuffer:(CMSampleBufferRef)sampleBuffer withType:(RPSampleBufferType)sampleBufferType 

参数

参数 类型 含义
sampleBuffer CMSampleBufferRef 采集到的声音 sampleBuffer。
sampleBufferType RPSampleBufferType RPSampleBufferTypeAudioApp:ReplayKit 采集到的 App 声音。RPSampleBufferTypeAudioMic:ReplayKit 采集到的麦克风声音。

介绍

相比于 sendCustomPCMData,sendAudioSampleBuffer 主要用于 ReplayKit 录屏推流的场景。 要开启自定义音频采集,需要完成如下两个步骤:

  1. 开启自定义采集:给 TXLivePushConfig 中的 customModeType 属性增加 CUSTOM_MODE_AUDIO_CAPTURE 选项,代表开启自定义音频采集。
  2. 设定音频采样率:将 TXLivePushConfig 中的 audioSampleRate 属性设置为您期望的音频采样率,audioChannels 设置为期望的声道数,默认值:1(单声道)。

当使用 ReplayKit 做录屏推流时,iOS 的 ReplayKit 接口会回调两种类型的声音数据:

  • RPSampleBufferTypeAudioApp,也就是要录制的 App 的声音数据。
  • RPSampleBufferTypeAudioMic,也就是要录制的麦克风的声音数据。

当您通过 sendAudioSampleBuffer 向 SDK 调用各种类型的声音数据时,SDK 内部会进行混流,否则只会发送一路的声音数据。


setSendAudioSampleBufferMuted

要求 SDK 发送静音数据。

- (void)setSendAudioSampleBufferMuted:(BOOL)muted 

参数

参数 类型 含义
muted BOOL YES;静音;NO;关闭静音。

介绍

该函数配合 sendAudioSampleBuffer 使用,在 InApp 类型录制切后台场合时需要调用,系统屏幕录制不需要。


更多实用接口

sendMessageEx

发送 SEI 消息,播放端(TXLivePlayer)通过 onPlayEvent(EVT_PLAY_GET_MESSAGE)来接收该消息。

- (BOOL)sendMessageEx:(NSData *)data 

介绍

本接口是将数据直接塞入视频数据头中,因此不能太大(几个字节比较合适),一般常用于塞入自定义时间戳等信息。

说明:

  • sendMessage 已经不推荐使用,会导致 H5 播放器产生兼容性问题,请使用 sendMessageEx。
  • 若您使用过 sendMessage,不推荐立刻升级到 sendMessageEx。
  • sendMessageEx 发送消息给旧版本5.0及以前的 SDK 版本时,消息会无法正确解析,但播放不受影响。

sendMessage

- (void)sendMessage:(NSData *)data 

showVideoDebugLog

打开包含视频状态信息的调试浮层,该浮层一般用于 SDK 调试期间,外发版本请不要打开。

- (void)showVideoDebugLog:(BOOL)isShow 

setLogViewMargin

设置调试浮层在视频 view 上的位置。

- (void)setLogViewMargin:(TXEdgeInsets)margin 

setEnableClockOverlay

设置推流是否覆盖时钟。

- (void)setEnableClockOverlay:(BOOL)enabled 
说明:

需要双方的时间相同才能获取准确的延迟时间。


enableClockOverlay

获取当前推流画面是否有覆盖时钟。

- (BOOL)enableClockOverlay

目录