SCRCPY(1)

📦
version 5.0.1 · 6 versions
, in arch rolling, nixpkgs unstable

✨ scrcpy — General Commands Manual ✨

bestie. sit down. this is the scrcpy(1) page and it's about to change your whole life. 💅

🎀 NAME

scrcpy — display and control your Android device. that's the whole thing. that's the pitch. 🫶

🌈 SYNOPSIS

scrcpy [options]

🦋 DESCRIPTION

scrcpy gives you display and control of Android devices connected over USB (or over TCP/IP). and the iconic part? it does not require any root access. no rooting, no unlocking, no drama. we love a low-maintenance queen 👑

💅 OPTIONS 💅

okay this is the long part, but stay with me, every single one matters 🍓

  • --always-on-top — makes the scrcpy window always on top (above other windows). main character energy, it refuses to be covered 💁‍♀️
  • --angle degrees — rotates the video content by a custom angle, in degrees (clockwise).
  • --audio-bit-rate value — encodes the audio at the given bit rate, expressed in bits/s. unit suffixes are supported: 'K' (x1000) and 'M' (x1000000). default is 128K (128000).
  • --audio-buffer ms — configures the audio buffering delay (in milliseconds). lower values decrease the latency, but increase the likelihood of buffer underrun (which causes audio glitches 😭). default is 50.
  • --audio-codec name — selects an audio codec (opus, aac, flac or raw). default is opus.
  • --audio-codec-options key[:type]=value[,...] — sets a list of comma-separated key:type=value options for the device audio encoder. the possible values for 'type' are 'int' (default), 'long', 'float' and 'string'. the list of possible codec options lives in the Android documentation: https://d.android.com/reference/android/media/MediaFormat
  • --audio-dup — duplicates audio (captures it and keeps it playing on the device). this feature is only available with --audio-source=playback.
  • --audio-encoder name — uses a specific MediaCodec audio encoder (depending on the codec provided by --audio-codec). the available encoders can be listed by --list-encoders.
  • --audio-source source — selects the audio source. possible values are:
    • "output": forwards the whole audio output, and disables playback on the device.
    • "playback": captures the audio playback (Android apps can opt-out, so the whole output is not necessarily captured).
    • "mic": captures the microphone.
    • "mic-unprocessed": captures the microphone unprocessed (raw) sound.
    • "mic-camcorder": captures the microphone tuned for video recording, with the same orientation as the camera if available.
    • "mic-voice-recognition": captures the microphone tuned for voice recognition.
    • "mic-voice-communication": captures the microphone tuned for voice communications (it will for instance take advantage of echo cancellation or automatic gain control if available).
    • "voice-call": captures voice call.
    • "voice-call-uplink": captures voice call uplink only.
    • "voice-call-downlink": captures voice call downlink only.
    • "voice-performance": captures audio meant to be processed for live performance (karaoke), includes both the microphone and the device playback.

default is output.

  • --audio-output-buffer ms — configures the size of the SDL audio output buffer (in milliseconds). do not change this setting unless you have a good reason. default is 10.
  • -b, --video-bit-rate value — encodes the video at the given bit rate, expressed in bits/s. unit suffixes are supported: 'K' (x1000) and 'M' (x1000000). default is 8M (8000000).
  • --background-color hexcolor — sets the background color, encoded as a hexadecimal color code (#RGB or #RRGGBB). default is #222 (dark gray).
  • --camera-ar ar — selects the camera size by its aspect ratio (+/- 10%). possible values are "sensor" (use the camera sensor aspect ratio), "num:den" (e.g. "4:3") and "value" (e.g. "1.6").
  • --camera-facing facing — selects the device camera by its facing direction. possible values are "front", "back" and "external".
  • --camera-fps fps — specifies the camera capture frame rate. if not specified, Android's default frame rate (30 fps) is used.
  • --camera-high-speed — enables high-speed camera capture mode. this mode is restricted to specific resolutions and frame rates, listed by --list-camera-sizes.
  • --camera-id id — specifies the device camera id to mirror. the available camera ids can be listed by --list-cameras.
  • --camera-size widthxheight — specifies an explicit camera capture size.
  • --camera-torch — turns on the camera torch when the camera starts. 🔥 literally.
  • --camera-zoom zoom — specifies the camera zoom initial value.
  • --capture-orientation value — possible values are 0, 90, 180, 270, flip0, flip90, flip180 and flip270, possibly prefixed by '@'. the number represents the clockwise rotation in degrees; the "flip" keyword applies a horizontal flip before the rotation. if a leading '@' is passed (@90) for display capture, then the rotation is locked, and is relative to the natural device orientation. if '@' is passed alone, then the rotation is locked to the initial device orientation. default is 0.
  • --crop width:height:x:y — crops the device screen on the server. the values are expressed in the device natural orientation (typically, portrait for a phone, landscape for a tablet).
  • -d, --select-usb — uses the USB device (if there is exactly one, like adb -d). also see -e (--select-tcpip).
  • --disable-screensaver — disables the screensaver while scrcpy is running.
  • --display-id id — specifies the device display id to mirror. the available display ids can be listed by --list-displays. default is 0.
  • --display-ime-policy value — sets the policy for selecting where the IME should be displayed. possible values are "local", "fallback" and "hide":
    • "local" means that the IME should appear on the local display.
    • "fallback" means that the IME should appear on a fallback display (the default display).
    • "hide" means that the IME should be hidden.

by default, the IME policy is left unchanged.

  • --display-orientation value — sets the initial display orientation. possible values are 0, 90, 180, 270, flip0, flip90, flip180 and flip270. the number represents the clockwise rotation in degrees; the "flip" keyword applies a horizontal flip before the rotation. default is 0.
  • -e, --select-tcpip — uses the TCP/IP device (if there is exactly one, like adb -e). also see -d (--select-usb).
  • -f, --fullscreen — starts in fullscreen. 🌸
  • --force-adb-forward — does not attempt to use "adb reverse" to connect to the device.
  • -G — same as --gamepad=uhid, or --keyboard=aoa if --otg is set.
  • --gamepad mode — selects how to send gamepad inputs to the device. possible values are "disabled", "uhid" and "aoa":
    • "disabled" does not send gamepad inputs to the device.
    • "uhid" simulates physical HID gamepads using the Linux HID kernel module on the device.
    • "aoa" simulates physical HID gamepads using the AOAv2 protocol. it may only work over USB.

also see --keyboard and --mouse.

  • -h, --help — prints this help.
  • --hwdec mode — configures hardware video decoding on the computer. possible values are "auto" (the first available hardware decoder, software decoding otherwise), "disabled" (always use software decoding), "vaapi" (Linux only), "d3d11va" (Windows only) and "videotoolbox" (macOS only). default is "auto".
  • --ignore-video-encoder-constraints — does not consider video encoder capabilities. this is useful if the reported capabilities are incorrect. it may help to force a value for --min-size-alignment.
  • -K — same as --keyboard=uhid, or --keyboard=aoa if --otg is set.
  • --keep-active — keeps the screen on by simulating user activity. 💀 your phone stays awake, no cap.
  • --keyboard mode — selects how to send keyboard inputs to the device. possible values are "disabled", "sdk", "uhid" and "aoa":
    • "disabled" does not send keyboard inputs to the device.
    • "sdk" uses the Android system API to deliver keyboard events to applications.
    • "uhid" simulates a physical HID keyboard using the Linux HID kernel module on the device.
    • "aoa" simulates a physical HID keyboard using the AOAv2 protocol. it may only work over USB.

for "uhid" and "aoa", the keyboard layout must be configured (once and for all) on the device, via Settings -> System -> Languages and input -> Physical keyboard. this settings page can be started directly using the shortcut MOD+k (except in OTG mode), or by executing:

adb shell am start -a android.settings.HARD_KEYBOARD_SETTINGS

this option is only available when the HID keyboard is enabled (or a physical keyboard is connected). also see --mouse and --gamepad.

  • --kill-adb-on-close — kills adb when scrcpy terminates.
  • --legacy-paste — injects computer clipboard text as a sequence of key events on Ctrl+v (like MOD+Shift+v). this is a workaround for some devices not behaving as expected when setting the device clipboard programmatically.
  • --list-apps — lists Android apps installed on the device.
  • --list-camera-sizes — lists the valid camera capture sizes.
  • --list-cameras — lists cameras available on the device.
  • --list-encoders — lists video and audio encoders available on the device.
  • --list-displays — lists displays available on the device.
  • -m, --max-size value — limits both the width and height of the video. for display mirroring, the other dimension is computed so that the device aspect ratio is preserved (except for flex displays). for camera mirroring, the value is used to select the camera source size instead. default is 0 (unlimited).
  • -M — same as --mouse=uhid, or --mouse=aoa if --otg is set.
  • --max-fps value — limits the framerate of screen capture (officially supported since Android 10, but may work on earlier versions).
  • --min-size-alignment alignment — configures the minimum video size alignment. this is a power-of-2 value (1, 2, 4, 8 or 16) that the video width and height must be multiples of.

...and the alignment it actually ends up using is the maximum of that value and whatever the video codec insists on. So like, it's a floor, not a boss. 💅

Default is 1.

  • --mouse mode — picks how your mouse inputs get yeeted over to the device. the options are "disabled", "sdk", "uhid" and "aoa", and here's the tea on each:
    • "disabled" — mouse inputs just… don't get sent. ghosted. ✨
    • "sdk" — uses the Android system API to deliver mouse events to applications.
    • "uhid" — simulates a physical HID mouse using the Linux HID kernel module on the device.
    • "aoa" — simulates a physical mouse using the AOAv2 protocol. heads up: it may only work over USB. 🫶

When you're in "uhid" or "aoa" mode, your computer mouse gets captured so it can control the device directly (this is called relative mouse mode, iykyk).

To escape, press LAlt, LSuper or RSuper — that toggles the capture mode and hands the mouse back to your computer. saving you from the mouse-trap era. 😭

Also go peek at --keyboard and --gamepad while you're here.

  • --mouse-bind xxxx[:xxxx] — sets up the bindings for your secondary clicks, i.e. which click does what.

The argument has to be one or two sequences (separated by ':') of exactly 4 characters, one for each secondary click, in this order: right click, middle click, 4th click, 5th click. fr fr, exactly four.

The first sequence = the primary bindings, used when a mouse button is pressed alone. The second sequence = the secondary bindings, used when a mouse button is pressed while Shift is held. combo move. 💅

If you skip the second sequence entirely, it just mirrors the first one. lazy but valid.

Every character has to be one of these iconic lil guys:

  • '+' — forward the click to the device
  • '-' — ignore the click
  • 'b' — trigger shortcut BACK (or turn the screen on if it's off)
  • 'h' — trigger shortcut HOME
  • 's' — trigger shortcut APP_SWITCH
  • 'n' — trigger shortcut "expand notification panel"

Default is 'bhsn:++++' for SDK mouse, and '++++:bhsn' for AOA and UHID. note how they're like, exact opposites. obsessed. 🦋

  • -n, --no-control — disables device control, so you're just mirroring the device in read-only mode. look, don't touch. 👀
  • -N, --no-playback — kills video and audio playback on the computer. it's literally equivalent to passing --no-video-playback --no-audio-playback.
  • --new-display[=[widthxheight][/dpi]] — spins up a whole new display with the resolution and density you specify. if you don't provide them, they default to the main display's dimensions and DPI.

Examples, because examples ate:

--new-display=1920x1080
--new-display=1920x1080/420
--new-display         # main display size and density
--new-display=/240    # main display size and 240 dpi
  • --no-audio — disables audio forwarding. silence. 🤫
  • --no-audio-playback — disables audio playback on the computer (the audio still gets forwarded, it's just not played here).
  • --no-cleanup — so by default, scrcpy removes the server binary from the device and restores the device state (show touches, stay awake and power mode) on exit. this option turns all that cleanup off. leaving your mess behind, main character energy. 💅
  • --no-clipboard-autosync — by default scrcpy automatically syncs the computer clipboard to the device clipboard before injecting Ctrl+v, and syncs the device clipboard to the computer clipboard whenever it changes. this option disables that automatic synchronization. no more surprise pastes. 🙈
  • --no-downsize-on-error — by default, on a MediaCodec error, scrcpy automatically tries again with a lower definition. this option disables that behavior. no plan B. 💀
  • --no-key-repeat — do not forward repeated key events when a key is held down. hold it and nothing spams. ✨
  • --no-mipmaps — if the renderer is OpenGL 3.0+ or OpenGL ES 2.0+, mipmaps get generated automatically to improve downscaling quality. this option disables the generation of mipmaps.
  • --no-mouse-hover — do not forward mouse hover events (that's mouse motion with no clicks). the mouse just vibes, unannounced.
  • --no-power-on — do not power on the device on start. let it sleep. 😴
  • --no-terminal-title — disables terminal title updates. your terminal tab stays exactly as it was.
  • --no-vd-destroy-content — disables the virtual display "destroy content on removal" flag.

With this option, when the virtual display is closed, the running apps are moved to the main display rather than being destroyed. rescue mission. 🫶

  • --no-vd-system-decorations — disables the virtual display system decorations flag.
  • --no-video — disables video forwarding. audio only era. 🎀
  • --no-video-playback — disables video playback on the computer.
  • --no-window — disables the scrcpy window. implies --no-video-playback. the window said "not me participating today". 🙈
  • --no-window-aspect-ratio-lock — disables the window aspect ratio lock. resize it into whatever shape you want, chaos permitted. 💅
  • --orientation value — literally the same as passing --display-orientation=value --record-orientation=value. two birds, one flag. 🦋
  • --otg — run in OTG mode: simulate a physical keyboard and mouse, as if the computer keyboard and mouse were plugged directly into the device via an OTG cable.

in this mode, adb (USB debugging) is not necessary, and mirroring is disabled. icon behavior honestly.

LAlt, LSuper or RSuper toggle the mouse capture mode, giving control of the mouse back to the computer.

keyboard and mouse can be disabled separately using --keyboard=disabled and --mouse=disabled.

it may only work over USB. ⚠️

See --keyboard, --mouse and --gamepad.

  • -p, --port port[:port] — set the TCP port (or range) that the client listens on.

Default is 27183:27199.

  • --pause-on-exit[=mode] — configures pause on exit. possible values are "true" (always pause on exit), "false" (never pause on exit) and "if-error" (pause only if an error occurred).

This is useful to prevent the terminal window from automatically closing, so that error messages can be read. bless. 🫶

Default is "false".

Passing the option with no argument is equivalent to passing "true".

  • --power-off-on-close — turn the device screen off when closing scrcpy. leaving the device how you'd want to find it. 💅
  • --prefer-text — inject alpha characters and space as text events instead of key events.

This avoids issues when combining multiple keys to enter special characters, but it breaks the expected behavior of alpha keys in games (typically WASD). pick your fighter. 😭

  • --print-fps — starts the FPS counter, printing framerate logs to the console. you can start or stop it at any time with MOD+i.
  • --push-target path — sets the target directory for pushing files to the device via drag & drop. it's passed as-is to adb push.

Default is "/sdcard/Download/".

  • -r, --record file — record the screen to a file.

The format is determined by the --record-format option if set, or by the file extension. iykyk by filename. 🎀

  • --raw-key-events — inject key events for all input keys, and ignore text events.
  • --record-format format — force the recording format. valid formats are mp4, mkv, m4a, mka, opus, aac, flac or wav.
  • --record-orientation value — set the record orientation.

Possible values are 0, 90, 180 and 270. the number represents the clockwise rotation in degrees. 🔄

Default is 0.

  • --render-driver name — requests SDL to use the given render driver (this is just a hint, so no promises).

Supported names are currently "direct3d", "opengl", "opengles2", "opengles", "metal" and "software".

More deets at <https://wiki.libsdl.org/SDL_HINT_RENDER_DRIVER> — go read, bestie.

  • --render-fit mode — sets the render-fit mode, which configures how the rendering fits the window.

Possible values are "letterbox", "stretched" and "unscaled":

  • "letterbox": preserve the aspect ratio and fit the window as best as possible (black bars are added either at the top and bottom or at the sides if needed).
  • "stretched": fit the window without preserving the aspect ratio.
  • "unscaled": render the display without scaling.

Default is "letterbox", unless --flex-display is set, in which case it is "unscaled". plot twist. ✨

  • --require-audio — by default, scrcpy mirrors only the video if audio capture fails on the device. this option makes scrcpy fail if audio is enabled but does not work. all or nothing, periodt.
  • -s, --serial number — the device serial number. mandatory only if several devices are connected to adb. pick your fav. 👑
  • -S, --turn-screen-off — turn the device screen off immediately.
  • --screen-off-timeout seconds — set the screen off timeout while scrcpy is running (restore the initial value on exit). polite. 🎀
  • --shortcut-mod key[+...]][,...] — specify the modifiers to use for scrcpy shortcuts. possible keys are "lctrl", "rctrl", "lalt", "ralt", "lsuper" and "rsuper".

Several shortcut modifiers can be specified, separated by ','.

For example, to use either LCtrl or LSuper for scrcpy shortcuts, pass "lctrl,lsuper".

Default is "lalt,lsuper" (left-Alt or left-Super). 💅

  • --start-app name — start an Android app, by its exact package name.

Add a '?' prefix to select an app whose name starts with the given name, case-insensitive (retrieving app names on the device may take some time, so be patient bestie):

scrcpy --start-app=?firefox

Add a '+' prefix to force-stop before starting the app:

scrcpy --new-display --start-app=+org.mozilla.firefox

Both prefixes can be used, in that order:

scrcpy --start-app=+?firefox
  • -t, --show-touches — enable "show touches" on start, and restore the initial value on exit.

it only shows physical touches (not clicks from scrcpy). hands only. 🙌

  • --tcpip[=[+]ip[:port]] — configure and connect the device over TCP/IP. the wireless era. 🌈

If a destination address is provided, then scrcpy connects to this address before starting. the device must listen on the given TCP port (default is 5555).

If no destination address is provided, then scrcpy attempts to find the IP address and adb port of the current device (typically connected over USB), enables TCP/IP mode if necessary, then connects to this address before starting. doing the detective work for you. 🕵️

Prefix the address with a '+' to force a reconnection.

  • --time-limit seconds — set the maximum mirroring time, in seconds. a lil timer, then it's over. ⏳
  • --tunnel-host ip — set the IP address of the adb tunnel to reach the scrcpy server. this option automatically enables --force-adb-forward.

Default is localhost.

  • --tunnel-port port — set the TCP port of the adb tunnel to reach the scrcpy server. this option automatically enables --force-adb-forward.
  • --tunnel-port (continued from above) — default is 0 (not forced): the local port used for establishing the tunnel will be used. iykyk 🫶
  • -v, --version — print the version of scrcpy. that's it, that's the whole job 💅
  • -V, --verbosity value — sets the log level: "verbose", "debug", "info", "warn" or "error". default is "info" for release builds, "debug" for debug builds 🔥
  • --v4l2-sink /dev/videoN — output to a v4l2loopback device. yes bestie you can pipe your phone into OBS, iconic behavior ✨
  • --v4l2-buffer ms — add a buffering delay (in milliseconds) before pushing frames. this increases latency to compensate for jitter 📉→📈

it's basically the same vibe as --video-buffer, but specific to V4L2 sink.

default is 0 (no buffering).

  • --video-buffer ms — add a buffering delay (in milliseconds) before displaying video frames. again: more latency, but it smooths out the jitter 🧚

default is 0 (no buffering).

  • --video-codec name — pick a video codec: h264, h265, av1, vp8 or vp9. default is h264 🎀
  • --video-codec-options key[:type]=value[,...] — set a list of comma-separated key:type=value options for the device video encoder 🛠️

the possible values for 'type' are 'int' (default), 'long', 'float' and 'string'.

the list of possible codec options lives in the Android documentation:

<https://d.android.com/reference/android/media/MediaFormat>
  • --video-encoder name — use a specific MediaCodec video encoder (depending on the codec provided by --video-codec).

you can see the available encoders with --list-encoders 👀

  • --video-source source — select the video source (display or camera). camera mirroring requires Android 12+ 📸

default is display.

  • -w, --stay-awake — keep the device on while scrcpy is running, when the device is plugged in. no more screen going sleepy mid-demo 😴🚫
  • --window-borderless — disable window decorations, aka display a borderless window. main character window energy 👑
  • --window-title text — set a custom window title. make it cute, make it yours 🎀
  • --window-x value — set the initial window horizontal position. default is "auto".
  • --window-y value — set the initial window vertical position. default is "auto".
  • --window-width value — set the initial window width. default is 0 (automatic).
  • --window-height value — set the initial window height. default is 0 (automatic).
  • -x, --flex-display — continuously resize the virtual display to match the window. it literally flexes, periodt 💪

🌈 EXIT STATUS 🌈

scrcpy will exit with code 0 on normal program termination. if an initial connection can't be established, the exit code 1 gets returned. and if the device disconnects while a session is active, exit code 2 gets returned.

lowkey memorize these — when your script explodes at 2am, the exit code is literally telling you what went down 💀

🎀 SHORTCUTS 🎀

okay so in the following list, MOD is the shortcut modifier. by default it's (left) Alt or (left) Super, but you can configure it with --shortcut-mod (see above) 🦋

  • MOD+q — quit. bye bestie 👋
  • MOD+f, F11 — switch fullscreen mode
  • MOD+Left — rotate display left
  • MOD+Right — rotate display right
  • MOD+Shift+Left, MOD+Shift+Right — flip display horizontally
  • MOD+Shift+Up, MOD+Shift+Down — flip display vertically
  • MOD+z — pause or re-pause display
  • MOD+Shift+z — unpause display
  • MOD+Shift+r — reset video capture/encoding
  • MOD+g — resize window to 1:1 (pixel-perfect) 🔍
  • MOD+w, double-click on black borders — resize window to remove black borders
  • MOD+h, Home, middle-click — click on HOME
  • MOD+b, MOD+Backspace, right-click (when screen is on) — click on BACK
  • MOD+s — click on APP_SWITCH
  • MOD+m — click on MENU
  • MOD+Up — click on VOLUME_UP
  • MOD+Down — click on VOLUME_DOWN
  • MOD+p — click on POWER (turn screen on/off)
  • right-click (when screen is off) — turn screen on
  • MOD+o — turn device screen off (keep mirroring) 🙈
  • MOD+Shift+o — turn device screen on
  • MOD+r — rotate device screen
  • MOD+n — expand notification panel
  • MOD+Shift+n — collapse notification panel
  • Mod+c — copy to clipboard (inject COPY keycode, Android >= 7 only)
  • Mod+x — cut to clipboard (inject CUT keycode, Android >= 7 only)
  • MOD+v — copy computer clipboard to device, then paste (inject PASTE keycode, Android >= 7 only)
  • MOD+Shift+v — inject computer clipboard text as a sequence of key events
  • MOD+k — open keyboard settings on the device (for HID keyboard only)
  • MOD+i — enable/disable FPS counter (print frames/second in logs) 📊
  • Ctrl+click-and-move — pinch-to-zoom and rotate from the center of the screen
  • Shift+click-and-move — tilt vertically (slide with 2 fingers)
  • Ctrl+Shift+click-and-move — tilt horizontally (slide with 2 fingers)
  • drag & drop an APK file — install APK from computer 📦
  • drag & drop a non-APK file — push file to device (see --push-target)
  • MOD+t — turn on the camera torch (camera mode only) 🔦
  • MOD+Shift+t — turn off the camera torch (camera mode only)
  • MOD+Up — zoom camera in (camera mode only)
  • MOD+Down — zoom camera out (camera mode only)

🧚 ENVIRONMENT VARIABLES 🧚

  • ADB — path to adb.
  • ANDROID_SERIAL — device serial to use if no selector (-s, -d, -e or --tcpip=addr) is specified.
  • SCRCPY_ICON_DIR — path to the icon directory.
  • SCRCPY_SERVER_PATH — path to the server binary.

👑 AUTHORS 👑

scrcpy is written by Romain Vimont. absolute legend behavior, ngl 🫶

this manual page was written by Yangfl for the Debian Project (and may be used by others).

🐛 REPORTING BUGS 🐛

report bugs to:

<https://github.com/Genymobile/scrcpy/issues>
fr fr do report them — a good bug report is a love letter to maintainers 💌

Copyright © 2018 Genymobile

<https://www.genymobile.com>

Copyright © 2018-2026 Romain Vimont

<rom@rom1v.com>

licensed under the Apache License, Version 2.0.

🌸 WWW 🌸

<https://github.com/Genymobile/scrcpy>

and that's the whole page bestie!! 🎀✨ this was SCRCPY(1) — the scrcpy manual page, source/version + date living in that little footer right down there — go mirror your phone and slay 💅🦋

📦 where this page comes from