文档

常用功能

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

基础功能

创建播放器

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

说明

如需播放ARTC流,除了需要在集成时引入RTS相关依赖,Android端还需在创建播放器前调用FlutterAliPlayerFactory.loadRtsLibrary();加载RtsSDK动态库。

  1. 创建播放器。

    创建单实例播放器。

    FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer();

    创建多实例播放器。

    需要在Flutter层管理playerId,在播放器的回调中会返回对应的playerId,用来通知Flutter层。

    FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer(playerId: playerId);
  2. 设置监听器。

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

    • 创建手动播放时,OnPrepard必须设置,因为手动播放需要在OnPrepard回调中调用play开始播放。

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

    以下示例仅展示部分接口,如下所示:

    // 准备成功
    fAliplayer.setOnPrepard((playerId) {});
    // 首帧显示
    fAliplayer.setOnRenderingStart((playerId) {});
    // 视频宽高变化
    fAliplayer.setOnVideoSizeChanged((width, height,playerId) {});
    // 播放器状态变化
    fAliplayer.setOnStateChanged((newState,playerId) {});
    // 加载状态
    fAliplayer.setOnLoadingStatusListener(
        loadingBegin: (playerId) {},
        loadingProgress: (percent, netSpeed,playerId) {},
        loadingEnd: (playerId) {});
    // 拖动完成
    fAliplayer.setOnSeekComplete((playerId) {});
    // 播放器事件信息回调,包括buffer、当前播放进度等等信息,根据infoCode来判断,对应FlutterAvpdef.infoCode
    fAliplayer.setOnInfo((infoCode, extraValue, extraMsg,playerId) {});
    // 播放完成
    fAliplayer.setOnCompletion((playerId) {});
    // 设置流准备完成
    fAliplayer.setOnTrackReady((playerId) {});
    // 截图结果
    fAliplayer.setOnSnapShot((path,playerId) {});
    // 错误结果
    fAliplayer.setOnError((errorCode, errorExtra, errorMsg,playerId) {});
    // 切换流变化
    fAliplayer.setOnTrackChanged((value,playerId) {});
  3. 创建播放源。

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

    • Flutter播放器SDK仅支持1种直播播放方式,为UrlSource播放。

    点播视频播放

    点播UrlSource播放

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

    阿里云播放地址可以调用GetPlayInfo接口获取。建议您通过SDK方式来获取音视频播放地址,免去自签名的麻烦。调用接口获取音视频播放地址的示例请参见开发者门户

    void onViewPlayerCreated(viewId) async {
      // 将渲染的View设置给播放器
      fAliplayer.setPlayerView(viewId);
      // 设置播放源
      switch (_playMode) {
          // UrlSource播放方式
        case ModeType.URL:
          this.fAliplayer.setUrl("播放地址"); // 必选参数,播放地址,可以是第三方点播地址,或阿里云点播服务中的播放地址。
          break;
        default:
      }
    }

    点播VidAuth播放(推荐)

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

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

    • 音视频播放凭证可以调用GetVideoPlayAuth接口获取。建议您通过SDK方式来获取音视频播放凭证,免去自签名的麻烦。调用接口获取音视频播放凭证的示例请参见开发者门户

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

    void onViewPlayerCreated(viewId) async {
      // 将渲染的View设置给播放器
      fAliplayer.setPlayerView(viewId);
      // 设置播放源
      switch (_playMode) {
        // VidAuth播放方式
        case ModeType.AUTH:
          FlutterAliplayer.generatePlayerConfig().then((value) {
          this.fAliplayer.setVidAuth(
              vid: "Vid信息",// 必选参数,视频ID(VideoId)。
              region: "接入地域",// 必选参数,点播服务的接入地域,默认为cn-shanghai。
              playAuth: "<yourPlayAuth>",// 必选参数,播放凭证,需要调用点播服务的GetVideoPlayAuth接口生成。
              playConfig: value);
            });
          break;
        default:
      }
    }

    点播VidSts播放

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

    void onViewPlayerCreated(viewId) async {
      // 将渲染的View设置给播放器
      fAliplayer.setPlayerView(viewId);
      // 设置播放源
      switch (_playMode) {
        // VidSts播放方式
        case ModeType.STS:
          FlutterAliplayer.generatePlayerConfig().then((value) {
          this.fAliplayer.setVidSts(
              vid: "Vid信息",// 必选参数,视频ID(VideoId)。
              region: "接入地域",// 必选参数,点播服务的接入地域,默认为cn-shanghai。
              accessKeyId: "<yourAccessKeyId>",// 必选参数,STS临时AK对的访问密钥ID,需要调用STS服务的AssumeRole接口生成。
              accessKeySecret: "<yourAccessKeySecret>",// 必选参数,STS临时AK对的访问密钥,需要调用STS服务的AssumeRole接口生成。
              securityToken: "<yourSecurityToken>",// 必选参数,STS安全令牌,需要调用STS服务的AssumeRole接口生成。
          	  playConfig: value);
        	});
          break;
        default:
      }
    }

    点播加密播放

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

    直播视频UrlSource播放

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

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

    void onViewPlayerCreated(viewId) async {
      // 将渲染的View设置给播放器
      fAliplayer.setPlayerView(viewId);
      // 设置播放源
      switch (_playMode) {
        // UrlSource播放方式
        case ModeType.URL:
          this.fAliplayer.setUrl("填写资源的播放地址"); // 播放地址可以是第三方直播地址,或阿里云直播服务中的拉流地址。
          break;
        default:
      }
    }
  4. 设置显示View。

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

    @override
    Widget build(BuildContext context) {
      var x = 0.0;
      var y = 0.0;
      Orientation orientation = MediaQuery.of(context).orientation;
      var width = MediaQuery.of(context).size.width;
    
      var height;
      if (orientation == Orientation.portrait) {
        height = width * 9.0 / 16.0;
      } else {
        height = MediaQuery.of(context).size.height;
      }
      AliPlayerView aliPlayerView = AliPlayerView(
          onCreated: onViewPlayerCreated,
          x: x,
          y: y,
          width: width,
          height: height);
      return OrientationBuilder(
        builder: (BuildContext context, Orientation orientation) {
          return Scaffold(
            body: Column(
              children: [
                Container(
                    color: Colors.black,
                    child: aliPlayerView,
                    width: width,
                    height: height),
              ],
            ),
          );
        },
      );
  5. 可选:开启自动播放,默认为关闭状态。

    fAliplayer.setAutoPlay(true);
  6. 准备播放。

    调用prepare()方法准备播放。

    fAliplayer.prepare();
  7. 开始播放。

    • 如果未开启自动播放,需要在OnPrepard回调中调用fAliplayer.play();开始播放视频。

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

    fAliplayer.play();

控制播放

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

开始播放

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

 fAliplayer.play();

从指定时间开始播放

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

// posotion为指定的时间,单位:毫秒。seekMode取值:FlutterAvpdef.ACCURATE(精准seek)和FlutterAvpdef.INACCURATE(非精准seek)
fAliplayer.seek(position,seekMode);

暂停播放

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

fAliplayer.pause();

停止播放

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

fAliplayer.stop();

设置显示模式

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

填充

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

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

旋转

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

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

镜像

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

// 设置无镜像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_NONE);
// 设置水平镜像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_HORIZONTAL);
// 设置垂直镜像
fAliplayer.setMirrorMode(FlutterAvpdef.AVP_MIRRORMODE_VERTICAL);        

获取播放信息

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

获取当前播放进度

获取当前的播放时刻,在onInfo回调中获取,单位毫秒。示例如下:

fAliplayer.setOnInfo((infoCode,extraValue,extraMsg,playerId){
        if(infoCode==FlutterAvpdef.CURRENTPOSITION){
        // extraValue为当前播放进度
}
});

获取播放时长

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

fAliplayer.getMediaInfo().then((value){
        _videoDuration=value['duration'];
});

监听播放状态

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

fAliplayer.setOnStateChanged((newState,playerId){
    //newState为播放状态
switch(newState){
            caseFlutterAvpdef.AVPStatus_AVPStatusIdle:        // 空转、闲时、静态
                    break;
            caseFlutterAvpdef.AVPStatus_AVPStatusInitialzed:  // 初始化完成
                    break;
            caseFlutterAvpdef.AVPStatus_AVPStatusPrepared:    // 准备完成
                    break;
            caseFlutterAvpdef.AVPStatus_AVPStatusStarted:     // 正在播放
                    break;
            caseFlutterAvpdef.AVPStatus_AVPStatusPaused:      // 播放暂停
break;
            caseFlutterAvpdef.AVPStatus_AVPStatusStopped:     // 播放停止
break;
            caseFlutterAvpdef.AVPStatus_AVPStatusCompletion:  // 播放完成
break;
            caseFlutterAvpdef.AVPStatus_AVPStatusError:       // 播放错误
break;
default:
    }
});

设置音量

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

音量调节

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

// volume的值为0~2之间的实数。
fAliPlayer.setVolume(1);
// 获取音量信息。
fAliPlayer.getVolume();

静音设置

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

fAliplayer.setMute(true);

倍速播放

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

// 设置倍速播放:支持0.5~5倍速的播放,通常按0.5的倍数来设置,例如0.5倍、1倍、1.5倍等
fAliplayer.setRate(1.0);

多清晰度设置

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

获取清晰度

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

fAliplayer.getMediaInfo().then((value){
        AVPMediaInfoinfo=AVPMediaInfo.fromJson(value);
info.tracks.forEach((element){
                if(element.trackType==3){
        // 清晰度
    Stringdefinition=element.trackDefinition;
// 流索引
intindex=element.trackIndex;
                }
        }
});

切换清晰度

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

fAliplayer.selectTrack(trackIdx);

清晰度切换通知

清晰度切换成功回调。

fAliplayer.setOnTrackChanged((value,playerId){
        // 有回调表示切换成功,切换失败接口暂未提供
});

循环播放

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

fAliplayer.setLoop(true);

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

fAliplayer.setOnInfo((infoCode, extraValue, extraMsg, playerId) {
      if(infoCode == FlutterAvpdef.LOOPINGSTART){
        // 循环播放开始通知
      }
});

进阶功能

短视频列表播放

  1. 创建列表播放器。

    FlutterAliListPlayer fAliListPlayer = FlutterAliPlayerFactory.createAliListPlayer();
  2. 添加资源、移除资源。

    列表播放器目前只支持两种播放方式:UrlSource播放和VidSts播放。

    // uid是视频的唯一标志。用于区分视频是否一样。如果uid一样,则认为是一样的
    fAliListPlayer.addUrlSource(url,uid);
    fAliListPlayer.addVidSource(vid,uid);
    fAliListPlayer.removeSource(uid);
  3. 设置预加载个数。

    合理设置预加载个数,能够有效的提高起播的速度。示例如下:

    // 设置预加载个数。总共加载的个数为: 1 + count*2。
    fAliListPlayer.setPreloadCount(count);
  4. 播放视频源。

    // uid为必填项,如果是URL播放方式,只需要uid即可,如果是STS方式,则需要填写STS信息
    fAliListPlayer.moveTo();

软硬解切换

Flutter播放器SDK提供了H.264、H.265的硬解码能力,同时提供了setEnableHardwareDecoder开关。默认开,并且在硬解初始化失败时,自动切换为软解,保证视频的正常播放。示例如下:

// 开启硬解,默认开启
fAliplayer.setEnableHardwareDecoder(enable);

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

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

fAliplayer.getMediaInfo().then((value) {
// value为map,value['tracks']可以获取对应的TrackInfos 列表信息,可以参考Demo中AVPMediaInfo info = AVPMediaInfo.fromJson(value); 了解如何解析TrackInfo

});

在播放过程中,可以通过调用播放器的selectTrack方法切换播放的码流,参数为TrackInfo中的trackIndex,切换的结果会在OnTrackChangedListener监听之后会回调。

// 多码率切换
fAliplayer.selectTrack(index);
// 多码率切换并自适应
fAliplayer.selectTrack(-1);

截图

Flutter播放器SDK提供了对当前视频截图的功能,由setOnSnapShot接口实现。

// 截图成功监听
fAliplayer.setOnSnapShot((path,playerId) {

});
// 截图,path为图片保存路径
fAliplayer.snapshot(path);

试看

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

配置试看功能之后,通过setVidAuth接口的previewTime方法设置播放器的试看时长。示例如下:

// previewTime为试看时间,单位:秒
// VidAuth播放方式
fAliplayer.setVidAuth(
        vid: "填写资源的vid",
        region: "填写资源的region",
        playAuth: "填写资源的region",
        previewTime: "填写试看时间,单位:秒");

 // VidSts播放方式
 fAliplayer.setVidSts(
        vid: "填写资源的vid",
        region: "填写资源的region",
        accessKeyId: "填写资源的鉴权id",
                accessKeySecret: "填写资源的鉴权密钥",
                securityToken: "填写资源的安全Token",
        previewTime: "填写试看时间,单位:秒");

其他配置

Flutter播放器SDK的其他播放配置。需要在prepare()方法之前设置给播放器。

var configMap = {
  'mStartBufferDuration':_mStartBufferDurationController.text,// 起播缓冲区时长,单位:毫秒
  'mHighBufferDuration':_mHighBufferDurationController.text,// 高缓冲时长,单位:毫秒
  'mMaxBufferDuration':_mMaxBufferDurationController.text,// 最大缓冲区时长,单位:毫秒
  'mMaxDelayTime': _mMaxDelayTimeController.text,// 直播最大延迟,单位:毫秒。注意:仅直播有效
  'mNetworkTimeout': _mNetworkTimeoutController.text,// 网络超时时间,单位:毫秒
  'mNetworkRetryCount':_mNetworkRetryCountController.text,// 网络超时重试次数,单位:毫秒
  'mMaxProbeSize': _mMaxProbeSizeController.text,// 最大probe大小
  'mReferrer': _mReferrerController.text,// 设置referrer
  'mHttpProxy': _mHttpProxyController.text,// http代理
  'mEnableSEI': mEnableSEI,// 是否启用SEI
  'mClearFrameWhenStop': !mShowFrameWhenStop,// 停止后是否清空画面
  'mDisableVideo': mDisableVideo,// 禁用Video
  'mDisableAudio': mDisableAudio,// 禁用Audio
  'mUserAgent':mUserAgent,// 设置UserAgent
};
// 应用配置
fAliplayer.setConfig(configMap);

性能

本地缓存

Flutter播放器SDK提供了本地缓存(边播边缓存)的功能,能够让用户重复播放视频时,达到省流量的目的。需要在prepare之前给播放器配置setCacheConfig即可实现此功能。示例如下:

var map = {
  "mMaxSizeMB": _mMaxSizeMBController.text,// 缓存目录的最大占用空间
  "mMaxDurationS": _mMaxDurationSController.text,// 设置能够缓存的单个文件的最大时长
  "mDir": _mDirController.text,// 缓存目录
  "mEnable": mEnableCacheConfig,// 是否开启缓存功能
};
fAliplayer.setCacheConfig(map);

视频下载

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

  • 普通下载

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

  • 安全下载

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

使用说明

  • 仅VidSts和VidAuth方式支持视频下载功能。

  • 使用播放器的视频下载功能,需要在点播控制台开启并配置下载模式,详细操作请参见下载设置

  • 视频下载支持断点续传。

操作步骤

  1. 可选:配置安全下载的加密校验文件。仅安全下载需要配置,普通下载无需配置。

    说明

    请确保配置的加密校验文件与App信息一致,否则会导致视频下载失败。

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

    配置一次即可,示例如下:

    FlutterAliPlayerFactory.initService(byteData);
  2. 创建并设置下载器。

    示例如下:

    FlutterAliDownloader downloader = FlutterAliDownloader.init();
    // 设置保存路径
    downloader.setSaveDir(path)
  3. 开始下载。

    调用了开始下载后,会自动设置监听,并将回调信息返回。示例如下:

    // 1.prepare
      // 参数说明:type可选值为FlutterAvpdef.DOWNLOADTYPE_STS / FlutterAvpdef.DOWNLOADTYPE_AUTH 。当type为DOWNLOADTYPE_STS时候,必填参数为:{vid,accessKeyId,accessKeySecret,securityToken},当 type 为 DOWNLOADTYPE_AUTH 时,必须填参数为 {vid,playAuth}
      downloader.prepare(type, vid).then((value) {
          // value为map,对应Demo中的DownloadModel自定义下载类
          DownloadModel downloadModel = DownloadModel.fromJson(value);
          // 2.selectItem,根据不同的trackInfo来确定需要下载哪个清晰度
          List<TrackInfoModel> trackInfos = downloadModel.trackInfos;
          downloader.selectItem(vid,trackInfos[0].index);
          //3.start
          downloader.start(vid, trackInfos[0].index).listen((event) {
            // 说明:event可能会有多种信息,可参考FlutterAvpdef.EventChanneldef中的信息,以下为具体说明:
            if (event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_PROGRESS){
                // 下载进度百分比信息,获取下载进度百分比:event[EventChanneldef.DOWNLOAD_PROGRESS]
            }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_PROCESS){
                // 处理进度百分比信息,获取处理进度百分比:event[EventChanneldef.DOWNLOAD_PROCESS]
            }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_COMPLETION){
                // 下载完成,可以通过 event['vid']、event['index'] 获取对应的vid和index用于判断是哪个视频下载完成,event['savePath'] 用于获取下载完成视频的本地路径
            }else if(event[EventChanneldef.TYPE_KEY] == EventChanneldef.DOWNLOAD_ERROR){
                // 下载失败,可以通过 event['vid']、event['index'] 获取对应的vid和index用于判断是哪个视频下载失败,event['errorCode']、event['errorMsg'] 可以获取对应的错误码,和错误信息
            }
          });
      });
  4. 停止下载。

    示例如下:

    downloader.stop(vid, index)
  5. 删除下载。

    删除下载选项,如果删除成功,则下载的本地文件也会随之删除。示例如下:

    downloader.delete(vid, index)
  6. 释放下载对象。

    当某个下载对象不再使用时,使用release方法将其释放,防止内存泄漏。示例如下:

    downloader.release(vid, index)

视频加密播放

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

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