SDK

得图PanoPlayer Android版SDK使用指南

简介

Android SDK包含全景图片、全景视频、漫游主题等多种展示方式,支持全景模式、小行星模式、鱼眼模式和 VR 双屏模式沉浸式观看,支持直播和点播功能。 支持android4.0(api14)及其以上版本。

更新说明

环境配置

下载Sdk:

其中, DePanoPlayerDemo 是示例工程,panoPlay_Android 是包换sdk jar包和动态库的module,直接用Android Studio打开并编译即可查看demo实例。

Sdk引入

1.如果项目 IDE 为 Android Studio 并使用 Gradle 来管理项目,可以以模块的方式将 panoPlay_Android 引入到您的目标工程中。

然后选择 panoPlay_Android 所在的路径,全部采取默认配置点击下一步至“完成”即可 成功导入。 导入成功后,如下图所示:

在项目根目录下的settings.gradle文件中会包含 panoPlay_Android。

2.依赖库导入完成后,打开APP项目下的build.gradle文件,添加panoPlay_Android依赖。 dependencies { compile project(path: ':panoPlay_Android') }

直接引用Jar包

如果您不想以模块方式添加依赖, 可以采用直接复制资源的方式添加支持库

1.打开panoPlay_Android 文件夹

2.复制 libs下的所有文件到您APP 工程的 Libs目录下

3.复制res文件中 raw 下的所有文件到您APP工程的 res 文件夹raw 文件中

权限及其他设置

AndroidManifest权限配置

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

OpenGL 版本配置:

<uses-feature android:glEsVersion="0x00020000" android:required="true"/>

SDK接口说明

布局文件引用

布局文件中引入播放器核心类PanoPlayerSurfaceView

函数调用

  1. 在代码中获取播放器
    PanoPlayerSurfaceView PanoPlayerSurfaceView ppsview= (PanoPlayerSurfaceView) findViewById(R.id.glview);
  2. 获取播放器的控制器
    PanoPlayer renderer=ppsvVideo.getRender();

创建播放文件链接

创建播放链接类PanoPlayerUrl加载文件 PanoPlayerUrl panoplayerurl = new PanoPlayerUrl();

加载视频或图像

加载视频或图像有两种方法:

通过加载Xml文件Url播放

panoplayerurl. setXmlUrl("xml文件url地址")

通过构造xml加载

String T = 
"<DetuVr>
    <settings init=\"pano1\" initmode=\"default\"  "+"enablevr=\"false\" title=\"\" />
    <backgroundmusic  url=\"\" volume="20" isautoplay="true" />
    <scenes>
        <scene name=\"pano1\" title=\"\"  "+ "thumburl=\"\">
        <preview url=\"%s\" type=\"CUBESTRIP\"></preview>
        <image type=\"%s\" "+ "url=\"%s\" device=\"%d\"/>
        <view hlookat='0' vlookat='90' fov='110' viewmode='default' />
        </scene>
    </scenes>
</DetuVr>";

panoplayerurl. setXmlContent("xml内容")`

初始化XML配置

配置播放的数据类型
/**
  1.其中image 节点下的type值控制播放的文件媒体类型
      type=sphere :代表播放的是图片类型的数据
      type=video : 代表播放的是视频类型的数据
      type=cube : 代表播放的是六面图 数据
  2.image节点下的device值控制播放的资源类型
      device=0 :代表资源是标准的2:1 数据
      device=11 :代表资源是单鱼眼数据——即SphereS 拍摄出来的数据
      device=2002 : 代表资源是双鱼眼数据——即twin相机拍摄出来的数据
  */
  //例如: 播放一个标准2:1 图片我可以这样初始化:
 String xmlstring = String.format(T,"","sphere", "资源url",0);
 //例如:播放一个Twin 相机拍摄出来的双鱼眼视频,可以这样初始化:
 String xmlstring = String.format(T,"","video", "资源url",2002);

开始播放

panoplayerurl.setXmlContent(xmlstring);
renderer.Play(panoplayerurl);

注: 可使用的文件路径规则:

"http://site.com/image.png" // from Web
"file:///mnt/sdcard/image.png" // from SD card
"assets://image.png" // from assets
"drawable://" + R.drawable.img // from drawables

播放回调函数调用

  1. 播放图片回调 在播放图片时可通过IPanoPlayerListener接口绑定播放事件:
    renderer.setListener(IPanoPlayerListener listener);
  2. 播放视频回调 在播放视频时需同时绑定IPanoPlayerListener和IPanoPlayerVideoPluginListener接口才可获取到完整的播放事件:
    renderer.setListener(IPanoPlayerListener listener);
    renderer.setVideoPluginListener(IPanoPlayerVideoPluginListener listener);

播放回调说明

回调接口 包含回调 回调说明
IPanoPlayerListener void PanoPlayOnLoading() 播放器数据正在加载中
void PanoPlayOnLoaded() 播放器数据加载完成
void PanoPlayOnEnter(PanoramaData var1) 播放器场景加载完成
void PanoPlayOnLeave(PanoramaData var1); 播放器场景已移除
void PanoPlayOnError(PanoPlayerErrorCode var1) 播放出错
IPanoPlayerVideoPluginListener void PluginVideoOnInit() 播放器数据初始化完成
void PluginVideoOnStatusChanged(PanoVideoPluginStatus status) 播放状态变化
void PluginVideoOnProgressChanged(int curTime, int bufTime, int maxTime) 播放进度变化。其中curTime为当前播放的位置;bufTime为缓冲位置;maxTime为视频总长度
void PluginVideoOnSeekFinished() 视频进度拖动完成
void PluginVideOnPlayerError(PanoPlayerErrorStatus var1, String var2) 播放出错

模式切换

在播放图片和视频时还可进行模式切换,有两种方式: 直接切换和渐变切换,您可根据需要选择其中一种。

直接切换:renderer.setViewMode(ViewMode mode);

渐变切换 : prenderer.setAnimationViewMode(ViewMode mode);

注 : 在播放器XML配置文件中声明播放模式:

 <view hlookat='0' vlookat='90' fov='110' viewmode='default' />

<!--viewmodel:显示模式 分别为 default(默认全景) ,sphere(圆) ,flat(平面), lineflat(2:1平面),vr(vr模式)-->

模式说明

模式 说明
ViewMode.VIEWMODE_FISHEYE 鱼眼模式
ViewMode.VIEWMODE_LITTLEPLANET 小行星模式
ViewMode.VIEWMODE_DEF 默认模式
ViewMode.VIEWMODE_PLANE 平面模式
ViewMode.VIEWMODE_VR_HORIZONTAL VR 模式水平
ViewMode.VIEWMODE_VR_VERTICAL VR 模式竖直

其他设置

  1. 设置陀螺仪开关 可调用renderer.setGyroEnable(boolean enable);来设置播放器是否使用陀螺仪:enable 为true 时,陀螺仪可用;为false 时,陀螺仪不可用。

  2. 缩放开关 可调用renderer.setZoomEnable(boolean enable);来设置播放器是否使用缩放:enable 为true 时,缩放可用;为false 时,缩放不可用。

  3. 滑动事件 可调用setGestureEnable(boolean enable);来设置播放器的滑动事件,enable 为true 时,滑动事件可用;为false 时,滑动事件不可用。

  4. 截屏 可调用renderer.getScreenShot(IScreenShot cb);来截取当前画面

  5. 画面自动旋转 可调用renderer.setIsautoplay(boolean isautoplay);并调用设置播放旋转速度setautoPlayValue(float ath)0-0.5);

  6. 视频播放进度控制 在视频播放过程中还可进行视频播放控制。在public void PluginVideoOnInit()函数中获取播放器插件控制器:
    @Override
    public void PluginVideoOnInit() {
        Plugin plugin = renderer.getCurPlugin();
        if (plugin instanceof VideoPlugin) {
            videoplugin = (VideoPlugin) plugin;
            //设置播放器日志级别
            //videoplugin.setLogLevel(IjkMediaPlayer.IJK_LOG_VERBOSE);
        }
    }

    从某一时刻开始播放:

    videoplugin.seekTo(int progress);

    获取播放缓冲百分比:

    int buffr = videoplugin.getreadBufferingPercent();

    暂停播放:

    videoplugin.pause();

    开始播放:

    videoplugin.start();

    重新播放:

    videoplugin.replayer();

    播放器点击事件:

    renderer.setOnClickPanoViewListener();

    播放器长按事件:

    videoplugin.setOnLongClickPanoViewListener();

    混淆配置

#得图全景播放器
-keep class org.simple.** { *; }
-keep interface org.simple.** { *; }

-keep class org.opencv.** {
    <fields>;
    <methods>;
}

-keep class com.google.** {
    <fields>;
    <methods>;
}

-keep class com.adobe.** {
    <fields>;
    <methods>;
}

-keep class org.apache.** {
    <fields>;
    <methods>;
}

-keep class com.player.data.** {
    <fields>;
    !private <methods>;
}

-keep class com.player.util.** {
    <fields>;
    !private <methods>;
}

-keep class com.player.panoplayer.** {
    <fields>;
    !private <methods>;
}

-keep class com.player.renderer.** {
    <fields>;
    !private <methods>;
}

-keep class com.player.calibration.** {
    <fields>;
    <methods>;
}

-keep class com.player.configuration.machine.** {
    <fields>;
    <methods>;
}

-keepclasseswithmembers class * {
    public <init>(android.content.Context,android.util.AttributeSet);
}

-keepclasseswithmembers class * {
    public <init>(android.content.Context,android.util.AttributeSet,int);
}

-keepclasseswithmembers class * {
    void onClick*(...);
}

-keepclasseswithmembers class * {
    *** *Callback(...);
}

-keepclassmembers public class * extends android.view.View {
    void set*(***);
    *** get*();
}

-keep class org.apache.http.** {
    <fields>;
    <methods>;
}

-keep class com.nostra13.universalimageloader.** {
    <fields>;
    <methods>;
}

-keep class aurelienribon.tweenengine.** {
    <fields>;
    <methods>;
}

-keep class cz.msebera.** {
    <fields>;
    <methods>;
}

-keep class tv.danmaku.ijk.media.player.** {
    <fields>;
    <methods>;
}

# Also keep - Enumerations. Keep the special static methods that are required in
# enumeration classes.
-keepclassmembers enum  * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

# Keep names - Native method names. Keep all native class/method names.
-keepclasseswithmembers,allowshrinking class * {
    native <methods>;
}

注意事项

为了更好的管理播放器资源引用,您需在您的onDestroy() 方法手动销毁播放器,释放播放资源。

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if (renderer != null) {
            renderer.release();
        }
    }

常见问题

  1. 模式设置无法生效

    在场景未加载完成之前调用 setViewMode( ) 设置播放模式. 播放器会优先采用XML里配置的 viewmode 显示, 如果没配置将显示默认模式(全景模式) . 如果要让默认 初始模式为全景, 请在XML中 设置viewmode='vr' 即可.

  2. 本地视频或图片无法播放

    请确保本地文件路径是以 file:// 开头

  3. 播放器可支持哪些媒体格式的资源

    图片支持 jpg、jpeg和png格式; 视频支持用rtsp、rtmp、hls、m3u8 协议推流的直播,也支持 mp4、flv、rmvb和avi 格式的点播视频。

  4. 关于画面卡顿问题

    由于直播和点播均支持4K超高清播放,但部分Android手机不支持硬解,播放器在采用软解码视频时由于手机性能跟不上会造成画面卡顿。

XML 节点说明

1)DetuVr根节点

参数 必填 数量 说明
settings 单个 设置标签
backgroundmusic 单个 当前场景背景音乐
scenes 单个 所有场景标签
scene 多个 具体场景
preview 单个 前置标签 存放缩略图等
image 单个 存放全景资源地址等
view 单个 存放显示视角等参数

2)settings节点

参数 类型 必填 说明
init String 默认显示的场景名称 对应scene标签中的name属性
initmode String 默认的显示模式 分别为 default(默认全景) ,sphere(圆) ,flat(平面), lineflat(2:1平面),vr(vr模式)
enablevr boolean 是否开启vr
title String 保留字段,暂时没用

3)backgroundmusic节点

参数 类型 必填 说明
url String 背景音乐资源地址
volume String 音量
isautoplay boolean 是否自动播放

4)scenes节点

参数 类型 必填 说明
name String 场景名称
title String 场景标题
thumburl String 场景缩略图

5)preview节点

参数 类型 必填 说明
url String 6面图缩略图地址

6)image节点说明

参数 类型 必填 说明
type String 显示类型 cube(6面图),sphere(单张图片),video(视频)
url String 全景资源地址,为type为cube时,地址中必须带%s 字段. 如:url=http://www.detu.com/a_%s.jpg 时播放器会去下载以下6个图片 http://www.detu.com/a_f.jpg http://www.detu.com/a_b.jpg http://www.detu.com/a_l.jpg http://www.detu.com/a_r.jpg http://www.detu.com/a_u.jpg http://www.detu.com/a_d.jpg
device String 设备号,type为cube时设备号没作用,0为2:1资源; 1:sphere 800拍摄的; 11:sphere s 拍摄的; 2002 twin拍摄的

7)view节点说明

参数 类型 必填 说明
hlookat String 横向偏移角度
vlookat String 纵向编译角度
fov String 摄像机视角
vrfov String vr模式下的摄像机视角
gyroEnable String 陀螺仪是否开启
viewmodel String 显示模式 分别为 default(默认全景) ,sphere(圆) ,flat(平面), lineflat(2:1平面),vr(vr模式)