文档

基础功能

更新时间:

本文为您介绍如何创建iOS播放器实例并提供设置音量、设置拖拽播放、监听播放状态、设置循环播放、设置倍速播放、切换音轨等基础播放功能的使用示例。

创建播放器

本节介绍如何用最简单的方式让iOS播放器SDK播放视频,按照播放方式的不同可以分为手动播放和自动播放。

说明

5.4.7.1及之后版本的iOS播放器SDK,在配置License后,需要在播放器实例初始化前主动调用初始化证书服务。代码示例如下:

[AliPrivateService initLicenseService];
  1. 创建播放器。

    创建AliPlayer播放器。

    说明

    播放器提供的播放质量监控(可查看播放器整体播放质量相关数据)、单点追查(可定位到具体的用户或设备,分析其播放行为,快速定位播放异常等问题)及视频播放统计功能都依赖埋点日志上报功能而实现。

    在创建播放器时,根据setTraceId参数的设置不同,其后续可实现的功能不同,具体如下:

    • setTraceId参数不传(默认):埋点日志上报功能开启,后续可以使用播放质量监控和视频播放统计功能,无法使用单点追查功能。

    • setTraceId参数传入traceid:traceid的值由您自行定义,需为您的用户或用户设备的唯一标识符,例如传入您业务的userid或者IMEI、IDFA等您业务用户的设备ID。传入traceid后,埋点日志上报功能开启,后续可以使用播放质量监控、单点追查和视频播放统计功能。

    • setTraceId参数设置为DisableAnalytics:关闭埋点日志上报,后续无法使用播放质量监控、单点追查和视频播放统计功能。

    // 创建播放器
    self.player = [[AliPlayer alloc] init];
    // 建议传入traceId
    [play setTraceID:@"xxxxxx"];
  2. 设置监听器。

    播放器支持设置多个监听器。

    • prepare必须设置,因为手动播放需要在prepare回调中调用start开始播放。

    • onPlayerEventonError较为重要,建议您设置。

    @interface SimplePlayerViewController ()<AVPDelegate>
    @end
    - (void)viewDidLoad {
        self.player = [[AliPlayer alloc] init];
        self.player.playerView = self.avpPlayerView.playerView;
        self.player.delegate = self;
        //...
    }
    /**
     @brief 错误代理回调
     @param player 播放器player指针
     @param errorModel 播放器错误描述,参考AliVcPlayerErrorModel
     */
    - (void)onError:(AliPlayer*)player errorModel:(AVPErrorModel *)errorModel {
        // 提示错误,及stop播放
    }
    /**
     @brief 播放器事件回调
     @param player 播放器player指针
     @param eventType 播放器事件类型,@see AVPEventType
     */
    -(void)onPlayerEvent:(AliPlayer*)playereventType:(AVPEventType)eventType{
        switch(eventType){
            caseAVPEventPrepareDone:{
                // 准备完成
                // 在player设置autoPlay为NO时,建议在准备完成回调中手动调用start。
                [self.playerstart];
            }
                break;
            case AVPEventAutoPlayStart:
                // 自动播放开始事件
                break;
            case AVPEventFirstRenderedStart:
                // 首帧显示
                break;
            case AVPEventCompletion:
                // 播放完成
                break;
            case AVPEventLoadingStart:
                // 缓冲开始
                break;
            case AVPEventLoadingEnd:
                // 缓冲完成
                break;
            case AVPEventSeekEnd:
                // 跳转完成
                break;
            case AVPEventLoopingStart:
                // 循环播放开始
                break;
            default:
                break;
        }
    }
    /**
     @brief 视频当前播放位置回调
     @param player 播放器player指针
     @param position 视频当前播放位置
     */
    - (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
        // 更新进度条
    }
    /**
     @brief 视频缓存位置回调
     @param player 播放器player指针
     @param position 视频当前缓存位置
     */
    - (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
        // 更新缓冲进度
    }
    /**
     @brief 获取track信息回调
     @param player 播放器player指针
     @param info track流信息数组参考AVPTrackInfo
     */
    - (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
        // 获取多码率信息
    }
    /**
     @brief 字幕显示回调
     @param player 播放器player指针
     @param index 字幕显示的索引号
     @param subtitle 字幕显示的字符串
     */
    - (void)onSubtitleShow:(AliPlayer*)player index:(int)index subtitle:(NSString *)subtitle {
        // 获取字幕进行显示
    }
    /**
     @brief 字幕隐藏回调
     @param player 播放器player指针
     @param index 字幕显示的索引号
     */
    - (void)onSubtitleHide:(AliPlayer*)player index:(int)index {
        // 隐藏字幕
    }
    /**
     @brief 获取截图回调
     @param player 播放器player指针
     @param image 图像
     */
    - (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
        // 预览,保存截图
    }
    /**
     @brief track切换完成回调
     @param player 播放器player指针
     @param info 切换后的信息参考AVPTrackInfo
     */
    - (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
        // 切换码率结果通知
    }
  3. 创建DataSource。

    • iOS播放器SDK支持4种点播播放方式,包括:UrlSource播放、VidAuth播放(视频点播用户推荐使用)、VidSts播放、加密播放。

    • iOS播放器SDK支持2种直播播放方式,UrlSource播放和加密播放。

    说明
    • UrlSource是直接通过URL播放,VidSts,VidAuth是通过Vid进行播放。

    • 接入地域Region的设置,请参见点播地域标识

    点播视频播放

    点播UrlSource播放

    使用UrlSource播放方式播放点播视频,需要将播放器的source属性设置为播放地址。

    • 阿里云视频点播服务中的播放地址:可以调用GetPlayInfo接口获取。建议您集成点播服务端SDK来获取音视频播放地址,免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户

    • 本地视频地址:请确保有访问权限,可以通过系统API获取到可访问的本地视频文件完整路径,例如:/sdcard/xxx/xxx/xxx.mp4content://xxx/xxx/xx.mp4

    AVPUrlSource *urlSource = [[AVPUrlSource alloc] urlWithString:url]; // 必选参数,播放地址,可以是第三方点播地址,或阿里云点播服务中的播放地址,也可以是本地视频地址。
    [self.player setUrlSource:urlSource]; 

    点播VidAuth播放(推荐)

    使用VidAuth播放方式播放点播视频,需要将播放器的vid属性设置为音视频ID,将playauth属性设置为音视频播放凭证。

    • 音视频ID:可以在音视频上传完成后通过控制台(路径:媒资库>音/视频)或服务端接口(SearchMedia)获取。

    • 音视频播放凭证:可以调用GetVideoPlayAuth接口获取。建议您集成点播服务端SDK来获取音视频播放凭证,免去自签名的麻烦。调用接口获取音视频播放凭证的示例请参见开发者门户

    推荐视频点播用户采用此播放方式。相比STS播放方式,PlayAuth播放方式在易用性和安全性上更有优势,对比详情请参见凭证方式与STS方式对比

    AVPVidAuthSource *authSource = [[AVPVidAuthSource alloc] init];
    authSource.vid = @"Vid信息"; // 必选参数,视频ID(VideoId)。
    authSource.playAuth = @"<yourPlayAuth>"; // 必选参数,播放凭证,需要调用点播服务的GetVideoPlayAuth接口生成。
    authSource.region = @"接入地域"; // 5.5.5.0及之后版本播放器SDK,本参数已弃用,无需设置region,播放器会自动解析region;5.5.5.0之前版本播放器SDK,本参数必选,点播服务的接入地域,默认为cn-shanghai。
    // authSource.authTimeout = 3600; // 播放地址的有效时长,单位:秒。该时长会覆盖在视频点播控制台设置的URL鉴权的有效时长。如果不传,则取默认值3600。如需设置此参数,请确保该时间大于视频的实际时长,防止播放地址在播放完成前过期。
    [self.player setAuthSource:authSource];

    点播VidSts播放

    使用点播VidSts播放方式播放点播视频是指用STS临时凭证而非点播音视频播放凭证播放。STS安全令牌和STS临时AK对(AccessKeyId和AccessKeySecret)需要提前获取,获取方式请参见使用STS临时授权方案上传视频

    AVPVidStsSource *source = [[AVPVidStsSource alloc] init];
    source.vid = @"Vid信息"; // 必选参数,视频ID(VideoId)。
    source.region = @"接入地域"; // 必选参数,点播服务的接入地域,默认为cn-shanghai。
    source.securityToken = @"<yourSecurityToken>"; // 必选参数,STS安全令牌,需要调用STS服务的AssumeRole接口生成。
    source.accessKeySecret = @"<yourAccessKeySecret>"; // 必选参数,STS临时AK对的访问密钥,需要调用STS服务的AssumeRole接口生成。
    source.accessKeyId = @"<yourAccessKeyId>"; // 必选参数,STS临时AK对的访问密钥ID,需要调用STS服务的AssumeRole接口生成。
    // source.authTimeout = 3600; // 播放地址的有效时长,单位:秒。该时长会覆盖在视频点播控制台设置的URL鉴权的有效时长。如果不传,则取默认值3600。如需设置此参数,请确保该时间大于视频的实际时长,防止播放地址在播放完成前过期。
    // 设置播放源
    [self.player setStsSource:source]

    点播加密播放

    点播视频支持HLS标准加密、阿里云私有加密和DRM加密。加密播放请参见如何播放加密视频

    直播视频播放

    直播UrlSource播放

    使用URL播放方式播放直播视频,需要将播放器的source属性设置为直播拉流地址。播放地址可以是第三方直播地址或阿里云直播服务中的拉流地址。

    阿里云直播拉流地址可以通过直播控制台的地址生成器生成。详情请参见直播地址生成器

    AVPUrlSource *urlSource = [[AVPUrlSource alloc] urlWithString:url]; // 必选参数,播放地址,可以是第三方直播地址,或阿里云直播服务中的拉流地址。
    [self.player setUrlSource:urlSource];

    直播DRM加密播放

    直播DRM加密播放请参见播放DRM加密视频-Web端

  4. 设置显示View。

    如果播放源有画面,那么需要设置显示的view到播放器中,用来显示画面。示例如下:

    self.player.playerView = self.avpPlayerView.playerView;// 用户显示的view
  5. 可选:开启自动播放,默认为关闭状态。

    self.player.autoPlay = YES;
  6. 准备播放。

    调用[self.player prepare]开始读取并解析数据。

    [self.player prepare];
  7. 开始播放。

    • 如果未开启自动播放,需要在AVPEventPrepareDone回调中调用start开始播放视频。

    • 如果开启了自动播放,则不需要调用start,数据解析完成后将开始自动播放视频。

    重要

    自动播放的时候将不会回调AVPEventPrepareDone回调,而会回调AVPEventAutoPlayStart回调。

    [self.player start];

控制播放

iOS播放器SDK支持开始、暂停、从指定时间点播放等主流操作。

开始播放

开始播放视频,由start接口实现。示例如下:

 [self.player start];

从指定时间开始播放

跳转到某个时刻进行播放,由seekToTime接口实现。适用于用户拖拽进度条,或续播等需要从指定时间点开始播放的场景。示例如下:

// position为指定的时间。单位:毫秒。seekMode可设置为精准模式和非精准模式。
// 精准seek
[self.player seekToTime:position seekMode:AVP_SEEKMODE_ACCURATE];
// 非精准seek
[self.player seekToTime:position seekMode:AVP_SEEKMODE_INACCURATE];

暂停播放

暂停播放视频,由pause接口实现。示例如下:

[self.player pause];

停止播放

停止播放视频,由stop接口实现。示例如下:

[self.player stop];

设置显示模式

iOS播放器SDK支持填充、旋转、镜像等显示设置。

填充

支持设置宽高比适应、宽高比填充和拉伸填充这3种画面填充模式,由scalingMode接口实现。示例如下:

// 设置宽高比适应(将按照视频宽高比等比缩小到view内部,不会有画面变形)
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFIT;
// 设置宽高比填充(将按照视频宽高比等比放大,充满view,不会有画面变形)
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFILL;
// 设置拉伸填充(如果视频宽高比例与view比例不一致,会导致画面变形)
self.player.scalingMode = AVP_SCALINGMODE_SCALETOFILL;

旋转

指画面按指定角度旋转,由rotateMode接口实现。示例如下:

// 设置画面顺时针旋转0度
self.player.rotateMode = AVP_ROTATE_0;
// 设置画面顺时针旋转90度
self.player.rotateMode = AVP_ROTATE_90;
// 设置画面顺时针旋转180度
self.player.rotateMode = AVP_ROTATE_180;
// 设置画面顺时针旋转270度
self.player.rotateMode = AVP_ROTATE_270;

镜像

支持水平镜像、垂直镜像和无镜像,由mirrorMode接口实现。示例如下:

// 设置无镜像
self.player.mirrorMode = AVP_MIRRORMODE_NONE;
// 设置水平镜像
self.player.mirrorMode = AVP_MIRRORMODE_HORIZONTAL;
// 设置垂直镜像
self.player.mirrorMode = AVP_MIRRORMODE_VERTICAL;

获取播放信息

iOS播放器SDK支持获取当前的播放进度、播放时长和缓冲进度信息。

获取当前播放进度

指获取当前的播放时刻,需要在onCurrentPositionUpdate回调中获取position。示例如下:

- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
// position为当前播放进度,单位为毫秒
NSString *position = [NSString stringWithFormat:@"%lld, position"];
}

获取播放时长

指获取视频总时长。需要在视频加载完成以后才可以获取到,比如在 onPrepared 回调之后再获取。单位:毫秒。示例如下:

-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
  switch (eventType) {
    case AVPEventPrepareDone: {
      if (self.player.duration >= 0) {
       NSString *duration  = self.player.duration;
      }
    }
      break;
    default:
      break;
  }
}

获取缓冲进度

指获取视频当前的缓冲进度,需要在onBufferedPositionUpdate回调中获取position。示例如下:

- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    NSString *bufferPosition = position;
}

获取实时渲染帧率、音视频码率、网络下行码率

示例如下:

// 获取当前渲染的帧率,数据类型为Float。
[self.playergetOption:AVP_OPTION_RENDER_FPS]
// 获取当前播放的视频码率,数据类型为Float,单位为bps。
[self.playergetOption:AVP_OPTION_VIDEO_BITRATE]
// 获取当前播放的音频码率,数据类型为Float,单位为bps。
[self.playergetOption:AVP_OPTION_AUDIO_BITRATE]
// 获取当前的网络下行码率,数据类型为Float,单位为bps。
[self.playergetOption:AVP_OPTION_DOWNLOAD_BITRATE]

监听播放状态

指监听播放器的状态,onPlayerStatusChanged回调参数为当前播放器状态。示例如下:

- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
    switch (newStatus) {
    case AVPStatusIdle:{
           // 空转,闲时,静态
        }
 break;
        case AVPStatusInitialzed:{
           // 初始化完成
        }
 break;
        case AVPStatusPrepared:{
           // 准备完成
        }
 break;
        case AVPStatusStarted:{
           // 正在播放
        }
 break;
case AVPStatusPaused:{
           // 播放暂停
        }
 break;
case AVPStatusStopped:{
           // 播放停止
        }
 break;
case AVPStatusCompletion:{
           // 播放完成
        }
 break;
case AVPStatusError:{
           // 播放错误
        }
 break;
        default:
            break;
    }
}

设置音量

设置音量包括音量调节和静音设置。

音量调节

指调节音量大小,支持0~2倍,当音量大于1时,可能出现噪音,不推荐使用。由volume接口实现。设置后还可获取音量信息。示例如下:

// volume的值为0~2之间的实数。
self.player.volume = 1.0f;
// 获取音量信息。
self.player.volume

静音设置

指将播放中的视频设置为静音状态,由muted接口实现。示例如下:

self.player.muted = YES;

倍速播放

iOS播放器SDK提供了倍速播放视频的功能,通过设置rate方法,能够以0.5倍~5倍速去播放视频。同时保持变声不变调。示例如下:

// 设置倍速播放:支持0.5~5倍速的播放,通常按0.5的倍数来设置,例如0.5倍、1倍、1.5倍等
self.player.rate = 1.0f;

多清晰度设置

直播UrlSource播放方式

说明
  • 支持阿里云视频直播的播放地址或经直播转码后(现支持通用转码和自定义转码)的转码流地址,直播转码详情请参见转码管理;地址获取方式请参见生成推流地址和播放地址

  • 支持ARTC协议和FLV协议的直播流的不同清晰度切换。

  • 推流的gop size需要设置为2s,域名需要配置为时间戳随源。

  • 切换到不符合上述要求的流地址时,会切换失败。

切换清晰度

通过switchStream方法切换清晰度,传递对应新清晰度的URL即可。

[self.player switchStream:newUrl];

清晰度切换通知

清晰度切换成功与失败回调。

//切换成功回调
- (void)onStreamSwitchedSuccess:(AliPlayer*)player URL:(NSString*)URL;

//切换失败回调
- (void)onStreamSwitchedFail:(AliPlayer*)player URL:(NSString*)URL errorModel:(AVPErrorModel *)errorModel;

点播Vid播放方式(VidAuth或VidSts)

如果使用Vid方式(VidAuth或VidSts)播放,无需额外设置。iOS播放器SDK会从点播服务获取清晰度列表。iOS播放器SDK支持获取和切换清晰度,UrlSource方式暂不支持此设置。

获取清晰度

当视频加载完成后,可以获取视频的清晰度。可以使用onTrackReady监听回调返回info信息,获取清晰度trackBitrate。

- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    for (int i=0; i<info.count; i++) {
        AVPTrackInfo* track = [info objectAtIndex:i];
        switch (track.trackType) {
            case AVPTRACK_TYPE_VIDEO: {
                int trackBitrate = track.trackBitrate;
            }
                break;
        }
    }
}

切换清晰度

切换清晰度通过selectTrack方法,传递对应TrackInfo的index即可。

[self.playerselectTrack:index];

清晰度切换通知

清晰度切换完成回调onTrackChanged。

- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
 // 切换完成
}

循环播放

iOS播放器SDK提供了循环播放视频的功能。调用loop开启循环播放,播放完成后,将会自动从头开始播放视频。示例如下:

self.player.loop = YES;

同时循环开始的回调将会使用AVPEventLoopingStart中通知。示例如下:

- (void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventLoopingStart:
            break;
    }
}

切换音轨

iOS播放器SDK提供了切换音轨的功能,适用于用户观看多语言配音的视频时可以自主进行配音语言切换等场景。

使用说明

目前仅支持非列表播放流(例如MP4流)、单码率混合HLS流、单码率非混合HLS流的音频流之间的切换以及多码率混合HLS流的子流切换。各类型视频流说明如下:

视频流类型

视频流后缀

码率数量

子m3u8数量

子流类型

切换说明

非列表播放流(例如MP4流)

.mp4

1

-

一条播放流汇聚了一路视频流、可能多路音频流和多路字幕流。

支持多路音频流之间的切换。

单码率混合HLS流

.m3u8

1

1

一条播放流汇聚了一路视频流、可能多路音频流和多路字幕流。

支持多路音频流之间的切换。

单码率非混合HLS流

.m3u8

1

n

m3u8,每条子流只能是视频流、音频流或字幕流中的一种。

支持多路音频流之间的切换。

多码率混合HLS流

.m3u8

n

n

m3u8,每条子流汇聚了一路视频流、可能多路音频流和多路字幕流,不同子流之间码率不同。

目前仅支持子流之间的切换,不支持子流的多路音频流之间的切换。

使用示例

  1. 设置回调。

      // onSubTrackReady回调,通常发生在prepare回调之前。
    - (void)onSubTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
        // 通过getSubMediaInfo主动获取对应的MediaInfo信息,需要在收到onSubTrackReady回调后才可以调用,否则为空。
        AVPMediaInfo* subMediaInfo = [player getSubMediaInfo];
        //遍历
        for (int i=0; i<subMediaInfo.tracks.count; i++) {
        	AVPTrackInfo* track = [mediaInfo.tracks objectAtIndex:i];
            //获取到对应的track
        }
    }
  2. 切换音轨。

    [self.player selectTrack:myTrack.trackIndex accurate:YES]

获取SDK日志

在播放器SDK运行过程中会生成详细的日志信息,包括网络请求的状态、系统调用的结果、权限申请情况等各种运行事件。开发者可以通过查看这些日志进行代码调试或排查问题,提高开发效率。

方式一:通过开发工具的控制台获取播放器SDK日志

此方式适用于在您本地可以复现问题并抓取日志的场景。

  1. 打开日志并设置日志级别。

    // 打开日志开关
    [AliPlayer setEnableLog:YES];
    // 设置日志级别,默认为LOG_LEVEL_INFO,如需排查问题,请设置为LOG_LEVEL_TRACE
    [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:nil];
  2. 收集日志。

    • 方法一:控制台查看日志

      复现问题后,可在您开发工具(例如XCode)的控制台获取日志。

    • 方法二:自定义路径将日志输出到文件

      1. 打开日志后,在创建播放器实例之前,在沙盒路径下自定义设置日志文件的生成路径。

        NSArray *paths =NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,NSUserDomainMask, YES);
        NSString *documentDirectory = [paths objectAtIndex:0];
        // logFilePath为示例路径,可以自己在沙盒路径下创建自定义文件,比如xxxx.log文件。
        NSString *logFilePath = [documentDirectory stringByAppendingPathComponent:@"xxxx.log"];
      2. 将日志信息注入到自定义文件中。

        freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stdout);
        freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stderr);
      3. 复现问题后,可在您自定义设置的路径下获取生成的.log日志文件。

方式二:通过LogCallback监听播放器SDK的输出日志

此方式适用于问题发生在您的用户侧,在您本地无法复现问题并抓取日志的场景。可以通过LogCallback监听播放器SDK的输出日志,并自动输出到您App的日志通道中。

  1. 打开日志并设置日志级别。

    // 打开日志
    [AliPlayer setEnableLog:YES];
    // 设置日志级别,默认为LOG_LEVEL_INFO,如需排查问题,请设置为LOG_LEVEL_TRACE
    [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:^(AVPLogLevel logLevel, NSString *strLog) {
     NSLog(@"strLog:%@", strLog);
    }];
  2. 收集日志。

    复现问题后,日志将通过您App的日志通道自动输出到您App的日志文件。

  • 本页导读 (1)
文档反馈