基础功能

本章节为您介绍推流基础功能的接入方法，根据文档提供的操作步骤进行配置，您可接入直播推流能力。

前提条件

• 已完成iOS 推流 SDK 集成；
• 已完成iOS 推流 SDK 初始化。

注意事项

真机调试：由于 SDK 使用了大量 iOS 系统的音视频接口，这些接口在仿真模拟器下可能会出现异常，推荐您使用真机进行代码调试。

功能接入

本节问您详细介绍如何通过推流 SDK 实现直播推流控制的能力，包括但不限于创建推流引擎、初始化配置、事件监听、配置渲染视图、配置推流地址。

初始化配置

本节为您介绍创建推流引擎初始化配置方法。

1. 引入头文件。

   说明

   SDK 的集成方法不同，引入的头文件的方式存在差异。

   • 静态库集成：TTSDK 以静态库集成方式接入时，引入方式如下所示：

     #import <TTSDK/VeLivePusher.h>
     

   • 动态库集成：TTSDK 以动态库集成方式接入时，引入方式如下所示：

     #import <TTSDKFramework/VeLivePusher.h>
     

2. 初始化推流引擎配置。

   通过修改参数属性值，配置推流引擎的视频采集参数和音频采集参数。每个参数均有默认值，您可以使用默认配置，也可以根据业务场景进行修改，关于参数含义和默认值请参见注释。

   • 视频采集配置

     VeLiveVideoCaptureConfiguration *videoCaptureConfig = [[VeLiveVideoCaptureConfiguration alloc] init];
     // 视频采集宽度，单位为 px，默认值为 720。
     videoCaptureConfig.width = 720;
     // 视频采集高度，单位为 px，默认值为 1280。
     videoCaptureConfig.height = 1280;
     // 视频采集帧率，单位为 fps，默认值为 15。
     videoCaptureConfig.fps = 15;
     

   • 音频采集配置

     VeLiveAudioCaptureConfiguration *audioCaptureConfig = [[VeLiveAudioCaptureConfiguration alloc] init];
     // 音频采样率，默认值为 `VeLiveAudioSampleRate44100`
     audioCaptureConfig.sampleRate = VeLiveAudioSampleRate44100;
     // 音频采集声道数，默认值为 `VeLiveAudioChannelStereo`
     audioCaptureConfig.channel = VeLiveAudioChannelStereo;
     

   • 推流引擎配置

     VeLivePusherConfiguration *config = [[VeLivePusherConfiguration alloc] init];
     // 推流失败后，尝试重连的次数。默认值为 3。
     config.reconnectCount = 3;
     // 推流失败后，尝试重连的时间间隔。单位为 s，默认值为 5。
     config.reconnectIntervalSeconds = 5;
     // 视频采集参数设置
     config.videoCaptureConfig = videoCaptureConfig;
     // 音频采集参数设置
     config.audioCaptureConfig = audioCaptureConfig;
     

创建引擎

本节为您介绍创建推流引擎的方法，需要您提前完成初始化配置。代码示例如下所示：

self.livePusher = [[VeLivePusher alloc] initWithConfig:config];

配置事件监听

本节为您介绍推流引擎的事件监听方式。代码示例如下所示：

// 设置推流引擎基础事件回调监听
[self.livePusher setObserver:self];
// 设置周期性信息回调监听
[self.livePusher setStatisticsObserver:self interval:3];
	 
// 添加视频帧回调监听
[self.livePusher addVideoFrameListener:self];
// 移除视频帧回调监听
[self.livePusher removeVideoFrameListener:self];
	 
// 添加音频帧回调监听
[self.livePusher addAudioFrameListener:self];
// 移除音频帧回调监听
[self.livePusher removeAudioFrameListener:self];

配置预览视图

如果您使用推流引擎自带的预览视图，需要调用下面方法进行配置。

[self.livePusher setRenderView:self.view];

配置本地预览填充模式

如果您需要设置本地预览填充模式，可调用 setRenderFillMode: 方法进行配置。填充模式默认值 VeLivePusherRenderModeFill，即视频帧自适应画布的填充模式，更多填充模式说明请参见 VeLivePusherRenderMode。

[self.livePusher setRenderFillMode:VeLivePusherRenderModeFill];

配置镜像方案

如果您需要使用镜像，我们提供了 3 种镜像方案供您选择。

• 采集镜像

  本功能会在采集时就对视频帧进行镜像效果处理，预览和推流都会产生镜像效果。代码示例如下所示：

  [self.livePusher setVideoMirror:(VeLiveVideoMirrorCapture) enable:YES];
  

• 本地预览镜像

  本功能会镜像本地的预览视图，不影响采集和推流。代码示例如下所示：

  [self.livePusher setVideoMirror:(VeLiveVideoMirrorPreview) enable:YES];
  

• 推流镜像

  本功能会镜像编码前的视频帧，不影响预览和采集。代码示例如下所示：

  [self.livePusher setVideoMirror:(VeLiveVideoMirrorPushStream) enable:YES];
  

视频采集控制

为了适应多种业务需求，我们提供了 6 种视频采集模式，并且可以在采集模式之间进行切换。

• 前置摄像头采集

  本功能启用前置摄像头采集功能。代码示例如下所示：

  // 开启前置摄像头采集
  [self.livePusher startVideoCapture:(VeLiveVideoCaptureFrontCamera)];
  // 切换至前置摄像头采集
  [self.livePusher switchVideoCapture:(VeLiveVideoCaptureFrontCamera)];
  

• 后置摄像头采集

  本功能启用后置摄像头采集功能。代码示例如下所示：

  // 开启后置摄像头采集
  [self.livePusher startVideoCapture:(VeLiveVideoCaptureBackCamera)];
  // 切换至后置摄像头采集
  [self.livePusher switchVideoCapture:(VeLiveVideoCaptureBackCamera)];
  

• 外部视频采集

  当您不需要使用推流引擎自带的视频采集能力时，可以开启外部视频采集，更多详情请参考外部采集源推流。代码示例如下所示：

  注意

  当您开启了外部视频采集，需要调用 [self.livePusher pushExternalVideoFrame:VeLiveVideoFrame.new]; 送入视频帧数据。

  // 开始外部视频采集
  [self.livePusher startVideoCapture:(VeLiveVideoCaptureExternal)];
  // 切换至外部视频采集
  [self.livePusher switchVideoCapture:(VeLiveVideoCaptureExternal)];
  

• 自定义图片

  自定义图片模式支持您使用自定义图片作为视频源进行直播，或在主播 App 进入后台时使用自定义图片作为视频源。更多详情请参考图片推流

  注意

  在使用本接口之前，您需要先调用 [self.livePusher updateCustomImage:[UIImage new]]; 更新自定义图片。

  代码示例如下所示：：

  // 开始自定义图片推流
  [self.livePusher startVideoCapture:(VeLiveVideoCaptureCustomImage)];
  // 切换至自定义图片推流
  [self.livePusher switchVideoCapture:(VeLiveVideoCaptureCustomImage)];
  

• 尾帧

  当主播 App 进入后台时，您可以使用最近采集的最后一帧图像作为视频源继续进行直播。代码示例如下所示：

  注意

  使用尾帧作为视频源，前提必须至少要有一个视频帧数据传入给推流引擎。一般情况下都是从其它采集类型切换至尾帧。

  // 切换至尾帧推流
  [self.livePusher switchVideoCapture:(VeLiveVideoCaptureLastFrame)];
  

• 黑帧

  当主播 App 进入后台时，您可以使用纯黑色视频帧继续进行直播。代码示例如下所示：

  // 开始黑帧推流
  [self.livePusher startVideoCapture:(VeLiveVideoCaptureDummyFrame)];
  // 切换至黑帧推流
  [self.livePusher switchVideoCapture:(VeLiveVideoCaptureDummyFrame)];
  

音频采集控制

为了适应多种业务需求，我们提供了 3 种音频采集模式，并且可以在采集模式之间进行切换。

• 麦克风采集

  使用推流引擎自带的麦克风采集能力。代码示例如下所示：

  // 开启麦克风采集
  [self.livePusher startAudioCapture:(VeLiveAudioCaptureMicrophone)];
  // 切换至麦克风采集
  [self.livePusher switchAudioCapture:(VeLiveAudioCaptureMicrophone)];
  

• 外部采集

  当您不需要使用推流引擎自带的麦克风采集能力时，您可以自行采集音频数据并送入推流引擎中。代码示例如下所示：

  注意

  开启了外部音频采集，需要调用 [self.livePusher pushExternalAudioFrame:VeLiveAudioFrame.new]; 送入音频帧数据。

  // 开启外部音频采集
  [self.livePusher startAudioCapture:(VeLiveAudioCaptureExternal)];
  // 切换至外部音频采集
  [self.livePusher switchAudioCapture:(VeLiveAudioCaptureExternal)];
  

• 静音帧

  当您只需要进行视频直播而不需要音频时，可以开启音频静音采集。代码示例如下所示：

  说明

  主播使用静音帧采集和开启静音，在观众端看到的效果一致。区别在于静音帧采集不会真正启用设备的音频采集能力。

  // 开启静音帧
  [self.livePusher startAudioCapture:(VeLiveAudioCaptureMuteFrame)];
  // 切换至静音帧
  [self.livePusher switchAudioCapture:(VeLiveAudioCaptureMuteFrame)];
  

视频编码参数控制

您可以通过调用 setVideoEncoderConfiguration: 设置视频编码参数。您可以在推流开始后通过该接口动态修改分辨率和码率。我们为您提供了不同清晰度的最佳视频编码参数，您也可以根据您的需求进行调整。代码示例如下所示：

VeLiveVideoEncoderConfiguration *videoEncoderConfig = [[VeLiveVideoEncoderConfiguration alloc] initWithResolution:(VeLiveVideoResolution720P)];
// 推流视频编码格式，默认值为 VeLiveVideoCodecH264
videoEncoderConfig.codec = VeLiveVideoCodecH264;
// 视频目标编码码率，单位为 kbps，默认值为 1200。
videoEncoderConfig.bitrate = 1200;
// 视频最小编码码率，单位为 kbps，默认值为 800；如果开启自适应码率，推流 SDK 根据网络情况，进行编码码率自适应的最小码率。
videoEncoderConfig.minBitrate = 800;
// 视频最大编码码率，单位为 kbps，默认值为 1900；如果开启自适应码率，推流 SDK 根据网络情况，进行编码码率自适应的最大码率。
videoEncoderConfig.maxBitrate = 1900;
// 视频 GOP 大小，单位为 s，默认值为 2。
videoEncoderConfig.gopSize = 2;
// 视频编码帧率，单位为 fps，默认值为 15。
videoEncoderConfig.fps = 15;
// 是否启用 B 帧，默认值为 NO
videoEncoderConfig.enableBFrame = NO;
// 是否开启硬件编码，默认值为 YES
videoEncoderConfig.enableAccelerate = YES;
// 配置编码参数
[self.livePusher setVideoEncoderConfiguration:videoEncoderConfig];

音频编码参数控制

我们为您提供了一套最佳音频编码参数配置，您也可以根据您的需求进行调整。代码示例如下所示：

VeLiveAudioEncoderConfiguration *audioEncoderConfig = [[VeLiveAudioEncoderConfiguration alloc] init];
// 音频编码码率，单位为 kbps，默认值为 64。
audioEncoderConfig.bitrate = 64;
// 音频编码采样率，默认值为 VeLiveAudioSampleRate44100
audioEncoderConfig.sampleRate = VeLiveAudioSampleRate44100;
// 音频声道数，默认值为 VeLiveAudioChannelStereo
audioEncoderConfig.channel = VeLiveAudioChannelStereo;
// AAC 编码类型，默认值为 VeLiveAudioAACProfileLC
audioEncoderConfig.profile = VeLiveAudioAACProfileLC;
// 配置音频编码参数
[self.livePusher setAudioEncoderConfiguration:audioEncoderConfig];

美颜控制

美颜特效是直播场景的基础功能，视频直播 SDK 内置了美颜特效 CV SDK 的相关接口，帮助您完成美颜特效能力的快速接入。在开始对接前，请先联系商务，获取对应版本的 CV SDK（推荐使用 4.2.3 及以上版本）、授权文件 License 和特效资源包。

• 初始化美颜管理器

  // 注意：本方法只在工程中集成过智能美化特效的SDK时生效
  VeLiveVideoEffectManager *effectManager = [self.livePusher getVideoEffectManager];
  // 特效鉴权License路径，请根据工程配置查找正确的路径
  NSString *licensePath = @"LicenseBag.bundle/xxx.licbag";
  // 特效模型资源包路径
  NSString *algoModelPath = @"ModelResource.bundle";
  // 创建美颜配置
  VeLiveVideoEffectLicenseConfiguration *licConfig = [[VeLiveVideoEffectLicenseConfiguration alloc] initWithPath:licensePath];
  // 设置美颜配置
  [effectManager setupWithConfig:licConfig];
  // 设置算法包路径
  [effectManager setAlgoModelPath:algoModelPath];
  
  // 开启美颜特效处理
  if ([effectManager setEnable:YES] != 0) {
      NSLog(@"美颜 License 无效，请检查路径是否正确或者是否已经过期");
  }
  

• 设置美颜特效

  • 设置美颜美型

    NSString *beautyPath = [NSBundle.mainBundle pathForResource:@"ComposeMakeup.bundle/xxx" ofType:nil];
    // 设置美颜美型特效资源包
    [self.livePusher.getVideoEffectManager setComposeNodes:@[beautyPath]];
    // 设置美颜美型特效强度, NodeKey 可在 资源包下的 .config_file 中获取，如果没有 .config_file ，请联系商务咨询
    [self.livePusher.getVideoEffectManager updateComposerNodeIntensity:beautyPath nodeKey:@"whiten" intensity:0.5];
    

  • 设置滤镜

    NSString *filterPath = [NSBundle.mainBundle pathForResource:@"FilterResource.bundle/xxx" ofType:nil];
    // 设置滤镜资源包路径
    [self.livePusher.getVideoEffectManager setFilter:filterPath];
    // 设置滤镜特效强度
    [self.livePusher.getVideoEffectManager updateFilterIntensity:0.5];
    

  • 设置贴纸

    NSString *stickerPath = [NSBundle.mainBundle pathForResource:@"StickerResource.bundle/xxx" ofType:nil];
    // 设置贴纸资源包路径
    [self.livePusher.getVideoEffectManager setSticker:stickerPath];
    

水印控制

支持半透明水印，您可以根据需要设置半透明的PNG图片。代码示例如下所示：

// [UIImage new]，创建一个空的UIImage对象作为水印图片，实际应用中，可替换成一个实际的图像对象；取值为 null 时，表示禁用水印
// x：水印的水平偏移量，即水印图片相对视频流左上角的横向偏移与视频流宽度的比值，0.2 表示水印在视频宽度的 20% 处水平偏移，取值范围为 [0.0,1.0]
// y：水印的垂直偏移量，即水印图片相对视频流左上角的纵向偏移与视频流高度的比值，0.3 表示水印在视频高度的 30% 处垂直偏移，取值范围为 [0.0,1.0]
// scale：水印图片的缩放比例，1.0表示不进行缩放，保持原始大小，取值范围为 [0.0,1.0]
[self.livePusher setWatermark:[UIImage new] x:0.2 y:0.3 scale:1.0];

相机控制

在使用推流引擎自带的摄像头采集时，我们提供了多种相机控制能力。代码示例如下所示：

• 闪光灯

  // 是否支持闪光灯
  if (self.livePusher.getCameraDevice.isTorchSupported) {
  	// 开启闪光灯
  	[self.livePusher.getCameraDevice enableTorch:YES];
  	// 关闭闪光灯
  	[self.livePusher.getCameraDevice enableTorch:NO];
  }
  

• 摄像头缩放

  // 获取最大支持缩放倍数
  float maxRatio = self.livePusher.getCameraDevice.getMaxZoomRatio;
  // 获取最小支持缩放倍数
  float minRatio = self.livePusher.getCameraDevice.getMinZoomRatio;
  // 设置缩放倍数
  float ratio = 3.0;
  [self.livePusher.getCameraDevice setZoomRatio:MIN(maxRatio, MAX(minRatio, ratio))];
  

• 自动对焦

  // 开启自动对焦
  [self.livePusher.getCameraDevice enableAutoFocus:YES];
  // 关闭自动对焦
  [self.livePusher.getCameraDevice enableAutoFocus:NO];
  

• 手动对焦

  // 设置手动对焦焦点
  [self.livePusher.getCameraDevice setFocusPosition:CGPointMake(0.5, 0.5)];
  

音频控制

在使用推流引擎自带音频采集能力时，我们提供了多种音频控制能力。代码示例如下所示：

• 音量响度

  // 获取当前音量响度
  float voiceLoudness = self.livePusher.getAudioDevice.getVoiceLoudness;
  // 设置音量响度，取值范围 [0.0-1.0]
  [self.livePusher.getAudioDevice setVoiceLoudness:0.5];
  

• 耳返

  // 是否开启了耳返
  BOOL echoEnable = self.livePusher.getAudioDevice.isEnableEcho;
  if (echoEnable) {
      // 关闭耳返
      [self.livePusher.getAudioDevice enableEcho:NO];
  } else {
      // 开启耳返
      [self.livePusher.getAudioDevice enableEcho:YES];        
  }
  

横竖屏控制

我们提供了横竖屏控制能力，代码示例如下所示：

// 设置设备方向
[self.livePusher setOrientation:(UIApplication.sharedApplication.statusBarOrientation)];

静音控制

我们提供了静音控制能力，代码示例如下所示：

if (self.livePusher.isMute) {
    // 取消静音
    [self.livePusher setMute:NO];
} else {
    // 开启静音
    [self.livePusher setMute:YES];
}

日志级别

您可以通过调用 setLogLevel: 设置打印到控制台的日志级别，代码示例如下：

// 输出 INFO、WARNING 和 ERROR 级别的日志
[VeLivePusher setLogLevel:VeLivePusherLogLevelInfo]

开始推流

调用推流引擎的 startPush 开始推流。代码示例如下所示：

[self.livePusher startPush:@"rtmp://push.example.com/push"];

停止推流

调用推流引擎的 stopPush 停止推流。代码示例如下所示：

[self.livePusher stopPush];

销毁引擎

调用推流引擎的 release 销毁推流。代码示例如下所示：

[self.livePusher destroy];
self.livePusher = nil;