You need to enable JavaScript to run this app.
导航

基础功能

最近更新时间2023.11.29 17:46:38

首次发布时间2022.01.21 18:42:59

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

前提条件

已完成 SDK 集成SDK 初始化

注意事项

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

功能接入

本节为您详细介绍如何通过拉流 SDK 实现直播拉流播放控制的能力,包括但不限于创建播放器、初始化配置、事件监听、配置渲染 View、配置播放地址。

创建播放器

使用拉流 SDK,需要先创建直播播放器。您可以参考以下代码创建播放器。

// 创建播放器
TVLManager *livePlayer = [[TVLManager alloc] init];

初始化配置

您可以通过 VeLivePlayerConfiguration 对播放器进行初始化相关配置。详细参数说明如下表所示。

参数类型说明
enableSeiBOOL是否开启 SEI 消息的解析,默认值为 NO。
enableHardwareDecodeBOOL是否开启硬件解码功能,默认值为 YES。开启硬件解码后,如果出现硬件解码启动失败或硬件解码失败的情况,播放器内部会自动切换为软解。
networkTimeoutMsNSInteger网络超时时间,单位为 ms,默认值为 5000。播放器发起网络请求,如果超过了该时间仍未收到服务器响应,则认为网络请求失败。
retryIntervalTimeMsNSInteger重试时间间隔,单位为 ms,默认值为 5000。在播放直播时,如果出现了网络异常等问题导致播放中断,播放器会立即进行一次重试,重试失败之后,每达到重试间隔时间,播放器会再次重试。
retryMaxCountNSInteger在网络连接错误的情况下,播放器最大重试次数,默认值为 5。如果取值为 0,表示关闭播放器内部重试。
enableLiveDNSBOOL是否开启本地 DNS 预解析,默认值为 NO。开启本地 DNS 预解析可以优化起播时间,缩短启播时间。如果本地 DNS 预解析出现异常,可能会影响播放器的正常使用。
enableStatisticsCallbackBOOL是否开启播放信息周期性回调。默认值为 NO。
statisticsCallbackIntervalNSInteger播放信息周期性回调的时间间隔,单位为 s,默认值为 5。

您可以参考以下代码示例进行初始化配置。

// 创建配置
VeLivePlayerConfiguration *config = [[VeLivePlayerConfiguration alloc]init];
// 打开周期性回调
config.enableStatisticsCallback = YES;
// 打开 Local DNS 预解析
config.enableLiveDNS = YES;
// 初始化播放器
[self.livePlayer setConfig:config];

配置事件监听

您可以通过配置事件回调监听来获取播放器的内部状态信息,包括播放器状态、错误信息、音视频首帧回调以及周期性统计数据等。代码示例如下所示。

  1. 配置播放器回调。
@interface VeLivePullViewController () <VeLivePlayerObserver>
@end

// 配置播放器回调
[self.livePlayer setObserver:self];
  1. 播放器回调处理。
- (void)onError:(TVLManager *)player error:(VeLivePlayerError *)error {
    // 错误回调
}

- (void)onFirstVideoFrameRender:(TVLManager *)player isFirstFrame:(BOOL)isFirstFrame {
    // 视频首帧回调
}

- (void)onFirstAudioFrameRender:(TVLManager *)player isFirstFrame:(BOOL)isFirstFrame {
    // 音频首帧回调
}

- (void)onStallStart:(TVLManager *)player {
    // 卡顿开始回调
}

- (void)onStallEnd:(TVLManager *)player {
    // 卡顿结束回调
}

- (void)onVideoRenderStall:(TVLManager *)player stallTime:(int64_t)stallTime  {
    // 视频卡顿回调
}

- (void)onAudioRenderStall:(TVLManager *)player stallTime:(int64_t)stallTime  {
    // 音频卡顿回调
}

- (void)onResolutionSwitch:(TVLManager *)player resolution:(VeLivePlayerResolution)resolution error:(VeLivePlayerError *)error reason:(VeLivePlayerResolutionSwitchReason)reason  {
    // 播放档位变化回调
}

- (void)onVideoSizeChanged:(TVLManager *)player width:(int)width height:(int)height  {
    // 分辨率变化回调
}

- (void)onReceiveSeiMessage:(TVLManager *)player message:(NSString*)message  {
    // SEI 通知回调
}

- (void)onMainBackupSwitch:(TVLManager *)player streamType:(VeLivePlayerStreamType)streamType error:(VeLivePlayerError *)error  {
    // 主备切换回调
}

- (void)onPlayerStatusUpdate:(TVLManager *)player status:(VeLivePlayerStatus)status  {
    // 播放器状态变化回调
}

- (void)onStatistics:(TVLManager *)player statistics:(VeLivePlayerStatistics *)statistics {
    // 周期性回调
}

- (void)onSnapshotComplete:(TVLManager *)player image:(UIImage *)image  {
    // 截图回调
}

- (void)onRenderVideoFrame:(TVLManager *)player videoFrame:(VeLivePlayerVideoFrame *)videoFrame  {
    // 视频帧订阅回调
}

- (void)onRenderAudioFrame:(TVLManager *)player audioFrame:(VeLivePlayerAudioFrame *)audioFrame  {
    // 音频帧订阅回调
}

配置渲染 View

播放器的视图以 UIView 的形式呈现,内部会创建一个 playerView,视频播放时会在该 playerView 上进行渲染。使用时,只需将 playerView 添加到您的自定义 UIView 上即可。

// 配置 metal 渲染
self.livePlayer.playerViewRenderType = TVLPlayerViewRenderTypeMetal;

// 配置 playerView 尺寸
self.livePlayer.playerView.frame = UIScreen.mainScreen.bounds;

// 将 playerView 添加到您的自定义 view 上
[self.view addSubview:self.livePlayer.playerView];

配置播放地址

通过 setPlayUrl 接口配置单一播放地址,支持 RTMP、FLV、HLS 等直播协议地址。代码示例如下所示。

// 通过 URL 进行播放
NSString *playUrl = "http://pull.example.com/live/stream.flv";
// 配置播放地址
[self.livePlayer setPlayUrl:playUrl];

说明

如果您需要配置多路组合播放地址,可使用 setPlayStreamData 接口,该接口支持 RTM、QUIC、主备流、多档位、ABR 等功能,详细的代码示例和接入方法请参考进阶功能接入

播放画面调整

您可以通过以下接口调整播放画面的填充模式、镜像和旋转角度,以获得更好的观看体验。

配置填充模式

通过播放器的 setRenderFillMode 接口可以配置播放画面的填充模式,播放器支持以下 3 种填充模式。

填充模式说明
VeLivePlayerFillModeAspectFit显示完整的视频帧。视频帧等比缩放,直至视频帧恰好在画布上全部显示。如果视频帧长宽比例与画布不同,视窗上未被视频帧填满区域将填充为黑色。
VeLivePlayerFillModeFullFill视频帧自适应画布。视频帧非等比缩放,直至填满画布。在此过程中,视频帧的长宽比例可能会发生变化。
VeLivePlayerFillModeAspectFill视频填满画布。视频帧等比缩放,直至填满画布,超出屏幕的部分将被裁剪,画面可能不完整。

您可以参考以下代码示例配置填充模式。

// 配置填充模式
[self.livePlayer setRenderFillMode:VeLivePlayerFillModeAspectFill];

配置镜像

通过播放器的 setRenderMirror 接口可以配置播放画面的镜像模式,播放器支持以下 3 种镜像模式。

镜像说明
VeLivePlayerMirrorNone关闭镜像
VeLivePlayerMirrorHorizontal水平镜像
VeLivePlayerMirrorVertical垂直镜像

您可以参考以下代码示例配置镜像。

// 配置水平镜像
[self.livePlayer setRenderMirror:VeLivePlayerMirrorHorizontal];

配置旋转

通过播放器的 setRenderRotation 接口可以配置播放画面的旋转角度,播放器支持以下 4 种旋转角度。

旋转说明
VeLivePlayerRotation0关闭旋转
VeLivePlayerRotation90顺时针旋转 90 度
VeLivePlayerRotation180顺时针旋转 180 度
VeLivePlayerRotation270顺时针旋转 270 度

您可以参考以下代码示例配置旋转角度。

// 配置画面旋转 90 度
[self.livePlayer setRenderRotation:VeLivePlayerRotation90];

开始播放

调用播放器的 play 接口开始播放。代码示例如下所示。

[self.livePlayer play]; //开始播放。

调用播放器的 isPlaying 接口可以获取当前的播放状态。代码示例如下所示。

BOOL isPlaying = [self.livePlayer isPlaying]; //获取播放状态

暂停播放

调用播放器的 pause 接口暂停播放,代码示例如下所示。

[self.livePlayer pause]; //暂停播放

说明

在直播中,暂停和停止的行为相同。暂停后再调用 play 方法,播放器将重新拉流。

停止播放

调用播放器的 stop 接口停止播放。代码示例如下所示。

[self.livePlayer stop]; //停止播放

销毁播放器

调用播放器的 destroy 接口销毁播放器并释放内存。当您停止播放后需要销毁播放器时,请调用该接口。代码示例如下所示。

[self.livePlayer destroy]; // 销毁拉流引擎,退出前释放播放器,释放内存

前后台切换

在应用程序从前台切换到后台时,播放器默认会继续播放音频。如果您希望在后台状态停止播放,可参考以下示例代码。

// app 回到前台通知
[NSNotificationCenter.defaultCenter addObserver:self
						selector:@selector(applicationDidBecomeActive)
            name:UIApplicationDidBecomeActiveNotification
            object:nil];
// app 退到后台通知
[NSNotificationCenter.defaultCenter addObserver:self
						selector:@selector(applicationWillResignActive)
						name:UIApplicationWillResignActiveNotification
            object:nil];

- (void)applicationDidBecomeActive {
    [self.livePlayer play]; // 回到前台,继续播放
}

// 退到后台处理
- (void)applicationWillResignActive {
    [self.livePlayer pause]; // 退到后台,暂停播放
}

静音配置

调用播放器的 setMute 接口可以控制是否静音播放。代码示例如下所示。

[self.livePlayer setMute:YES]; // 配置静音播放

调用播放器的 isMute 接口可以获取当前是否为静音状态。代码示例如下所示。

BOOL isMute = [self.livePlayer isMute]; // 获取静音状态

配置播放音量

调用播放器的 setPlayerVolume 接口可以控制播放音量,参数表示音量大小,默认值为 1.0,取值范围为 [0.0,1.0]。代码示例如下所示。

[self.livePlayer setVolume:0.5]; // 配置播放音量

日志级别

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

// 输出 INFO、WARNING 和 ERROR 级别的日志
[TVLManager setLogLevel:VeLivePlayerLogLevelInfo];