From 15c449b63e4632fa357df28c10516a94e47bbb92 Mon Sep 17 00:00:00 2001 From: Valentin Korenjak Date: Sat, 21 Mar 2026 22:11:50 +0100 Subject: [PATCH] =?UTF-8?q?Osve=C5=BEitev=20readme-ja?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 185 +++++++++++++++++++++++++++--------------------------- 1 file changed, 93 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 44339e1..d8f50c6 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,48 @@ # Projekcija besedil (Lyrics Projector) -A Tkinter-based song projector application with optional Flask web interface for remote control. +A Tkinter-based song projector application with a Flask web interface for remote control. Designed for displaying lyrics on a large screen while controlling them from a computer or mobile device. ## Features -- **Tkinter GUI**: Full-screen song display with customizable fonts, colors, and sizing -- **Song Database**: SQLite database with lyrics and metadata -- **Web Interface** (optional): Control the projector via web browser - - Load songs by number or search by title - - Navigate between lyrics pages - - Toggle uppercase display - - Clear/dim the screen -- **Keyboard Shortcuts**: Quick navigation and screen control -- **Settings**: JSON-based configuration for fonts, colors, and display options +- **Tkinter GUI**: Full-screen song display with customizable fonts, colors, and sizing. +- **Smart Text Wrapping**: Automatically splits long lines and divides lyrics into pages based on screen height and stanza breaks. +- **Song Database**: SQLite database with lyrics and metadata. +- **Web Interface**: Comprehensive remote control via web browser. + - Load songs by number or search by title. + - Real-time status synchronization across multiple devices. + - Navigate between lyrics pages. + - **Song Editor**: Edit existing songs or add new ones directly from the web interface. + - Toggle uppercase display. + - Clear/dim the screen. + - Virtual keypad for mobile-friendly input. +- **Keyboard Shortcuts**: Quick navigation and screen control using physical or numeric keypad. +- **Settings**: JSON-based configuration for fonts, colors, display options, and remote update URLs. +- **System Integration**: + - Prevents screen sleep/saver on Windows and Linux (GNOME). + - Automatic cursor hiding. + - Remote system commands (shutdown, restart). + - Remote database updates via URL. ## Project Structure ``` -projekcija/ +Projekcija/ ├── projector.py # Main Tkinter application -├── nastavitve.py # Settings defaults and initialization -├── add_song.py # Utility to import songs into database +├── settings.json # User configuration (generated from sample) +├── settings.json.sample # Template for settings ├── songs.db # SQLite database with lyrics -├── settings.json # User configuration +├── startup.sh # Linux launcher script +├── startup.bat # Windows launcher script +├── tools/ # Utility scripts +│ ├── add_song.py # Import songs into database +│ ├── nastavitve.py # Settings management +│ └── ... ├── web/ # Flask web server package -│ ├── __init__.py │ ├── server.py # Flask app and API endpoints -│ ├── static/ # Web assets -│ │ ├── styles.css -│ │ └── script.js -│ └── templates/ -│ └── index.html +│ ├── static/ # Web assets (JS, CSS) +│ └── templates/ # HTML templates ├── tests/ # Test suite -│ ├── test_api.py -│ ├── test_integration.py -│ └── test_mock.py -└── startup.bat # Windows batch launcher +└── ... ``` ## Installation @@ -43,110 +50,104 @@ projekcija/ ### Requirements - Python 3.8+ - Flask (for web interface) -- sqlite3 (included with Python) +- `sqlite3` (included with Python) ### Setup -```bash -# Install Flask -pip install flask +1. **Install Dependencies**: + ```bash + pip install flask + ``` -# Create or import songs into database (optional) -python add_song.py -``` +2. **Configure Settings**: + Copy `settings.json.sample` to `settings.json` and adjust values as needed. + +3. **Prepare Database**: + Ensure `songs.db` exists. You can use tools in the `tools/` directory to manage songs. ## Usage ### Launch the Application -```bash -python projector.py -``` - -Or use the batch file: +**Windows:** ```bash startup.bat ``` -### Keyboard Shortcuts +**Linux:** +```bash +./startup.sh +``` -- **Enter**: Load song by number (when typing in keyboard mode) +**Manual:** +```bash +python projector.py +``` + +### Keyboard Shortcuts (Projector Window) + +- **0-9**: Type song number +- **Enter**: Load song by number / Next page - **+** (plus): Clear/dim the screen - **-** (minus): Previous page +- **\*** (multiply): Toggle uppercase - **/** (slash): Search songs by title +- **Backspace**: Delete last digit of song number + +### Special Commands (Input as song number) + +- **9999**: Shutdown system +- **9998**: Restart system +- **9997**: Restart application +- **9988**: Exit application +- **9901**: Update songs database from `db_update_url` ### Configuration Edit `settings.json` to customize: -- Font name, size, and color -- Background color -- Display width percentage -- **web_port**: Set to a port number (e.g., 5000) to enable web interface, or 0 to disable - -Example `settings.json`: -```json -{ - "font_name": "Times New Roman", - "font_size": 32, - "fg_color": "#FFFFFF", - "bg_color": "#000000", - "screen_width_percent": 60, - "font_bold": true, - "web_port": 5000 -} -``` +- **font_name**: Font family (e.g., "Arial") +- **font_size**: Base font size +- **fg_color**: Text color (HEX) +- **bg_color**: Background color (HEX) +- **screen_width_percent**: Width of the text area (e.g., 60) +- **font_bold**: Use bold font (true/false) +- **show_song_info**: Show song number and page info at bottom (true/false) +- **web_port**: Port for web interface (0 to disable) +- **db_update_url**: URL for remote database synchronization ### Web Interface -If `web_port` is configured and > 0, the web interface opens automatically: - +Access the control panel at: ``` -http://127.0.0.1:/ +http://:/ ``` Features: -- **Load by Number**: Input song ID and press "Naloži" -- **Search**: Find songs by keyword -- **Navigation**: Next/Previous buttons to flip pages -- **Case Toggle**: "velikE črke" button for uppercase -- **Clear Screen**: "Zatemniti ekran" button to dim display +- **Load by Number**: Input song ID and press "Naloži" (or Enter). +- **Search**: Real-time search by title. +- **Navigation**: Next/Previous buttons. +- **Edit Mode**: Click "Uredi besedilo" to modify the current song or add a new one. +- **Virtual Keypad**: Toggleable numeric keypad for touch devices. +- **Wake Lock**: Attempts to keep the mobile screen on while the interface is open. -## Testing +## API Endpoints -Run the integration test to verify the web server: - -```bash -python -m tests.test_integration -``` - -This starts a mock projector, launches the Flask server, and exercises all API endpoints. - -## Architecture - -### Database Schema -- `songs` table: `id, title, lyrics` -- Read-only mode (no modifications via web interface) - -### API Endpoints -- `GET /` – HTML interface -- `GET /api/state` – Current projector state (text, page, navigation flags) -- `POST /api/load_song` – Load a song +- `GET /api/state` – Current projector state +- `POST /api/load_song` – Load a song by number - `POST /api/next_page` – Next page - `POST /api/prev_page` – Previous page - `POST /api/clear_screen` – Clear display - `POST /api/toggle_caps` – Toggle uppercase -- `POST /api/search_songs` – Find songs by title +- `POST /api/search_songs` – Search songs +- `GET /api/get_song_details` – Get lyrics for editing +- `POST /api/update_song` – Save song changes or create new -### Threading -- Web server runs in a daemon thread -- Safe SQLite access with `check_same_thread=False` +## Testing -## Notes - -- The web interface is optional; disable it by setting `web_port: 0` in settings -- HTML, CSS, and JavaScript are stored in separate files under `web/` -- For production deployment, use a WSGI server (Gunicorn, uWSGI) instead of Flask development server -- Songs database is read-only via web interface; add songs using admin tools or direct SQL +Run the test suite: +```bash +python -m tests.test_integration +``` ## License