Add detailed comments to scripts and comprehensive README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
c90bdb1ce2
commit
15a8a9536e
1 changed files with 124 additions and 0 deletions
124
README.md
Normal file
124
README.md
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
# Monitor TUI - Omarchy
|
||||
|
||||
A terminal user interface for managing monitor settings in [Omarchy](https://omarchy.com) (Hyprland). Change resolution, scaling, position, and refresh rate without editing config files.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
git clone https://github.com/28allday/Monitor-TUI-Omarchy.git
|
||||
cd Monitor-TUI-Omarchy
|
||||
chmod +x monitor-tui.sh
|
||||
./monitor-tui.sh
|
||||
```
|
||||
|
||||
On first run, the script installs itself to `~/.local/bin/monitor-tui` and adds a keybind (**SUPER+ALT+M**) so you can open it anytime.
|
||||
|
||||
## Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Resolution** | Choose from all available modes reported by your monitor |
|
||||
| **Refresh rate** | Select from supported rates (60Hz, 144Hz, 240Hz, etc.) |
|
||||
| **Scaling** | Preset options (1x, 1.25x, 1.5x, 2x) or custom values |
|
||||
| **Position** | Auto, left, right, above, below, or custom coordinates |
|
||||
| **VRR** | Enable/disable Variable Refresh Rate (FreeSync/G-Sync) |
|
||||
| **Multi-monitor** | Configure each display independently, auto-calculate positions |
|
||||
| **Live preview** | Changes apply instantly — no restart needed |
|
||||
| **Backup/restore** | Automatic backup before changes, easy restore |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Reads live monitor data from `hyprctl monitors -j`
|
||||
2. Shows a menu with your current settings and available options
|
||||
3. Applies changes instantly via `hyprctl keyword` (live, no restart)
|
||||
4. Saves to `~/.config/hypr/monitors.conf` for persistence across reboots
|
||||
|
||||
## Keybind
|
||||
|
||||
After installation, press **SUPER+ALT+M** to open the monitor TUI from anywhere.
|
||||
|
||||
The keybind is added to `~/.config/hypr/bindings.conf` inside a marked block so it can be cleanly removed by the uninstaller.
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Purpose | Included in Omarchy? |
|
||||
|-----------|---------|---------------------|
|
||||
| `hyprctl` | Reads monitor info and applies changes | Yes (comes with Hyprland) |
|
||||
| `jq` | Parses JSON output from hyprctl | Yes |
|
||||
| `bc` | Floating-point math for scale calculations | Usually yes |
|
||||
|
||||
## Multi-Monitor Setup
|
||||
|
||||
When you have multiple monitors, the TUI:
|
||||
|
||||
1. Shows all connected displays with their current settings
|
||||
2. Lets you configure each one independently
|
||||
3. Auto-calculates position when you choose "Right of", "Above", or "Below"
|
||||
4. Accounts for scaling when calculating positions (uses logical pixels)
|
||||
|
||||
### Position Calculation
|
||||
|
||||
The TUI calculates positions using logical (scaled) dimensions, not raw pixels. For example:
|
||||
- A 4K monitor at 2x scale = 1920 logical pixels wide
|
||||
- A 1080p monitor at 1x scale = 1920 logical pixels wide
|
||||
- Placing the 1080p monitor to the right: position = 1920x0
|
||||
|
||||
## Files
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `~/.local/bin/monitor-tui` | Installed script |
|
||||
| `~/.config/hypr/monitors.conf` | Monitor configuration (edited by TUI) |
|
||||
| `~/.config/hypr/monitors.conf.bak` | Automatic backup before changes |
|
||||
| `~/.config/hypr/bindings.conf` | Keybind added here (SUPER+ALT+M) |
|
||||
| `~/.config/hypr/.monitor-tui-installed` | Marker file tracking installation |
|
||||
|
||||
## Uninstalling
|
||||
|
||||
```bash
|
||||
chmod +x monitor-tui-uninstall.sh
|
||||
./monitor-tui-uninstall.sh
|
||||
```
|
||||
|
||||
This removes:
|
||||
- The installed script from `~/.local/bin/`
|
||||
- The keybind from `~/.config/hypr/bindings.conf`
|
||||
- The window rules from Hyprland config
|
||||
- The installation marker
|
||||
|
||||
Your monitor configuration (`monitors.conf`) is **not** removed.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### TUI shows "No monitors detected"
|
||||
|
||||
- Make sure you're running inside Hyprland: `echo $XDG_CURRENT_DESKTOP`
|
||||
- Check hyprctl works: `hyprctl monitors`
|
||||
|
||||
### Changes don't persist after reboot
|
||||
|
||||
- Check the config file was written: `cat ~/.config/hypr/monitors.conf`
|
||||
- Make sure `monitors.conf` is sourced in your main config:
|
||||
```
|
||||
# In ~/.config/hypr/hyprland.conf
|
||||
source = ~/.config/hypr/monitors.conf
|
||||
```
|
||||
|
||||
### Scale looks wrong
|
||||
|
||||
- Hyprland works best with specific scale values: 1, 1.25, 1.333333, 1.5, 1.666667, 1.75, 2
|
||||
- Fractional scaling can cause blurry text in some XWayland apps
|
||||
|
||||
### SUPER+ALT+M doesn't work
|
||||
|
||||
- Check the keybind was added: `grep "monitor-tui" ~/.config/hypr/bindings.conf`
|
||||
- Reload Hyprland: `hyprctl reload`
|
||||
|
||||
## Credits
|
||||
|
||||
- [Omarchy](https://omarchy.com) - The Arch Linux distribution this was built for
|
||||
- [Hyprland](https://hyprland.org/) - Wayland compositor
|
||||
|
||||
## License
|
||||
|
||||
This project is provided as-is for the Omarchy community.
|
||||
Loading…
Add table
Reference in a new issue