Scrcpy Server Integration and Upgrade

scrcpy Server Integration and Upgrade

中文

Last updated: 2026-07-22

Current baseline

Screen Remote currently bundles the official scrcpy server 4.1. app/build.gradle.kts is the single source of truth for version, download URL, asset path, and SHA-256:

• scrcpyServerVersion = "4.1"
• Asset: app/src/main/assets/scrcpy-server.jar
• Pre-build verification: :app:verifyScrcpyServerVersion
• Explicit update task: :app:updateScrcpyServer

The wiki does not duplicate the exact hash, which could drift from Gradle.

Current client protocol assumptions

• Server arguments explicitly enable send_device_meta=true and send_stream_meta=true.
• scrcpy assigns socket roles by accept() order and has no client role handshake.
• The client establishes video, optional audio, and control channels strictly and sequentially, never concurrently.
• All required channels and the video dummy byte must be ready before the connection set is exposed upstream.
• Fixed-size metadata uses complete reads; one read is never assumed to fill a header.
• Video and audio negotiate independently. An audio codec ID of zero may disable audio at runtime.
• Negotiated codecs and dimensions are runtime facts and do not overwrite user preferences.
• Remote display power is changed through the SET_DISPLAY_POWER control message, not an obsolete server startup option.

Key implementation boundaries

Boundary	Current implementation
Server arguments and startup	infrastructure/scrcpy/connection/internal/ServerSetup.kt
SCID, forwarding, and sockets	infrastructure/scrcpy/connection/
Video/audio metadata	ConnectionMetadataReader.kt and infrastructure/scrcpy/stream/
Control protocol	infrastructure/scrcpy/protocol/ScrcpyProtocol.kt
Control writes	infrastructure/scrcpy/controller/ScrcpyControllerTransport.kt
Server asset and verification	app/build.gradle.kts

Upgrade workflow

1. Review upstream server protocol changes first; desktop client UI changes are not a substitute for protocol review.
2. Update scrcpyServerVersion, SHA-256, and affected client protocol implementation together.
3. Run ./gradlew :app:updateScrcpyServer to download and verify the asset through the build task.
4. Verify server arguments, socket count and order, dummy byte, metadata, packet formats, and control messages.
5. Run protocol and socket-order tests, then the complete unit suite and debug build.
6. Validate startup, video, optional audio, control, and cleanup on a real device through at least one of USB, TCP, or Wireless Debugging.

Regression anchors

./gradlew testDebugUnitTest --tests '*ConnectionSocketOrderTest'
./gradlew testDebugUnitTest --tests '*ScrcpyStreamProtocolTest'
./gradlew :app:verifyScrcpyServerVersion
./gradlew assembleDebug

When server interfaces, metadata, or control protocol change, add or update the corresponding focused tests as well.