mirror of
https://github.com/Genymobile/scrcpy
synced 2024-11-11 01:10:32 +00:00
b9d244b4c9
Rework the documentation to present the keyboard and mouse input modes. PR #4473 <https://github.com/Genymobile/scrcpy/pull/4473>
137 lines
4.2 KiB
Markdown
137 lines
4.2 KiB
Markdown
# Keyboard
|
|
|
|
Several keyboard input modes are available:
|
|
|
|
- `--keyboard=sdk` (default)
|
|
- `--keyboard=uhid` (or `-K`): simulates a physical HID keyboard using the UHID
|
|
kernel module on the device
|
|
- `--keyboard=aoa`: simulates a physical HID keyboard using the AOAv2 protocol
|
|
- `--keyboard=disabled`
|
|
|
|
By default, `sdk` is used, but if you use scrcpy regularly, it is recommended to
|
|
use [`uhid`](#uhid) and configure the keyboard layout once and for all.
|
|
|
|
|
|
## SDK keyboard
|
|
|
|
In this mode (`--keyboard=sdk`, or if the parameter is omitted), keyboard input
|
|
events are injected at the Android API level. It works everywhere, but it is
|
|
limited to ASCII and some other characters.
|
|
|
|
Note that on some devices, an additional option must be enabled in developer
|
|
options for this keyboard mode to work. See
|
|
[prerequisites](/README.md#prerequisites).
|
|
|
|
Additional parameters (specific to `--keyboard=sdk`) described below allow to
|
|
customize the behavior.
|
|
|
|
|
|
### Text injection preference
|
|
|
|
Two kinds of [events][textevents] are generated when typing text:
|
|
- _key events_, signaling that a key is pressed or released;
|
|
- _text events_, signaling that a text has been entered.
|
|
|
|
By default, numbers and "special characters" are inserted using text events, but
|
|
letters are injected using key events, so that the keyboard behaves as expected
|
|
in games (typically for WASD keys).
|
|
|
|
But this may [cause issues][prefertext]. If you encounter such a problem, you
|
|
can inject letters as text (or just switch to [UHID](#uhid)):
|
|
|
|
```bash
|
|
scrcpy --prefer-text
|
|
```
|
|
|
|
(but this will break keyboard behavior in games)
|
|
|
|
On the contrary, you could force to always inject raw key events:
|
|
|
|
```bash
|
|
scrcpy --raw-key-events
|
|
```
|
|
|
|
[textevents]: https://blog.rom1v.com/2018/03/introducing-scrcpy/#handle-text-input
|
|
[prefertext]: https://github.com/Genymobile/scrcpy/issues/650#issuecomment-512945343
|
|
|
|
|
|
### Key repeat
|
|
|
|
By default, holding a key down generates repeated key events. Ths can cause
|
|
performance problems in some games, where these events are useless anyway.
|
|
|
|
To avoid forwarding repeated key events:
|
|
|
|
```bash
|
|
scrcpy --no-key-repeat
|
|
```
|
|
|
|
|
|
## Physical keyboard simulation
|
|
|
|
Two modes allow to simulate a physical HID keyboard on the device.
|
|
|
|
To work properly, it is necessary to configure (once and for all) the keyboard
|
|
layout on the device to match that of the computer.
|
|
|
|
The configuration page can be opened in one of the following ways:
|
|
- from the scrcpy window (when `uhid` or `aoa` is used), by pressing
|
|
<kbd>MOD</kbd>+<kbd>k</kbd> (see [shortcuts](shortcuts.md))
|
|
- from the device, in Settings → System → Languages and input → Physical
|
|
devices
|
|
- from a terminal on the computer, by executing `adb shell am start -a
|
|
android.settings.HARD_KEYBOARD_SETTINGS`
|
|
|
|
From this configuration page, it is also possible to enable or disable on-screen
|
|
keyboard.
|
|
|
|
|
|
### UHID
|
|
|
|
This mode simulates a physical HID keyboard using the [UHID] kernel module on the
|
|
device.
|
|
|
|
[UHID]: https://kernel.org/doc/Documentation/hid/uhid.txt
|
|
|
|
To enable UHID keyboard, use:
|
|
|
|
```bash
|
|
scrcpy --keyboard=uhid
|
|
scrcpy -K # short version
|
|
```
|
|
|
|
Once the keyboard layout is configured (see above), it is the best mode for
|
|
using the keyboard while mirroring:
|
|
|
|
- it works for all characters and IME (contrary to `--keyboard=sdk`)
|
|
- the on-screen keyboard can be disabled (contrary to `--keyboard=sdk`)
|
|
- it works over TCP/IP (wirelessly) (contrary to `--keyboard=aoa`)
|
|
- there are no issues on Windows (contrary to `--keyboard=aoa`)
|
|
|
|
One drawback is that it may not work on old Android versions due to permission
|
|
errors.
|
|
|
|
|
|
### AOA
|
|
|
|
This mode simulates a physical HID keyboard using the [AOAv2] protocol.
|
|
|
|
[AOAv2]: https://source.android.com/devices/accessories/aoa2#hid-support
|
|
|
|
To enable AOA keyboard, use:
|
|
|
|
```bash
|
|
scrcpy --keyboard=aoa
|
|
```
|
|
|
|
Contrary to the other modes, it works at the USB level directly (so it only
|
|
works over USB).
|
|
|
|
It does not use the scrcpy server, and does not require `adb` (USB debugging).
|
|
Therefore, it is possible to control the device (but not mirror) even with USB
|
|
debugging disabled (see [OTG](otg.md)).
|
|
|
|
Note: On Windows, it may only work in [OTG mode](otg.md), not while mirroring
|
|
(it is not possible to open a USB device if it is already open by another
|
|
process like the _adb daemon_).
|