Update README for GUI-only, add Windows/theming/keybinds docs

This commit is contained in:
pax 2026-04-04 06:05:43 -05:00
parent 4a40ccebbd
commit abc3eee20a

107
README.md
View File

@ -2,89 +2,86 @@
Local desktop application for browsing, searching, and favoriting images from booru-style imageboards. Local desktop application for browsing, searching, and favoriting images from booru-style imageboards.
Dual interface — **Qt6 GUI** and **Textual TUI**. Green-on-black theme.
## Features ## Features
- Tag-based search across multiple booru sites (Danbooru, Gelbooru, Moebooru) - Supports Danbooru, Gelbooru, Moebooru, and e621
- Auto-detect site API type — just paste the URL - Auto-detect site API type — just paste the URL
- Thumbnail grid with full image preview (zoom/pan) - Tag search with autocomplete and history
- Favorites system with local download cache and offline browsing - Thumbnail grid with image/video preview (zoom, pan, GIF animation)
- Tag autocomplete - Favorites with folder organization
- Per-site API key support - Save to library, drag-and-drop, multi-select bulk operations
- Custom CSS theming (native OS look by default)
- Cross-platform: Linux and Windows
## Install ## Install
```sh ```sh
pip install -e ".[all]" pip install -e .
```
Or install only what you need:
```sh
pip install -e ".[gui]" # Qt6 GUI only
pip install -e ".[tui]" # Textual TUI only
``` ```
### Dependencies ### Dependencies
- **GUI**: PySide6 (Qt6) - Python 3.11+
- **TUI**: Textual - PySide6 (Qt6)
- **Core**: httpx, Pillow, SQLite (stdlib) - httpx
- Pillow
## Usage ## Usage
```sh ```sh
# Qt6 GUI booru-viewer
booru-gui
# Terminal TUI
booru-tui
``` ```
### TUI Keybinds Or run directly:
```sh
python -m booru_viewer.main_gui
```
### Windows
Download `booru-viewer.exe` from [Releases](https://git.pax.moe/pax/booru-viewer/releases).
For WebM video playback, install **VP9 Video Extensions** from the Microsoft Store.
### Keybinds
| Key | Action | | Key | Action |
|-----|--------| |-----|--------|
| `/` | Focus search | | Click / Arrow keys | Select and preview |
| `Enter` | Preview selected | | `h`/`j`/`k`/`l` | Grid navigation |
| `f` | Toggle favorite | | `Ctrl+A` | Select all |
| `j`/`k` | Navigate down/up | | `Ctrl+Click` / `Shift+Click` | Multi-select |
| `n`/`p` | Next/previous page |
| `1`/`2`/`3` | Browse / Favorites / Sites |
| `Escape` | Close preview |
| `q` | Quit |
### GUI Keybinds
| Key | Action |
|-----|--------|
| `F` | Toggle favorite on selected |
| `Ctrl+S` | Manage sites |
| `Ctrl+Q` | Quit |
| Scroll wheel | Zoom in preview | | Scroll wheel | Zoom in preview |
| Right click | Close preview | | Middle click | Reset view |
| `0` | Fit to view | | `+`/`-`/`0` | Zoom in / out / fit |
| `+`/`-` | Zoom in/out | | `Ctrl+Left`/`Right` | Previous / next post in preview |
| `Ctrl+P` | Privacy screen |
| `F11` | Fullscreen |
| Right click | Context menu |
## Adding Sites ## Adding Sites
Open the site manager (GUI: `Ctrl+S`, or in the Sites tab). Enter a URL and click Auto-Detect — the app probes for Danbooru, Gelbooru, and Moebooru APIs automatically. File > Manage Sites. Enter a URL, click Auto-Detect, and save.
Or via Python: API credentials are optional — needed for Gelbooru and rate-limited sites.
```python ## Theming
from booru_viewer.core.db import Database
db = Database()
db.add_site("Danbooru", "https://danbooru.donmai.us", "danbooru")
db.add_site("Gelbooru", "https://gelbooru.com", "gelbooru")
```
## Data The app uses your OS native theme by default. To customize, create `custom.qss` in your data directory:
- Database: `~/.local/share/booru-viewer/booru.db` - **Linux**: `~/.local/share/booru-viewer/custom.qss`
- Image cache: `~/.local/share/booru-viewer/cache/` - **Windows**: `%APPDATA%\booru-viewer\custom.qss`
- Thumbnails: `~/.local/share/booru-viewer/thumbnails/`
A green-on-black theme template is available in Settings > Theme > Create from Template.
## Data Locations
| | Linux | Windows |
|--|-------|---------|
| Database | `~/.local/share/booru-viewer/booru.db` | `%APPDATA%\booru-viewer\booru.db` |
| Cache | `~/.local/share/booru-viewer/cache/` | `%APPDATA%\booru-viewer\cache\` |
| Library | `~/.local/share/booru-viewer/saved/` | `%APPDATA%\booru-viewer\saved\` |
## License ## License