音视频播放

更新时间：2025-09-04 19:56:30

RTCXMedia 提供设备的直播，点播，截图，录制，音频对讲等相关功能

// 导入媒体播放SDK头文件
#import <RTCXMedia/RTCXMedia.h>

播放器初始化

@interface RTCXPlayInfo : NSObject
// 设备型号 如：xLeWcoelZbyOePbJludl
@property (nonatomic, copy) NSString *productKey;
// 设备序列号SN 如：TEST20240820002
@property (nonatomic, copy) NSString *deviceName;
// 平台为设备颁发的ID，设备的唯一标识符
@property (nonatomic, copy) NSString *iotId;

@end

@interface RTCXPlayerView : UIView
/**
 player相关接口调用
 */
@property (nonatomic, strong) RTCXPlayerController *playerController;

/**
 初始化View
 @param frame 需要展示视频的frame
 @param playInfo 播放设备信息
 */
- (id)initWithFrame:(CGRect)frame withPlayInfo:(RTCXPlayInfo *)playInfo;
@end

调用示例如下：

RTCXPlayInfo *playInfo = [[RTCXPlayInfo alloc] init];
playInfo.iotId = self.curDevice.iotId;
playInfo.productKey = self.curDevice.productKey;
playInfo.deviceName = self.curDevice.deviceName;
// 初始化播放器，传入frame和设备model
self.playerView = [[RTCXPlayerView alloc] initWithFrame:CGRectMake(0, 0, SCREEN_WIDTH, SCREEN_WIDTH * 9.0 / 16.0) withDevice:playInfo];
self.playerView.playerController.delegate = self;// 创建player控制类并设置代理监听player状态，playeview.playerController会懒加载创建控制类
self.playerView.playerController.dataSource = self;// 设置playeview.playerController的dataSource
// 初始化player播放的视图，可以把该playerView加到任意view上
[self.view addSubview:self.playerView];

直播

@protocol RTCXPlayerInterface <NSObject>
/**
 直播调用
 */
- (void)start;
@end

调用示例如下:

// 开始直播
[self.playerView.playerController start];

云/SD 卡回放

@protocol RTCXPlayerInterface <NSObject>
/**
 回放调用

 @param playbackInfo  回放参数
 */
- (void)seekToTime:(RTCXPlaybackInfo*)playbackInfo;
@end

调用示例如下:

// 云回放或SD卡回放
RTCXPlaybackInfo *playbackInfo = [[RTCXPlaybackInfo alloc] init];
playbackInfo.startTime = [startTime timeIntervalSince1970];
playbackInfo.endTime = [startTime timeIntervalSince1970];
playbackInfo.playbackType = _isPlaybackSDCard?IOTPlaybackTypeSDCardRecord:IOTPlaybackTypeCloudRecord;
[self.playerView.playerController seekToTime:playbackInfo];

监听播放状态

/// 播放器状态回调
typedef NS_ENUM(NSInteger, RTCXCameraPlayerState) {
    // 播放初始化播放未开始
    RTCXCameraPlayerStateInitial = -1,
    // 播放准备就绪
    RTCXCameraPlayerStatePrepared = 0,
    // 播放状态
    RTCXCameraPlayerStatePlaying,
    // 开始图像渲染
    RTCXCameraPlayerStateRenderingStart,
    // 暂停状态
    RTCXCameraPlayerStatePaused,
    // 缓冲状态开始
    RTCXCameraPlayerStateBuffingStart,
    // 缓冲状态结束
    RTCXCameraPlayerStateBuffingEnd,
    // 事件，剪辑视频等，播放完毕
    RTCXCameraPlayerStatePlaybackCompleted,
    // 播放停止
    RTCXCameraPlayerStateStopped,
    /// 播放错误
    RTCXCameraPlayerStateError
};

@protocol RTCXPlayerDelegate <NSObject>
/**
 player播放状态回调

 @param playState player状态（RTCXCameraPlayerState）
 @param code player错误码
 */
- (void)onPlayStateChanged:(RTCXCameraPlayerState)playState code:(int)code;
@end

调用示例如下:

#pragma mark -- RTCXPlayerDelegate --
- (void)onPlayStateChanged:(RTCXCameraPlayerState)playState code:(int)code {
    COMMON_PRINTF(@"+++++++直播页播放状态：%d, code: %d",playState,code);
    dispatch_async(dispatch_get_main_queue(), ^{
        switch (playState) {
            case RTCXCameraPlayerStatePrepared:
                [self.livePlayerView setWaitingAnimation:YES];
                break;
            case RTCXCameraPlayerStatePlaying:
                [self.livePlayerView setWaitingAnimation:NO];
                break;
            case RTCXCameraPlayerStateRenderingStart:
                [self.livePlayerView setWaitingAnimation:NO];
                break;
                
            case RTCXCameraPlayerStateBuffingStart:
                [self.livePlayerView setWaitingAnimation:YES];
                break;
            case RTCXCameraPlayerStateBuffingEnd:
                [self.livePlayerView setWaitingAnimation:NO];
                break;
            case RTCXCameraPlayerStateStopped:
                [self.livePlayerView setWaitingAnimation:NO];
                break;
            default:
                break;
        }
    });
}

播放状态码

播放状态	状态码&描述
RTCXCameraPlayerStateStopped	-501：SD卡回放没有更多数据了（回放结束）
RTCXCameraPlayerStatePlaybackCompleted	-10010：到达了限制播放时长
RTCXCameraPlayerStateError	-2：播放通道断开连接 -5：播放通道异常预警 -10025：SD卡回放达到最大路数限制 -10047：低功耗设备即将进入休眠

播放器销毁

当不再需要播放的时候，要销毁播放器

@protocol RTCXPlayerInterface <NSObject>
/**
 释放player（不再需要时调用释放）
 */
- (void)releasePlayer;
@end

调用示例如下:

// 销毁播放器
[self.playerView.playerController releasePlayer];

截图

@protocol RTCXPlayerInterface <NSObject>
/**
 截图
 
 @param bOriginalPic 是否原始尺寸
 @param isAdd 是否添加时间水印
 @return image
 */
- (UIImage *)snapshot:(BOOL)bOriginalPic isAddTimeWatermark:(BOOL)isAdd;
@end

调用示例如下:

// 截图
UIImage *image = [self.playerView.playerController snapshot:YES isAddTimeWatermark:NO];

静音

@protocol RTCXPlayerInterface <NSObject>
/**
 设置播放是否静音
 
 @param mute 是否静音 YES：静音  NO：非静音
 */
- (void)setMuteRemoteAudio:(BOOL)mute;
@end

调用示例如下:

// 是否静音 YES/NO
[self.mainPlayer.playerController setMuteRemoteAudio:!on];

倍速播放

注意

1. SD卡非1倍速播放时，是不支持静音设置和视屏录制的

@protocol RTCXPlayerInterface <NSObject>
/**
 倍速播放
 
 @param rate 0.5、1、2、4等
 */
- (void)setPlaybackSpeed:(float)rate;
@end

调用示例如下:

 // 设置倍速
[self.mainPlayer.playerController setPlaybackSpeed:rate];

边播边录

@protocol RTCXPlayerInterface <NSObject>
/**
 边播边录
 
 @param path 保存文件夹
 @param isAdd 是否添加时间水印
 @return image
 */
- (BOOL)startRecord:(NSString *)path isAddTimeWatermark:(BOOL)isAdd;
/**
 停止边播边录
 */
- (BOOL)stopRecord;
@end

@protocol RTCXPlayerDelegate <NSObject>
@optional
/**
 视频录制回调

 @param currentTime 回调当前录制时间
 @param filePath 回调数据路径
 @param error 视频录制错误
 */
- (void)onPlayerMp4Record:(NSInteger)currentTime filePath:(NSString *)filePath error:(NSError *)error;
@end

调用示例如下:

// 边播边录
- (BOOL)functionRecordingWhilePlaying:(BOOL)on {
    if (on) {
        BOOL result = [self.playerView.playerController startRecord:[self fileName] isAddTimeWatermark:NO];
        [self showToast:result? @"边播边录成功":@"边播边录失败"];
        return result;
    } else {
        return [self.playerView.playerController stopRecord];
    }
}

#pragma mark -- RTCXPlayerDelegate --
- (void)onPlayerMp4Record:(NSInteger)currentTime filePath:(NSString *)filePath error:(NSError *)error {
    COMMON_PRINTF(@"视屏录制中。。。：%d, filePath: %@, error:%@",currentTime,filePath,error);
    if (filePath) {
    //录制完成，保存到手机相册
        self.recordTimeL.hidden = YES;
        self.recordTimeL.text = @"";
        UISaveVideoAtPathToSavedPhotosAlbum(filePath, nil, nil, nil);
        [self showToast:[NSString stringWithFormat:@"record save success"]];
    } else {
    //显示录制进度
        self.recordTimeL.hidden = NO;
        self.recordTimeL.text = millisecondsToTimeString(currentTime);
    }
}

画面旋转

/**
 设置旋转角度
 
 @param degrees 旋转角度 
 */
- (void)setVideoRotate:(IOTRenderRotation)degrees;
@end

调用示例如下:

// 设置画面旋转90度
[self.mainPlayer.playerController setVideoRotate:IOT_RENDER_ROTATION_90];

音频通话（语音对讲）

typedef NS_ENUM(NSInteger, RTCXAudioVideoTalkType) {
    RTCXAudioVideoTalkType_Audio,    // 音频通话
    RTCXAudioVideoTalkType_Video,    // 视频通话
};

@protocol RTCXAudioVideoTalkInterface <NSObject>

/**
 初始化对象
 @param deviceInfo 设备信息
 @param avTalkType 音频、视频通话话类型
 */
- (id)initWithDeviceInfo:(RTCXPlayInfo *)deviceInfo avTalkType:(RTCXAudioVideoTalkType)avTalkType;
/**
 开始通话
 */
- (void)startTalk;
/**
 结束通话
 */
- (void)endTalk;
@end

调用示例如下:

// 初始化音频通话引擎
-(RTCXAudioVideoTalk *)audioVideoTalkEngin {
    if (_audioVideoTalkEngin == nil) {
        RTCXPlayInfo *deviceInfo = [[RTCXPlayInfo alloc] init];
        deviceInfo.iotId = self.curDevice.iotId;
        deviceInfo.productKey = self.curDevice.productKey;
        deviceInfo.deviceName = self.curDevice.deviceName;
        _audioVideoTalkEngin = [[RTCXAudioVideoTalk alloc] initWithDeviceInfo:deviceInfo avTalkType:RTCXAudioVideoTalkType_Audio];
    }
    return _audioVideoTalkEngin;
}
// 开始音频通话
[self.audioVideoTalkEngin startTalk];
// 结束音频通话
[self.audioVideoTalkEngin endTalk];

直播预连

调用物模型接口直播预连接

[[[kRTCXThingManager buildThing:obj.iotId] getThingActions] invokeServiceV1:@"PreConnect" params:@{@"Stream":obj.deviceName,@"Channel":@(0),@"Protocol":@"rtc",@"App":obj.productKey} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
    if (response.success) {
        NSLog(@"PreConnect succeed -- %@",obj.nickName?:obj.deviceName);
    } else {
        NSString *errorMsg = response.responseError.userInfo[NSLocalizedFailureReasonErrorKey];
        [self showToast:errorMsg];
    }
 }];

多目设备播放

注意

1. 多目设备播放接入需要创建多个播放器RTCXPlayerView
2. 初始化RTCXPlayerView时，需要设置lensId（镜头ID)区分不同播放器
3. 截图、录制、静音等操作需要同时操作两个播放器对应能力方法（根据实际业务情况来定）

• 判断是否是双目设备

通过调用物模型属性接口，获取镜头数量LensCount对应的值，如果LensCount = 2，则为双目设备

[[[kRTCXThingManager buildThing:self.device.productKey deviceName:self.device.deviceName iotId:self.device.iotId] getThingActions] getPropertiesFull:^(RTCXThingActionsResponse * _Nullable response) {
    if (response.success) {
        NSDictionary *propertyMap = response.dataObject[@"propertyMap"];
        int lensCount = [[[propertyMap valueForKey:@"LensCount"] valueForKey:@"value"] intValue];// 设备镜头数量
        if (lensCount == 2) {
            //  当前设备为双目设备
        }
    } else {
        [weakSelf showToast:@"获取属性失败"];
    }
}];

• 初始化双目播放器

调用示例如下:

if （self.lensCount == 2）{// 判断为双目设备时
    RTCXPlayInfo *playInfo = [[RTCXPlayInfo alloc] init];
    playInfo.iotId = self.curDevice.iotId;
    playInfo.productKey = self.curDevice.productKey;
    playInfo.deviceName = self.curDevice.deviceName;
    // 云台镜头播放器
    playInfo.lensId = @(0);// 云台镜头ID（非双目不需要设置此参数）
    self.mainPlayerView = [[RTCXPlayerView alloc] initWithFrame:CGRectMake(0, 0, self.playerRect.size.width, self.playerRect.size.height) withPlayInfo:playInfo];
    self.mainPlayerView.playerController.delegate = self;
    self.mainPlayerView.playerController.dataSource = self;
    [self.view addSubview:self.mainPlayerView];
    // 广角镜头播放器
    playInfo.lensId = @(1);// 广角镜头ID（非双目不需要设置此参数）
    self.secondPlayerView = [[RTCXPlayerView alloc] initWithFrame:CGRectMake(0, 0, self.playerRect.size.width, self.playerRect.size.height) withPlayInfo:playInfo];
    self.secondPlayerView.playerController.delegate = self;
    self.secondPlayerView.playerController.dataSource = self;
    [self.view addSubview:self.secondPlayerView];
}

码率

@protocol RTCXPlayerInterface <NSObject>
/**
 获取码率 单位bit
 */
- (long)getBitrate;
@end

调用示例如下:

// 获取码率
long bit = [self.mainPlayer.playerController getBitrate];

帧率

@protocol RTCXPlayerInterface <NSObject>
/**
 获取帧率 fps
 */
- (long)getPlayFPS;
@end

调用示例如下:

// 获取帧率
long fps = [self.mainPlayer.playerController getPlayFPS];

主子码流

直播支持设置主码流、子码流、其他码流播放，App可以在初始化播放器的时候提前设置码流参数，如果初始化播放器时未设置码流，则默认播放主码流；

RTCXPlayInfo *playInfo = [[RTCXPlayInfo alloc] init];
RTCXPlayInfo.streamType = 1; // 设置码流
// 初始化播放器，传入frame和设备model
self.playerView = [[RTCXPlayerView alloc] initWithFrame:CGRectMake(0, 0, SCREEN_WIDTH, SCREEN_WIDTH * 9.0 / 16.0) withDevice:playInfo];
// 也可以通过该方法设置码流
// [self.playerView.playerController setPlayStreamType:1];
...

若需要播放中途切换码流，需要先停止（releasePlayer）播放，设置码流后，再重新开启播放（start）

@protocol RTCXPlayerInterface <NSObject>
/**
 设置码流类型，0：主码流； 1：辅码流；2、3、...：其他码流
 */
- (void)setPlayStreamType:(int)streamType;
@end

调用示例如下:

// 设置主、子码流、其他码流
[self.mainPlayer.playerController setPlayStreamType:streamType==0?1:0];

云视频下载

支持将云端存储的录像视频和事件视频以MP4格式下载到本地

// 导入媒体播放SDK头文件
#import <RTCXMedia/RTCXMedia.h>

相关API接口对应如下：

@protocol RTCXMediaDownloadDelegate <NSObject>

@optional
/**
 @brief 下载进度回调
 
 @param mediaDownload 下载实例
 @param progress 下载时间进度（单位：毫秒）
 @param completed 下载是否完成
 */
- (void)mediaDownload:(RTCXMediaDownload *)mediaDownload downloadProgress:(int)progress completed:(BOOL)completed;

/**
 @brief  下载文件路径回调
 
 @param mediaDownload 下载实例
 @param filePath 下载文件路径
 */
- (void)mediaDownload:(RTCXMediaDownload *)mediaDownload downloadFilePath:(NSString *)filePath;

/**
 @brief 下载错误回调
 
 @param mediaDownload 下载实例
 @param error 错误error
 */
- (void)mediaDownload:(RTCXMediaDownload *)mediaDownload downloadFileError:(NSError *)error;

@end

@protocol RTCXMediaDownloadDataSource <NSObject>

@optional
/**
 设置时间水印字体本地文件路径
 
 @return 水印字体文件路径
 */
- (NSString *)fontPath;
/**
 设置logo水印本地路径
 
 @return logo水印本地路径
 */
- (NSString *)logoWatermarkPath;
/**
 设置logo水印位置
 
 @return logo水印位置
 */
- (RTCXLogoWatermarkPosition)logoWatermarkPosition;
/**
 设置视频分辨率尺寸
 
 @return CGSize 如：（1280.0，720.0）
 */
- (CGSize)resolutionSize;

@end

@protocol RTCXMediaDownloadInterface <NSObject>
/**
 @brief 开始下载（目前只对云端视频下载有效，并且一次下载视频长度最多5分钟）

 @param config 下载参数对象
 */
- (void)startDownloadWithConfig:(RTCXMediaDownloadConfig *)config;
/**
 @brief 结束下载，下载完成时，必须调用此接口，保存的视频才能正常播放，可通过下载进度回调判断是否完成

 */
- (void)stopDownload;
@end

@interface RTCXMediaDownload : NSObject<RTCXMediaDownloadInterface>

@property (nonatomic, weak) id <RTCXMediaDownloadDelegate> delegate;
@property (nonatomic, weak) id <RTCXMediaDownloadDataSource> dataSource;

@end

调用示例如下:

1. 初始化下载示例对象

if (!_mediaDownload) {
    _mediaDownload = [[RTCXMediaDownload alloc] init];
    _mediaDownload.delegate = self;
}

2. 配置下载请求参数模型，开始下载

RTCXMediaDownloadConfig *config = [[RTCXMediaDownloadConfig alloc] init];
config.iotId = self.curDevice.iotId;
NSMutableArray *timelineList = [self getTimelineArrayforPlayerFrom:self.startTime toEndTime:self.endTime];
config.beginTime = timelineList.firstObject;
config.endTime = timelineList.lastObject;
config.savePath = [self savePath];
config.fileName = _eventClipInfo.eventID;
[_mediaDownload startDownloadWithConfig:config];

3. 监听下载进度和结果

#pragma mark -- RTCXMediaDownloadDelegate --
- (void)mediaDownload:(RTCXMediaDownload *)mediaDownload downloadProgress:(int)progress completed:(BOOL)completed {
    NSLOG_PRINTF(@"当前下载进度：%d, %d",progress,completed);
    double _totalTime = [_eventClipInfo.endTime timeIntervalSince1970] * 1000.0 - [_eventClipInfo.startTime timeIntervalSince1970] * 1000.0;
    if (_totalTime >= 5*60*1000) {
        _totalTime = 5*60*1000;// 最多下载5分钟视频
    }
    double per = progress / _totalTime;
    if (per >= 1) {
        per = 1;
    }
    self.progressLabel.text = per == 1?@"":[NSString stringWithFormat:@"%.0f%%",per *100];
    if (per == 1 || completed) {
        [self showToast:NSLocalizedString(@"下载已完成", nil)];
        self.progressLabel.text = @"";
        [self.mediaDownload stopDownload];
    }
}

- (void)mediaDownload:(RTCXMediaDownload *)mediaDownload downloadFilePath:(NSString *)filePath {
    NSLOG_PRINTF(@"当前下载路径：%@",filePath);
    if (filePath) {
        UISaveVideoAtPathToSavedPhotosAlbum(filePath, nil, nil, nil);
    }
}

- (void)mediaDownload:(RTCXMediaDownload *)mediaDownload downloadFileError:(NSError *)error {
    NSLOG_PRINTF(@"当前下载错误：%ld ：%@",error.code,error.userInfo[NSLocalizedFailureReasonErrorKey]);
}

4. 监听到下载完成，需要停止下载（释放资源）

[self.mediaDownload stopDownload];