Android SDK

Android SDK接入文档

1. ASP Android SDK使用方法

1.1. 集成环境要求

最低支持Android版本:5.1

1.2. 主要文件

aspengine-third-release.aar

该AAR定义了ASP Android SDK的核心API,通过该包,应用程序可实现对ASP关键流程的控制,如启动/停止流,暂停/恢复流,注入输入事件,接收事件消息等。

该AAR包还定义了高度集成ASP能力的增强型UI组件,通过这些组件,开发人员能够更快速地搭建整合了ASP能力的应用程序。

1.3. 示例 - 使用核心API

1.3.1. 通过maven repo二方包方式接入SDK

目前暂不支持

1.3.2. 以集成AAR包方式接入SDK

  1. aspengine-third-release.aar 拷贝到app/libs目录下。

  2. 在应用模块的build.gradle加入:

dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
    // aspengine-sdk依赖的ini配置解析库
    implementation 'org.ini4j:ini4j:0.5.4'
}
  1. AndroidManifest 声明必要的权限:

<uses-permission android:name="android.permission.INTERNET" />
  1. AndroidManifest 配置Activity:

// 强制界面以横屏方式显示
<activity android:name=".ASPEngineDemoActivity" 
          android:launchMode="singleTop"
          android:screenOrientation="sensorLandscape">

1.3.3. 调用示例

public class ASPEngineDemoActivity extends Activity
        implements ICursorListener, IResolutionUpdateListener, IOrientationUpdateListener {
    static final String TAG = "MainActivity";

    private SurfaceView mAspSurfaceView = null;

    private ASPEngine.Builder mEngineBuilder = null;
    private IASPEngine mEngine = null;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        this.requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN);

        setContentView(R.layout.activity_main);

        mAspSurfaceView = findViewById(R.id.asp_surface_view);
        
        // 监听touch消息并注入到ASPEngine
        mAspSurfaceView.setOnTouchListener(new View.OnTouchListener() {
            @Override
            public boolean onTouch(View view, MotionEvent motionEvent) {
                if (mEngine != null) {
                    return mEngine.sendTouchEvent(motionEvent);
                }
                return false;
            }
        });

        // 监听鼠标操作事件并注入到ASPEngine
        mAspSurfaceView.setOnGenericMotionListener(new View.OnGenericMotionListener(){
            @Override
            public boolean onGenericMotion(View v, MotionEvent motionEvent) {
                Log.d(TAG,String.format("mouse, onGenericMotion: %d", motionEvent.getSource()));
                if (0 != (motionEvent.getSource() & InputDevice.SOURCE_MOUSE)) {
                    if (mEngine != null) {
                        return mEngine.sendMouseEvent(motionEvent);
                    }
                }
                return true;
            }
        });

        // 创建Builder
        mEngineBuilder = new IASPEngine.Builder();
        
        // 创建ASPEngine对象
        mEngine = mEngineBuilder.build();
        
        // 设置Surface
        mEngine.setSurface(mAspSurfaceView);

        IASPEngineListener listener = new IASPEngineListener() {
            @Override
            public void onConnectionSuccess() {
                // server连接成功
                Log.i(TAG, "onConnectionSuccess");
            }

            @Override
            public void onConnectionFailure(int errorCode, String errorMsg) {
                // server连接失败
                Log.i(TAG, "onConnectionFailure errorCode:" + errorCode + " errorMsg:" + errorMsg);
            }

            @Override
            public void onEngineError(int errorCode, String errorMsg) {
                // ASPEngine内部发生错误
                Log.i(TAG, "onEngineError errorCode:" + errorCode + " errorMsg:" + errorMsg);
            }

            @Override
            public void onDisconnected(int reason) {
                // 连接已断开
                Log.i(TAG, "onDisconnected reason=" + reason);
            }

            @Override
            public void onReconnect() {
                // 发生重连
                Log.i(TAG, "onReconnect");
            }
        };

        // 监听连接及ASPEngine内部状态
        mEngine.registerASPEngineListener(listener);
        // 监听云端游标状态变化消息
        mEngine.registerCursorListener(this);
        // 监听云端分辨率变化消息
        mEngine.registerResolutionUpdateListener(this);
        // 监听云端屏幕旋转消息
        mEngine.registerOrientationUpdateListener(this);
    }
    
    /**
     * 用户登录成功后,通过无影OpenAPI接口获取对应云电脑的server session信息,并通过
     * 该方法启动ASPEngine.
     *
     * 登录及通过无影OpenAPI接口调用由应用开发者实现,相关接口使用方法请参考对应的文档
     *
     */
    protected void onGetServerSession(String session) {
        // 启动ASPEngine
        mEngine.start(session, null);
    }

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

    @Override
    public boolean dispatchKeyEvent(KeyEvent event) {
        if (mEngine != null) {
            // 截获并注入键盘按键消息
            if (!mEngine.sendKeyboardEvent(event)) {
                return super.dispatchKeyEvent(event);
            }
            return true;
        }
        return super.dispatchKeyEvent(event);
    }
    
    /*
     * Cursor callback BEGIN
     * */
    @Override
    public void onCursorBitmapUpdate(int hotX, int hotY, int width, int height, byte[] rgba) {
        // 云上游标形态发生变化,将变化内容同步到本地游标
        Log.d(TAG,String.format("onCursorBitmapUpdate: hotX:%d, hotY:%d, width:%d, height:%d, len:%d :", hotX, hotY, width, height,rgba.length));
        //BitmapFactory.Options options = new BitmapFactory.Options();
        //options.inMutable = true;
        Bitmap rawBmp = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888);
        rawBmp.copyPixelsFromBuffer(ByteBuffer.wrap(rgba));
        if(rawBmp == null) {
            Log.i(TAG, "can't create cursor bitmap from rgba");
            return;
        }

        PointerIcon cursor = PointerIcon.create(rawBmp, hotX, hotY);
        mAspSurfaceView.setPointerIcon(cursor);
    }

    @Override
    public void onCursorHide()
    {
        // 云上游标被隐藏
        Log.i(TAG, "onCursorHide");
        PointerIcon cursor = PointerIcon.getSystemIcon(getApplicationContext(),PointerIcon.TYPE_NULL);
        mAspSurfaceView.setPointerIcon(cursor);
    }

    @Override
    public void onCursorReset() {
        // 云上游标被重置
        Log.i(TAG, "onCursorReset");
        PointerIcon cursor = PointerIcon.getSystemIcon(getApplicationContext(),PointerIcon.TYPE_DEFAULT);
        mAspSurfaceView.setPointerIcon(cursor);
    }

    @Override
    public void onCursorMove(int x, int y) {
        // 云上游标位置移动
    }
    /* Cursor callback END */

    @Override
    public void onResolutionUpdate(int oldWidth, int oldHeight, int width, int height) {
        // 云上分辨率发生变化,根据需要,端侧可以决定是否需要按照长宽比例对渲染内容进行scale
        Log.i(TAG, "onResolutionUpdate stream ow " + oldWidth + " oh " + oldHeight
                + " w " + width + " h " + height);
        Log.i(TAG, "current view width " + mAspSurfaceView.getWidth()
                + " height " + mAspSurfaceView.getHeight());

        float factorX = 1f;
        float factorY = 1f;

        float aspectRatio  = 1.0f * width / height;
        float viewAspectRatio = 1.0f * mAspSurfaceView.getWidth() / mAspSurfaceView.getHeight();
        Log.i(TAG, "StreamView aspect ratio " + viewAspectRatio
                + " VS remote window aspect ratio " + aspectRatio);
        // TODO: suppose current device orientation is landscape
        if (viewAspectRatio > aspectRatio) {
            // Align stream content with view height for landscape
            int expectedWidth = (int) (mAspSurfaceView.getHeight() * aspectRatio);
            Log.i(TAG, "Expect width " + expectedWidth);
            factorX = 1.0f * expectedWidth / mAspSurfaceView.getWidth();
        } else {
            // Align stream content with view width for portrait
            int expectedHeight = (int) (mAspSurfaceView.getWidth() / aspectRatio);
            Log.i(TAG, "Expect height " + expectedHeight);
            factorY = 1.0f * expectedHeight / mAspSurfaceView.getHeight();
        }

        Log.i(TAG, "Calculate scale factor x " + factorX + " y " + factorY);

        mAspSurfaceView.setScaleX(factorX);
        mAspSurfaceView.setScaleY(factorY);
    }

    @Override
    public void onOrientationUpdate(int oldOrientation, int newOrientation) {
        // 云上发生旋转屏幕的动作,客户端需要同步旋转屏幕并固定下来
        Log.i(TAG, "onOrientationUpdate from " + oldOrientation + " to " + newOrientation);
        switch (newOrientation) {
            case IOrientationUpdateListener.ORIENTATION_0:
            case IOrientationUpdateListener.ORIENTATION_180:
                setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT);
                break;
            case IOrientationUpdateListener.ORIENTATION_90:
                setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE);
                break;
            default:
                Log.i(TAG, "Unknown new orientation: " + newOrientation);
                break;
        }
    }
}

1.4. 示例 - 使用增强型UI组件

1.4.1. 以集成AAR包方式接入SDK

  1. aspengine-thrid-release.aar拷贝到app/libs目录下。

  2. 在应用模块的build.gradle加入:

dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
    // aspengine-sdk依赖的ini配置解析库
    implementation 'org.ini4j:ini4j:0.5.4'
}
  1. AndroidManifest 声明必要权限:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.VIBRATE"/>
  1. AndroidManifest 配置Activity:

// 强制界面以横屏方式显示
<activity android:name=".StreamViewDemoActivity" 
          android:launchMode="singleTop"
          android:screenOrientation="sensorLandscape">
  1. layout配置:

<?xml version="1.0" encoding="utf-8"?>
<android.widget.RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".StreamViewDemoActivity">

    <com.aliyun.wuying.aspsdk.aspengine.ui.StreamView
        android:id="@+id/stream_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:focusableInTouchMode="true"
        android:focusable="true"
        android:focusedByDefault="true" />

</android.widget.RelativeLayout>

1.4.2 调用示例

public class StreamViewDemoActivity extends Activity {
    private static final String TAG = "StreamViewDemoActivity";
    private StreamView mStreamView = null;
    
    private IASPEngineListener mListener = new IASPEngineListener() {
        @Override
        public void onConnectionSuccess() {
            Log.i(TAG, "onConnectionSuccess");
        }
        @Override
        public void onConnectionFailure(int errorCode, String errorMsg) {
            Log.i(TAG, "onConnectionFailure errorCode:" + errorCode + " errorMsg:" + errorMsg);
        }
        @Override
        public void onEngineError(int errorCode, String errorMsg) {
            Log.i(TAG, "onEngineError errorCode:" + errorCode + " errorMsg:" + errorMsg);
        }1
        @Override
        public void onDisconnected(int reason) {
            Log.i(TAG, "onDisconnected reason=" + reason);
        }
        @Override
        public void onReconnect() {
            Log.i(TAG, "onReconnect");
        }
    };
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        requestWindowFeature(Window.FEATURE_NO_TITLE);
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN, WindowManager.LayoutParams.FLAG_FULLSCREEN);

        setContentView(R.layout.activity_stream_view_demo);

        mStreamView = findViewById(R.id.stream_view);
        
        mStreamView.setASPEngineListener(mListener);
    }
    
    /**
     * 用户登录成功后,通过无影OpenAPI接口获取对应云电脑的server session信息,并通过
     * 该方法启动ASPEngine.
     *
     * 登录及通过无影OpenAPI接口调用由应用开发者实现,相关接口使用方法请参考对应的文档
     *
     */
    protected void onGetServerSession(String session) {
        // 开始ASP建连
        Bundle config = new Bundle();
        config.putString(StreamView.CONFIG_CONNECTION_TICKET, session);
        mStreamView.start(mConfigs);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        mStreamView.dispose();
        mStreamView = null;
    }
}

2. 接口定义及说明

2.1. IASPEngine.Builder

IASPEngine对象的构造器

2.1.1. Builder

构建一个IASPEngine的Builder

public Builder()

2.1.2. build

构建一个ASPEngine对象

public IASPEngine build()

返回值:

类型

说明

IASPEngine

ASPEngine对象

2.1.3. enableVDAagentCheck

建连时是否强制检查VDAgent的可用性,默认是进行检查。

当该值设置为True时,若在建连时发现VDAgent不可用,则会报错并断开当前连接。

不建议设置为false,通常只有在进行内部调试时才会这么做。

public IASPEngine.Builder enableVDAgentCheck(boolean enabled)

参数:

参数

类型

说明

enabled

boolean

默认为true

true表示建连时会强制检查VDAgent的可用性;false表示不检查

返回值:

类型

说明

ASPEngine.Builder

Builder对象本身

2.1.4. enableRTC

设置是否使用RTC传输流化数据内容,默认使用RTC传输流化数据内容

public IASPEngine.Builder enableRTC(boolean enabled)

2.2. IASPEngine

IASPEngine是ASP Android SDK的核心接口,主要为应用提供以下几个方面的API:

  • 提供串流控制接口,如启动/断开串流,暂停/恢复推流,设置鼠标server mode等

  • 提供音视频设置接口,如视频分辨率,fps等

  • 提供input事件向云端的注入接口

  • 提供一系列regsiter方法用于注册监听SDK/云上各种状态的listener

2.2.1. start

通过从PaaS获取的server session启动串流服务,串流启动结果会通过IASPEngineListener回调返回给应用

public void start(String connectionTicket, String caFilePath)

参数:

参数

类型

说明

connectionTicket

string

应用通过PaaS API从管控获取的serverSession串

caFile

string

CA文件的绝对路径,用于tls通信加密

2.2.2 start

通过指定的server连接参数启动云端的串流服务,串流启动结果会通过IASPEngineListener回调返回给应用

该方法通常用于日常调试,适用于不经过网关(或已知网关地址并得到可访问的token),能够直连ASP Server的情形

public void start(String host, String port, String udpPort, String caFilePath, String token, boolean enableTls)

参数:

参数

类型

说明

host

string

ASP server或网关的地址

port

string

ASP server或网关可连接端口号

udpPort

string

UDP端口号,用于RTC数据传输,通常与port一致

caFile

string

CA文件的绝对路径,用于tls通信加密

token

string

用于访问网关的token,通常是由参与联调负责网关的人员提供

enableTls

boolean

true表示使用tls进行数据加密;false表示不使用tls数据加密

2.2.3 stop

立即停止云端的串流服务,当连接断开时,应用可以通过IASPEngineListener回调得到连接断开的消息

public void stop()

2.2.4 pause

暂停云端的串流推流

public void pause(IRemoteResult result)

参数:

参数

类型

说明

result

IRemoteResult

调用结果回调

目前不提供该操作的异步回调结果,应用可提供null值作为实参

2.2.5 resume

恢复云端的串流推流

public void resume(IRemoteResult result)

参数:

参数

类型

说明

result

IRemoteResult

调用结果回调

目前不提供该操作的异步回调结果,应用可提供null值作为实参

2.2.6 enableStatistics

开启/关闭性能数据统计报告,报告会通过注册的IStatisticsListener返回

public void enableStatistics(boolean enable)

参数:

参数

类型

说明

enable

boolean

默认为true

true表示ASPEngine会周期性地将包含性能及关键运行数据的报告通过已注册的IStatisticsListener对象返回;false表示关闭性能数据统计报告

2.2.7 toggleServerCursorMode

开启/关闭云上光标模式(该方法未实现

public void toggleServerCursorMode(boolean toggled)

参数:

参数

类型

说明

toggled

boolean

默认为true

true表示启用Server Cursor模式,需要通过ICursorListener监听光标状态变化,并在端侧应用进行适配;false表示关闭Server Cursor模式

2.2.8 setSurface

设置一个SurfaceView到ASPEngine。

ASPEngine在建立串流后,将通过设置的SurfaceView渲染流化图像。

void setSurface(SurfaceView surfaceView)

参数:

参数

类型

说明

surfaceView

android.view.SurfaceView

用于呈现流化图像的SurfaceView对象

2.2.9 setVideoProfile

设置视频流的分辨率及帧率

目前fps参数不会生效

public void setVideoProfile(int width, int height, int fps, IRemoteResult result)

参数:

参数

类型

说明

width

int

视频流分辨率目标宽度,像素

height

int

视频流分辨率目标高度,像素

fps

int

视频流目标fps

result

IRemoteResult

调用结果回调

2.2.10 setImePreedit

当获取到本地输入法的预览文字后,通过该接口设置云上输入法需要显示的预览文字

该方法未实现

public void setImePreedit(String preeditStr, IRemoteResult result)

参数:

参数

类型

说明

preeditStr

String

IME预览文字

result

IRemoteResult

调用结果回调

2.2.11 setImeCommit

当本地输入法的预览文字被提交到输入框中后,通过该接口设置云上输入法需要提交到输入框显示的文字

该方法未实现

public void setIMEPreedit(String commitStr, IRemoteResult result)

参数:

参数

类型

说明

commitStr

String

IME预览文字

result

IRemoteResult

调用结果回调

2.2.12 setKeyboardLockModifiers

设置键盘锁状态

该方法未实现

public void setKeyboardLockModifiers(int modifiers, IRemoteResult result)

参数:

参数

类型

说明

modifiers

int

键盘锁状态

result

IRemoteResult

调用结果回调

2.2.13 registerASPEngineListener

注册IASPEngineListener,用于监听串流连接及运行错误状态

public void registerASPEngineListener(IASPEngineListener listener)

参数:

参数

类型

说明

listener

IASPEngineListener

用于监听串流连接及运行错误状态

2.2.14 unregisterASPEngineListener

取消对串流连接及运行错误状态的监听

public void unregisterASPEngineListener(IASPEngineListener listener)

参数:

参数

类型

说明

listener

IASPEngineListener

注册时使用的listener对象

2.2.15 registerIMEListener

注册IIMEListener,用于监听云上输入框焦点获取及输入法UI位置状态

该方法未实现

public void registerIMEListener(IIMEListener listener)

参数:

参数

类型

说明

listener

IIMEListener

用于监听云上输入框焦点获取及输入法UI位置状态的对象

2.2.16 unregisterIMEListener

取消对云上输入框焦点获取及输入法UI位置状态的监听

该方法未实现

public void unregisterIMEListener(IIMEListener listener)

参数:

参数

类型

说明

listener

IIMEListener

注册时使用的listener对象

2.2.17 registerAudioVolumeListener

注册IAudioVolumeListener,用于监听云上音量变化

该方法未实现

public void registerAudioVolumeListener(IAudioVolumeListener listener)

参数:

参数

类型

说明

listener

IAudioVolumeListener

用于监听云上音量变化的对象

2.2.18 unregisterAudioVolumeListener

取消对云上音量变化的监听

该方法未实现

public void unregisterAudioVolumeListener(IAudioVolumeListener)

参数:

参数

类型

说明

listener

IAudioVolumeListener

注册时使用的listener对象

2.2.19 registerResolutionUpdateListener

注册IResolutionUpdateListener,用于监听视频流分辨率变化

public void registerResolutionUpdateListener(IResolutionUpdateListener listener)

参数:

参数

类型

说明

listener

IResolutionUpdateListener

用于监听视频流分辨率变化的对象

2.2.20 unregisterResolutionUpdateListener

取消对视频流分辨率变化的监听

public void unregisterResolutionUpdateListener(IResolutionUpdateListener)

参数:

参数

类型

说明

listener

IResolutionUpdateListener

注册时使用的listener对象

2.2.21 registerCursorListener

注册ICursorListener,用于监听云上光标的状态变化

public void registerCursorListener(ICursorListener listener)

参数:

参数

类型

说明

listener

ICursorListener

用于监听云上光标状态变化的对象

2.2.22 unregisterCursorListener

取消对云上光标状态变化的监听

public void unregisterCursorListener(ICursorListener listener)

参数:

参数

类型

说明

listener

ICursorListener

注册时使用的listener对象

2.2.23 registerOrientationUpdateListener

注册IOrientationUpdateListener,用于监听云上屏幕旋转事件

public void registerOrientationUpdateListener(IOrientationUpdateListener listener)

参数:

参数

类型

说明

listener

IOrientationUpdateListener

用于监听云上屏幕旋转事件

2.2.24 unregisterOrientationUpdateListener

取消对云上屏幕旋转事件的监听

public void unregisterOrientationUpdateListener(IOrientationUpdateListener listener)

参数:

参数

类型

说明

listener

IOrientationUpdateListener

注册时使用的listener对象

2.2.25 registerStatisticsListener

注册IStatisticsListener,用于监听性能及关键运行状态数据报告

public void registerStatisticsListener(IStatisticsListener listener)

参数:

参数

类型

说明

listener

IStatisticsListener

用于监听性能及关键运行状态数据报告的对象

2.2.26 unregisterStatisticsListener

取消对性能及关键运行状态数据报告的监听

public void unregisterStatisticsListener(IStatisticsListener listener)

参数:

参数

类型

说明

listener

IStatisticsListener

注册时使用的listener对象

2.2.27 sendTouchEvent

向云上发送Touch消息

public boolean sendTouchEvent(MotionEvent event)

参数:

参数

类型

说明

event

android.view.MotionEvent

Touch消息

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.2.28 sendTouchEvent

向云上发送Touch消息,并异步返回发送结果

该方法未实现

public void sendTouchEvent(MotionEvent event, IRemoteResult result)

参数:

参数

类型

说明

event

android.view.MotionEvent

Touch消息

result

IRemoteResult

调用结果回调

2.2.29 sendKeyboardEvent

向云上发送键盘按键消息

public boolean sendKeyboardEvent(KeyEvent event)

参数:

参数

类型

说明

event

android.view.KeyEvent

Key消息

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.2.30 sendKeyboardEvent

向云上发送键盘按键消息,并异步返回发送结果

该方法未实现

public void sendKeyboardEvent(KeyEvent event, IRemoteResult result)

参数:

参数

类型

说明

event

android.view.KeyEvent

Key消息

result

IRemoteResult

调用结果回调

2.2.31 sendMouseEvent

向云上发送鼠标按键消息

public boolean sendMouseEvent(MotionEvent motionEvent)

参数:

参数

类型

说明

motionEvent

android.view.MotionEvent

Android MotionEvent消息,source是鼠标

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.2.32 sendMouseEvent

向云上发送鼠标按键消息,并异步返回发送结果

该方法未实现

public void sendMouseEvent(MotionEvent motionEvent, IRemoteResult result)

参数:

参数

类型

说明

motionEvent

android.view.MotionEvent

Android MotionEvent消息,source是鼠标

result

IRemoteResult

调用结果回调

2.2.33 sendMouseEvent

向云上发送鼠标按键消息

public boolean sendMouseEvent(float x, float y, float axisValue, int action, int button, int state)

参数:

参数

类型

说明

x

float

光标x坐标

y

float

光标y坐标

axisValue

float

滚轮偏移量

action

int

当前鼠标操作的Action值

button

int

当前鼠标操作对应按键键值

state

int

当前鼠标操作对应的按键状态

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.2.34 sendGamePadConnected

向云上发送GamePad设备已连接的消息

该方法未实现

public boolean sendGamePadConnected(int id, int type)

参数:

参数

类型

说明

id

int

游戏手柄标识

type

int

SOURCE_GAMEPAD | SOURCE_DPAD |

SOURCE_JOYSTICK 的组合

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.2.35 sendGamePadDisconnected

向云上发送GamePad设备断开连接的消息

该方法未实现

public boolean sendGamePadDisconnected(int id)

参数:

参数

类型

说明

id

int

游戏手柄标识

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.2.36 sendGamePadEvent

向云上发送GamePad按键消息

该方法未实现

public boolean sendGamePadEvent(int id,String event)

参数:

参数

类型

说明

id

int

游戏手柄标识

event

String

GamePad事件,json字串

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.2.37 sendGamePadEvent

向云上发送GamePad按键消息,并异步返回发送结果

该方法未实现

public void sendGamePadEvent(String event, IRemoteResult result)

参数:

参数

类型

说明

event

String

GamePad事件,json字串

result

IRemoteResult

调用结果回调

2.2.38 enableMouseMode

激活或关闭鼠标模式。

当鼠标模式激活时,会在屏幕呈现虚拟鼠标。

public boolean enableMouseMode(boolean enabled)

参数:

参数

类型

说明

enabled

boolean

true表示激活鼠标模式,false表示关闭鼠标模式

返回值:

类型

说明

boolean

true表明鼠标模式设置成功;false表示设置失败

2.2.39 enableDesktopMode

设置ASPEngine以桌面模式运行,设置为enabled后,ASPEngine会将所有Touch消息转换为Mouse事件向服务端发送。

public void enableDesktopMode(boolean enabled)

参数:

参数

类型

说明

enabled

boolean

True表明将ASPEngine设置为以桌面模式运行。

False关闭桌面模式

2.2.40 reconnect

发生连接异常断开时,可通过该接口执行重连动作。

通常针对disconnect reason=2200执行该动作,应用程序需要通过Open API重新获取连接云电脑的token并交给重连接口执行重连动作。

public void reconnect(String connectionToken)

参数:

参数

类型

说明

connectionToken

String

应用程序通过Open API获取连接云电脑的token

2.2.41 dispose

断开与云电脑的连接并释放native资源,调用该方法后,ASPEngine对象处于不可用状态,应用逻辑不应再使用相同的对象执行任何串流相关操作

public void dispose()

2.2.42 setMediaStreamPlayer

使用应用自定义的媒体引擎替换SDK中默认的媒体引擎实现,该方法只能在发起串流之前,或串流断开之后调用。

boolean setMediaStreamPlayer(MediaStreamPlayer player);

参数

类型

说明

player

MediaStreamPlayer

应用自定义的媒体引擎

返回值:

类型

说明

boolean

true表明应用自定义媒体引擎设置成功,false表示设置失败

2.2.43 setAlignStreamResolutionWithSurfaceSize

设置是否在串流开始时,自动将流分辨率同步为端侧用于渲染图像的SurfaceView的大小,默认开启该功能。

void setAlignStreamResolutionWithSurfaceSize(boolean aligned);

参数

类型

说明

aligned

boolean

True表明自动将流分辨率同步为端侧用于渲染图像的SurfaceView的大小。

False表明不进行自动同步。

2.2.44 registerRequestSystemPermissionListener

注册IRequestSystemPermissionListener,用于监听ASPEngine申请系统权限的请求。

public void registerRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数:

参数

类型

说明

listener

IRequestSystemPermissionListener

用于监听ASPEngine申请系统权限的请求

2.2.45 unregisterRequestSystemPermissionListener

取消对ASPEngine申请系统权限请求的监听

public void unregisterRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数:

参数

类型

说明

listener

IRequestSystemPermissionListener

注册时使用的listener对象

2.2.46 mute

设置是否进入静音模式

void mute(boolean muted);

参数

类型

说明

muted

boolean

True表明将进入静音模式

False关闭静音模式

2.3 Listener

2.3.1 IRemoteResult

用于应用在使用异步设置/控制接口时,获取远程调用的响应结果:

onSuccess

当远程调用成功后,通过该方法告知应用。

某些流程云上可能没有执行成功的反馈,则以收到云上响应作为success标准

public void onSuccess()

onFailure

当远程调用失败时,通过该方法告知应用。

public void onFailure(int errorCode, String errorMsg)

参数:

参数

类型

说明

errorCode

int

错误码

errorMsg

String

关于错误的描述

onTimeout

当远程调用发生超时时,通过该方法告知应用。

public void onTimeout()

2.3.2 IASPEngineListener

用于监听串流连接的状态

onConnectionSuccess

当串流建连成功后,通过该方法告知应用

public void onConnectionSuccess()

onConnectionFailure

当串流建连失败,或连接状态发生异常,通过该方法告知应用

public void onConnectionFailure(int errorCode, String errorMsg)

参数:

参数

类型

说明

errorCode

int

错误码

errorMsg

String

关于错误的描述

onEngineError

ASPEngine内部逻辑发生异常时,如解码错误,内部状态错误等,通过该方法告知应用

public void onEngineError(int errorCode, String errorMsg)

参数:

参数

类型

说明

errorCode

int

错误码

errorMsg

String

关于错误的描述

onDisconnected

当连接断开时,通过该方法告知应用

public void onDisconnected(int reason)

参数:

参数

类型

说明

reason

int

连接断开的原因

该值为2200时,表明侦测到RTT通信超时,与云电脑的连接异常断开,这种情况下,应用程序可以调用IASPEngine.reconnect接口执行重连操作

onReconnect

当连接发生重连动作时,通过该方法告知应用

public void onReconnect()

2.3.3 IIMEListener

用于监听云上输入框焦点变化及输入法UI位置状态

onIMEFocusUpdate

当云上输入框获取/失去焦点时,通过该方法告知应用

public void onIMEFocusUpdate(boolean hasFocus)

参数:

参数

类型

说明

hasFocus

boolean

true表示云上输入框已获取焦点;false表示云上输入框丢失焦点

onIMELocationUpdate

当云上输入法UI的位置发生变化时时,通过该方法告知应用

public void onIMELocationUpdate(int x, int y)

参数:

参数

类型

说明

x

int

云上输入法UI在屏幕上的X坐标

y

int

云上输入法UI在屏幕上的Y坐标

2.3.4 IAudioVolumeListener

用于监听云上系统的音量变化

onAudioVolumeUpdate

当云上系统的音量发生变化时,通过该方法告知应用

public void onAudioVolumeUpdate(double volume)

参数:

参数

类型

说明

volume

double

云上系统的音量

2.3.5 IResolutionUpdateListener

用于监听视频流的分辨率变化

onResolutionUpdate

当视频流的分辨率发生变化时,通过该方法告知应用

public void onResolutionUpdate(int oldWidth, int oldHeight, int width, int height)

参数:

参数

类型

说明

oldWidth

int

变化前的辨率宽度,首次渲染时,该值为0

oldHeight

int

变化前的分辨率高度首次渲染时该值为-1

width

int

变化后的分辨率宽度

height

int

变化后的分辨率高度

2.3.6 ICursorListener

用于监听云上光标的状态变化,如光标形态变化,光变可见性变化等

onCursorBitmapUpdate

当云上光标形态变化时,通过该方法告知应用

public void onCursorBitmapUpdate(int hotX, int hotY, Bitmap bitmap)

参数:

参数

类型

说明

hotX

int

光标热点X坐标

hotY

int

光标热点Y坐标

bitmap

Bitmap

cursor图片

onCursorReset

当云上光标状态被重置时,通过该方法告知应用

public void onCursorReset()

onCursorHide

当云上光标被隐藏时,通过该方法告知应用

public void onCursorHide()

onCursorMove

当云上光标位置发生变化时,通过该方法告知应用

public void onCursorMove(int x, int y)

参数:

参数

类型

说明

x

int

光标移动的X坐标

y

int

光标移动的Y坐标

2.3.7 IOrientationUpdateListener

用于监听云上屏幕旋转事件

onOrientationUpdate

当云上发生屏幕旋转事件时,通过该方法告知应用

public void onOrientationUpdate(int oldOrientation, int newOrientation)

参数:

参数

类型

说明

oldOrientation

int

云上屏幕旋转前的orientation

newOrientation

int

云上屏幕旋转后的orientation

2.3.8 IStatisticsListener

用于监听性能及关键运行状态数据报告

onStatisticsInfoUpdate

若应用调用了enableStatistics,则ASPEngine会定期更新性能及关键运行状态数据报告,并通过该方法告知应用

public void onStatisticsInfoUpdate(StatisticsInfo info)

参数:

参数

类型

说明

info

StatisticsInfo

性能及关键运行状态数据报告

StatisticsInfo

class StatisticsInfo {
   public int mReceiveFps = 0; // 端侧每秒接收到的视频祯数量
   public int mRenderFps = 0; // 端侧渲染FPS
   public double mDownstreamBandwithMBPerSecond = 0; // 下行带宽,MB/s
   public double mUpstreamBandwithMBPerSecond = 0; // 上行带宽,MB/s
   public long mP2pFullLinkageLatencyMS = -1; // 端到端全链路时延,毫秒
   // 目前该值需要在guest os中使用特定应用才可准确表示
   public long mNetworkLatencyMS = -1; // 网络rtt时延,毫秒
   public double mLostRate = 0; // 丢包率
   public long mServerRenderLatencyMS = -1; // 服务端渲染时延,毫秒
   public long mServerEncoderLatencyMS = -1; // 服务端编码时延,毫秒
   public long mServerTotalLatencyMS = -1; // 服务端总时延,毫秒
}

2.3.9. IRequestSystemPermissionListener

用于监听ASPEngine申请系统全新的请求

onRequestSystemPermission

当ASPEngine需要申请某个系统权限时,通过该方法告知应用。

public void onRequestSystemPermission(SystemPermission permission)

参数:

参数

类型

说明

permission

SystemPermission

ASPEngine申请的系统权限

SystemPermission

enum SystemPermission {
    RECORD_AUDIO; // 录音权限
}

2.3.10 IExtDeviceListener

用于监听存储设备或摄像头等设备的连接变化

 /**
 * 当存储设备连接或断开连接时回调
 * @param udisks 存储设备列表
 */
void onUDisksUpdate(List<UDiskItem> udisks);

/**
 * 当摄像头设备连接或者断开连接时回调
 * @param cameras 摄像头设备列表
 */
void onCamerasUpdate(List<CameraItem> cameras);

设备控制:

当获取到设备列表后,可以通过以下接口单独控制某设备

UDiskItem类设备控制

/**
 * 获取当前设备连接状态
 * @return ConnectStatus.DISCONNECTED: 未连接状态 ConnectStatus.CONNECTED: 连接状态
 */
ConnectStatus getStatus();

/**
 * 获取当前设备名称
 * @return 设备名称
 */
String getName();

/**
 * 获取存储路径
 * @return 存储路径
 */
String getPath();

/**
 * 连接设备
 */
void connect();
/**
 * 断开设备
 */
void disConnect();

CameraItem类设备控制

/**
 * 获取当前设备连接状态
 * @return ConnectStatus.DISCONNECTED: 未连接状态 ConnectStatus.CONNECTED: 连接状态
 */
ConnectStatus getStatus();

/**
 * 获取当前设备名称
 * @return 设备名称
 */
String getName();

/**
 * 连接设备
 */
void connect();

/**
 * 断开设备
 */
void disConnect();

/**
 * 获取是否预览镜像
 */
boolean isPreviewMirror();

/**
 * 设置预览镜像
 */
void setPreviewMirror(boolean mirror);

2.4 Static方法

2.4.1 IASPEngine.setLogAdapter

设置一个全局的LoggerAdapter对象,应用程序通过继承并实现LoggerAdapter定义的抽象方法实现Log重定向功能

public static void setLogAdapter(LoggerAdapter logAdapter)

参数:

参数

类型

说明

logAdapter

LoggerAdapter

LoggerAdapter对象,由应用提供

LoggerAdapter

public interface LoggerAdapter {
    public void onLogMessage(String tag, String msg, LogLevel level);
}

2.5 StreamView

StreamView是一个RelativeLayout容器,其子view至少包含一个SurfaceView用于渲染流化图像。

StreamView内部集成了ASPEngine,并实现了对ASP流的控制及input注入,事件提示等功能,通过StreamView,应用程序能够更快速地集成ASP的相关能力。

2.5.1 配置常量名

常量名

对应配置值的类型

配置说明

CONFIG_HOST_ADDRESS

string

ASP server或网关连接所使用的地址,String

CONFIG_PORT

string

ASP server或网关连接所使用的端口号

CONFIG_USE_TLS

boolean

是否使用tls加密

CONFIG_USE_VPC

boolean

端侧是否处于VPC网络环境

CONFIG_ENABLE_VDAGENT_CHECK

boolean

是否在建连过程中检查VDAgent可用性

CONFIG_PREFER_RTC_TRANSPORT

boolean

是否偏好使用RTC作为流化数据传输方式

CONFIG_TOKEN

string

连接网关所使用的token

CONFIG_CA_FILE_PATH

string

CA文件的绝对路径,用于tls通信加密

CONFIG_ENABLE_STATISTICS

boolean

是否激活性能统计,若激活,将在视频流上额外呈现性能数据

CONFIG_CONNECTION_TICKET

string

通过PaaS接口获取的server session字串

2.5.2 start

根据指定配置项启动串流流程。

public void start(Bundle configs)

参数:

参数

类型

说明

configs

android.os.Bundle

ASP串流配置,应用程序至少需要提供

CONFIG_CONNECTION_TICKET,或指定的ASP server/网关连接信息

2.5.3 stop

立即停止云端的串流服务

public void stop()

2.5.4 dispose

立即停止云端的串流服务并重置StreamView内部状态,activity在接收到onDestroy消息时需要调用该方法

public void dispose()

2.5.5 scaleStreamVideo

StreamView根据指定的策略对流化图像内容进行相应的缩放处理

public void scaleStreamVideo(ScaleType scaleType)

参数:

参数

类型

说明

scaleType

StreamView

流化图像缩放策略,包括:

●FILL_STREAM_VIEW - 总是将流化图像拉伸至与StreamView相同大小。当StreamView的长宽比例与流化图像长宽比例不相等时。采用该策略可能导致图像有明显的变形 ●FIT_STREAM_CONTENT - 对StreamView的渲染区域进行调整,使得StreamView总是能以相同的长宽比例渲染流化图像内容。采用该策略时,流化图像可能无法填满整个StreamView

2.5.6 enableDesktopMode

设置StreamView以桌面模式运行,设置为enabled后,StreamView会将所有Touch消息转换为Mouse事件向服务端发送。

public void enableDesktopMode(boolean enabled)

参数:

参数

类型

说明

enabled

boolean

True表明将StreamView设置为以桌面模式运行。

False关闭桌面模式

2.5.7 setASPEngineListener

注册IASPEngineListener,用于监听串流连接及运行错误状态

public void registerASPEngineListener(IASPEngineListener listener)

参数:

参数

类型

说明

listener

IASPEngineListener

用于监听串流连接及运行错误状态

2.5.8 setVideoProfile

设置视频流的分辨率及帧率

目前fps参数不会生效

public void setVideoProfile(int width, int height, int fps, IRemoteResult result)

参数:

参数

类型

说明

width

int

视频流分辨率目标宽度,像素

height

int

视频流分辨率目标高度,像素

fps

int

视频流目标fps

result

IRemoteResult

调用结果回调

2.5.9 sendKeyEvent

向云上发送键盘按键消息

public boolean sendKeyEvent(KeyEvent event)

参数:

参数

类型

说明

event

android.view.KeyEvent

Key消息

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.5.10 simulateMouseClick

模拟向云上发送鼠标点击事件

参数:

参数

类型

说明

leftButton

boolean

true表示模拟鼠标左键点击事件,false表示模拟鼠标右键点击事件

2.5.11 getASPEngineDelegate

获取StreamView内部IASPEngine实例的代理对象

public ASPEngineDelegate getASPEngineDelegate()

返回值:

类型

说明

ASPEngineDelegate

StreamView内部IASPEngine实例的代理对象

2.5.12 ASPEngineDelegate

ASPEngineDelegate是IASPEngine实例的代理类,StreamView通过该类向外暴露部分IASPEngine接口。

应用程序可通过StreamView.getASPEngineDelegate获取该类的实例。

2.5.12.1 registerASPEngineListener

注册IASPEngineListener,用于监听串流连接及运行错误状态

public void registerASPEngineListener(IASPEngineListener listener)

参数:

参数

类型

说明

listener

IASPEngineListener

用于监听串流连接及运行错误状态

2.5.12.2 unregisterASPEngineListener

取消对串流连接及运行错误状态的监听

public void unregisterASPEngineListener(IASPEngineListener listener)

参数:

参数

类型

说明

listener

IASPEngineListener

注册时使用的listener对象

2.5.12.3 registerStatisticsListener

注册IStatisticsListener,用于监听性能及关键运行状态数据报告

public void registerStatisticsListener(IStatisticsListener listener)

参数:

参数

类型

说明

listener

IStatisticsListener

用于监听性能及关键运行状态数据报告的对象

2.5.12.4 unregisterStatisticsListener

取消对性能及关键运行状态数据报告的监听

public void unregisterStatisticsListener(IStatisticsListener listener)

参数:

参数

类型

说明

listener

IStatisticsListener

注册时使用的listener对象

2.5.12.5 enableMouseMode

激活或关闭鼠标模式

public boolean enableMouseMode(boolean enabled)

参数:

参数

类型

说明

enabled

boolean

true表示激活鼠标模式,false表示关闭鼠标模式

返回值:

类型

说明

boolean

true表明鼠标模式设置成功;false表示设置失败

2.5.12.6 setVideoProfile

设置视频流的分辨率及帧率

public void setVideoProfile(int width, int height, int fps, IRemoteResult result)

参数:

参数

类型

说明

width

int

视频流分辨率目标宽度,像素

height

int

视频流分辨率目标高度,像素

fps

int

视频流目标fps

result

IRemoteResult

调用结果回调

2.5.12.7 sendKeyboardEvent

向云上发送键盘按键消息

public boolean sendKeyboardEvent(KeyEvent event)

参数:

参数

类型

说明

event

android.view.KeyEvent

Key消息

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.5.12.8 sendKeyboardEvent

向云上发送键盘按键消息,并异步返回发送结果

该方法未实现

public void sendKeyboardEvent(KeyEvent event, IRemoteResult result)

参数:

参数

类型

说明

event

android.view.KeyEvent

Key消息

result

IRemoteResult

调用结果回调

2.5.12.9 sendMouseEvent

向云上发送鼠标按键消息

public boolean sendMouseEvent(MotionEvent motionEvent)

参数:

参数

类型

说明

motionEvent

android.view.MotionEvent

Android MotionEvent消息,source是鼠标

返回值:

类型

说明

boolean

true表明event已成功发送到服务端;false表示发送失败

2.5.12.10 sendMouseEvent

向云上发送鼠标按键消息,并异步返回发送结果

该方法未实现

public void sendMouseEvent(MotionEvent motionEvent, IRemoteResult result)

参数:

参数

类型

说明

motionEvent

android.view.MotionEvent

Android MotionEvent消息,source是鼠标

result

IRemoteResult

调用结果回调

2.5.12.11 enableDesktopMode

设置ASPEngine以桌面模式运行,设置为enabled后,ASPEngine会将所有Touch消息转换为Mouse事件向服务端发送。

public void enableDesktopMode(boolean enabled)

参数:

参数

类型

说明

enabled

boolean

True表明将ASPEngine设置为以桌面模式运行。

False关闭桌面模式

2.5.12.12 reconnect

发生连接异常断开时,可通过该接口执行重连动作。

通常针对disconnect reason=2200执行该动作,应用程序需要通过Open API重新获取连接云电脑的token并交给重连接口执行重连动作。

public void reconnect(String connectionToken)

参数:

参数

类型

说明

connectionToken

String

应用程序通过Open API获取连接云电脑的token

2.5.12.13 setMediaStreamPlayer

使用应用自定义的媒体引擎替换SDK中默认的媒体引擎实现,该方法只能在发起串流之前,或串流断开之后调用。

boolean setMediaStreamPlayer(MediaStreamPlayer player);

参数

类型

说明

player

MediaStreamPlayer

应用自定义的媒体引擎

返回值:

类型

说明

boolean

true表明应用自定义媒体引擎设置成功,false表示设置失败

2.5.12.14 setAlignStreamResolutionWithSurfaceSize

设置是否在串流开始时,自动将流分辨率同步为端侧用于渲染图像的SurfaceView的大小,默认开启该功能。

void setAlignStreamResolutionWithSurfaceSize(boolean aligned);

参数

类型

说明

aligned

boolean

True表明自动将流分辨率同步为端侧用于渲染图像的SufaceView的大小。

False表明不进行自动同步。

2.5.12.15 registerRequestSystemPermissionListener

注册 IRequestSystemPermissionListener,用于监听ASPEngine申请系统权限的请求。

public void registerRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数:

参数

类型

说明

listener

IRequestSystemPermissionListener

用于监听ASPEngine申请系统权限的请求

2.5.12.16 unregisterRequestSystemPermissionListener

取消对ASPEngine申请系统权限请求的监听

public void unregisterRequestSystemPermissionListener(IRequestSystemPermissionListener listener)

参数:

参数

类型

说明

listener

IRequestSystemPermissionListener

注册时使用的listener对象

2.5.12.17 mute

设置是否进入静音模式

void mute(boolean muted);

参数

类型

说明

muted

boolean

True表明将进入静音模式

False关闭静音模式

2.5.12.18 setToQualityFirst

设置画质优先模式,该模式下所支持的最高帧率为 30 FPS,最高画质为优质

/**
 * 设置画质优先模式,该模式下所支持的最高帧率为 30 FPS,最高画质为优质
 */
void setToQualityFirst();
2.5.12.19 setToFpsFirst

设置流畅优先模式,该模式下所支持最高帧率为 60 FPS,最高画质为良好

/**
 * 设置流畅优先模式,该模式下所支持最高帧率为 60 FPS,最高画质为良好
 */
void setToFpsFirst();
2.5.12.20 setToCustomPicture

用户自定义模式,用户可以自定义帧率和画质

 /**
  * 用户自定义模式,用户可以自定义帧率和画质
  * @param fps 值为 0 到 60 区间,代表帧率设置,值越高越流畅
  * @param quality 值为 0 到 4 区间,0:无损,1:优质 2:良好 3:一般 4:自动
  */
void setToCustomPicture(int fps, int quality);

参数

类型

说明

fps

int

值为 0 到 60 区间,代表帧率设置,值越高越流畅

quality

int

值为 0 到 4 区间,0:无损,1:优质 2:良好 3:一般 4:自动

2.5.12.21 enableStatistics

设置状态检测是否可用

void enableStatistics(boolean enabled);

参数

类型

说明

enabled

boolean

True 状态检测可用

False 状态检测不可用

3. 使用自定义媒体引擎处理媒体数据

通过实现com.aliyun.wuying.aspsdk.aspengine.MediaStreamPlayer,应用程序可使用自定义的媒体引擎处理串流媒体数据,这些数据主要包括:

  • 视频流数据 - 以H264/H265压缩帧为主的视频裸流

  • 自适应图片流数据 - 以位图为主的图像流

  • 音频下行数据 - 以Opus/PCM为主的音频下行数据流

  • 光标数据 - 启用虚拟鼠标模式时,应用程序可接收到光标图像及位置数据,应用程序可使用这些数据自行绘制虚拟光标

应用程序可以通过调用IASPEngine.setMediaStreamPlayer接口向无影SDK提供自定以的媒体引擎实现。

3.1 MediaStreamPlayer

MediaStreamPlayer是一个抽象类,它要求应用程序实现全局的初始化/销毁方法,并提供处理不同媒体数据的自定义实现:

image.png

其中:

  • IVideoStreamHandler接口定义了用于处理视频流数据的方法

  • IAdaptiveGraphicStreamHandler接口定义了用于处理自适应图片流数据的方法

  • IAudioPlaybackStreamHandler接口定义了用于处理音频下行数据的方法

  • ICursorBitmap接口定义了用于处理光标数据的方法

应用程序可自行选择实现上述接口中的一个或多个,无影SDK最终会根据应用程序提供的接口实现设置云上下发流的类型,规则如下:

  • 若应用程序同时提供了IVideoStreamHandler及IAdaptiveGraphicStreamHandler的实现,则串流被设置为混合模式,无影将根据当前使用的场景自动在自适应图片流及视频流之间进行切换

  • 若应用程序仅提供IVideoStreamHandler的实现,则串流将被设置为Video stream only,此时服务端只会提供视频流数据

  • 若应用程序仅提供IAudioPlaybackStreamHandler的实现,则串流将被设置为Image stream only,此时服务端只会提供图片流数据

应用程序可通过实现MediaStreamPlayer的一系列onCreateXXXHandler方法向SDK提供针对不同媒体数据的自定义实现:

    @Override
    protected IVideoStreamHandler onCreateVideoStreamHandler() {
        return new VideoStreamHandler();
    }

    @Override
    protected IAdaptiveGraphicStreamHandler onCreateAdaptiveGraphicStreamHandler() {
        return null;
    }

    @Override
    protected IAudioPlaybackStreamHandler onCreateAudioPlaybackStreamHandler() {
        return new AudioPlaybackStreamHandler();
    }

    @Override
    protected ICursorBitmapHandler onCreateCursorBitmapHandler() {
        return null;
    }

在上面的例子中,自定义媒体引擎提供了IVideoStreamHandler及IAudioPlaybackStreamHandler的实现,onCreateXXXHandler方法在一次串流过程中只会被执行一次。

主要方法调用流程:

image.png

3.1.1 initialize

由应用程序实现该方法,可用于执行自定义媒体引擎相关的全局初始化动作。

该方法在每次串流过程中将被执行一次。

public ErrorCode initialize()

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行初始化成功,否则表示初始化失败

3.1.2 release

由应用程序实现该方法,可用于执行自定义媒体引擎相关的全局释放动作。

该方法在每次串流过程中将被执行一次。

public ErrorCode release()

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行释放成功,否则表示释放失败

3.1.3 enableStatistics

由应用程序实现该方法,可用于激活/关闭性能统计数据采集。

public void enableStatistics(boolean enabled)

参数:

参数

类型

说明

enabled

boolean

True表明开启性能数据采集。

False关闭性能数据采集。

3.1.4 onCreateVideoStreamHandler

由应用程序实现该方法,用于向SDK提供处理视频流数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

public IVideoStreamHandler onCreateVideoStreamHandler()

返回值:

类型

说明

IVideoStreamHandler

由应用程序提供的用于处理视频流数据的媒体引擎实现。

若应用不提供视频流处理实现,则返回null,在这种情况下视频流数据不会得到任何处理。

3.1.5 onCreateAdaptiveGraphicStreamHandler

由应用程序实现该方法,用于向SDK提供处理自适应图片流数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

public IAdaptiveGraphicStreamHandler onCreatAdaptiveGraphicStreamHandler()

返回值:

类型

说明

IAdaptiveGraphicStreamHandler

由应用程序提供的用于处理自适应图片流数据的媒体引擎实现。

若应用不提供自适应图片流处理实现,则返回null,在这种情况下,图片流数据不会得到任何处理。

3.1.6 onCreateAudioPlaybackStreamHandler

由应用程序实现该方法,用于向SDK提供处理音频下行数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

public IAudioPlaybackStreamHandler onCreatAudioPlaybackStreamHandler()

返回值:

类型

说明

IAudioPlaybackStreamHandler

由应用程序提供的用于处理音频下行数据的媒体引擎实现。

若应用不提供音频下行数据处理实现,则返回null,在这种情况下音频下行数据不会得到任何处理。

3.1.7 onCreateCursorBitmapHandler

由应用程序实现该方法,用于向SDK提供处理光标数据的媒体引擎实现。

该方法在每次串流过程中将被执行一次。

通过该方法提供的接口实现仅在虚拟鼠标模式激活时被使用。

public ICursorBitmapHandler onCreatCursorBitmapHandler()

返回值:

类型

说明

ICursorBitmapHandler

由应用程序提供的用于处理光标数据的媒体引擎实现。

若应用不提供光标数据处理实现,则返回null,在这种情况下,即使虚拟鼠标模式被激活,光标位置数据也不会得到任何处理。

3.2 IVideoStreamHandler

该接口定义了处理视频流数据的主要方法,其主要工作流程如下:

image

当应用发生前后台切换时,用于渲染的Surface将被销毁或重建,在这种情况下,IVideoStreamHandler.setVideoSurface将被多次调用,当Surface被销毁时,通过setVideoSurface传入的surface对象为null,应用程序需要处理好decoder及render的容错工作。

应用程序通过实现IVideoStreamHandler.setEventHandler方法可获取无影SDK提供的事件处理接口,通过该接口,应用程序可以将自定义媒体引擎内的一些视频处理事件通知给无影SDK内部,目前主要用于性能数据统计:

    @Override
    public void setEventHandler(EventHandler handler) {
        Log.i(TAG, "setEventHandler handler " + handler);
        VideoStreamEventHandler.getInstance().reset(handler);
    }

...
    
    public synchronized void onVideoFrameRendered() {
        VFrame frame = mVideoFrame.remove();
        if (mEnabled && mHandler != null) {
            Event event = new Event();
            event.type = EventType.RENDER_PERF_INFO;
            event.decodePerfInfo = new VDecodePerfInfo();
            event.renderPerfInfo = new VRenderPerfInfo();
            event.renderPerfInfo.frameId = frame.frameId;
            event.renderPerfInfo.sessionId = frame.sessionId;
            // 通知无影SDK一帧视频图像完成渲染,SDK内部根据frameId计算端侧全链路时延
            mHandler.callback(event);
        }
    }

3.2.1 setEventHandler

由应用程序实现该方法,当自定义媒体引擎被无影SDK加载时,SDK通过该方法向应用程序提供EventHandler,应用程序可通过该handler发送视频流处理事件。

public void setEventHandler(EventHandler handler)

参数:

参数

类型

说明

handler

EventHandler

由无影SDK提供的handler对象,应用程序通过该对象向SDK发送视频流处理事件

3.2.2 addVideoTrack

由应用程序实现该方法,当一路视频流创建时,通过该方法通知应用程序。

目前一次串流过程中最多只存在一路视频。

ErrorCode addVideoTrack(int trackId, VProfile profile);

参数:

参数

类型

说明

trackId

int

视频流Id

profile

VProfile

视频流信息

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.2.3 setVideoSurface

由应用程序实现该方法,当用于渲染视频的Surface状态发生变化时,通过该方法通知应用程序。

ErrorCode setVideoSurface(int trackId, Surface surface);

参数:

参数

类型

说明

trackId

int

视频流Id

surface

android.view.Surface

用于渲染视频的Surface对象。

当应用切换到后台或发生锁屏动作时,该对象可能为null

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.2.4 playVideo

由应用程序实现该方法,当用视频流准备就绪时,通过该方法通知应用程序。

ErrorCode playVideo(int trackId);

参数:

参数

类型

说明

trackId

int

视频流Id

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.2.5 removeVideoTrack

由应用程序实现该方法,当视频流被销毁时,通过该方法通知应用程序。

ErrorCode removeVideoTrack(int trackId);

参数:

参数

类型

说明

trackId

int

视频流Id

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.2.6 pushVideoFrame

由应用程序实现该方法,当用于接收到新的视频帧时,通过该方法通知应用程序。

ErrorCode setVideoSurface(int trackId, Surface surface);

参数:

参数

类型

说明

trackId

int

视频流Id

frame

VFrame

新接收到的视频帧信息

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.2.7 getVideoTracks

由应用程序实现该方法,SDK通过该方法从应用程序获取当前正在处理所有视频流信息。

HashMap<Integer, VProfile> getVideoTracks();

返回值:

类型

说明

HashMap<Integer, VProfile>

应用程序获取当前正在处理所有视频流信息

3.2.8 release

由应用程序实现该方法,当所有的视频流被销毁时,通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3 IAudioPlaybackStreamHandler

该接口定义了处理音频流数据的主要方法,其主要工作流程如下:

image

3.3.1 initAudio

由应用程序实现该方法,当SDK内的音频通道创建时,通过该方法通知应用程序。

ErrorCode initAudio();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3.2 deInitAudio

由应用程序实现该方法,当SDK内的音频通道被销毁时,通过该方法通知应用程序。

ErrorCode deInitAudio();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3.3 startAudioPlayback

由应用程序实现该方法,当云电脑将要开始下发音频流时,通过该方法通知应用程序。

ErrorCode startAudioPlayback();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3.4 stopAudioPlayback

由应用程序实现该方法,当云电脑停止下发音频流时,通过该方法通知应用程序。

ErrorCode stopAudioPlayback();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3.5 pushAudioPlaybackFrame

由应用程序实现该方法,当接收到新的下行音频帧时,通过该方法通知应用程序。

ErrorCode pushAudioPlaybackFrame(AFrame pbData);

参数:

参数

类型

说明

pbData

AFrame

新接收到的音频帧信息

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3.6 updateAudioPlaybackVol

由应用程序实现该方法,当云电脑里的系统音量大小发生变化时,通过该方法通知应用程序。

ErrorCode updateAudioPlaybackVol(int volume);

参数:

参数

类型

说明

volume

int

云电脑里的系统音量值,最大值为USHRT_MAX,0表示静音。

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3.7 updateAudioPlaybackMute

由应用程序实现该方法,当云电脑被静音/解除静音时,通过该方法通知应用程序。

ErrorCode updateAudioPlaybackMute(int mute);

参数:

参数

类型

说明

mute

int

1表示云电脑进入静音状态,0表示解除静音

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.3.8 release

由应用程序实现该方法,当音频通道被销毁时,通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.4 IAdaptiveGraphicStreamHandler

该接口定义了处理图像流数据的主要方法,其主要工作流程如下:

image

目前应用程序获取到的图片帧格式为位图ARGB8888。

一次串流过程中最多存在一个图片流。

3.4.1 setAdaptiveGraphicSurface

由应用程序实现该方法,当用于渲染图片的Surface状态发生变化时,通过该方法通知应用程序

ErrorCode setAdaptiveGraphicSurface(Surface surface);

参数:

参数

类型

说明

surface

android.view.Surface

用于渲染图片的Surface对象。

当应用切换到后台或发生锁屏动作时,该对象可能为null

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.4.2 invalidateAdaptiveGraphicSurface

由应用程序实现该方法,当用于接收到新的图片帧数据时,通过该方法通知应用程序

ErrorCode invalidateAdaptiveGraphicSurface(Region region, byte[] buffer, BitmapFormat format);

参数:

参数

类型

说明

region

Region

图片帧绘制区域信息

buffer

byte[]

图片帧数据

format

BitmapFormat

图片帧格式信息,默认为ARGB8888

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.4.3 release

由应用程序实现该方法,当图片流被销毁时,通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.5 ICursorBitmapHandler

该接口定义了处理光标数据的主要方法,在虚拟鼠标模式激活时,应用程序向SDK提供该接口的实现用于光标图像的绘制,其主要工作流程如下:

image

3.5.1 setCursorBitmap

由应用程序实现该方法,当云电脑里的光标形状生变化时,通过该方法通知应用程序。

ErrorCode setCursorBitmap(CursorBitmap bitmap);

参数:

参数

类型

说明

bitmap

CursorBitmap

云电脑光标图形数据

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.5.2 unsetCursorBitmap

由应用程序实现该方法,当云电脑里的光标被隐藏时,通过该方法通知应用程序。

ErrorCode unsetCursorBitmap();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.5.3 setCursorPosition

由应用程序实现该方法,当云电脑里的光标形状生变化时,通过该方法通知应用程序。

ErrorCode setCursorPosition(float x, float y);

参数:

参数

类型

说明

x

float

光标的X坐标

y

float

光标的Y坐标

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

3.5.4 release

由应用程序实现该方法,当连接断开,取消光标显示时,通过该方法通知应用程序执行清理动作。

ErrorCode release();

返回值:

类型

说明

ErrorCode

ErrorCode.OK表明执行成功,否则表示失败

4. 附件

4.1 demo

AndroidDemo.zip

4.2 sdk

AndroidSDK.aar.zip

说明

下载和使用即表示您认可《无影云电脑SDK隐私权政策》

本平台所有文档、SDK、客户端程序仅限于本人或本企业使用,未经阿里云同意不会转发给三方个人或企业。