Android-播放器-SDK-开发指南

开始前请确保下述前提条件已准备就绪：

• 下载最新的播放器 Android SDK。
• 准备Android 运行环境：Android 2.2 及以上的所有系统。
• 适配CPU指令集：ARM v7，ARM 64及 Intel X86。
• 申请账号并开通权限： 您需要登录百度智能云，在安全认证页面 获取 Access Key (AK)。SDK 认证时必须传入 AK 参数。

• 集成添加播放器 SDK 到 App 工程：

  (1) 创建Android工程。

  (2) 将 SDK 中的 Jar 包添加到 App 工程的 libs 目录下，并在工程属性中设置依赖此 Jar 包。

  (3) 选取同 CPU 类型匹配的 so 动态库压缩包，并解压到工程目录的 libs 目录。

  (4) (可选) 将 res 文件夹合并到工程目录的 res 目录。

   需用到 BMediaController 时执行合并操作。

• 权限声明

  请您在的 Android App 的 AndroidManifest.xml 中声明如下权限:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.WRITE_SETTINGS" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

视频播放开发指南

作为Android 播放器 SDK 的核心特性，视频播放功能目前已开放了为媒体播放显示提供支持的 BVideoView 类接口的源码，并即将开放为媒体播放控制提供支持的 BMediaController 类接口源码，目前您既可使用 BVideoView 及 BMediaController 快速开发，亦可基于 BVideoView 做定制开发。同时，我们正在努力开放更多源代码以方便您的深度定制。

API简介

• setOnNetworkSpeedListener: 注册此监听函数可以获取播放网络视频时得到的带宽，仅仅计算播放时获得的网速，比通过系统函数获取的网速更加精确。
• setFirstBufferingTime：控制播放器首帧数据的最大缓冲时长，这个时间表示缓冲结束，不代表在这个时间点之内能看到第一帧数据。
• setCacheBufferSize: 播放网络视频时自定义网络缓冲区的大小，如无特殊需求时不建议设置。
• setCacheTime: 播放网络视频时自定义缓冲等待的最大时长（单位：秒），没有设置的情况下，默认为1秒，最小可设置为0.5秒，最大可设置为4秒。
• setUserAgent: 播放网络视频时自定义向服务器发送的 user agent。
• setCustomHttpHeader: 播放网络视频时自定义向服务器发送 http get 的请求，如 refer、Trailer等，以 \r\n 分隔。例如：“referrer:.baidu.com\r\nRetry-After:120\r\nPragma:no-cache\r\n”。

使用 BVideoView 及 BMediaController 快速实现播放

播放器 SDK 提供“播放\暂停”键及其它两个自定义键，可实现类似“上一部”及“下一部”功能，您也可以自己实现控件。如果注册了两个相应的 listener，自定义键会显示在 controller 中，否则不会显示。在 controller 中也显示了当前播放时间及视频总时间，并有 seekbar，可以对当前播放进行 seek 操作。

1.创建BVideoView及BMediaController。

可通过两种方式创建 BVideoView 及 BMediaController，示例代码如下：

           # 方式1：直接在布局文件中创建
           <RelativeLayout
              android:id="@+id/videoview_holder"
              android:layout_width="wrap_content"
              android:layout_height="wrap_content"
              android:layout_centerInParent="true" >
              <com.baidu.cyberplayer.core.BVideoView
                 Android:id=”@id/videoview”
                 Android:layout_width=”fill_parent”
                 Android:layout_height=”fill_parent”/>
            </RelativeLayout>
            ... ...
            <RelativeLayout
              android:id="@+id/controller_holder"
              android:layout_width="wrap_content"
              android:layout_height="wrap_content"
              android:layout_centerInParent="true"
              <com.baidu.cyberplayer.core.BMediaController
                Android:id=”@id/controllerbar”
                Android:layout_width=”fill_parent”
                Android:layout_height=”fill_parent” />
            </RelativeLayout>

            # 方式2：在源码中动态创建，然后添加到页面中
            BVideoView mVV;
            BMediaController mVVCtl;
            ...
            mViewHolder = (RelativeLayout) findViewById(R.id.videoview_holder);
            mControllerHolder = (LinearLayout) findViewById(R.id.controller_holder);

            mVV = new BVideoView(MediaControllerPlayingActivity.this);
            mVVCtl = new BMediaController(MediaControllerPlayingActivity.this);
            LinearLayout.LayoutParams param = new LinearLayout.LayoutParams(
              LinearLayout.LayoutParams.FILL_PARENT，
              LinearLayout.LayoutParams.FILL_PARENT);
            mViewHolder.addView(mVV, param);
            mControllerHolder.addView(mVVCtl, param);

2.关联 BVideoView 与 BMediaController 实现播放。

(1)（可选）播放前调用 BVideoView.setNativeLisbDirectory() 指定底层库的加载位置。

仅当需要指定底层库的加载位置时调用，执行一次即可，不用每次播放前都调用。

(2)（可选）注册 listener 监听播放过程，以便应用程序根据监听结果进行相应处理。

(3)（可选）关联 BVideoView 与 BMediaController 开始播放。

示例代码:

            mVV.setMediaController(mVVCtl);
            mVV.setDecodeMode(BVideoView.DECODE_SW); //可选择软解模式或硬解模式
            mVV.setVideoPath(path);
            mVV.showCacheInfo(true);
            mVV.start();

其中 showCacheInfo()用来设定缓冲时是否在 videoview 上显示缓冲状态和缓冲百分比，默认显示。 setDecodeMode()用来设定软硬解模式。默认软解模式，您可以根据 Android 系统默认支持的格式来决定，若默认支持的格式是MP4、3GP等，建议打开硬解开关以节省功耗、提高播放性能。

3.使用 BVideoView 与 BMediaController 实现多码率选择播放。

(1)获取可选的码率、分辨率数组。

先后使用BVideoView的静态接口 getMediaInfo 跟 getSupportedResolution（或者 getSupportedBitrateKb ）可获取当前视频地址所支持的分辨率（或者码率）数组。

示例代码：

            new Thread(new Runnable() {
                @Override
                public void run() {
                    Looper.prepare();
                    BVideoView.getMediaInfo(VideoViewPlayingActivity.this, mVideoSource);
                    mAvailableResolution = BVideoView.getSupportedResolution();
                    mAvailableBitrateKb = BVideoView.getSupportedBitrateKb();
                }
            }).start();

注意：由于 getMediaInfo 是耗时操作，请在子线程中调用。

(2)在 BMediaController 中注册事件侦听器。

初始化响应分辨率选择按钮点击事件的 OnClickListener，并调用 BMediaController 的 setResolutionListener 接口将侦听器设置给 BMediaController 实例。

示例代码：

            private View.OnClickListener mSelectResolutionListener = new View.OnClickListener() {
                @Override
                public void onClick(View v) {
                    if (mResolutionSelector != null && mAvailableResolution != null) {
                        mResolutionSelector.setAdapter(
                                    new ArrayAdapter<String>(VideoViewPlayingActivity.this, R.layout.resolution_item, mAvailableResolution));
                        mResolutionSelector.setVisibility(View.VISIBLE);
                    }
                }
            };
            mVVCtl.setResolutionListener(mSelectResolutionListener);

(3)选择分辨率进行播放。

调用 BVideoView 的 selectResolutionType，并传入该视频所支持的分辨率（或者码率）数组的下标，便可播放该分辨率（和码率）的视频。

示例代码：

            mResolutionSelector.setOnItemClickListener(new OnItemClickListener() {
                @Override
                public void onItemClick(AdapterView<?> arg0, View arg1, int arg2, long arg3) {
                    if (mVV != null) {
                        mVV.selectResolutionType(arg2);
                    }
                    mResolutionSelector.setVisibility(View.GONE);
                }
            });

基于 BVideoView 定制播放控制界面

使用 BVideoView 进行定制方法与[使用 BVideoView 及 BMediaController 快速实现播放](#使用 BVideoView 及 BMediaController 快速实现播放) 基本相同，具体实现时请注意:

• 调用 BVideoView.start() 后需要等待 OnPreparedListener.onPrepared()来表示视频准备播放就绪，这个过程建议您在界面上添加等待或提示信息。
• 调用 OnPreparedListener.onPrepared() 后您可以通过 BVideoView.getCurrentPosition()、BVideoView.getDuration()获取当前播放时间及视频总时长来显示播放进度。进度条拖动时可以通过 BVideoView.seekTo()来对视频进行 seek 操作。
• 执行 BVideoView.stopPlayback()停止视频，此操作是异步操作，需要等待 OnCompletionListener.onCOmpletion()，这表示播放真正结束，此时才能进行下一次播放。

M3U8视频下载

播放器支持对M3U8视频进行下载和管理。

类文件

下载管理方法

下载及播放

1. 调用VideoDownloadManager.getInstance(context, userName)完成初始化，从而获得下载管理单例。

2. 调用startOrResumeDownloader(url, observer)创建下载任务。

   函数原型：

   public void startOrResumeDownloader(String url, DownloadObserver observer)

   此时也可调用暂停（pauseDownloader）、恢复（startOrResumeDownloader）、删除（deleteDownloader）、批量停止（stopAll）等接口对下载任务进行管理。

   请您继承DownloadObserver类并实现update方法，以便在任务下载过程中实时获取状态变化的通知。

   public void update(AbstractDownloadableVideoItem downloader)

3. 任务下载过程中，回调update(AbstractDownloadableVideoItem downloader)，实时获取下载状态。

   downloader对象可获得下述方法：

   方法	描述
   getUrl	获取单个下载的url
   getLocalAbsolutePath	获取下载文件的本地绝对路径
   getProgress	获取下载进度
   getStatus	获取下载状态（枚举类DownloadStatus）
   getErrorCode	下载状态为Error的时候，通过该接口获取错误码
   getFailReason	获取下载失败或中止的简单描述

   注：错误码如AbstractDownloadableVideoItem.ERROR_CODE_INVALID_URL等

   其中，发生错误时的错误码如下表：

   错误码	描述
   ERROR_CODE_NO_ERROR	无错误
   ERROR_CODE_INVALID_URL	地址无效
   ERROR_CODE_NETWORK_FAILED	网络问题
   ERROR_CODE_SDCARD_UNMOUNTED	本地存储问题
   ERROR_CODE_M3U8_\INVALID_FORMAT	m3u8格式问题
   ERROR_CODE_M3U8_SAVE_FAILED	m3u8存储问题
   ERROR_CODE_M3U8_DRM_INVALID	drm保护相关key或者token无效
   ERROR_CODE_TS_SAVE_FAILED	ts文件保存失败

4. 下载成功后，AbstractDownloadableVideoItem回调getLocalAbsolutePath，将folderPath + "/" + fileName传给播放器进行本地播放。

字幕播放开发指南

作为 Android 播放器 SDK 新亮点的外挂字幕功能，支持播放视频时导入外挂的字幕，提供包括下载字幕、加载本地字幕、字幕显示调整等，目前只支持 srt 字幕格式。我们正在努力支持更多的字幕格式，敬请期待。

API 简介

播放内核中的字幕模块通过 SubtitleManager 进行管理，使用字幕时需调用 BVideoView 中的 getSubtitlePlayManager() 来获得 SubtitleManager 实例。

字幕显示设置通过 SubtitleSettings 进行管理，更改字幕设置时需通过 SubtitleManager 的 getSubtitleSettings 来获得 SubtitleSettings 实例来进行调整。

所提供的所有方法均非线程安全，Android 应用需保证在同一个线程中调用这些方法。

SubtitleErrorCallback

SubtitleErrorCallback 接口定义字幕播放时出错的回调方法，在获得 SubtitleManager 时需要传入此回调。

    public interface SubtitleErrorCallback { 
      /**
       * @Description: 字幕下载、播放时调用
       * @param error errorCode 的错误在 subtitleError 中定义 */
       void onSubtitleError(SubtitleError error); 
    }

SubtitleError

SubtitleError 封装了错误代码和错误消息，有两个 public 变量: errorCode 和 errorMsg。通过两个变量记录错误代码和错误消息，具体错误代码也在此类中定义。

public class SubtitleError {
    /** 错误信息 code */
    public int errorCode;
    /** 错误信息 desc */
    public String errorMsg;

    public SubtitleError(int errorcode, String errormsg){
        this.errorCode = errorcode;
        this.errorMsg = errormsg;
    }

    /**默认错误*/
    public static final int ERR_SUBTITLE_UNKNOWN = 1001;
    /**参数非法*/
    public static final int ERR_ARGUMENT_ILLEGAL = 1002;
    /**不支持的字幕类型*/
    public static final int ERR_UNSUPPORT_TYPE = 2001;
    /**更新视频位置信息时出错*/
    public static final int ERR_CANNOT_UPDATE_POSITION = 3001;
    /**对齐方式不支持*/
    public static final int ERR_ALIGN_UNSUPPORT = 4002;
    /**网络连接不可用*/
    public static final int ERR_NETWORK_NOT_CONNECTED = 5000;
    /**不能创建文件*/
    public static final int ERR_FAIL_CREATE_FILE = 5001;
    /**rename 失败*/
    public static final int ERR_FAIL_RENAME_FILE = 5002;
    /**MalformedURL*/
    public static final int ERR_MALFORMED_URL = 5003;
    /**IOException*/
    public static final int ERR_IO_EXCEPTION = 5004;
    /**未找到文件*/
    public static final int ERR_FILE_NOT_FOUND = 5005;
    /**编码不支持*/
    public static final int ERR_FILE_NOT_FOUND = 5006;
    /**目录不可写*/
    public static final int ERR_FILE_NOT_FOUND = 5007;
    /**server 返回错误*/
    public static final int ERR_SERVER_ERRORNO = 5008;
}

SubtitleManager 获取

Activity 中创建 BvideoView 的实例，通过调用此实例中的 getSubtitlePlayManager()方法创建。

示例代码:

    BVideoView mVV = new BVideoView(this);
    SubtitleManager manager = mVV.getSubtitlePlayManager(
            new SubtitleErrorCallback() {
                  public void onSubtitleFailed (SubtitleError error) (); 
            }
        );

播放字幕

• 下载并播放字幕

    /**
     * @Description: 下载并启动字幕
     * @param downUrl 下载url
     * @param dir 下载目录
     * @param fileName 文件名
     * @param baseAdjust 自动同步调整值, ms;
     * @param downCallback 下载完成时的回调
     */
    public void startSubtitle(
        final String downUrl,
        final String dir,
        final String fileName,
        final int baseAdjust,
        final DownFinishCallback downCallback) {};
  
    /**
     * @Description:
     * @param downUrl 下载并启动字幕
     * @param fullPath 需要保存字幕的 full path
     * @param baseAdjust 自动同步调整值, ms;
     * @param downCallback 下载完成时的回调
     */
    public void startSubtitle(
        final String downUrl,
        final String fullPath,
        final int baseAdjust,
        final DownFinishCallback downCallback) {};

  其中 DownFinishCallback 为下载结束的回调，定义如下:

    public interface DownFinishCallback {
        /**
         * @Description: 下载完成时回调方法
         * @param isSuccess 如果下载成功则返回true,并自动启动字幕播放。失败返回false。
         * @param msg 如果为true,返回下载的fullPath,如果为false,返回错误消息。
         */
         void onDownFinished(boolean isSuccess, String msg);
    }

• 播放本地字幕

    /**
     * @Description: 启动字幕
     * @param subtitlePath 字幕本地绝对路径,需以字幕类型尾,用于判断类型
     */
    public void startSubtitle(String subtitlePath){};

• 开/关字幕显示

    /**
     * @Description: 设置是否显示字幕 * @param isShow 如果显示为true
     */
    public void setIsShowSubtitle(boolean isShow){};

• 手动调节字幕

    /**
     * @Description: 手动调节字幕
     * @param msec 调节的毫秒数,传正整数为加快,负整数为减慢
     */
    public void manualSyncSubtitle(int msec) {};

设置字幕

字幕的配置通过 SubtitleSettings 进行管理。先通过 SubtitleManager 的 getSubtitleSettings() 来获得 SubtitleSettings 实例，然后再调用SubtitleSettings的函数调整字幕播放。

SubtitleSettings 提供字幕调整接口：

• 设置字幕颜色

    /**
     * @Description: 设置显示颜色,
     * @param mDisplayColor 显示的颜色,
     * 注意此int值是包含透明度的值,请用Color.parseColor或Color.argb转换
     */
    public void setDisplayColor(int displayColor) {};

• 设置字幕文字大小

    /**
     * @Description: 设置字幕文字大小
     * @param mDisplayFontSize 字幕大小,单位为px
     */
    public void setDisplayFontSize(float displayFontSize);

• 设置字幕位置

    /**
     * @Description: 设置字幕对齐方式与padding
     * @param align 对齐方式, ALIGN_BOTTOM或ALIGN_TOP 
     * @param padding 与底部的padding, 单位px
     */
    public void setDisplayLocation(int align, int padding);

多屏互动开发指南

播放器 SDK 开放了 DLNA (Digital Living Network Alliance) 的控制器功能用以实现多屏互动。Android手机启动DLNA服务作为 DMS (Digital Media Server) 或者 DMC (Digital Media Controller)，同一个局域网中的DLNA设备（通常是电视或者音响）就可以连接Android手机。这些设备作为DMP (Digital Media Player) 或者 DMR(Digital Media Render)可以播放手机上的音频和视频。

API简介

使用 DLNA 功能，API 的调用分为以下几步:

• 传入AK进行初始化和权限验证。
• 启动DLNA服务。
• 获取 Render(电视等显示设备)列表。
• 指定某个Render与之关联。
• 指定待播放资源的 URL。
• 播放控制阶段，开始，暂停，拖动，调节音量。
• 停止DLNA服务。

其他可选操作:

• 播放前获取 Render 播放能力及所支持的格式和协议。
• 播放过程中，主动获取 Render 状态信息。
• 订阅 Render 状态，避免主动轮询。
• 出错监听。

注意:

• IDLNAServiceProvider是对外服务的唯一接口。

• API 调用根据是否为耗时操作分为同步调用和异步调用：

  • 同步调用立即返回结果。
  • 异步调用立即返回，通过已注册对应的回调获取执行结果。由于回调不是在 UI 线程中执行，请勿在回调中执行 UI 相关操作；如果操作失败，还可以通过对应回调查看错误码和错误消息详情。
• API 文档中标明了具体 API 是同步还是异步操作。

启动和停止DLNA服务

• 初始化及启动DLNA服务

  启动过程包括：获取IDLNAServiceProvider实例，使用AK做初始化，启动DLNA服务。

  示例代码：

    // Android context instance about application environment
    Context context = ...;
    // User's Access Key
    String AK = ...;
    // Callback handle for DLNA statup
    IEnableDLNACallBack enableDLNACallback = ...;
  
    IDLNAServiceProvider serviceProvider = DLNAProviderFactory.getProviderInstance(context);
    serviceProvider.initialize(AK, “”);
    serviceProvider.enableDLNA(enableDLNACallback);

• 关闭DLNA服务

  示例代码：

    // Callback handle for DLNA shutdown
    IDisableDLNACallBack  disableDLNACallback = ...;
  
    serviceProvider.disableDLNA(disableDLNACallback);

IDLNAServiceProvider相关函数说明如下：

选择设备和播放资源

DLNA服务启动后获取当前活动的设备列表，并提示选择要关联的设备并设置播放资源URL。

示例代码：

Map<String, String> renderMap = serviceProvider.getDeviceMap(DLNADeviceType.MEDIA_RENDERER);
...
//  为用户已选择的设备
String selectedDevice = ...;
// selectRenderDevice回调接口
ISelectRendererDeviceCallBack selectRendererDeviceCallback = ...;

serviceProvider.selectRenderDevice(selectedDevice, selectRendererDeviceCallback);

// 视频资源URL
String mediaUrl = ...;
// setMediaURI回调接口
ISetMediaURICallBack setMediaUriCallback = ...;
serviceProvider.setMediaURI(mediaUrl, setMediaUriCallback);

IDLNAServiceProvider相关函数说明如下：

播放控制

调用 IDLNAServiceProvider 的API 可实现播放控制。由于交互对象是网络中的其他终端设备，控制和交互过程存在网络延时和设备响应延时，即 API 调用返回后，被控制设备可能会出现延后一段时间作出响应的情况。

被控制的终端所处的状态会影响 API 调用是否成功，例如只有在播放状态下才能去进行 Seek 操作。所有的控制操作结果均通过注册的对应回调函数返回。

IDLNAServiceProvider播放控制函数说明如下：

获取设备状态

调用 IDLNAServiceProvider 的API 可获取被控设备相关状态。

IDLNAServiceProvider设备状态函数说明如下：