URL Scheme Automation EN

URL Scheme Automation

中文

Screen Remote accepts navigation, session, device-management, and settings actions from external apps, AI, or MCP tools through the browsable screen-remote:// URL scheme. app/MainActivity.kt and app/deeplink/ own the entry contract. MainActivity uses singleTask, so both cold launches and an existing instance parse a new Intent.

Target selection and persistence boundary

• A session selector resolves in order to a case-sensitive session id, the first case-sensitive matching session name, or a valid host:port transient target. IPv6 endpoints require brackets and URL encoding.
• A scrcpy URL clones the saved session's effective profile configuration, overrides only fields explicitly supplied by the URL, and creates an in-memory runtime session. It does not modify the saved session or profile.
• A direct endpoint creates a transient TCP session. Management URLs can likewise use a saved session or a transient endpoint.
• A new-session URL only prefills the editor and still requires the user to save. A command-management URL only prefills the command and never executes it automatically.

Supported routes

Purpose	URL form
Sessions page	screen-remote://open/sessions
Settings page	`screen-remote://open/settings[/about
Add / edit session	screen-remote://session/new?..., screen-remote://session/edit/{selector}
Start remote control	screen-remote://session/{selector}/scrcpy?...
Open device management	`screen-remote://session/{selector}/manage/{device
File path / command prefill	Append an encoded path to the file route, or pass command= to the command route
Change a global setting	screen-remote://setting/{setting}/{value}
ADB / diagnostics / disconnect	screen-remote://adb/keys/generate, screen-remote://diagnostics/logs, screen-remote://remote/disconnect

New-session parameters include name, address, color, profileId, useProfileDefaults, comma-separated backupAddresses and groupIds, plus any remote-control parameters.

Remote-control and settings parameters

Remote-control URLs support:

maxSize, videoBitRate, maxFps, videoEncoder, videoDecoder, audio, audioBitRate, audioEncoder, audioDecoder, gameMode, compatibilityMode, fullScreen, floatingBall, hardwareDecoding, screenRotationPolicy, clipboard, turnScreenOff, powerOffOnClose, cleanupOnDisconnect, stayAwake, keepDeviceAwake, showTouches, ignoreVideoEncoderConstraints, displayId, newDisplayEnabled, newDisplay, virtualDisplaySystemDecorations, preserveVirtualDisplayContent, startApp, codecOptions, and tunnelMode. screenRotationPolicy accepts none, local, or target. startApp is intentionally the only app-launch control accepted in remote-control URLs; the shell password for app launch is not currently exposed in URL parameters and must be configured in the session editor.

Compatibility aliases are enableAudio, useFullScreen, showFloatingBall, enableHardwareDecoding, and clipboardSync. Parameter names are normalized case-insensitively to their canonical names; routes, selectors, and enum values remain case-sensitive. Boolean values accept on/true/1/yes and off/false/0/no. Enabling compatibilityMode always disables audio, while automatic clipboard synchronization continues to follow the clipboard toggle.

Mutable global settings are debugmode, activitylog, audiolog, videolog, controllog, eventlog, shelllog, managementlog, haptic, performancestats, autoupdate, updatechannel, theme, and language. Enum values are respectively stable|prerelease, system|light|dark, and auto|chinese|english.

Validation and diagnostics

• Scheme, host, path, and parameters use allowlists; URL authorities reject credentials, ports, and fragments.
• External callers must UTF-8 URL-encode path segments, endpoints, file paths, commands, and query values.
• An unsupported or invalid URL records an English warning and performs no partial action.
• Debug builds additionally expose a read-only diagnostics provider protected by the system android.permission.DUMP permission. It reports devices, session, sockets, codecs, logs, metrics, and a dynamic URL catalog. Release builds do not contain this provider.

Code and regression anchors

• app/deeplink/ScreenRemoteDeepLink.kt, ScrcpyUrlParameters.kt, UrlRuntimeSession.kt
• feature/session/ui/MainScreen.kt, feature/session/viewmodel/MainViewModel.kt
• ScreenRemoteDeepLinkTest, ScrcpyUrlParametersTest, UrlRuntimeSessionTest