Runtime Main Path

Runtime Main Path

中文 · Architecture index

This page provides the end-to-end reading path for a remote-control session. Session State and Events and Session Configuration and Connection Lifecycle own the detailed state model and configuration ownership rules.

Main path

flowchart TD
    A["SessionData"] --> B["ScrcpyOptions"]
    B --> C["SessionManager.start"]
    C --> D["Session"]
    D --> E["ConnectionLifecycle.connect"]
    E --> F["ADB candidate race and verification"]
    F --> M{"Compatibility mode?"}
    M -->|Yes| N["ADB screenshot stream and ADB input"]
    M -->|No| G["Clean old scrcpy resources"]
    G --> H["Prepare tunnel and push server"]
    H --> I["Start scrcpy server"]
    I --> J["Connect video → optional audio → control"]
    J --> K["Validate video dummy byte and read metadata"]
    K --> L["Create streams, health monitor, decoders and controller"]

Loading

SessionManager currently keeps one active Session. The session owns its configuration snapshot, ADB reference, runtime state, event queue, and monitoring bus. ConnectionLifecycle orchestrates one connect or disconnect operation under a mutex.

Connecting

1. SessionData.toScrcpyOptions() creates the runtime snapshot, which must contain at least one ConnectionCandidate.
2. SessionManager.start() stops any old session before creating a new Session.
3. ConnectionLifecycle races candidates and obtains a verified AdbConnection. The winning object becomes the device fact used by this run.
4. Old sockets, forwards, and the server for the previous SCID are cleaned before a new connection is prepared.
5. The attempt receives a new SCID and socket name. The lifecycle prepares either a DIRECT_ADB or ADB_FORWARD tunnel and makes the server asset available.
6. Any required remote codec detection must finish before the final server command reads the launch configuration.
7. The scrcpy server starts, then video, optional audio, and control sockets connect in strict protocol order.
8. The client validates the dummy byte on the video socket and fully reads device and media metadata. Audio codec id 0 lets the server explicitly disable audio.
9. Video and audio streams are created. The final negotiated result controls health monitoring, after which the client starts decoders, rendering, audio playback, and the controller.

Compatibility mode branches after ADB verification. It skips SCID, tunnel, scrcpy-server, sockets, metadata, MediaCodec, audio, and the scrcpy control channel. CompatibilityModeController opens the bundled dadb helper's JPEG screenshot stream, publishes the source dimensions and latest frame, and serializes ADB input commands for taps, swipes, keys, and text. Capture startup and interruption retry up to three consecutive failures with bounded delay; stopping closes the helper stream and capture job.

Socket order is an invariant

The scrcpy server assigns roles by accept() order, so the client must use:

audio enabled:  video -> audio -> control
audio disabled: video -> control

The sockets must never be connected concurrently. After video connects, the client must also avoid blocking the whole sequence before the remaining required sockets connect. ConnectionSocketManager implements this invariant and ConnectionSocketOrderTest protects it.

Levels of success

• ADB connected: only the device channel is available.
• Server started: the remote process is ready for socket setup.
• SessionState.Connected: all required sockets are connected and the video dummy byte is confirmed.
• Media usable: metadata must also succeed, streams must exist, and the corresponding decoder must start.
• Compatibility frame usable: ADB is connected and the first helper screenshot has arrived. SessionState.Connected alone does not remove the loading overlay in this mode.

Do not collapse these phases into one connected boolean. Management features may require only ADB; the remote screen requires the full scrcpy and media path.

Stop, failure, and reconnection

• User exit follows explicit cleanup: cancel pending reconnection, move the session to Idle, stop media and monitoring, disconnect scrcpy resources, and stop the session.
• A failed connection attempt cleans resources it has already created. Coroutine cancellation preserves cancellation semantics while completing necessary cleanup in a non-cancellable region.
• Transport, socket, or decoder failures may request reconnection. Events enter one session serially to prevent duplicate reconnect jobs.
• A fixed decoder size failure or server capture/encoding failure publishes a user-confirmation request instead of silently changing configuration. Approved recovery reconnects the current run through 1920 → 1080 → 720, with at most three attempts and without persisting maxSize; automatic reconnect pauses while confirmation is pending.
• ConnectionLifecycle.disconnect() stops monitoring, closes sockets and the shell stream, removes a forward when present, terminates the server for the current SCID, and clears the active connection snapshot.
• A healthy ADB connection may remain cached by the ADB layer. The ADB layer validates and removes failed connections; scrcpy cleanup does not automatically destroy the transport.

Code-reading anchors

Concern	Entry point
Active session	infrastructure/scrcpy/session/SessionManager.kt, Session.kt
Connection and cleanup orchestration	infrastructure/scrcpy/connection/ConnectionLifecycle.kt
ADB candidate race	infrastructure/adb/connection/AdbConnectionRace.kt
Socket order and dummy byte	infrastructure/scrcpy/connection/ConnectionSocketManager.kt
Metadata and stream creation	infrastructure/scrcpy/connection/ConnectionMetadataReader.kt
Event reduction	infrastructure/scrcpy/session/internal/SessionRuntimeEvents.kt
Compatibility capture and ADB input	infrastructure/scrcpy/client/CompatibilityModeController.kt

Regression anchors

• ConnectionSocketOrderTest: protocol connection order.
• AdbConnectionRacePolicyTest: candidate-race decisions.
• ConnectionFailureClassifierTest: closure signals and error classification.
• ScrcpyStreamProtocolTest and ScrcpyAudioPacketTest: media protocol boundaries.
• SessionCodecFallbackTest: codec fallback for the current run.
• CompatibilityCaptureSettingsTest, RemoteConnectionOverlayStateTest: compatibility capture policy and first-frame readiness.
• VideoCaptureRecoveryPolicyTest: user-confirmed temporary size tiers.