Introducing a new way to review your PRs.

Read the announcement

genymobile / scrcpy

Display and control your Android device

View on GitHub

13 documents · Updated Nov 16, 2026

docs / client-server-bootstrap-and-adb-transport

Client-server bootstrap and ADB transport

Overview

The native bootstrap path is centered on app/…/server.c. sc_server_init() initializes the ADB executable state with sc_adb_init(), creates the stop condition and interruptor, clears the future video/audio/control sockets, and stores callbacks for connection failure, successful connection, and later disconnection. sc_server_start() then runs run_server() on the scrcpy-server thread.

run_server() first executes adb start-server through sc_adb_start_server() in app/…/adb.c, because later adb devices -l output is parsed rather than printed. Device selection is handled by sc_adb_select_device() in app/…/adb.c: it captures adb devices -l, parses it with sc_adb_parse_devices() from app/…/adb_parser.c, applies the selector requested by server->params (req_serial, USB-only, TCP/IP-only, $ANDROID_SERIAL, or all devices), rejects zero or multiple matches, and requires the selected state to be exactly device. Device type comes from sc_adb_device_get_type() in app/…/adb_device.c, which treats serials with : and mDNS names containing adb-tls-connect as TCP/IP, emulator-* as emulator, and the rest as USB.

TCP/IP setup is still orchestrated by app/…/server.c. If --tcpip=<addr> was provided, sc_server_configure_tcpip_known_address() appends :5555 if needed, optionally runs adb disconnect for the +addr form, then uses sc_adb_connect() to verify that adb connect output starts with connected or already connected. If --tcpip is requested without a destination, sc_server_configure_tcpip_unknown_address() either reuses an already-TCP/IP serial or calls sc_server_switch_to_tcpip(): it reads the WLAN address via sc_adb_get_device_ip()/sc_adb_parse_device_ip(), checks service.adb.tcp.port with adb shell getprop, runs adb tcpip 5555 when necessary, polls until the property reports the expected port, then reconnects by IP and port.

After a serial is fixed, push_server() in app/…/server.c resolves the server JAR path from SCRCPY_SERVER_PATH, the installed default, or the portable-local path, verifies it is a regular file, and pushes it to /data/local/tmp/scrcpy-server.jar with sc_adb_push(). Normal mirroring then creates a device socket name scrcpy_%08x from params->scid and opens an ADB tunnel with sc_adb_tunnel_open() in app/…/adb_tunnel.c.

Tunnel setup prefers adb reverse unless force_adb_forward is set. In reverse mode, enable_tunnel_reverse_any_port() runs adb reverse localabstract:<device_socket_name> tcp:<port>, then creates a local TCP listening socket on 127.0.0.1:<port> using net_socket()/net_listen_intr() from app/…/net.c and app/…/net_intr.c; if the local bind fails, it removes the reverse mapping and tries the next port in params->port_range. In forward mode, enable_tunnel_forward_any_port() runs adb forward tcp:<port> localabstract:<device_socket_name> across the same port range. The resulting struct sc_adb_tunnel records whether it is a forward tunnel, the local port, and, for reverse mode, the listening socket.

The Android server process is launched by execute_server() in app/…/server.c as adb -s <serial> shell CLASSPATH=/data/local/tmp/scrcpy-server.jar app_process / com.genymobile.scrcpy.Server <version> .... It serializes struct sc_server_params into key=value command arguments, includes tunnel_forward=true when the ADB tunnel is forward mode, and validates free-form string parameters against shell metacharacters because the command ultimately crosses ADB shell handling. The process is started with sc_adb_execute() and observed by sc_process_observer_init() from app/…/process.c; the observer invokes sc_server_on_terminated() if the process exits.

Socket acceptance differs by tunnel direction. In reverse mode, sc_server_connect_to() accepts video, audio, then control connections from the local listening socket with net_accept_intr(). In forward mode, the client actively connects to params->tunnel_host or localhost and params->tunnel_port or the selected ADB local port; the first connection goes through connect_to_server(), which retries up to 100 times and reads one byte after TCP connect to prove that the server behind the ADB tunnel is actually listening. Additional enabled streams open separate TCP connections to the same local forwarded port. Once stream sockets are established, the ADB tunnel is closed with sc_adb_tunnel_close(); the long-lived transport uses only the accepted/connected video, audio, and control sockets stored on struct sc_server.

The first enabled stream socket carries the fixed-size device information handshake. device_read_info() in app/…/server.c reads SC_DEVICE_NAME_FIELD_LENGTH bytes with net_recv_all_intr() and stores the NUL-terminated device name in server->info. After that, run_server() calls on_connected; the server thread then waits for sc_server_stop() to set server->stopped, signal the condition, and interrupt any in-flight ADB/process/socket operation through struct sc_intr.

Control-channel receiver setup is represented by app/…/receiver.c. sc_receiver_init() receives an already-established control socket, and sc_receiver_start() runs run_receiver() on a scrcpy-receiver thread. The receiver continuously reads raw bytes with net_recv(), deserializes one or more sc_device_msg messages, and dispatches clipboard updates to the SDL main thread, clipboard ACKs to receiver->acksync, and UHID output to receiver->uhid_devices. There is intentionally no sc_receiver_stop() in app/…/receiver.h; shutting down or closing the control socket makes net_recv() return and triggers the on_ended callback.

Disconnect handling has two layers. Server-process death is observed in app/…/server.c: sc_server_on_terminated() interrupts the current blocking operation and calls on_disconnected, so an early Android server exit can wake a pending accept/connect/read instead of hanging the bootstrap thread. UI-facing unexpected disconnect behavior is in app/…/disconnect.c: sc_disconnect_start() loads the disconnected icon on a worker thread, waits until a deadline unless sc_disconnect_interrupt() is called, and invokes on_timeout to request window closure when the grace period expires.

The low-level transport helpers are intentionally small. app/…/net.c wraps platform sockets, listen/accept/connect, recv/send, TCP_NODELAY, and interruption via shutdown() or close-on-interrupt wrappers on Windows/macOS. app/…/net_intr.c temporarily registers a socket in struct sc_intr before blocking network calls. app/…/process.c starts platform processes through sc_process_execute_p(), offers pipe reads, and provides a separate observer thread because the observer must notice process termination without reaping the process. app/…/process_intr.c similarly registers a process while reading from an ADB pipe. On Windows, app/…/command.c serializes argv into a correctly quoted CreateProcess() command line, which is part of the path used by platform process execution.

Coupling

  • If the server socket protocol changes, update both the Android server and the native handshake in app/…/server.c: device_read_info() assumes the first enabled stream delivers exactly SC_DEVICE_NAME_FIELD_LENGTH bytes immediately after connection, and connect_to_server() in forward mode consumes a one-byte readiness marker before normal stream use.
  • If the number or order of server-side sockets changes, update sc_server_connect_to() in app/…/server.c and the Android server together. The native client accepts/connects sockets in video, audio, control order and assigns the first enabled socket to the device-info handshake.
  • If tunnel naming or port semantics change, check app/…/server.c, app/…/adb_tunnel.c, and app/…/adb.c together. The native socket name is scrcpy_%08x, adb reverse maps localabstract:<name> to tcp:<port>, adb forward maps tcp:<port> to localabstract:<name>, and execute_server() must pass tunnel_forward=true when the Android side should listen instead of connect back.
  • If ADB device-list parsing changes, keep app/…/adb.c, app/…/adb_parser.c, and app/…/adb_device.c aligned. Selection depends on parser tolerance for daemon startup garbage, known ADB states, serials containing spaces, model extraction, and the USB/TCP/IP classification derived from serial syntax.
  • If adding free-form server parameters in app/…/server.c, validate them like crop, max_fps, camera_id, and codec option strings. The command is built as an argv array but crosses adb shell, and Windows process serialization in app/…/command.c does not make arbitrary shell characters safe for the device-side shell.
  • If stop or disconnect behavior changes, verify app/…/server.c, app/…/net_intr.c, app/…/process_intr.c, and app/…/intr.c together. Blocking ADB commands, pipe reads, accepts, connects, and device-info reads are only cancellable because the current process or socket is registered in struct sc_intr before the blocking call.
  • If the control socket ownership changes, update app/…/receiver.c and the server teardown in app/…/server.c. The receiver has no explicit stop API and relies on control-socket shutdown/close to break its net_recv() loop.

Risks

  • app/…/server.c and app/…/adb_tunnel.c: forward-mode startup is timing-sensitive. connect_to_server() may establish a TCP connection even when the Android server behind the ADB tunnel is not ready, so it reads one byte as a readiness probe; removing or reordering that byte would either break stream framing or make bootstrap falsely succeed against a not-yet-listening server.
  • app/…/adb.c and app/…/adb_parser.c: device discovery depends on parsing human-readable adb devices -l output into a fixed 64 KiB buffer. If ADB changes line formats, state names, or emits more output than expected, sc_adb_select_device() may fail to find a device or may reject a valid selection.
  • app/…/server.c: execute_server() has a fixed cmd[128] array and appends one entry for many optional parameters. Adding several server options without increasing or checking this bound can overrun the local argv array during bootstrap.
  • app/…/net.h and app/…/net.c: on Windows and macOS, net_interrupt() closes the socket to wake blocking accept()/recv(), and the comment notes a small handle-reuse race. Code that assumes net_interrupt() is a pure shutdown rather than a close can become platform-specific and fail during teardown.