valentin/Projekcija
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Osvežitev readme-ja

Browse Source
This commit is contained in:
Valentin Korenjak
2026-03-21 22:11:50 +01:00
parent 21d7baaea6
commit 15c449b63e
1 changed files with 93 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

181
README.md
View File

@@ -1,41 +1,48 @@
# Projekcija besedil (Lyrics Projector) # 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 ## Features
- **Tkinter GUI**: Full-screen song display with customizable fonts, colors, and sizing - **Tkinter GUI**: Full-screen song display with customizable fonts, colors, and sizing.
- **Song Database**: SQLite database with lyrics and metadata - **Smart Text Wrapping**: Automatically splits long lines and divides lyrics into pages based on screen height and stanza breaks.
- **Web Interface** (optional): Control the projector via web browser - **Song Database**: SQLite database with lyrics and metadata.
- Load songs by number or search by title - **Web Interface**: Comprehensive remote control via web browser.
- Navigate between lyrics pages - Load songs by number or search by title.
- Toggle uppercase display - Real-time status synchronization across multiple devices.
- Clear/dim the screen - Navigate between lyrics pages.
- **Keyboard Shortcuts**: Quick navigation and screen control - **Song Editor**: Edit existing songs or add new ones directly from the web interface.
- **Settings**: JSON-based configuration for fonts, colors, and display options - 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 ## Project Structure
``` ```
projekcija/ Projekcija/
├── projector.py # Main Tkinter application ├── projector.py # Main Tkinter application
├── nastavitve.py # Settings defaults and initialization ├── settings.json # User configuration (generated from sample)
├── add_song.py # Utility to import songs into database ├── settings.json.sample # Template for settings
├── songs.db # SQLite database with lyrics ├── 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 ├── web/ # Flask web server package
│ ├── __init__.py
│ ├── server.py # Flask app and API endpoints │ ├── server.py # Flask app and API endpoints
│ ├── static/ # Web assets │ ├── static/ # Web assets (JS, CSS)
│ │ ├── styles.css │ └── templates/ # HTML templates
│ │ └── script.js
│ └── templates/
│ └── index.html
├── tests/ # Test suite ├── tests/ # Test suite
│ ├── test_api.py └── ...
│ ├── test_integration.py
│ └── test_mock.py
└── startup.bat # Windows batch launcher
``` ```
## Installation ## Installation
@@ -43,110 +50,104 @@ projekcija/
### Requirements ### Requirements
- Python 3.8+ - Python 3.8+
- Flask (for web interface) - Flask (for web interface)
- sqlite3 (included with Python) - `sqlite3` (included with Python)
### Setup ### Setup
1. **Install Dependencies**:
```bash ```bash
# Install Flask
pip install flask 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 ## Usage
### Launch the Application ### Launch the Application
```bash **Windows:**
python projector.py
```
Or use the batch file:
```bash ```bash
startup.bat 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 - **+** (plus): Clear/dim the screen
- **-** (minus): Previous page - **-** (minus): Previous page
- **\*** (multiply): Toggle uppercase
- **/** (slash): Search songs by title - **/** (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 ### Configuration
Edit `settings.json` to customize: Edit `settings.json` to customize:
- Font name, size, and color - **font_name**: Font family (e.g., "Arial")
- Background color - **font_size**: Base font size
- Display width percentage - **fg_color**: Text color (HEX)
- **web_port**: Set to a port number (e.g., 5000) to enable web interface, or 0 to disable - **bg_color**: Background color (HEX)
- **screen_width_percent**: Width of the text area (e.g., 60)
Example `settings.json`: - **font_bold**: Use bold font (true/false)
```json - **show_song_info**: Show song number and page info at bottom (true/false)
{ - **web_port**: Port for web interface (0 to disable)
"font_name": "Times New Roman", - **db_update_url**: URL for remote database synchronization
"font_size": 32,
"fg_color": "#FFFFFF",
"bg_color": "#000000",
"screen_width_percent": 60,
"font_bold": true,
"web_port": 5000
}
```
### Web Interface ### Web Interface
If `web_port` is configured and > 0, the web interface opens automatically: Access the control panel at:
``` ```
http://127.0.0.1:<web_port>/ http://<computer-ip>:<web_port>/
``` ```
Features: Features:
- **Load by Number**: Input song ID and press "Naloži" - **Load by Number**: Input song ID and press "Naloži" (or Enter).
- **Search**: Find songs by keyword - **Search**: Real-time search by title.
- **Navigation**: Next/Previous buttons to flip pages - **Navigation**: Next/Previous buttons.
- **Case Toggle**: "velikE črke" button for uppercase - **Edit Mode**: Click "Uredi besedilo" to modify the current song or add a new one.
- **Clear Screen**: "Zatemniti ekran" button to dim display - **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: - `GET /api/state` – Current projector state
- `POST /api/load_song` – Load a song by number
```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
- `POST /api/next_page` – Next page - `POST /api/next_page` – Next page
- `POST /api/prev_page` – Previous page - `POST /api/prev_page` – Previous page
- `POST /api/clear_screen` – Clear display - `POST /api/clear_screen` – Clear display
- `POST /api/toggle_caps` – Toggle uppercase - `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 ## Testing
- Web server runs in a daemon thread
- Safe SQLite access with `check_same_thread=False`
## Notes Run the test suite:
```bash
- The web interface is optional; disable it by setting `web_port: 0` in settings python -m tests.test_integration
- 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
## License ## License