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

进阶播放

外挂字幕

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

  1. 创建显示字幕的控件。
    根据不同的字幕格式创建不同的View。
    mSubtitleLabelPtr = new QLabel(QString(""), this);
    mSubtitleLabelPtr->setParent(this);
  2. 设置字幕相关监听。
    //外挂字幕被添加
    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);
    }
  3. 添加字幕。
    mPlayerPtr->addExtSubtitle("url");
  4. 切换字幕。
    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_SUCCESSEVENT_PLAYER_CACHE_ERROR

视频下载

Windows播放器SDK提供了点播服务视频的下载功能,允许用户通过阿里云播放器将视频缓存至本地观看。同时,提供了普通下载和安全下载两种下载方式。
  • 普通下载

    下载后的视频数据未经过阿里云加密,用户可以用第三方播放器播放。

  • 安全下载

    下载后的视频数据经过阿里云加密。第三方播放器无法播放,仅支持使用阿里云的播放器进行播放。

使用说明

  • 仅VidSts和VidAuth方式支持视频下载功能。
  • 使用播放器的视频下载功能,需要在点播控制台开启并配置下载模式,详细操作请参见下载设置
  • 视频下载支持断点续传。

操作步骤

  1. 可选:配置安全下载的加密校验文件。仅安全下载需要配置,普通下载无需配置。
    说明 请确保配置的加密校验文件与App信息一致,否则会导致视频下载失败。

    如果设置为安全下载方式,则需要将在点播控制台生成的密钥文件配置到播放器SDK中,用于视频下载和播放的解密验证,密钥文件的生成请参见安全下载

    配置一次即可,示例如下:
    InitPrivateService(fileContentBuffer, fileLength);
  2. 创建并设置下载器。
    示例如下:
    mMediaDownloader = AliMediaDownloader::CreateMediaDownloader();
    mMediaDownloader->setListener(new AVDListenerImpl);
    mMediaDownloader->setSaveDirectory("saveDir");
  3. 准备下载源。
    通过prepare方法准备下载源,仅支持VidAuth(推荐)和VidSts方式的下载源。以VidSts方式的下载源为例,示例如下:
    AVPVidStsSource vidSource;
    vidSource.initWithVid("视频vid",
                          "accessKeyId",
                          "accessKeySecret",
                          "安全token",
                          "接入地域",
                          nullptr);
    mMediaDownloader->prepareWithVid(&vidSource);
  4. 准备成功后,选择下载项。
    准备成功后,会回调onPrepared方法。返回的TrackInfo中会包含各视频流的清晰度等信息,请选择一个Track进行下载,示例如下:
    void YourClass::onPrepared(AliMediaDownloader *downloader, AVPMediaInfo *mediaInfo) {
        AVPTrackInfo *track = mediaInfo->tracks[0];
        mMediaDownloader->selectTrack(track->trackIndex);
    }
  5. 更新下载源并开始下载。
    为了防止VidSts和VidAuth过期,建议更新下载源的信息后开始下载。示例如下:
    mMediaDownloader->updateWithVid(&vidSource);
    mMediaDownloader->start();
  6. 下载成功或失败后,释放下载器。
    下载成功后,释放下载器。示例如下:
    delete mMediaDownloader;
    mMediaDownloader = nullptr;

相关文档

接口说明