Skip to main content
Version: next

Options

Scrcpy protocol changes over time, and are usually not backward compatible. Tango is compatible with many versions of Scrcpy server, by providing a set of options classes for each server version (or range).

The options class serves two purposes:

  • It defines which server options are available (for you, the user)
  • It normalize the behavior between different server versions (for internal use)

It's important to use the correct options class for the server version you're using. Using an incorrect version almost always results in errors.

If the latest version of Scrcpy server doesn't have a matching options class, the last supported version can be tried. If it doesn't work, you may need to wait for an update.

With @yume-chan/scrcpy​

Tango supports all version between 1.15 and 3.1, by providing a set of options classes for each server version.

For example, ScrcpyOptions1_15 is the options class for server version 1.15, ScrcpyOptions1_15_1 for version 1.15.1, and ScrcpyOptions3_1 for version 3.1, and so on.

info

These options classes are fully tree-shakeable. When using a bundler/minifier, only code related to the version you're using will be included.

All options classes take a single object parameter for server options:

export class ScrcpyOptionsX_YY {
  constructor(init: Partial<ScrcpyOptionsX_YY.Init>);
}
import { ScrcpyOptions2_2 } from "@yume-chan/scrcpy";

const options = new ScrcpyOptions2_2({
  videoSource: "camera",
  // ...
});

Check the TypeScript definition files for available server options in each version.

Some part of the options class is stateful, so reuse an instance between multiple connections is not recommended. Don't do this unless you checked the source code to make sure only the stateless part is being used.

With @yume-chan/adb-scrcpy​

@yume-chan/adb-scrcpy needs to do some additional behavior normalizations, so it has its own options classes.

Similar to @yume-chan/scrcpy, there is an option class for each server version. The naming convention is the same as @yume-chan/scrcpy, but with an Adb prefix. For example, AdbScrcpyOptions2_1 is the options class for server version 2.1.

AdbScrcpyOptionsX_YY classes take the same server options parameter, and an optional client options object:

import type { AdbNoneProtocolSpawner } from "@yume-chan/adb";

export interface AdbScrcpyClientOptions {
  version?: string;
  spawner?: AdbNoneProtocolSpawner | undefined;
}

declare class AdbScrcpyOptionsX_YY extends ScrcpyOptionsX_YY {
  constructor(
    init: ScrcpyOptions1_15_1.Init,
    clientOptions?: AdbScrcpyClientOptions,
  );
}

AdbScrcpyClientOptions interface includes:

  • version: The server version to use. The default value matches the options class name. This option is rarely used, unless you are using a custom server binary with different version string.
  • spawner: A custom process spawner to start the server process. The default value is undefined, which uses adb.subprocess.noneProtocol. This option is rarely used, unless you have a different method (like SSH) to start processes on the device.
import { AdbScrcpyOptions2_1 } from "@yume-chan/adb-scrcpy";
import { ScrcpyOptions2_2 } from "@yume-chan/scrcpy";

const options = new AdbScrcpyOptions2_1({
  videoSource: "camera",
  // ...
});

List of server options (by version introduced)​

v1.15​

  • logLevel: Sets the logging level for the Scrcpy server
    • "debug" | "info" | "warn" | "error"(until 1.17)
    • "verbose" | "debug" | "info" | "warn" | "error"(since 1.18)
  • maxSize (number): Sets the maximum width and height of the video stream
  • maxFps (number): Sets the maximum frame rate for the video stream in frames per second
  • lockVideoOrientation: Locks the orientation of the video stream
    • "-1 | 0 | 1 | 2 | 3"(until 1.17)
    • "-2 | -1 | 0 | 1 | 2 | 3"(since 1.18)
  • tunnelForward (boolean): Use ADB forward tunnel instead of reverse tunnel
  • crop (string | ScrcpyCrop): Crops the video stream to a specific region
  • sendFrameMeta (boolean): Send presentation timestamps so that the client may record properly
  • control (boolean): Disables the control socket
  • displayId (number): Specifies which display to mirror
  • showTouches (boolean): Shows visual feedback for touches on the device screen
  • stayAwake (boolean): Prevents the device from sleeping while screen casting is active
  • codecOptions: Configures video encoding parameters for the selected codec
    • string | ScrcpyCodecOptions(until v1.17)
    • Deprecated, use videoCodecOptions instead(since v2.0)
  • bitRate: Sets the video bitrate for the stream in bits per second
    • number(until v1.17)
    • Deprecated, use videoBitRate instead(since v2.0)

v1.17​

  • encoderName: Specifies the name of the encoder to use for video encoding
    • string(until v1.17)
    • Deprecated, use videoEncoder instead(since v2.0)

v1.18​

  • powerOffOnClose (boolean): Automatically powers off the Android device when the scrcpy connection is closed

v1.21​

  • clipboardAutosync (boolean): Enables or disables automatic synchronization of clipboard content between device and client

v1.22​

  • downsizeOnError (boolean): Controls whether the server should downsize the video resolution when encountering initial encoding errors during startup
  • sendDeviceMeta (boolean): Controls whether the server should send device name and size at the start of the video stream
  • sendDummyByte (boolean): Controls whether the server should send a 0 byte at the start of the video stream to detect connection issues

v1.23​

  • cleanup (boolean): Controls whether the server should perform cleanup tasks on exit

v1.24​

  • powerOn (boolean): Controls whether the server should power on the device when starting streaming

v2.0​

  • scid (InstanceId | string | undefined): Specifies a session identifier for the Scrcpy server instance
  • videoCodec ("h264" | "h265" | "av1"): Use H.265 or AV1 video codecs
  • videoBitRate (number): Sets the video bitrate for the stream in bits per second
  • videoCodecOptions (CodecOptions | string | undefined): Configures video encoding parameters for the selected video codec
  • videoEncoder (string | undefined): Specifies the name of the encoder to use for video encoding
  • audio (boolean): Disables the audio socket
  • audioCodec: Specifies the audio codec to use by the server
    • "raw" | "opus" | "aac"(between v2.0 and v2.2)
    • "raw" | "opus" | "aac" | "flac"(since v2.3)
  • audioBitRate (number): Sets the audio bitrate for the stream in bits per second
  • audioCodecOptions (CodecOptions | string | undefined): Configures audio encoding parameters for the selected audio codec
  • audioEncoder (string | undefined): Specifies the name of the encoder to use for audio encoding
  • listEncoders (boolean): Lists available encoders on the device and exits
  • listDisplays (boolean): Lists available displays on the device and exits
  • sendCodecMeta (boolean): Controls whether codec metadata should be sent at the start of the video and audio streams

v2.1​

  • audioSource: Selects the audio source for capturing audio from the device
    • "output" | "mic"(between v2.1 and v2.5)
    • "output" | "mic" | "playback"(between v2.6 and v3.1)
    • "output" | "mic" | "playback" | "mic-unprocessed" | "mic-camcorder" | "mic-voice-recognition" | "mic-voice-communication" | "voice-call" | "voice-call-uplink" | "voice-call-downlink" | "voice-performance"(since v3.2)
  • video (boolean): Disables the video socket

v2.2​

  • videoSource ("display" | "camera"): Selects the video source for capturing video from the device
  • cameraId (string | undefined): Specifies the camera ID to use when videoSource is set to "camera"
  • cameraSize (string | undefined): Sets the camera capture size when videoSource is set to "camera"
  • cameraFacing ("front" | "back" | "external" | undefined): Specifies which camera facing direction to use when videoSource is set to "camera"
  • cameraAr (string | undefined): Sets the camera aspect ratio when videoSource is set to "camera"
  • cameraFps (number | undefined): Sets the camera capture frame rate when videoSource is set to "camera"
  • cameraHighSpeed (boolean): Controls whether the camera should operate in high-speed mode when videoSource is set to "camera"
  • listCameras (boolean): Lists available cameras on the device and exits
  • listCameraSizes (boolean): Lists available camera sizes for a specific camera and exits

v2.6​

  • audioDup (boolean): Controls whether to duplicate audio when capturing from the device

v3.0​

  • captureOrientation (CaptureOrientation | string | undefined): Controls the orientation for video capture
  • angle (number): Sets the rotation angle of the video stream in degrees
  • screenOffTimeout (number | undefined): Controls how long the device screen should remain on after the scrcpy connection is established
  • listApps (boolean): Lists installed applications on the device and exits
  • newDisplay (NewDisplay | string | undefined): Creates a new virtual display for video streaming
  • vdSystemDecorations (boolean): Controls whether the virtual display should include system decorations

v3.1​

  • vdDestroyContent (boolean): Controls whether the virtual display content is destroyed when the connection is closed

v3.2​

  • displayImePolicy ("local" | "fallback" | "hide" | undefined): Controls the policy for displaying the Input Method Editor (IME) during screen mirroring

List of server options (by category)​

Core Functionality​

  • control (boolean): Disables the control socket
  • scid (InstanceId | string | undefined): Specifies a session identifier for the Scrcpy server instance

Physical Display​

  • displayId (number): Specifies which display to mirror
  • maxSize (number): Sets the maximum width and height of the video stream
  • maxFps (number): Sets the maximum frame rate for the video stream in frames per second
  • sendFrameMeta (boolean)(since v1.15): Send presentation timestamps so that the client may record properly
  • sendDeviceMeta (boolean)(since v1.22): Controls whether the server should send device name and size at the start of the video stream
  • sendCodecMeta (boolean)(since v2.0): Controls whether codec metadata should be sent at the start of the video and audio streams

Display Orientation & Rotation​

  • lockVideoOrientation: Locks the orientation of the video stream
    • "-1 | 0 | 1 | 2 | 3"(until 1.17)
    • "-2 | -1 | 0 | 1 | 2 | 3"(between 1.18 and 3.0)
    • Deprecated, use captureOrientation instead(since v3.0)
  • captureOrientation (CaptureOrientation | string | undefined)(since v3.0): Controls the orientation for video capture
  • angle (number)(since v3.0): Sets the rotation angle of the video stream in degrees

Camera​

  • videoSource ("display" | "camera")(since v2.2): Selects the video source for capturing video from the device
  • cameraId (string | undefined)(since v2.2): Specifies the camera ID to use when videoSource is set to "camera"
  • cameraSize (string | undefined)(since v2.2): Sets the camera capture size when videoSource is set to "camera"
  • cameraFacing ("front" | "back" | "external" | undefined)(since v2.2): Specifies which camera facing direction to use when videoSource is set to "camera"
  • cameraAr (string | undefined)(since v2.2): Sets the camera aspect ratio when videoSource is set to "camera"
  • cameraFps (number | undefined)(since v2.2): Sets the camera capture frame rate when videoSource is set to "camera"
  • cameraHighSpeed (boolean)(since v2.2): Controls whether the camera should operate in high-speed mode when videoSource is set to "camera"
  • listCameras (boolean)(since v2.2): Lists available cameras on the device and exits
  • listCameraSizes (boolean)(since v2.2): Lists available camera sizes for a specific camera and exits

Virtual Display​

  • newDisplay (NewDisplay | string | undefined)(since v3.0): Creates a new virtual display for video streaming
  • vdSystemDecorations (boolean)(since v3.0): Controls whether the virtual display should include system decorations
  • vdDestroyContent (boolean)(since v3.1): Controls whether the virtual display content is destroyed when the connection is closed
  • displayImePolicy ("local" | "fallback" | "hide" | undefined)(since v3.2): Controls the policy for displaying the Input Method Editor (IME) during screen mirroring

Video Processing​

  • videoCodec ("h264" | "h265" | "av1")(since v2.0): Use H.265 or AV1 video codecs
  • videoBitRate (number)(since v2.0): Sets the video bitrate for the stream in bits per second
  • videoCodecOptions (CodecOptions | string | undefined)(since v2.0): Configures video encoding parameters for the selected video codec
  • videoEncoder (string | undefined)(since v2.0): Specifies the name of the encoder to use for video encoding
  • video (boolean)(since v2.1): Disables the video socket

Audio​

  • audio (boolean)(since v2.0): Disables the audio socket
  • audioCodec: Specifies the audio codec to use by the server
    • "raw" | "opus" | "aac"(between v2.0 and v2.2)
    • "raw" | "opus" | "aac" | "flac"(since v2.3)
  • audioBitRate (number)(since v2.0): Sets the audio bitrate for the stream in bits per second
  • audioCodecOptions (CodecOptions | string | undefined)(since v2.0): Configures audio encoding parameters for the selected audio codec
  • audioEncoder (string | undefined)(since v2.0): Specifies the name of the encoder to use for audio encoding
  • audioSource: Selects the audio source for capturing audio from the device
    • "output" | "mic"(between v2.1 and v2.5)
    • "output" | "mic" | "playback"(between v2.6 and v3.1)
    • "output" | "mic" | "playback" | "mic-unprocessed" | "mic-camcorder" | "mic-voice-recognition" | "mic-voice-communication" | "voice-call" | "voice-call-uplink" | "voice-call-downlink" | "voice-performance"(since v3.2)
  • audioDup (boolean)(since v2.6): Controls whether to duplicate audio when capturing from the device

Device Controls​

  • showTouches (boolean): Shows visual feedback for touches on the device screen
  • stayAwake (boolean): Prevents the device from sleeping while screen casting is active
  • powerOffOnClose (boolean)(since v1.18): Automatically powers off the Android device when the scrcpy connection is closed
  • powerOn (boolean)(since v1.24): Controls whether the server should power on the device when starting streaming
  • screenOffTimeout (number | undefined)(since v3.0): Controls how long the device screen should remain on after the scrcpy connection is established

Data Management​

  • crop (string | ScrcpyCrop): Crops the video stream to a specific region
  • clipboardAutosync (boolean)(since v1.21): Enables or disables automatic synchronization of clipboard content between device and client

Network & Connection​

  • tunnelForward (boolean): Use ADB forward tunnel instead of reverse tunnel
  • sendDummyByte (boolean)(since v1.22): Controls whether the server should send a 0 byte at the start of the video stream to detect connection issues

Encoding & Quality​

  • bitRate: Sets the video bitrate for the stream in bits per second
    • number(between v1.15 and v1.17)
    • Deprecated, use videoBitRate instead(since v2.0)
  • codecOptions: Configures video encoding parameters for the selected codec
    • string | ScrcpyCodecOptions(between v1.15 and v1.17)
    • Deprecated, use videoCodecOptions instead(since v2.0)
  • encoderName: Specifies the name of the encoder to use for video encoding
    • string(between v1.17 and v1.17)
    • Deprecated, use videoEncoder instead(since v2.0)

Error Handling & Performance​

  • downsizeOnError (boolean)(since v1.22): Controls whether the server should downsize the video resolution when encountering initial encoding errors during startup

System & Cleanup​

  • cleanup (boolean)(since v1.23): Controls whether the server should perform cleanup tasks on exit

Discovery & Debugging​

  • listEncoders (boolean)(since v2.0): Lists available encoders on the device and exits
  • listDisplays (boolean)(since v2.0): Lists available displays on the device and exits
  • listApps (boolean)(since v3.0): Lists installed applications on the device and exits

Foundational Concepts​

  • ScrcpyOptionValue: Interface for values that can be converted to scrcpy option strings
  • logLevel: Sets the logging level for the Scrcpy server
    • "debug" | "info" | "warn" | "error"(until 1.17)
    • "verbose" | "debug" | "info" | "warn" | "error"(since 1.18)