Scrcpy Service

Core Android service for managing screen mirroring connections and event handling

Overview

The Scrcpy class is the main Android service that manages the client-side screen mirroring functionality. It handles socket connections to the scrcpy server, manages video and audio decoders, and processes touch and key events.

Package: org.client.scrcpy

Extends: android.app.Service

Starting the Service

start()

Initializes and starts the scrcpy service with screen mirroring.

public void start(Surface surface, String serverAdr, int screenHeight, 
                  int screenWidth, int delay)

surface · Surface · required

The Android Surface to render video output

serverAdr · String · required

Server address in format “host:port” (e.g., “127.0.0.1:7008”)

screenHeight · int · required

Height of the display surface in pixels

screenWidth · int · required

Width of the display surface in pixels

delay · int · required

Network delay tolerance in milliseconds for frame dropping

Example:

Scrcpy scrcpy = new Scrcpy();
Surface surface = surfaceView.getHolder().getSurface();
scrcpy.start(surface, "127.0.0.1:7008", 1920, 1080, 100);

Touch Event Handling

touchevent()

Processes touch events and sends them to the remote device with coordinate transformation.

public boolean touchevent(MotionEvent touch_event, boolean landscape, 
                          int displayW, int displayH)

touch_event · MotionEvent · required

The Android MotionEvent to process

landscape · boolean · required

Whether the remote device is in landscape orientation

displayW · int · required

Current display width in pixels

displayH · int · required

Current display height in pixels

return · boolean

Returns true if the event was processed successfully

Supported Actions:

• ACTION_DOWN - First finger touch
• ACTION_UP - Last finger lift
• ACTION_MOVE - Touch movement (all fingers)
• ACTION_POINTER_DOWN - Additional finger touch
• ACTION_POINTER_UP - Additional finger lift

Example:

@Override
public boolean onTouchEvent(MotionEvent event) {
    if (scrcpy != null) {
        return scrcpy.touchevent(event, true, 1080, 1920);
    }
    return super.onTouchEvent(event);
}

Multi-touch Support:

The method handles multi-touch by iterating through all pointer indices for ACTION_MOVE events:

// From source (Scrcpy.java:163-170)
for (int i = 0; i < touch_event.getPointerCount(); i++) {
    int currentPointerId = touch_event.getPointerId(i);
    int x = (int) touch_event.getX(i);
    int y = (int) touch_event.getY(i);
    sendTouchEvent(touch_event.getAction(), touch_event.getButtonState(), 
                   (int) (x * realW / displayW), (int) (y * realH / displayH), 
                   currentPointerId);
}

Key Event Handling

sendKeyevent()

Sends a key event to the remote device.

public void sendKeyevent(int keycode)

keycode · int · required

Android KeyEvent keycode (e.g., KeyEvent.KEYCODE_BACK, KeyEvent.KEYCODE_HOME)

Example:

// Send back button
scrcpy.sendKeyevent(KeyEvent.KEYCODE_BACK);

// Send home button
scrcpy.sendKeyevent(KeyEvent.KEYCODE_HOME);

// Send volume up
scrcpy.sendKeyevent(KeyEvent.KEYCODE_VOLUME_UP);

Lifecycle Methods

pause()

Pauses video and audio decoding without disconnecting.

public void pause()

Example:

@Override
protected void onPause() {
    super.onPause();
    if (scrcpy != null) {
        scrcpy.pause();
    }
}

resume()

Resumes video and audio decoding after pause.

public void resume()

Example:

@Override
protected void onResume() {
    super.onResume();
    if (scrcpy != null) {
        scrcpy.resume();
    }
}

StopService()

Stops all decoders and terminates the service.

public void StopService()

Example:

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

ServiceCallbacks Interface

Implement this interface to receive service events.

public interface ServiceCallbacks {
    void loadNewRotation();
    void errorDisconnect();
}

setServiceCallbacks()

Registers a callback listener.

public void setServiceCallbacks(ServiceCallbacks callbacks)

callbacks · ServiceCallbacks · required

Implementation of the ServiceCallbacks interface

Callback Methods:

loadNewRotation · void

Called when the remote device rotation changes and a new surface is needed

errorDisconnect · void

Called when the connection is lost or an error occurs

Example:

scrcpy.setServiceCallbacks(new Scrcpy.ServiceCallbacks() {
    @Override
    public void loadNewRotation() {
        // Handle rotation change
        runOnUiThread(() -> {
            // Recreate surface with new dimensions
            updateSurfaceOrientation();
        });
    }
    
    @Override
    public void errorDisconnect() {
        // Handle disconnection
        runOnUiThread(() -> {
            Toast.makeText(context, "Connection lost", Toast.LENGTH_SHORT).show();
            finish();
        });
    }
});

Connection Information

get_remote_device_resolution()

Returns the remote device’s native resolution.

public int[] get_remote_device_resolution()

return · int[]

Array of two integers [width, height] representing the device resolution

Example:

int[] resolution = scrcpy.get_remote_device_resolution();
int width = resolution[0];
int height = resolution[1];
Log.d("Scrcpy", "Remote device: " + width + "x" + height);

check_socket_connection()

Checks if the socket connection is established.

public boolean check_socket_connection()

return · boolean

Returns true if connected, false otherwise

Example:

if (!scrcpy.check_socket_connection()) {
    Toast.makeText(this, "Not connected to device", Toast.LENGTH_SHORT).show();
}

Constants

LOCAL_IP · String

Default local IP address: "127.0.0.1"

LOCAL_FORWART_PORT · int

Default forwarding port: 7008

DEFAULT_ADB_PORT · int

Default ADB port: 5555

Event Data Format

Touch and key events are serialized as byte arrays before transmission:

Touch Event Format (20 bytes):

Bytes 0-3:   action (int)
Bytes 4-7:   buttonState (int)
Bytes 8-11:  x coordinate (int)
Bytes 12-15: y coordinate (int)
Bytes 16-19: pointerId (int)

Key Event Format (4 bytes):

Bytes 0-3: keycode (int)

See Also

• Video Decoder - Video stream decoding
• Audio Decoder - Audio stream decoding
• Event Controller - Server-side event handling