常用功能 - 视频点播

本文提供Windows播放器SDK常用功能的使用示例。

基础播放

创建播放器

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

创建播放器。

创建AliPlayer播放器。

using namespace alivc_player;
AliPlayer* mPlayerPtr = AliPlayer::CreatePlayer();

设置监听器。
Windows播放器SDK提供了各种事件回调，比如：onPlayerEvent、onError等事件。使用时需要一个类继承IAVPListener，并实现里面的纯虚函数。示例如下：
```
mPlayerPtr->setListener(new AVPListenerImpl);
```
创建播放源。
- Windows播放器SDK支持4种点播播放方式，包括：UrlSource播放、VidAuth播放（视频点播用户推荐使用）、VidSts播放、VidMps播放。
- Windows播放器SDK仅支持1种直播播放方式，为UrlSource播放。
点播视频播放
点播UrlSource播放 VidAuth播放点播VidSts播放 VidMps播放
使用点播UrlSource播放方式播放点播视频，需要将播放器的source属性设置为播放地址。播放地址可以是第三方点播地址或阿里云点播服务中的播放地址。阿里云播放地址可以调用获取音视频播放地址接口获取。建议您集成点播服务端SDK来获取音视频播放地址，免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户。

点播UrlSource播放示例
```
AVPUrlSource urlSource;
urlSource.setUrl("media url");  //播放地址，可以是第三方点播地址，或阿里云点播服务中的播放地址。
mPlayerPtr->setSource(urlSource);
```
使用VidAuth播放方式播放点播视频，需要将播放器的vid属性设置为音视频ID，将playauth属性设置为音视频播放凭证。音视频ID可以在音视频上传完成后通过控制台（路径：媒资库 > 音/视频。）或服务端接口（SearchMedia ）获取。音视频播放凭证可以调用获取音视频播放凭证接口获取。建议您集成点播服务端SDK来获取音视频播放凭证，免去自签名的麻烦。调用接口获取音视频播放凭证的示例请参见开发者门户。

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

VidAuth播放示例
```
AVPVidAuthSource authSource;
authSource.initWithVid("Vid信息",
    "playAuth信息",  // 播放凭证
     "接入地域");  // 点播服务的接入地域，默认为cn-shanghai
mPlayerPtr->setSource(authSource);
```
使用点播VidSts播放方式播放点播视频是指用STS临时凭证而非点播音视频播放凭证播放。STS临时Token需要提前获取，获取方式请参见获取STS临时Token 。播放时需要将播放器的securityToken属性设置为STS临时Token，同时设置为STS临时Token生成的临时AK对（accessKeyId和accessKeySecret）。

点播VidSts播放示例
```
AVPVidStsSource vidSource;
vidSource.initWithVid("Vid信息",   //视频ID（VideoId）
"<yourAccessKeyId>",   //鉴权ID
"<yourAccessKeySecret>",  //鉴权密钥
 	"<yourSecurityToken>",   //安全token
"region",   //接入地域
nullptr);
mPlayerPtr->setSource(vidSource);
```
VidMps播放方式是播放器为媒体处理用户（MPS用户）提供的播放方式。VidMps播放既需要提前获取以下信息：
- vid：媒体处理系统中的媒资ID。
- AcessKeyId和AccessKeySecret：随STS临时Token下发的临时AK对。
- SecurityToken：STS临时Token。
- domainRegion：媒体资源所在的地域。
- authInfo：授权信息。
获取MPS媒体相关信息请参见媒体处理视频播放。

VidMps播放示例
```
AVPVidMpsSource mpsSource;
mpsSource.initWithVid("媒体ID",   // 媒体ID，也是视频ID（VideoId），可以通过媒体处理控制台（媒体管理>媒体列表路径）查询。示例：1e067a2831b641db90d570b6480f****。
"<yourAccessKeyId>", // 鉴权ID
         "<yourAccessKeySecret>",  //鉴权密钥
"<yourSecurityToken>",   //安全token
         "认证信息",  // 设置认证信息
"接入地域",  // 媒体资源所在的区域（cn-shanghai，cn-hangzhou等）。
"播放Domain信息",  // 设置播放Domain
         "HlsUriToken信息"); // 设置HlsUriToken
mPlayerPtr->setSource(mpsSource);
```
直播视频UrlSource播放

使用UrlSource播放方式播放直播视频，需要将播放器的setUrl属性设置为直播拉流地址。播放地址可以是第三方直播地址或阿里云直播服务中的拉流地址。阿里云直播拉流地址可以通过直播控制台的地址生成器生成。详情请参见阿里云直播地址生成器。
```
AVPUrlSource urlSource;
urlSource.setUrl("media url");  //播放地址可以是第三方直播地址，或阿里云直播服务中的拉流地址。
mPlayerPtr->setSource(urlSource);
```
设置显示View。
如果播放源有画面，那么需要设置显示的view到播放器中，用来显示画面。示例如下：
```
mPlayerPtr->setView((void *)显示区域的HWND);
```
准备播放。
调用prepare()方法准备播放。
```
mPlayerPtr->prepare();
```
可选：开启自动播放，默认为关闭状态。
```
mPlayerPtr->setAutoPlay(true);
```
开始播放。
- 如果未开启自动播放，需要在OnPrepard回调中调用mPlayerPtr->start();开始播放视频。
- 如果开启了自动播放，则不需要调用mPlayerPtr->start();，数据解析完成后将开始自动播放视频。
```
mPlayerPtr->start();
```

控制播放

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

开始播放

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

mPlayerPtr->start();

从指定时间开始播放

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

//跳转到特定时刻的视频画面。
//mode取值：AVP_SEEKMODE_ACCURATE（精确seek）和AVP_SEEKMODE_INACCURATE（非精确seek）。非精确seek会跳转到向前最近的关键帧处。精确seek会跳转到精确的时间，但比非精确seek会慢一些。
mPlayerPtr->seekToTime(int64_t time_in_ms, mode);

暂停播放

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

mPlayerPtr->pause();

停止播放

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

mPlayerPtr->stop();

设置显示模式

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

填充

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

//设置宽高比适应（将按照视频宽高比等比缩小到view内部，不会有画面变形）
mPlayerPtr->setScalingMode(AVP_SCALINGMODE_SCALEASPECTFIT);
//设置宽高比填充（将按照视频宽高比等比放大，充满view，不会有画面变形）
mPlayerPtr->setScalingMode(AVP_SCALINGMODE_SCALEASPECTFILL);
//设置拉伸填充（如果视频宽高比例与view比例不一致，会导致画面变形）
mPlayerPtr->setScalingMode(AVP_SCALINGMODE_SCALETOFILL);

旋转

画面按指定角度旋转，由setRotateMode接口实现。设置后还可查询旋转角度。示例如下：

//设置画面顺时针旋转0度
mPlayerPtr->setRotateMode(AVP_ROTATE_0);
//设置画面顺时针旋转90度
mPlayerPtr->setRotateMode(AVP_ROTATE_90);
//设置画面顺时针旋转180度
mPlayerPtr->setRotateMode(AVP_ROTATE_180);
//设置画面顺时针旋转270度
mPlayerPtr->setRotateMode(AVP_ROTATE_270);
//获取旋转角度
mPlayerPtr->getRotateMode();

镜像

支持水平镜像、垂直镜像和无镜像，由setMirrorMode接口实现。示例如下：

//设置无镜像
mPlayerPtr->setMirrorMode(AVP_MIRRORMODE_NONE);
//设置水平镜像
mPlayerPtr->setMirrorMode(AVP_MIRRORMODE_HORIZONTAL);
//设置垂直镜像
mPlayerPtr->setMirrorMode(AVP_MIRRORMODE_VERTICAL);

获取播放信息

Windows播放器SDK支持获取当前的播放进度和播放时长。

获取当前播放进度

获取当前的播放时刻，在onCurrentPositionUpdate回调中获取，单位毫秒。示例如下：

void AlivcLivePlayerMainDlg::onCurrentPositionUpdate(AliPlayer *player, int64_t position)
{
    //position为当前播放进度，单位为毫秒
printf("current position is %lld ms", position);
}

获取播放时长

获取视频总时长。需要在视频加载完成以后才可以获取到，可以在AVPEventPrepareDone事件后获取duration。示例如下：

void AlivcLivePlayerMainDlg::onPlayerEvent(AliPlayer *player, AVPEventType eventType)
{
    if (eventType == AVPEventPrepareDone) {
        int64_t duration = mPlayerPtr->getDuration();
printf("total duration is %lld ms", duration);
    }
}

获取缓冲进度

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

void AlivcLivePlayerMainDlg::onBufferedPositionUpdate(AliPlayer *player, int64_t position)
{
    printf("buffered position is %lld ms", position);
}

监听播放状态

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

void AlivcLivePlayerMainDlg::onPlayerStatusChanged(AliPlayer *player, AVPStatus oldStatus, 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;
}
}

设置音量

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

音量调节

调节音量大小，由setVolume接口实现。设置后还可获取音量信息。示例如下：

//volume的值为0～2.0。
mPlayerPtr->setVolume(1.0f);
//获取音量信息。
mPlayerPtr->getVolume();

静音设置

将播放中的视频设置为静音状态，由setMute接口实现。示例如下：

mPlayerPtr->setMute(true);

倍速播放

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

//设置倍速播放：支持0.5～2倍速的播放，通常按0.5的倍数来设置，例如0.5倍、1倍、1.5倍等
mPlayerPtr->setRate(1.5);

多清晰度设置

如果使用VID方式（VidAuth（推荐）及VidSts）播放，无需额外设置。Windows播放器SDK会从视频点播服务获取清晰度列表。Windows播放器SDK支持获取和切换清晰度，UrlSource播放方式暂不支持此设置。

获取清晰度

当视频加载完成后，可以获取视频的清晰度。

void AlivcLivePlayerMainDlg::onTrackReady(AliPlayer *player, AVPTrackInfo *info[], int count)
{
    if (count < 0) {
        return;
    }

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

切换清晰度

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

mPlayerPtr->selectTrack(trackIndex);

清晰度切换通知

清晰度切换成功回调。

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

循环播放

Windows播放器SDK提供了循环播放视频的功能。调用setLoop开启循环播放，播放完成后，将会自动从头开始播放视频。同时循环开始的回调将会在AVPEventLoopingStart中通知。示例如下：

mPlayerPtr->setLoop(true);

进阶播放

外挂字幕

Windows播放器SDK支持添加和切换外挂字幕，现仅支持SRT格式。示例如下：

创建显示字幕的控件。

根据不同的字幕格式创建不同的View。

mSubtitleLabelPtr = new QLabel(QString(""), this);
mSubtitleLabelPtr->setParent(this);

设置字幕相关监听。

//外挂字幕被添加
void AlivcLivePlayerMainDlg::onSubtitleExtAdded(AliPlayer *player, int64_t trackIndex, const char *URL)
{
    emit SgnAddExtSubtitle((qint64) trackIndex);
}
//字幕显示回调
void AlivcLivePlayerMainDlg::onSubtitleShow(AliPlayer *player, int64_t trackIndex, int64_t subtitleId, const char *subtitle)
{
    emit SgnUpdateSubtitle(QString::fromStdString(subtitle), true);
}
//字幕隐藏回调
void AlivcLivePlayerMainDlg::onSubtitleHide(AliPlayer *player, int64_t trackIndex, int64_t subtitleId)
{
    emit SgnUpdateSubtitle(QString(""), false);
}

添加字幕。
```
mPlayerPtr->addExtSubtitle("url");
```

切换字幕。

mPlayerPtr->selectExtSubtitle(trackIndex, true);

纯音频播放

通过禁用视频播放，达到纯音频播放的效果。在prepare之前配置PlayerConfig。

AVPConfig *config = mPlayerPtr->getConfig();
config->mDisableVideo = true;
mPlayerPtr->setConfig(config);

网络自适应切换视频清晰度

Windows播放器SDK支持多码率自适应HLS、DASH视频流。在prepare成功之后，通过getMediaInfo可以获取到各个码流的信息，即TrackInfo。示例如下：

AVPMediaInfo info = mPlayerPtr->getMediaInfo();
for (int i = 0; i < info.trackCount; i++) {
     AVPTrackInfo *track = info.tracks[i];
}

说明 HLS、DASH视频流需要经过多码率视频转码模板组打包处理，可以在点播控制台的配置管理 > 媒体处理配置 > 转码模板组中配置生产对应的视频流，详细操作请参见视频或字幕打包模板设置。

在播放过程中，可以通过调用播放器的selectTrack方法切换播放的码流，取值为SELECT_AVPTRACK_TYPE_VIDEO_AUTO时，为多码率自适应。示例如下：

//多码率切换
mPlayerPtr->selectTrack(trackIndex);
//切换为自适应码率
mPlayerPtr->selectTrack(SELECT_AVPTRACK_TYPE_VIDEO_AUTO);

切换的结果会在onTrackChanged监听之后会回调。示例如下：

void AlivcLivePlayerMainDlg::onTrackChanged(AliPlayer *player, AVPTrackInfo *info)
{
    if (info->trackType == AVPTRACK_TYPE_VIDEO) {
        // video changed
    }
    // etc
}

截图

Windows播放器SDK提供了对当前视频截图的功能，由snapShot接口实现。截取的是原始的argb32格式的数据，回调接口为onSnapshotImageBuffer。示例如下：

//截取当前播放的画面
mPlayerPtr->snapshot();
//截图回调
void AlivcLivePlayerMainDlg::onSnapshotImageBuffer(AliPlayer *player, int width, int height, unsigned char *pARGBBuffer)
{
    QString savePath = "save path";
    QImage snapshot(pARGBBuffer, width, height, QImage::Format_ARGB32);
    snapshot.save(savePath);
}

注意截图不包含界面。

试看

Windows播放器SDK通过配合点播服务配置，可以实现试看功能，VidAuth播放（推荐）和VidSts播放方式支持试看功能。如何配置和使用试看功能，请参见点播试看。

配置试看功能之后，通过VidPlayerConfigGenerator接口的setPreviewTime方法设置播放器的试看时长。当设置试看的时长，通过播放器SDK播放视频时，服务端将不会返回完整的视频内容，而是返回试看时间段的内容。以VidSts播放方式为例，示例如下：

VidPlayerConfigGenerator playConfigGen;
playConfigGen.setPreviewTime(10);
AVPVidStsSource vidSource;
vidSource.initWithVid(视频vid,
                        "accessKeyId",
                        "accessKeySecret",
                        "安全token",
                        "接入地域",
                        playConfigGen.generatePlayerConfig());
mPlayerPtr->setSource(vidSource);

设置Referer

Windows播放器SDK支持设置Referer，配合控制台的黑白名单Referer，可以控制访问权限，由AVPConfig方法设置请求Referer。示例如下：

//先获取配置
AVPConfig *pConfig = mPlayerPtr->getConfig();
//设置referer
pConfig->referer = referer;
....//其他设置
//给播放器设置配置
mPlayerPtr->setConfig(pConfig);

设置UserAgent

Windows播放器SDK提供了AVPConfig用来设置请求UA。设置之后，播放器请求的过程中将会带上UA信息。示例如下：

//先获取配置
AVPConfig *pConfig = mPlayerPtr->getConfig();
//设置userAgent
pConfig->userAgent = userAgent;
....//其他设置
//设置配置给播放器
mPlayerPtr->setConfig(pConfig);

配置网络重试时间和次数

Windows播放器SDK支持设置网络超时的时间和重试次数，由AVPConfig接口实现。示例如下：

//先获取配置
AVPConfig *pConfig = mPlayerPtr->getConfig();
//设置网络超时时间，单位ms
pConfig->networkTimeout = 5000;
//设置超时重试次数。每次重试间隔为networkTimeout。networkRetryCount=0则表示不重试，重试策略App决定，默认值为2
pConfig->networkRetryCount = 2;
....//其他设置
//给播放器设置配置
mPlayerPtr->setConfig(pConfig);

说明

如果设置了networkRetryCount，若此时发生网络问题，导致出现loading后，那么将会重试networkRetryCount次，每次的间隔时间为networkTimeout。
如果重试次数超过上限值之后，还是loading的状态，那么就会回调onError事件，此时AVPErrorModel.code为ERROR_LOADING_TIMEOUT。
如果networkRetryCount设置为0，当网络重试超时的时候，播放器就会回调onPlayerEvent，参数eventWithString为EVENT_PLAYER_NETWORK_RETRY。此时可以调用播放器的reload方法进行重新加载网络，或者进行其他的处理。

配置缓存和延迟控制

对于播放器来说，缓存的控制非常重要。合理的配置可以有效的加快起播速度并减少卡顿。Windows播放器SDK通过AVPConfig提供了设置缓存和延迟的控制接口。示例如下：

//先获取配置
AVPConfig *pConfig = mPlayerPtr->getConfig();
//最大延迟。注意：仅直播有效。当延时比较大时，播放器SDK内部会追帧等，保证播放器的延时在这个范围内。
pConfig->maxDelayTime = 5000;
//最大缓冲区时长。单位ms。播放器每次最多加载所设置时长的缓冲数据。
pConfig->maxBufferDuration = 50000;
//高缓冲时长。单位ms。当网络不好导致加载数据时，如果加载的缓冲时长到达这个值，结束加载状态。
pConfig->highBufferDuration = 3000;
// 起播缓冲区时长。单位ms。时间设置越短，起播越快。也可能会导致播放之后很快就会进入加载状态。
pConfig->startBufferDuration = 500;
//其他设置
//给播放器设置配置
mPlayerPtr->setConfig(pConfig);

注意三个缓冲区时长的大小关系必须为：startBufferDuration ≤ highBufferDuration ≤ maxBufferDuration。

设置HTTP Header

播放器通过AVPConfig参数，可以给播放器中的请求加上HTTP的header参数。示例如下：

//先获取配置
AVPConfig *pConfig = mPlayerPtr->getConfig();
//设置header
pConfig->headerCount = 1;
pConfig->httpHeaders = new char *[pConfig->headerCount];
//比如使用httpdns时，需要设置Host。
pConfig->httpHeaders[0] = strdup("Host:example.com");
....//其他设置
//设置配置给播放器
mPlayerPtr->setConfig(pConfig);

性能

本地缓存

Windows播放器SDK提供了本地缓存（边播边缓存）的功能，能够让用户重复播放视频时，达到省流量的目的。只需在prepare之前给播放器配置AVPCacheConfig即可实现此功能。示例如下：

AVPCacheConfig mCacheConfig;
//开启缓存功能
mCacheConfig.enable = true;
//能够缓存的单个文件最大时长。超过此长度则不缓存
mCacheConfig.maxDuration = 100;
//缓存目录的最大大小。超过此大小，将会删除最旧的缓存文件
mCacheConfig.maxSizeMB = 200;
//缓存目录的位置，需替换成APP期望的路径
mCacheConfig.path = strdup("please use your cache path here");
//设置缓存配置给到播放器
mPlayerPtr->setCacheConfig(&mCacheConfig);

缓存成功之后，以下情况将会利用缓存文件（必须已经设置了setCacheConfig）：

如果设置了循环播放，那么第二次播放的时候，将会自动播放缓存的文件。
缓存成功后，重新创建播放器，播放同样的资源，也会自动使用缓存文件。

注意 VID的缓存文件是通过vid等信息定位的，所以VID的缓存文件将需要网络请求信息之后才能确定使用哪个缓存文件。

边播边缓存的使用有限制条件，具体如下：

对于UrlSource播放方式。如果是HLS（即M3U8）地址，将不会缓存。如果是其他支持的格式，则根据缓存配置进行缓存。
对于VidAuth、VidSts播放方式，将会根据缓存配置进行缓存。
播放器读取完全部的数据则视为缓存成功。如果在此之前，调用stop，或者出错onError，则缓存将会失败。
cache内的seek的操作不会影响缓存结果。cache外的seek会导致缓存失败。
如果加密文件与APP信息不一致，将会缓存失败。
cache的结果回调，会通过onPlayerEvent回调，包括EVENT_PLAYER_CACHE_SUCCESS和EVENT_PLAYER_CACHE_ERROR。

视频下载

Windows播放器SDK提供了点播服务视频的下载功能，能够通过VidAuth方式和VidSts方式下载点播服务上的视频。同时，下载的方式提供了安全下载和普通下载的模式（可登录点播控制台，选择配置管理 > 分发加速配置 > 下载设置设置）。

普通下载：使用点播服务加密视频后，下载的视频数据也不是经过阿里云加密的。用户可以用第三方播放器播放。
安全下载：使用点播服务没有加密视频，下载后的视频数据也是经过阿里云加密的。用户用第三方播放器是播放不了的。只能使用阿里云的播放器去播放。

创建下载器。示例如下：

mMediaDownloader = AliMediaDownloader::CreateMediaDownloader();
mMediaDownloader->setListener(new AVDListenerImpl);
mMediaDownloader->setSaveDirectory("saveDir");

下载SDK支持私有加密的下载。为了保证安全性，还需要设置一个加密校验信息，传入encryptedApp.dat文件的内容。示例如下：

InitPrivateService(fileContentBuffer, fileLength);

准备下载源。

通过prepare方法准备下载源，仅支持VidAuth（推荐）和VidSts方式的下载源。以VidSts方式的下载源为例，示例如下：

AVPVidStsSource vidSource;
vidSource.initWithVid(视频vid,
                        "accessKeyId",
                        "accessKeySecret",
                        "安全token",
                        "接入地域",
                        nullptr);
mMediaDownloader->prepareWithVid(&vidSource);

准备成功后选择下载项。

准备成功后，会回调onPrepared方法。选择某个Track进行下载，示例如下：

void YourClass::onPrepared(AliMediaDownloader *downloader, AVPMediaInfo *mediaInfo) {
    AVPTrackInfo *track = mediaInfo->tracks[0];
    mMediaDownloader->selectTrack(track->trackIndex);
}

更新下载源并开始下载。
完成以上操作后，开始下载（为了防止VidSts和VidAuth过期，最好先更新下载源的信息）。示例如下：
```
mMediaDownloader->updateWithVid(&vidSource);
mMediaDownloader->start();
```
下载成功或失败后，释放下载器。
下载成功后，释放下载器。示例如下：
```
delete mMediaDownloader;
mMediaDownloader = nullptr;
```

基础播放

创建播放器

控制播放

设置显示模式

获取播放信息

监听播放状态

设置音量

倍速播放

多清晰度设置

循环播放

进阶播放

外挂字幕

纯音频播放

网络自适应切换视频清晰度

截图

试看

设置Referer

设置UserAgent

配置网络重试时间和次数

配置缓存和延迟控制

设置HTTP Header

性能

本地缓存

视频下载

相关文档