Skip to main content

Connect to server

Scrcpy uses multiple Unix domain sockets to transmit video, audio, and control messages between client and server.

It supports two connection modes:

Reverse tunnel​

This is the default mode used by Scrcpy. The client listens on the Unix domain socket address, and the server connects to it.

Pros​

Because the client can listen on the socket address before the server starts, the server can connect to it immediately.

Cons​

The downside is that reverse tunnel may not be supported, for example with ADB over Wi-Fi on Android 8 and below, or with a custom transport.

In such cases, you can use the forward tunnel mode instead.

With Google ADB​

To setup the reverse tunnel manually with Google ADB, follow the steps below:

  1. Listen on a TCP port locally
  2. Run adb reverse add command to let Google ADB listen on the Unix domain socket address on device, and forward the connection to your TCP listener
  3. Start server using adb shell app_process command (described in previous page)
  4. Wait for incoming TCP connections. The number depends on the server options.

See server transport for more details.

With Tango​

Tango encapsulates the reverse tunnel feature into a callback-based API:

  1. Call reverse.add method to create a reverse tunnel.
  2. Start server using subprocess.spawn method.
  3. Wait for the correct amount of incoming connections.

With @yume-chan/adb-scrcpy​

The AdbScrcpyClient.start method uses reverse tunnels by default. It sets up the reverse tunnel and waits for the correct amount of connections automatically.

Forward tunnel​

This mode can be used as a fallback when reverse tunnel is not supported. In forward tunnel mode, the server listens on the Unix domain socket address, and the client creates multiple connections to it.

To tell Scrcpy server to use forward tunnel mode instead, add the tunnelForward: true option to your ScrcpyOptionsX_XX instance.

To make it easier to detect a success connection, Scrcpy server will write a single 0 byte in the first (usually video) socket. This behavior can be turned off using sendDummyByte: false option.

Pros​

Forward tunnel is always supported.

Cons​

Because the server needs some time to start and listen on the socket address, the client may not connect to it immediately. Usually, the client needs to continuously retry the connection until it succeeds.

With Google ADB​

Here are the steps to setup a forward tunnel and connect to it using Google ADB:

  1. Start server using adb shell app_process command (described in previous page)
  2. Run adb forward add command, to let Google ADB listen on a local TCP port, and forward the connections to the Unix domain socket address on device.
  3. Connect to the TCP port.
  4. Retry the connection until the correct amount of sockets are created.

Because local TCP sockets are handled by operating system and Google ADB server, the connection will always success, but it doesn't mean the connection has been forwarded to the remote address on device.

If the server is still starting, the connection will be closed without any data.

With Tango​

In Tango, the createSocket method can create sockets to the Unix domain socket address on device directly.

If the server has not been started and listen on the socket address, createSocket will throw an error.

You also need retry the connection until the correct amount of sockets are created.

With @yume-chan/adb-scrcpy​

When tunnelForward: true option is specified, AdbScrcpyClient automatically uses forward tunnel mode to connect to Scrcpy server.