JP-Input-XWayland-Helper

Lightweight prototype GUI helper for Japanese input on XWayland. This repository contains a small Python/Qt GUI (main.py) and a helper shell script (label_boot.sh) to launch it.

Requirements

• Python 3.8 or newer
• Python packages:
  • PyQt6
  • keyboard

Note: the keyboard package may require elevated privileges on Linux to use global keyboard hooks. See "Permissions" below.

Installation

Recommended: use a virtual environment.

1. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate

2. Upgrade pip and install dependencies:

   pip install --upgrade pip
   pip install PyQt6 keyboard

   Optionally, create a requirements.txt file with the following contents and install with pip install -r requirements.txt:

   PyQt6>=6.0
   keyboard>=0.13
   

Running the app

There are two ways to run the app from the repository root:

• Using the provided shell script:

  1. Make the script executable (if needed):

     chmod +x label_boot.sh

  2. Run it:

     ./label_boot.sh

  The script resolves its directory and runs main.py.

• Running the Python script directly:

  python3 main.py

If your system's python command points to Python 3, ./label_boot.sh or python main.py will also work. Otherwise prefer python3 to ensure Python 3 is used.

Permissions (Linux)

The keyboard library (used by this project) often needs root privileges on Linux to capture global keyboard events. If you find functionality limited or missing, try running with elevated privileges:

sudo python3 main.py

Running applications as root has security implications. Alternatively, consult the keyboard package documentation for safer ways to grant the required permissions on your distribution.

Notes

• This is a prototype GUI. The window includes an input field and a "コピー" (Copy) button — pressing Enter or the button copies the input to the clipboard.
• The code sets the window to stay on top and listens for specific key events to toggle visibility (see main.py for details).
• If you encounter issues with PyQt6 on your platform, installing system packages (e.g., platform-specific Qt libraries) may help; however, pip install PyQt6 is usually sufficient on most platforms.

License

This project is licensed under the MIT License. See the LICENSE file for details.