ASP Android SDK-Elastic Desktop Service-阿里云帮助中心

The ASP SDK for Android lets you integrate EDS streaming into your Android applications. With the SDK, your app can start and stop streams, inject touch, keyboard, and mouse events, control audio and video settings, and respond to cloud-side events such as cursor changes, resolution updates, and screen orientation changes.

Requirements: Android 5.1 or later.
Downloads: Get the SDK and the demo app before you start.

Note

Maven repository integration is coming soon. Use AAR file integration in the meantime.

How it works

A streaming session follows this sequence:

Get a server session — Call the Alibaba Cloud Workspace PaaS API from your backend to obtain a ServerSession string (connection ticket).
Initialize the SDK — Create an IASPEngine instance using IASPEngine.Builder, configure a SurfaceView, and register the listeners you need.
Start the stream — Pass the ServerSession to mEngine.start(session, null). The IASPEngineListener.onConnectionSuccess callback fires when the connection is established.
Inject input events — Forward touch, keyboard, and mouse events to the engine during the session.
Stop and release — Call mEngine.stop() to end the session and mEngine.dispose() to release native resources.

The SDK offers two integration styles:

Style	Best for
`IASPEngine` + `SurfaceView` (direct API)	Full control over rendering and event handling
`StreamView` (enhanced UI component)	Faster integration with less boilerplate code

Prerequisites

Before you begin, make sure you have:

An Android project targeting Android 5.1 (API level 22) or later
A backend service that can call the EDS PaaS API to obtain a ServerSession
The aspengine-third-release.aar file from the SDK download above

Integrate the SDK

Add the AAR file

Copy aspengine-third-release.aar to the app/libs directory.

Add the following dependencies to your module-level build.gradle:

dependencies {
    implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
    // INI file parsing library required by the ASP SDK
    implementation 'org.ini4j:ini4j:0.5.4'
}

Declare the required permission in AndroidManifest.xml:

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

Declare your streaming activity in AndroidManifest.xml. The example below forces landscape orientation to match the cloud computer display:

<activity android:name=".ASPEngineDemoActivity"
          android:launchMode="singleTop"
          android:screenOrientation="sensorLandscape">

Quickstart: Direct API (`IASPEngine`)

This approach gives you full control over rendering and input injection. The ASPEngineDemoActivity below shows the complete setup.

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

    private SurfaceView mAspSurfaceView = 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);

        // Forward touch events to the cloud computer
        mAspSurfaceView.setOnTouchListener((view, motionEvent) -> {
            if (mEngine != null) {
                return mEngine.sendTouchEvent(motionEvent);
            }
            return false;
        });

        // Forward mouse events to the cloud computer
        mAspSurfaceView.setOnGenericMotionListener((v, motionEvent) -> {
            if (0 != (motionEvent.getSource() & InputDevice.SOURCE_MOUSE)) {
                if (mEngine != null) {
                    return mEngine.sendMouseEvent(motionEvent);
                }
            }
            return true;
        });

        // Build the engine and configure the rendering surface
        mEngine = new IASPEngine.Builder().build();
        mEngine.setSurface(mAspSurfaceView);

        // Listen on connection status and engine errors
        mEngine.registerASPEngineListener(new IASPEngineListener() {
            @Override
            public void onConnectionSuccess() {
                Log.i(TAG, "onConnectionSuccess");
            }
            @Override
            public void onConnectionFailure(int errorCode, String errorMsg) {
                Log.i(TAG, "onConnectionFailure: " + errorCode + " " + errorMsg);
            }
            @Override
            public void onEngineError(int errorCode, String errorMsg) {
                Log.i(TAG, "onEngineError: " + errorCode + " " + errorMsg);
            }
            @Override
            public void onDisconnected(int reason) {
                // When reason == 2200, call reconnect() to restore the session
                Log.i(TAG, "onDisconnected reason=" + reason);
            }
            @Override
            public void onReconnect() {
                Log.i(TAG, "onReconnect");
            }
        });

        mEngine.registerCursorListener(this);
        mEngine.registerResolutionUpdateListener(this);
        mEngine.registerOrientationUpdateListener(this);
    }

    /**
     * Call this method after your backend retrieves the ServerSession
     * by calling the Alibaba Cloud Workspace PaaS API.
     */
    protected void onGetServerSession(String session) {
        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);
    }

    // --- ICursorListener callbacks ---

    @Override
    public void onCursorBitmapUpdate(int hotX, int hotY, int width, int height, byte[] rgba) {
        Bitmap rawBmp = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888);
        rawBmp.copyPixelsFromBuffer(ByteBuffer.wrap(rgba));
        if (rawBmp == null) return;
        PointerIcon cursor = PointerIcon.create(rawBmp, hotX, hotY);
        mAspSurfaceView.setPointerIcon(cursor);
    }

    @Override
    public void onCursorHide() {
        mAspSurfaceView.setPointerIcon(
            PointerIcon.getSystemIcon(getApplicationContext(), PointerIcon.TYPE_NULL));
    }

    @Override
    public void onCursorReset() {
        mAspSurfaceView.setPointerIcon(
            PointerIcon.getSystemIcon(getApplicationContext(), PointerIcon.TYPE_DEFAULT));
    }

    @Override
    public void onCursorMove(int x, int y) { /* Update cursor position if needed */ }

    // --- IResolutionUpdateListener callback ---

    @Override
    public void onResolutionUpdate(int oldWidth, int oldHeight, int width, int height) {
        // Scale the SurfaceView to match the stream aspect ratio
        float aspectRatio = 1.0f * width / height;
        float viewAspectRatio = 1.0f * mAspSurfaceView.getWidth() / mAspSurfaceView.getHeight();

        float factorX = 1f, factorY = 1f;
        if (viewAspectRatio > aspectRatio) {
            int expectedWidth = (int) (mAspSurfaceView.getHeight() * aspectRatio);
            factorX = 1.0f * expectedWidth / mAspSurfaceView.getWidth();
        } else {
            int expectedHeight = (int) (mAspSurfaceView.getWidth() / aspectRatio);
            factorY = 1.0f * expectedHeight / mAspSurfaceView.getHeight();
        }
        mAspSurfaceView.setScaleX(factorX);
        mAspSurfaceView.setScaleY(factorY);
    }

    // --- IOrientationUpdateListener callback ---

    @Override
    public void onOrientationUpdate(int oldOrientation, int 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;
        }
    }
}

Quickstart: `StreamView` (enhanced UI component)

StreamView is a RelativeLayout container with built-in ASP stream control, input injection, and event handling. Use it to reduce boilerplate code.

Additional setup

For StreamView, add the VIBRATE permission to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.VIBRATE"/>

Add StreamView to your activity layout:

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

    <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>

Activity code

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 + " " + errorMsg);
        }
        @Override
        public void onEngineError(int errorCode, String errorMsg) {
            Log.i(TAG, "onEngineError: " + errorCode + " " + errorMsg);
        }
        @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);
    }

    /**
     * Call this method after your backend retrieves the ServerSession
     * by calling the Alibaba Cloud Workspace PaaS API.
     */
    protected void onGetServerSession(String session) {
        Bundle config = new Bundle();
        config.putString(StreamView.CONFIG_CONNECTION_TICKET, session);
        mStreamView.start(config);
    }

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

API reference

`IASPEngine.Builder`

The builder to create an IASPEngine instance.

`Builder()`

public Builder()

`build()`

Builds and returns an IASPEngine instance.

public IASPEngine build()

Return type	Description
`IASPEngine`	The engine instance.

`enableVDAgentCheck(boolean enabled)`

Controls whether VDA availability is checked when establishing a connection. By default, the check is enabled.

If set to true and VDA is unavailable at connection time, the connection fails immediately. Disable this only for internal debugging.

public IASPEngine.Builder enableVDAgentCheck(boolean enabled)

Parameter	Type	Description
`enabled`	boolean	Default: `true`. When `true`, VDA availability is checked before the connection is established.

Return type	Description
`IASPEngine.Builder`	The builder instance, for method chaining.

`enableRTC(boolean enabled)`

Controls whether real-time communication (RTC) is used for stream data transmission. RTC is enabled by default.

public IASPEngine.Builder enableRTC(boolean enabled)

Parameter	Type	Description
`enabled`	boolean	Default: `true`. When `true`, RTC is used for stream data transmission.

Return type	Description
`IASPEngine.Builder`	The builder instance, for method chaining.

`IASPEngine`

The core interface of the ASP SDK for Android. Use it to:

Control streaming — start, stop, pause, and resume streams, and configure server cursor mode
Configure audio and video — set resolution and frame rate, mute audio
Inject input events — touch, keyboard, mouse, and gamepad
Register listeners — monitor connection status, resolution changes, cursor changes, and more

`start(String connectionTicket, String caFilePath)`

Starts streaming using a ServerSession obtained from the EDS PaaS API. Results are delivered through IASPEngineListener.

public void start(String connectionTicket, String caFilePath)

Parameter	Type	Description
`connectionTicket`	String	The `ServerSession` string returned by the PaaS API.
`caFilePath`	String	The absolute path to the certificate authority (CA) file for Transport Layer Security (TLS) encryption.

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

Starts streaming using explicit server connection parameters. Use this for debugging scenarios where you can connect to the ASP server directly or when you have a gateway address and access token.

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

Parameter	Type	Description
`host`	String	The IP address of the ASP server or gateway.
`port`	String	The port number of the ASP server or gateway.
`udpPort`	String	The UDP port number for RTC data transmission. In most cases, this is the same as `port`.
`caFilePath`	String	The absolute path to the CA file for TLS encryption.
`token`	String	The access token for connecting to the gateway.
`enableTls`	boolean	Specifies whether to encrypt data using TLS.

`stop()`

Immediately stops the stream. The IASPEngineListener.onDisconnected callback fires after the connection ends.

public void stop()

`pause(IRemoteResult result)`

Suspends stream ingest on the cloud computer.

public void pause(IRemoteResult result)

Parameter	Type	Description
`result`	IRemoteResult	Result callback. Pass `null` — no asynchronous result is returned for this operation.

`resume(IRemoteResult result)`

Resumes stream ingest on the cloud computer.

public void resume(IRemoteResult result)

Parameter	Type	Description
`result`	IRemoteResult	Result callback. Pass `null` — no asynchronous result is returned for this operation.

`enableStatistics(boolean enable)`

Enables or disables periodic performance statistics reporting via IStatisticsListener.

public void enableStatistics(boolean enable)

Parameter	Type	Description
`enable`	boolean	`true` (default): ASPEngine periodically reports performance metrics through the registered `IStatisticsListener`. `false`: statistics are not reported.

`toggleServerCursorMode(boolean toggled)`

Enables or disables server cursor mode on the cloud computer.

When server cursor mode is enabled, register ICursorListener to receive cursor state change events.

public void toggleServerCursorMode(boolean toggled)

Parameter	Type	Description
`toggled`	boolean	`true` (default): server cursor mode is enabled. `false`: server cursor mode is disabled.

`setSurface(SurfaceView surfaceView)`

Sets the SurfaceView used to render stream images. Call this after build() and before start().

void setSurface(SurfaceView surfaceView)

Parameter	Type	Description
`surfaceView`	android.view.SurfaceView	The surface for rendering stream images.

`setVideoProfile(int width, int height, int fps, IRemoteResult result)`

Sets the resolution and frame rate for the video stream.

The fps parameter is not yet available.

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

Parameter	Type	Description
`width`	int	Target resolution width, in pixels.
`height`	int	Target resolution height, in pixels.
`fps`	int	Target frame rate (fps).
`result`	IRemoteResult	Result callback.

`reconnect(String connectionToken)`

Reconnects to the cloud computer after an exception disconnects the session. Call this when IASPEngineListener.onDisconnected fires with reason == 2200 (RTT timeout). Retrieve a new connection token from the PaaS API before calling this method.

public void reconnect(String connectionToken)

Parameter	Type	Description
`connectionToken`	String	A new connection token obtained from the PaaS API.

`dispose()`

Disconnects from the cloud computer and releases all native resources. After calling this, the IASPEngine instance is no longer usable.

public void dispose()

`enableMouseMode(boolean enabled)`

Enables or disables mouse mode. When enabled, a virtual mouse appears on screen.

public boolean enableMouseMode(boolean enabled)

Parameter	Type	Description
`enabled`	boolean	`true`: enables mouse mode. `false`: disables mouse mode.

Return type	Description
boolean	`true` if mouse mode is enabled; `false` if disabled.

`enableDesktopMode(boolean enabled)`

Enables or disables desktop mode. When enabled, all touch events are converted to mouse events before being sent to the server.

public void enableDesktopMode(boolean enabled)

Parameter	Type	Description
`enabled`	boolean	`true`: desktop mode is enabled. `false`: disabled.

`setMediaStreamPlayer(MediaStreamPlayer player)`

Replaces the built-in media engine with a custom implementation. Call this only before starting or after stopping the stream.

boolean setMediaStreamPlayer(MediaStreamPlayer player)

Parameter	Type	Description
`player`	MediaStreamPlayer	The custom media engine.

Return type	Description
boolean	`true` if the custom engine was set successfully.

`setAlignStreamResolutionWithSurfaceSize(boolean aligned)`

Controls whether stream resolution is automatically synchronized to the SurfaceView size when streaming starts. Enabled by default.

void setAlignStreamResolutionWithSurfaceSize(boolean aligned)

Parameter	Type	Description
`aligned`	boolean	`true`: synchronize stream resolution to the surface size. `false`: do not synchronize.

`mute(boolean muted)`

Mutes or unmutes audio.

void mute(boolean muted)

Parameter	Type	Description
`muted`	boolean	`true`: mute audio. `false`: unmute.

Sending input events

All three input event methods return true if the event was delivered to the server, false if delivery failed.

Touch events

public boolean sendTouchEvent(MotionEvent event)

Parameter	Type	Description
`event`	android.view.MotionEvent	The touch event.

Keyboard events

public boolean sendKeyboardEvent(KeyEvent event)

Parameter	Type	Description
`event`	android.view.KeyEvent	The key event.

Mouse events — from `MotionEvent`

public boolean sendMouseEvent(MotionEvent motionEvent)

Parameter	Type	Description
`motionEvent`	android.view.MotionEvent	An Android motion event triggered by a mouse.

Mouse events — explicit parameters

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

Parameter	Type	Description
`x`	float	X-coordinate.
`y`	float	Y-coordinate.
`axisValue`	float	Mouse wheel offset.
`action`	int	Mouse event action.
`button`	int	Button pressed when the event was triggered.
`state`	int	Button state when the event was triggered.

Registering listeners

Method	Listener	Events
`registerASPEngineListener(IASPEngineListener)`	`IASPEngineListener`	Connection status and engine errors
`unregisterASPEngineListener(IASPEngineListener)`	—	—
`registerResolutionUpdateListener(IResolutionUpdateListener)`	`IResolutionUpdateListener`	Stream resolution changes
`unregisterResolutionUpdateListener(IResolutionUpdateListener)`	—	—
`registerCursorListener(ICursorListener)`	`ICursorListener`	Cursor scheme and visibility changes
`unregisterCursorListener(ICursorListener)`	—	—
`registerOrientationUpdateListener(IOrientationUpdateListener)`	`IOrientationUpdateListener`	Screen orientation changes
`unregisterOrientationUpdateListener(IOrientationUpdateListener)`	—	—
`registerStatisticsListener(IStatisticsListener)`	`IStatisticsListener`	Performance and runtime statistics
`unregisterStatisticsListener(IStatisticsListener)`	—	—
`registerRequestSystemPermissionListener(IRequestSystemPermissionListener)`	`IRequestSystemPermissionListener`	System permission requests from ASPEngine
`unregisterRequestSystemPermissionListener(IRequestSystemPermissionListener)`	—	—

Methods coming soon

The following methods are not yet available:

Method	Description
`setImePreedit(String preeditStr, IRemoteResult result)`	Sets preview text on the cloud from local IME input.
`setImeCommit(String commitStr, IRemoteResult result)`	Commits IME text to an input field on the cloud.
`setKeyboardLockModifiers(int modifiers, IRemoteResult result)`	Sets keyboard lock state.
`sendTouchEvent(MotionEvent event, IRemoteResult result)`	Sends a touch event with async result callback.
`sendKeyboardEvent(KeyEvent event, IRemoteResult result)`	Sends a key event with async result callback.
`sendMouseEvent(MotionEvent motionEvent, IRemoteResult result)`	Sends a mouse event with async result callback.
`sendGamePadConnected(int id, int type)`	Notifies the cloud that a gamepad connected.
`sendGamePadDisconnected(int id)`	Notifies the cloud that a gamepad disconnected.
`sendGamePadEvent(int id, String event)`	Sends a gamepad button event.
`sendGamePadEvent(String event, IRemoteResult result)`	Sends a gamepad event with async result callback.
`registerIMEListener(IIMEListener)` / `unregisterIMEListener(IIMEListener)`	Listens on IME focus and position changes on the cloud.
`registerAudioVolumeListener(IAudioVolumeListener)` / `unregisterAudioVolumeListener(IAudioVolumeListener)`	Listens on volume changes on the cloud.

`IASPEngine.setLogAdapter(LoggerAdapter logAdapter)` (static)

Redirects SDK log output to your application's logging system by providing a custom LoggerAdapter.

public static void setLogAdapter(LoggerAdapter logAdapter)

Parameter	Type	Description
`logAdapter`	LoggerAdapter	The log adapter provided by the application.

`LoggerAdapter` interface:

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

`StreamView`

StreamView is a RelativeLayout container with a built-in SurfaceView for rendering. It encapsulates ASP stream control, input injection, and event handling, so you can integrate streaming with minimal code.

To access the full IASPEngine API surface from StreamView, call getASPEngineDelegate() to get an ASPEngineDelegate instance.

Configuration parameters

Pass these constants as keys in a Bundle to StreamView.start(Bundle configs).

Constant	Type	Description
`CONFIG_CONNECTION_TICKET`	String	The `ServerSession` string from the PaaS API. Required for PaaS-based connections.
`CONFIG_HOST_ADDRESS`	String	ASP server or gateway address.
`CONFIG_PORT`	String	ASP server or gateway port.
`CONFIG_TOKEN`	String	Gateway access token.
`CONFIG_CA_FILE_PATH`	String	Absolute path to the CA file for TLS encryption.
`CONFIG_USE_TLS`	boolean	Specifies whether to use TLS encryption.
`CONFIG_USE_VPC`	boolean	Specifies whether the client connects over a VPC.
`CONFIG_ENABLE_VDAGENT_CHECK`	boolean	Specifies whether to check VDA availability at connection time.
`CONFIG_PREFER_RTC_TRANSPORT`	boolean	Specifies whether to use RTC as the transport method.
`CONFIG_ENABLE_STATISTICS`	boolean	Specifies whether to report performance statistics.

`start(Bundle configs)`

Starts streaming with the specified configuration.

public void start(Bundle configs)

Parameter	Type	Description
`configs`	android.os.Bundle	Streaming configuration. At minimum, set `CONFIG_CONNECTION_TICKET` or server connection parameters.

`stop()`

Immediately stops the stream.

public void stop()

`dispose()`

Stops streaming and resets the internal state. Call this in onDestroy().

public void dispose()

`scaleStreamVideo(ScaleType scaleType)`

Resizes the stream image according to the specified policy.

public void scaleStreamVideo(ScaleType scaleType)

Policy	Description
`FILL_STREAM_VIEW`	Stretches the stream image to fill `StreamView`. May distort the image if aspect ratios differ.
`FIT_STREAM_CONTENT`	Adjusts the rendering area to preserve the stream aspect ratio. The image may not fill the full `StreamView`.

`enableDesktopMode(boolean enabled)`

Enables or disables desktop mode. When enabled, all touch events are converted to mouse events.

public void enableDesktopMode(boolean enabled)

`setASPEngineListener(IASPEngineListener listener)`

Registers a listener for streaming connection status and engine errors.

public void registerASPEngineListener(IASPEngineListener listener)

`setVideoProfile(int width, int height, int fps, IRemoteResult result)`

Sets the resolution and frame rate for the video stream.

The fps parameter is not yet available.

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

`sendKeyEvent(KeyEvent event)`

Sends a key event to the cloud.

public boolean sendKeyEvent(KeyEvent event)

Return type	Description
boolean	`true` if the event was delivered; `false` if delivery failed.

`simulateMouseClick(boolean leftButton)`

Simulates a mouse click on the cloud.

Parameter	Type	Description
`leftButton`	boolean	`true`: simulate a left click. `false`: simulate a right click.

`getASPEngineDelegate()`

Returns the ASPEngineDelegate instance from StreamView, which exposes additional IASPEngine operations.

public ASPEngineDelegate getASPEngineDelegate()

`ASPEngineDelegate`

ASPEngineDelegate exposes selected IASPEngine operations through StreamView. Get an instance by calling StreamView.getASPEngineDelegate().

Available methods (same signatures as IASPEngine equivalents):

Method	Description
`registerASPEngineListener` / `unregisterASPEngineListener`	Connection status and engine errors
`registerStatisticsListener` / `unregisterStatisticsListener`	Performance statistics
`registerRequestSystemPermissionListener` / `unregisterRequestSystemPermissionListener`	System permission requests
`enableMouseMode(boolean enabled)`	Enable or disable mouse mode
`enableDesktopMode(boolean enabled)`	Enable or disable desktop mode
`setVideoProfile(int width, int height, int fps, IRemoteResult result)`	Set video resolution and frame rate
`sendKeyboardEvent(KeyEvent event)`	Send a key event (sync)
`sendMouseEvent(MotionEvent motionEvent)`	Send a mouse event from `MotionEvent` (sync)
`reconnect(String connectionToken)`	Reconnect after an exception
`setMediaStreamPlayer(MediaStreamPlayer player)`	Set a custom media engine
`setAlignStreamResolutionWithSurfaceSize(boolean aligned)`	Sync stream resolution to surface size
`mute(boolean muted)`	Mute or unmute audio
`enableStatistics(boolean enabled)`	Enable or disable statistics
`setToQualityFirst()`	Quality-first mode: high image quality, up to 30 fps
`setToFpsFirst()`	Smoothness-first mode: medium image quality, up to 60 fps
`setToCustomPicture(int fps, int quality)`	Custom mode: specify frame rate (0–60) and quality (0=lossless, 1=high, 2=medium, 3=normal, 4=auto)

Coming soon via ASPEngineDelegate:

Method	Description
`sendKeyboardEvent(KeyEvent event, IRemoteResult result)`	Send a key event with async result
`sendMouseEvent(MotionEvent motionEvent, IRemoteResult result)`	Send a mouse event with async result

Listeners

`IRemoteResult`

Receives the result of an asynchronous remote call.

`onSuccess()` — called when the remote call succeeds.

public void onSuccess()

Some cloud-side operations do not return a success response. If a response is received, the call is considered successful.

`onFailure(int errorCode, String errorMsg)` — called when the remote call fails.

public void onFailure(int errorCode, String errorMsg)

Parameter	Type	Description
`errorCode`	int	Error code.
`errorMsg`	String	Error message.

`onTimeout()` — called when the remote call times out.

public void onTimeout()

`IASPEngineListener`

Listens on streaming connection status and engine errors.

`onConnectionSuccess()` — connection established.

public void onConnectionSuccess()

`onConnectionFailure(int errorCode, String errorMsg)` — connection failed or an exception occurred during connection.

public void onConnectionFailure(int errorCode, String errorMsg)

Parameter	Type	Description
`errorCode`	int	Error code.
`errorMsg`	String	Error message.

`onEngineError(int errorCode, String errorMsg)` — an internal exception occurred (such as a decoding error or state error).

public void onEngineError(int errorCode, String errorMsg)

`onDisconnected(int reason)` — disconnected from the cloud computer.

public void onDisconnected(int reason)

Parameter	Type	Description
`reason`	int	Disconnect reason. When `reason == 2200`, the RTT timed out and the session was disconnected. Call `IASPEngine.reconnect()` to restore the connection.

`onReconnect()` — reconnected to the cloud computer.

public void onReconnect()

`IIMEListener`

Listens on IME focus state and UI position changes on the cloud.

This listener is coming soon.

`onIMEFocusUpdate(boolean hasFocus)` — an input field on the cloud gained or lost focus.

public void onIMEFocusUpdate(boolean hasFocus)

Parameter	Type	Description
`hasFocus`	boolean	`true`: an input field gained focus. `false`: an input field lost focus.

`onIMELocationUpdate(int x, int y)` — the position of the IME UI element changed.

public void onIMELocationUpdate(int x, int y)

Parameter	Type	Description
`x`	int	X-coordinate of the IME element on the cloud screen.
`y`	int	Y-coordinate of the IME element on the cloud screen.

`IAudioVolumeListener`

Listens on system volume changes on the cloud.

This listener is coming soon.

`onAudioVolumeUpdate(double volume)` — the system volume changed.

public void onAudioVolumeUpdate(double volume)

Parameter	Type	Description
`volume`	double	Current system volume on the cloud.

`IResolutionUpdateListener`

Listens on resolution changes of the video stream.

`onResolutionUpdate(int oldWidth, int oldHeight, int width, int height)` — the stream resolution changed.

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

Parameter	Type	Description
`oldWidth`	int	Previous resolution width. `0` before rendering starts.
`oldHeight`	int	Previous resolution height. `-1` before rendering starts.
`width`	int	New resolution width.
`height`	int	New resolution height.

`ICursorListener`

Listens on cursor changes on the cloud, including scheme and visibility.

`onCursorBitmapUpdate(int hotX, int hotY, Bitmap bitmap)` — the cursor scheme changed.

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

Parameter	Type	Description
`hotX`	int	X-coordinate of the cursor hotspot.
`hotY`	int	Y-coordinate of the cursor hotspot.
`bitmap`	Bitmap	Cursor bitmap.

`onCursorReset()` — the cursor was reset to default.

public void onCursorReset()

`onCursorHide()` — the cursor was hidden.

public void onCursorHide()

`onCursorMove(int x, int y)` — the cursor position changed.

public void onCursorMove(int x, int y)

Parameter	Type	Description
`x`	int	X-coordinate the cursor moved to.
`y`	int	Y-coordinate the cursor moved to.

`IOrientationUpdateListener`

Listens on screen orientation changes on the cloud.

`onOrientationUpdate(int oldOrientation, int newOrientation)` — the screen orientation changed.

public void onOrientationUpdate(int oldOrientation, int newOrientation)

Parameter	Type	Description
`oldOrientation`	int	Previous orientation.
`newOrientation`	int	New orientation.

`IStatisticsListener`

Listens on periodic performance and runtime statistics from ASPEngine.

`onStatisticsInfoUpdate(StatisticsInfo info)` — ASPEngine reports updated statistics. Only fires when enableStatistics(true) is set.

public void onStatisticsInfoUpdate(StatisticsInfo info)

`StatisticsInfo` fields:

class StatisticsInfo {
    public int mReceiveFps = 0;                      // Frames per second received on the client
    public int mRenderFps = 0;                       // Frames per second rendered on the client
    public double mDownstreamBandwithMBPerSecond = 0; // Downstream bandwidth (MB/s)
    public double mUpstreamBandwithMBPerSecond = 0;   // Upstream bandwidth (MB/s)
    public long mP2pFullLinkageLatencyMS = -1;        // End-to-end latency (ms); accurate only with specific guest OS apps
    public long mNetworkLatencyMS = -1;               // RTT latency (ms)
    public double mLostRate = 0;                      // Packet loss rate
    public long mServerRenderLatencyMS = -1;          // Server-side render latency (ms)
    public long mServerEncoderLatencyMS = -1;         // Server-side encoder latency (ms)
    public long mServerTotalLatencyMS = -1;           // Total server-side latency (ms)
}

`IRequestSystemPermissionListener`

Listens on requests from ASPEngine to apply for system permissions.

`onRequestSystemPermission(SystemPermission permission)` — ASPEngine needs a system permission.

public void onRequestSystemPermission(SystemPermission permission)

Parameter	Type	Description
`permission`	SystemPermission	The permission being requested.

`SystemPermission` enum:

enum SystemPermission {
    RECORD_AUDIO; // Microphone recording permission
}

`IExtDeviceListener`

Listens on connection and disconnection events for storage devices (USB disks) and webcams.

void onUDisksUpdate(List<UDiskItem> udisks);   // USB disk list changed
void onCamerasUpdate(List<CameraItem> cameras); // Camera list changed

Controlling a `UDiskItem`:

ConnectStatus getStatus(); // DISCONNECTED or CONNECTED
String getName();          // Device name
String getPath();          // Storage path on the cloud
void connect();            // Connect the device
void disConnect();         // Disconnect the device

Controlling a `CameraItem`:

ConnectStatus getStatus();               // DISCONNECTED or CONNECTED
String getName();                        // Device name
void connect();                          // Connect the device
void disConnect();                       // Disconnect the device
boolean isPreviewMirror();               // Whether preview mirroring is on
void setPreviewMirror(boolean mirror);   // Toggle preview mirroring

Custom media engine

By implementing the com.aliyun.wuying.aspsdk.aspengine.MediaStreamPlayer abstract class, you can replace the built-in media engine with your own. Custom engines can process:

Video streams — raw H.264 or H.265 encoded video
Adaptive graphic streams — ARGB_8888 bitmaps used as an alternative to video streams
Audio streams — Opus or PCM encoded audio data
Cursor data — cursor images for virtual mouse rendering (available only when virtual mouse mode is enabled)

Pass the custom engine to the SDK by calling IASPEngine.setMediaStreamPlayer(player) before starting the stream.

Stream type selection

The SDK selects the stream type based on which handlers your MediaStreamPlayer provides:

Handlers implemented	Stream type
`IVideoStreamHandler` + `IAdaptiveGraphicStreamHandler`	Mixed — SDK switches between video and image streams by scenario
`IVideoStreamHandler` only	Video streams only
`IAudioPlaybackStreamHandler` only	Image streams only

`MediaStreamPlayer`

An abstract class. Implement the onCreateXXXHandler methods to provide custom processing for each media type. Each method is called once per streaming session.

Methods to implement:

Method	Called by	Description
`initialize()`	SDK, once per session	Initialize the media engine. Return `ErrorCode.OK` on success.
`release()`	SDK, once per session	Release the media engine. Return `ErrorCode.OK` on success.
`enableStatistics(boolean enabled)`	SDK	Enable or disable performance statistics collection.
`onCreateVideoStreamHandler()`	SDK, once per session	Return an `IVideoStreamHandler` implementation, or `null` to skip video processing.
`onCreateAdaptiveGraphicStreamHandler()`	SDK, once per session	Return an `IAdaptiveGraphicStreamHandler` implementation, or `null` to skip image stream processing.
`onCreateAudioPlaybackStreamHandler()`	SDK, once per session	Return an `IAudioPlaybackStreamHandler` implementation, or `null` to skip audio processing.
`onCreateCursorBitmapHandler()`	SDK, once per session	Return an `ICursorBitmapHandler` implementation, or `null` to skip cursor data processing. Only active when virtual mouse mode is enabled.

Example — providing video and audio handlers:

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

@Override
protected IAdaptiveGraphicStreamHandler onCreateAdaptiveGraphicStreamHandler() {
    return null; // Not used in this implementation
}

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

@Override
protected ICursorBitmapHandler onCreateCursorBitmapHandler() {
    return null; // Not used in this implementation
}

`IVideoStreamHandler`

Processes video stream data. All methods are implemented by the application.

When the app moves to the background or a screen lock occurs, the rendering surface is destroyed and setVideoSurface is called with null. Handle this gracefully in your decoder and renderer.

Use setEventHandler to receive an EventHandler from the SDK. Send video rendering events through this handler to enable end-to-end latency tracking.

Example — reporting a rendered frame:

@Override
public void setEventHandler(EventHandler 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;
        // Notify the SDK that a frame was rendered; the SDK uses frameId for latency calculation
        mHandler.callback(event);
    }
}

Method	Description
`setEventHandler(EventHandler handler)`	Receives the SDK-provided `EventHandler`. Use it to report video rendering events.
`addVideoTrack(int trackId, VProfile profile)`	A video stream was created.
`setVideoSurface(int trackId, Surface surface)`	The rendering surface status changed. `surface` is `null` when the app is in the background.
`playVideo(int trackId)`	Video data is ready to play.
`removeVideoTrack(int trackId)`	The video stream was destroyed.
`pushVideoFrame(int trackId, VFrame frame)`	A new video frame was received.
`getVideoTracks()`	Returns a `HashMap<Integer, VProfile>` of all active video streams.
`release()`	All video streams are destroyed; clean up resources.

`IAudioPlaybackStreamHandler`

Processes audio stream data. All methods are implemented by the application.

Method	Description
`initAudio()`	An audio channel was created.
`deInitAudio()`	The audio channel was destroyed.
`startAudioPlayback()`	The cloud computer is about to push audio data.
`stopAudioPlayback()`	The cloud computer stopped pushing audio data.
`pushAudioPlaybackFrame(AFrame pbData)`	A new audio frame was received.
`updateAudioPlaybackVol(int volume)`	The cloud volume changed. Valid values: 0 to `USHRT_MAX`.
`updateAudioPlaybackMute(int mute)`	The cloud mute state changed. `1` = muted, `0` = unmuted.
`release()`	The audio channel is destroyed; clean up resources.

`IAdaptiveGraphicStreamHandler`

Processes image stream data. Image frames use the ARGB_8888 bitmap format. Only one image stream exists per session.

Method	Description
`setAdaptiveGraphicSurface(Surface surface)`	The image rendering surface status changed. `surface` is `null` when the app is in the background.
`invalidateAdaptiveGraphicSurface(Region region, byte[] buffer, BitmapFormat format)`	A new image frame was received. Draw `buffer` into `region`. Default format: `ARGB8888`.
`release()`	The image stream was destroyed; clean up resources.

`ICursorBitmapHandler`

Processes cursor data when virtual mouse mode is enabled.

Method	Description
`setCursorBitmap(CursorBitmap bitmap)`	The cursor scheme on the cloud changed.
`unsetCursorBitmap()`	The cursor on the cloud was hidden.
`setCursorPosition(float x, float y)`	The cursor position changed.
`release()`	The cloud disconnected and the cursor is no longer displayed; clean up resources.

Limitations

The following features are not yet available. They will be enabled in a future release.

Maven repository integration
fps parameter in setVideoProfile()
IME input support (setImePreedit, setImeCommit, registerIMEListener)
Keyboard lock modifiers (setKeyboardLockModifiers)
Asynchronous overloads for sendTouchEvent, sendKeyboardEvent, and sendMouseEvent
Audio volume listener (registerAudioVolumeListener)
Gamepad input (sendGamePadConnected, sendGamePadDisconnected, sendGamePadEvent)
Server cursor mode toggle (toggleServerCursorMode)

All documents, SDKs, and client programs of this platform are for restricted use by you or your organization. Do not share these resources with third parties or other organizations without prior consent from Alibaba Cloud.

How it works

Prerequisites

Integrate the SDK

Add the AAR file

Quickstart: Direct API (IASPEngine)

Quickstart: StreamView (enhanced UI component)

Additional setup

Activity code

API reference

IASPEngine.Builder

Builder()

build()

enableVDAgentCheck(boolean enabled)

enableRTC(boolean enabled)

IASPEngine

start(String connectionTicket, String caFilePath)

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

stop()

pause(IRemoteResult result)

resume(IRemoteResult result)

enableStatistics(boolean enable)

toggleServerCursorMode(boolean toggled)

setSurface(SurfaceView surfaceView)

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

reconnect(String connectionToken)

dispose()

enableMouseMode(boolean enabled)

enableDesktopMode(boolean enabled)

setMediaStreamPlayer(MediaStreamPlayer player)

setAlignStreamResolutionWithSurfaceSize(boolean aligned)

mute(boolean muted)

Sending input events

Registering listeners

Methods coming soon

IASPEngine.setLogAdapter(LoggerAdapter logAdapter) (static)

StreamView

Configuration parameters

start(Bundle configs)

stop()

dispose()

scaleStreamVideo(ScaleType scaleType)

enableDesktopMode(boolean enabled)

setASPEngineListener(IASPEngineListener listener)

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

sendKeyEvent(KeyEvent event)

simulateMouseClick(boolean leftButton)

getASPEngineDelegate()

ASPEngineDelegate

Listeners

IRemoteResult

IASPEngineListener

IIMEListener

IAudioVolumeListener

IResolutionUpdateListener

ICursorListener

IOrientationUpdateListener

IStatisticsListener

IRequestSystemPermissionListener

IExtDeviceListener

Custom media engine

Stream type selection

MediaStreamPlayer

IVideoStreamHandler

IAudioPlaybackStreamHandler

IAdaptiveGraphicStreamHandler

ICursorBitmapHandler

Limitations

Quickstart: Direct API (`IASPEngine`)

Quickstart: `StreamView` (enhanced UI component)

`IASPEngine.Builder`

`Builder()`

`build()`

`enableVDAgentCheck(boolean enabled)`

`enableRTC(boolean enabled)`

`IASPEngine`

`start(String connectionTicket, String caFilePath)`

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

`stop()`

`pause(IRemoteResult result)`

`resume(IRemoteResult result)`

`enableStatistics(boolean enable)`

`toggleServerCursorMode(boolean toggled)`

`setSurface(SurfaceView surfaceView)`

`setVideoProfile(int width, int height, int fps, IRemoteResult result)`

`reconnect(String connectionToken)`

`dispose()`

`enableMouseMode(boolean enabled)`

`enableDesktopMode(boolean enabled)`

`setMediaStreamPlayer(MediaStreamPlayer player)`

`setAlignStreamResolutionWithSurfaceSize(boolean aligned)`

`mute(boolean muted)`

`IASPEngine.setLogAdapter(LoggerAdapter logAdapter)` (static)

`StreamView`

`start(Bundle configs)`

`stop()`

`dispose()`

`scaleStreamVideo(ScaleType scaleType)`

`enableDesktopMode(boolean enabled)`

`setASPEngineListener(IASPEngineListener listener)`

`setVideoProfile(int width, int height, int fps, IRemoteResult result)`

`sendKeyEvent(KeyEvent event)`

`simulateMouseClick(boolean leftButton)`

`getASPEngineDelegate()`

`ASPEngineDelegate`

`IRemoteResult`

`IASPEngineListener`

`IIMEListener`

`IAudioVolumeListener`

`IResolutionUpdateListener`

`ICursorListener`

`IOrientationUpdateListener`

`IStatisticsListener`

`IRequestSystemPermissionListener`

`IExtDeviceListener`

`MediaStreamPlayer`

`IVideoStreamHandler`

`IAudioPlaybackStreamHandler`

`IAdaptiveGraphicStreamHandler`

`ICursorBitmapHandler`