@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/native_live/iOS/V2TXLivePlayer_api_iOS.md

@@ -1,676 +0,0 @@
-# 腾讯云直播SDK V2TXLivePlayer 播放接口文档
-
-## 概述
-
-`V2TXLivePlayer` 是腾讯云直播播放器的核心接口类，负责从指定的直播流地址拉取音视频数据，并进行解码和本地渲染播放。
-
-**平台支持**: iOS, macOS
-
-## 核心功能
-
-### 🎯 主要能力
-- ✅ **多协议支持**: HTTP-FLV、WebRTC、TRTC、HLS、RTMP
-- ✅ **画面控制**: 旋转、填充模式、镜像
-- ✅ **播放控制**: 播放/停止、暂停/恢复、音量调节
-- ✅ **缓存优化**: 自动调整缓存策略
-- ✅ **无缝切换**: 直播流多分辨率无缝切换
-- ✅ **自定义处理**: 音视频数据监听和自定义渲染
-- ✅ **高级功能**: 截图、SEI消息、画中画、本地录制
-
-### 🔧 技术特性
-- **低延迟**: 优化的缓存策略和网络自适应
-- **高兼容**: 支持多种视频编码格式和分辨率
-- **易集成**: 简洁的API设计和完整的回调机制
-- **高性能**: 硬件加速解码和高效的渲染管线
-
-### 播放器实例创建
-```objc
-V2TXLivePlayer *player = [[V2TXLivePlayer alloc] init];
-```
-
-## 接口详解
-
-### 1. 基础设置接口
-
-#### setObserver() - 设置播放器回调
-```objc
-- (void)setObserver:(id<V2TXLivePlayerObserver>)observer;
-```
-
-**参数**:
-- `observer`: 播放器回调目标对象，需实现 `V2TXLivePlayerObserver` 协议
-
-**使用时机**: 播放器初始化后立即设置
-
-**说明**: 通过设置回调，可以监听播放器状态、播放音量回调、音视频首帧回调、统计数据、警告和错误信息等
-
-**示例**:
-```objc
-[player setObserver:self];
-```
-
-#### setRenderView() - 设置视频渲染 View
-```objc
-- (V2TXLiveCode)setRenderView:(TXView *)view;
-```
-
-**参数**:
-- `view`: 播放器渲染 View，iOS为UIView，macOS为NSView
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 必须在开始播放前设置渲染视图
-
-**示例**:
-```objc
-[player setRenderView:videoView];
-```
-
-#### setRenderRotation() - 设置播放器画面的旋转角度
-```objc
-- (V2TXLiveCode)setRenderRotation:(V2TXLiveRotation)rotation;
-```
-
-**参数**:
-- `rotation`: 旋转角度 `V2TXLiveDef#V2TXLiveRotation`
-  - `V2TXLiveRotation0`【默认值】: 0度, 不旋转
-  - `V2TXLiveRotation90`: 顺时针旋转90度
-  - `V2TXLiveRotation180`: 顺时针旋转180度
-  - `V2TXLiveRotation270`: 顺时针旋转270度
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-// 设置视频画面旋转0度
-[player setRenderRotation:V2TXLiveRotation0];
-// 设置视频画面旋转90度
-[player setRenderRotation:V2TXLiveRotation90];
-// 设置视频画面旋转180度
-[player setRenderRotation:V2TXLiveRotation180];
-// 设置视频画面旋转270度
-[player setRenderRotation:V2TXLiveRotation270];
-```
-
-#### setRenderFillMode() - 设置播放器画面的填充模式
-```objc
-- (V2TXLiveCode)setRenderFillMode:(V2TXLiveFillMode)mode;
-```
-
-**参数**:
-- `mode`: 填充模式 `V2TXLiveDef#V2TXLiveFillMode`
-  - `V2TXLiveFillModeFill`【默认值】: 图像铺满屏幕，不留黑边，如果图像宽高比不同于屏幕宽高比，部分画面内容会被裁剪掉
-  - `V2TXLiveFillModeFit`: 图像适应屏幕，保持画面完整，但如果图像宽高比不同于屏幕宽高比，会有黑边的存在
-  - `V2TXLiveFillModeScaleFill`: 图像拉伸铺满，因此长度和宽度可能不会按比例变化
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-// 图像铺满屏幕
-[player setRenderFillMode:V2TXLiveFillModeFill];
-// 图像适应屏幕
-[player setRenderFillMode:V2TXLiveFillModeFit];
-// 图像拉伸铺满
-[player setRenderFillMode:V2TXLiveFillModeScaleFill];
-```
-
-#### setRenderMirrorMode() - 设置播放器画面的镜像模式
-```objc
-- (V2TXLiveCode)setRenderMirrorMode:(BOOL)enable;
-```
-
-**参数**:
-- `enable`: 是否开启播放端镜像模式【默认值】：NO
-
-**说明**: 开启镜像模式后，视频画面将左右翻转，您可以根据需要随时切换观看效果
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-// 开启镜像模式
-[player setRenderMirrorMode:YES];
-// 关闭镜像模式
-[player setRenderMirrorMode:NO];
-```
-
-### 2. 播放控制接口
-
-#### startLivePlay() - 开始播放音视频流
-```objc
-- (V2TXLiveCode)startLivePlay:(NSString *)url;
-```
-
-**参数**:
-- `url`: 音视频流的播放地址，支持 HTTP-FLV、WebRTC、TRTC、HLS、RTMP
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 操作成功，开始连接并播放
-- `V2TXLIVE_ERROR_INVALID_PARAMETER`: 操作失败，url 不合法
-- `V2TXLIVE_ERROR_REFUSED`: RTC 不支持同一设备上同时推拉同一个 StreamId
-- `V2TXLIVE_ERROR_INVALID_LICENSE`: licence 不合法，播放失败
-
-**重要说明**: 
-- 10.7 版本开始，需要通过 `V2TXLivePremier#setLicence` 设置 Licence 后方可成功播放，否则将播放失败（黑屏），全局仅设置一次即可
-- 直播 Licence、短视频 Licence 和视频播放 Licence 均可使用
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-V2TXLiveCode result = [player startLivePlay:@"http://example.com/live/stream_1080p.flv"];
-if (result == V2TXLIVE_OK) {
-    NSLog(@"开始播放成功");
-} else if (result == V2TXLIVE_ERROR_INVALID_PARAMETER) {
-    NSLog(@"播放地址不合法");
-} else if (result == V2TXLIVE_ERROR_REFUSED) {
-    NSLog(@"调用被拒绝");
-} else if (result == V2TXLIVE_ERROR_INVALID_LICENSE) {
-    NSLog(@"Licence 不合法，请检查 Licence");
-}
-```
-
-#### stopPlay() - 停止播放音视频流
-```objc
-- (V2TXLiveCode)stopPlay;
-```
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 开始播放后
-
-**示例**:
-```objc
-[player stopPlay];
-```
-
-#### isPlaying() - 播放器是否正在播放中
-```objc
-- (int)isPlaying;
-```
-
-**返回值**:
-- `1`: 正在播放中
-- `0`: 已经停止播放
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-int isPlaying = [player isPlaying];
-if (isPlaying == 1) {
-    NSLog(@"正在播放中");
-} else {
-    NSLog(@"播放停止");
-}
-```
-
-### 3. 音视频控制接口
-
-#### pauseAudio() - 暂停播放器的音频流
-```objc
-- (V2TXLiveCode)pauseAudio;
-```
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制，若在开始播放前调用，则开始播放后，仅有视频画面，无音频播放
-
-**示例**:
-```objc
-[player pauseAudio];
-```
-
-#### resumeAudio() - 恢复播放器的音频流
-```objc
-- (V2TXLiveCode)resumeAudio;
-```
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-[player resumeAudio];
-```
-
-#### pauseVideo() - 暂停播放器的视频流
-```objc
-- (V2TXLiveCode)pauseVideo;
-```
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制，若在开始播放前调用，则开始播放后，仅有音频播放，无视频播放
-
-**示例**:
-```objc
-[player pauseVideo];
-```
-
-#### resumeVideo() - 恢复播放器的视频流
-```objc
-- (V2TXLiveCode)resumeVideo;
-```
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-[player resumeVideo];
-```
-
-#### setPlayoutVolume() - 设置播放器音量
-```objc
-- (V2TXLiveCode)setPlayoutVolume:(NSUInteger)volume;
-```
-
-**参数**:
-- `volume`: 音量大小，取值范围0 - 100【默认值】: 100
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-[player setPlayoutVolume:50];
-```
-
-### 4. 高级功能接口
-
-#### setCacheParams() - 设置播放器缓存自动调整的最小和最大时间
-```objc
-- (V2TXLiveCode)setCacheParams:(CGFloat)minTime maxTime:(CGFloat)maxTime;
-```
-
-**参数**:
-- `minTime`: 缓存自动调整的最小时间，取值需要大于0【默认值】：1
-- `maxTime`: 缓存自动调整的最大时间，取值需要大于0【默认值】：5
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-- `V2TXLIVE_ERROR_INVALID_PARAMETER`: 操作失败，minTime 和 maxTime 需要大于0
-
-**优化建议**:
-- 网络稳定：设置较小缓存（1-3秒）
-- 网络波动：设置较大缓存（3-5秒）
-- 无特殊要求，建议使用默认值
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-[player setCacheParams:1.0 maxTime:5.0];
-```
-
-#### switchStream() - 直播流多分辨率无缝切换，支持 FLV 和 LEB
-```objc
-- (V2TXLiveCode)switchStream:(NSString *)newUrl;
-```
-
-**参数**:
-- `newUrl`: 新分辨率拉流地址
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 开始播放后
-
-**示例**:
-```objc
-[player setObserver:self];
-
-[player startLivePlay:@"http://example.com/live/stream_1080p.flv"];
-
-
-[player switchStream:@"http://example.com/live/stream_720p.flv"];
-
-#pragma mark - V2TXLivePlayerObserver
-- (void)onStreamSwitched:(V2TXLivePlayer *)player url:(NSString *)url code:(V2TXLiveCode)code {
-    if (code == V2TXLIVE_OK) {
-        NSLog(@"流切换成功，当前播放地址：%@", url);
-    } else if (code == V2TXLIVE_ERROR_STREAM_SWITCH_FAIL) {
-        NSLog(@"流切换失败，切换超时");
-    } else if (code == V2TXLIVE_ERROR_STREAM_SWITCH_SERVER_ERROR) {
-        NSLog(@"流切换失败，服务端错误");
-    } else if (code == V2TXLIVE_ERROR_STREAM_SWITCH_CLIENT_ERROR) {
-        NSLog(@"流切换失败，客户端错误");
-    }
-}
-```
-
-#### getStreamList() - 获取码流信息，支持 HLS
-```objc
-- (NSArray<V2TXLiveStreamInfo *> *)getStreamList;
-```
-
-**返回值**: 码流信息数组，包含不同清晰度的流信息
-
-**使用时机**: 开始播放后
-
-**示例**:
-```objc
-[player startLivePlay:@"http://example.com/live/stream_1080p.m3u8"];
-
-NSArray<V2TXLiveStreamInfo *> *streamList = [player getStreamList];
-```
-
-#### enableVolumeEvaluation() - 启用播放音量大小提示
-```objc
-- (V2TXLiveCode)enableVolumeEvaluation:(NSUInteger)intervalMs;
-```
-
-**参数**:
-- `intervalMs`: 决定了 `onPlayoutVolumeUpdate` 回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于0则会关闭回调，建议设置为300ms【默认值】：0，不开启
-
-**说明**: 开启后可以在 `V2TXLivePlayerObserver` 回调中获取到 SDK 对音量大小值的评估
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-[player setObserver:self];
-[player enableVolumeEvaluation:300];
-[player setObserver:self];
-
-#pragma mark - V2TXLivePlayerObserver
-- (void)onPlayoutVolumeUpdate:(int)volume {
-    // 处理音量更新
-}
-```
-
-#### snapshot() - 截取播放过程中的视频画面
-```objc
-- (V2TXLiveCode)snapshot;
-```
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-- `V2TXLIVE_ERROR_REFUSED`: 播放器处于停止状态，不允许调用截图操作
-
-**使用时机**: 开始播放后
-
-**示例**:
-```objc
-[player setObserver:self];
-[player snapshot];
-#pragma mark - V2TXLivePlayerObserver
-- (void)onSnapshotComplete:(UIImage *)image {
-    // 处理截图结果
-}
-```
-
-#### enableObserveVideoFrame() - 开启/关闭自定义视频渲染
-```objc
-- (V2TXLiveCode)enableObserveVideoFrame:(BOOL)enable 
-                          pixelFormat:(V2TXLivePixelFormat)pixelFormat 
-                           bufferType:(V2TXLiveBufferType)bufferType;
-```
-
-**参数**:
-- `enable`: 是否开启自定义渲染【默认值】：NO
-- `pixelFormat`: 自定义渲染回调的视频像素格式 `V2TXLiveDef#V2TXLivePixelFormat`
-- `bufferType`: 自定义渲染回调的视频数据格式 `V2TXLiveDef#V2TXLiveBufferType`
-
-**说明**: 
-- SDK 在您开启此开关后将不再渲染视频画面，您可以通过 `V2TXLivePlayerObserver` 获得视频帧，并执行自定义的渲染逻辑
-- 支持的类型组合：
-  V2TXLivePixelFormatTexture2D, V2TXLiveBufferTypeTexture（推荐）
-  V2TXLivePixelFormatI420, V2TXLiveBufferTypeByteArray
-  V2TXLivePixelFormatI420, V2TXLiveBufferTypeByteBuffer
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-- `V2TXLIVE_ERROR_NOT_SUPPORTED`: 像素格式或者数据格式不支持
-
-**使用时机**: 开始播放前
-
-**示例**:
-```objc
-// 开启自定义渲染
-[player enableObserveVideoFrame:YES 
-                     pixelFormat:V2TXLivePixelFormatTexture2D 
-                      bufferType:V2TXLiveBufferTypeTexture];
-[player setObserver:self];
-
-#pragma mark - V2TXLivePlayerObserver
-- (void)onRenderVideoFrame:(V2TXLiveVideoFrame *)videoFrame {
-    // 自定义渲染
-}
-```
-
-#### enableObserveAudioFrame() - 开启/关闭对音频数据的监听回调
-```objc
-- (V2TXLiveCode)enableObserveAudioFrame:(BOOL)enable;
-```
-
-**参数**:
-- `enable`: 是否开启音频数据回调【默认值】：NO
-
-**说明**: 如果您开启此开关，您可以通过 `V2TXLivePlayerObserver` 获得音频数据，并执行自定义的逻辑
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 开始播放前
-
-**示例**:
-```objc
-// 开启音频数据监听
-[player enableObserveAudioFrame:YES];
-[player setObserver:self];
-
-#pragma mark - V2TXLivePlayerObserver
-- (void)onPlayoutAudioFrame:(V2TXLiveAudioFrame *)audioFrame {
-    // 处理音频数据
-}
-```
-
-#### enableReceiveSeiMessage() - 开启/关闭接收 SEI 消息
-```objc
-- (V2TXLiveCode)enableReceiveSeiMessage:(BOOL)enable payloadType:(int)payloadType;
-```
-
-**参数**:
-- `enable`: YES: 开启接收 SEI 消息; NO: 关闭接收 SEI 消息【默认值】: NO
-- `payloadType`: 指定接收 SEI 消息的 payloadType，支持 5、242、243，请与发送端的 payloadType 保持一致
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 开始播放前
-
-**示例**:
-```objc
-// 开启SEI消息接收
-[player enableReceiveSeiMessage:YES payloadType:5];
-[player enableReceiveSeiMessage:YES payloadType:242];
-[player enableReceiveSeiMessage:YES payloadType:243];
-[player setObserver:self];
-
-#pragma mark - V2TXLivePlayerObserver
-- (void)onReceiveSeiMessage:(int)payloadType data:(NSData *)data {
-    // 处理SEI消息
-}
-```
-
-#### enablePictureInPicture() - 开启/关闭画中画功能（iOS特有）
-```objc
-- (V2TXLiveCode)enablePictureInPicture:(BOOL)enable;
-```
-
-**参数**:
-- `enable`: YES开启，NO关闭【默认值】：NO
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-
-**使用时机**: 无限制
-
-**说明**: 仅iOS平台支持，macOS不支持此功能
-
-**示例**:
-```objc
-// 开启画中画功能
-[player enablePictureInPicture:YES];
-```
-
-#### startLocalRecording() - 开始录制音视频流
-```objc
-- (V2TXLiveCode)startLocalRecording:(V2TXLiveLocalRecordingParams *)params;
-```
-
-**参数**:
-- `params`: 请参考 `V2TXLiveDef.h` 中关于 `V2TXLiveLocalRecordingParams` 的介绍
-
-**重要说明**:
-- 拉流开启后才能开始录制，非拉流状态下开启录制无效
-- 录制过程中不要动态切换软/硬解，生成的视频极有可能出现异常
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-- `V2TXLIVE_ERROR_INVALID_PARAMETER`: 参数不合法，例如 filePath 为空
-- `V2TXLIVE_ERROR_REFUSED`: API被拒绝，拉流尚未开始
-
-**使用时机**: 开始播放后
-
-**示例**:
-```objc
-[player setObserver:self];
-
-#pragma mark - V2TXLivePlayerObserver
-- (void)onLocalRecordBegin:(int)code storagePath:(NSString *)storagePath {
-    NSLog(@"开始录制");
-}
-
-- (void)onLocalRecording:(long)durationMs storagePath:(NSString *)storagePath {
-    NSLog(@"录制中..., durationMs: %ld", durationMs);
-}
-
-- (void)onLocalRecordComplete:(int)code storagePath:(NSString *)storagePath {
-    NSLog(@"录制完成");
-}
-
-V2TXLiveLocalRecordingParams *params = [[V2TXLiveLocalRecordingParams alloc] init];
-params.filePath = @"filepath";
-params.interval = 2000;
-V2TXLiveCode code = [player startLocalRecording:params];
-if (code == V2TXLIVE_OK) {
-    NSLog(@"录制开启成功");
-} else if (code == V2TXLIVE_ERROR_INVALID_PARAMETER) {
-    NSLog(@"录制参数不合法");
-} else if (code == V2TXLIVE_ERROR_REFUSED) {
-    NSLog(@"录制调用被拒绝");
-}
-```
-
-#### stopLocalRecording() - 停止录制音视频流
-```objc
-- (void)stopLocalRecording;
-```
-
-**说明**: 当停止拉流后，如果视频还在录制中，SDK 内部会自动结束录制
-
-**使用时机**: 开始播放并且开启录制后
-
-**示例**:
-```objc
-[player stopLocalRecording];
-```
-
-#### showDebugView() - 是否显示播放器状态信息的调试浮层
-```objc
-- (void)showDebugView:(BOOL)isShow;
-```
-
-**参数**:
-- `isShow`: 是否显示【默认值】：NO
-
-**使用时机**: 无限制
-
-**示例**:
-```objc
-[player showDebugView:YES];
-```
-
-#### setProperty() - 调用 V2TXLivePlayer 的高级 API 接口
-```objc
-- (V2TXLiveCode)setProperty:(NSString *)key value:(NSObject *)value;
-```
-
-**参数**:
-- `key`: 高级 API 对应的 key
-- `value`: 调用 key 所对应的高级 API 时，需要的参数
-
-**说明**: 该接口用于调用一些高级功能，有特殊需求，请于商务或架构师联系
-
-**返回值**: `V2TXLiveCode`
-- `V2TXLIVE_OK`: 成功
-- `V2TXLIVE_ERROR_INVALID_PARAMETER`: 操作失败，key 不允许为 nil
-
-## 使用示例
-
-```objc
-// 创建播放器实例
-V2TXLivePlayer *player = [[V2TXLivePlayer alloc] init];
-
-// 设置回调
-[player setObserver:self];
-
-// 设置渲染视图
-[player setRenderView:videoView];
-
-// 开始播放
-V2TXLiveCode result = [player startLivePlay:@"rtmp://example.com/live/stream"];
-if (result == V2TXLIVE_OK) {
-    // 播放成功
-}
-
-// 暂停视频
-[player pauseVideo];
-
-// 恢复视频
-[player resumeVideo];
-
-// 停止播放
-[player stopPlay];
-```
-
-## 注意事项
-
-1. **Licence 要求**: 10.7 版本开始必须设置有效的 Licence 才能正常播放
-2. **权限要求**: 需要网络权限和音频播放权限
-3. **线程安全**: 所有接口调用需在主线程执行
-4. **内存管理**: 及时释放播放器资源，避免内存泄漏
-5. **平台差异**: 画中画功能仅iOS平台支持，macOS不支持
-
-## 相关接口
-
-- `V2TXLivePlayerObserver`: 播放器回调接口
-- `V2TXLiveCode`: 错误码和状态码定义
-- `V2TXLiveDef`: 数据结构和枚举定义
-- `V2TXLivePremier`: SDK全局管理接口