155 lines
4.8 KiB
Markdown
155 lines
4.8 KiB
Markdown
# Projekcija besedil (Lyrics Projector)
|
||
|
||
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.
|
||
- **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/
|
||
├── projector.py # Main Tkinter application
|
||
├── settings.json # User configuration (generated from sample)
|
||
├── settings.json.sample # Template for settings
|
||
├── songs.db # SQLite database with lyrics
|
||
├── 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
|
||
│ ├── server.py # Flask app and API endpoints
|
||
│ ├── static/ # Web assets (JS, CSS)
|
||
│ └── templates/ # HTML templates
|
||
├── tests/ # Test suite
|
||
└── ...
|
||
```
|
||
|
||
## Installation
|
||
|
||
### Requirements
|
||
- Python 3.8+
|
||
- Flask (for web interface)
|
||
- `sqlite3` (included with Python)
|
||
|
||
### Setup
|
||
|
||
1. **Install Dependencies**:
|
||
```bash
|
||
pip install flask
|
||
```
|
||
|
||
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
|
||
|
||
**Windows:**
|
||
```bash
|
||
startup.bat
|
||
```
|
||
|
||
**Linux:**
|
||
```bash
|
||
./startup.sh
|
||
```
|
||
|
||
**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**: 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
|
||
|
||
Access the control panel at:
|
||
```
|
||
http://<computer-ip>:<web_port>/
|
||
```
|
||
|
||
Features:
|
||
- **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.
|
||
|
||
## API Endpoints
|
||
|
||
- `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` – Search songs
|
||
- `GET /api/get_song_details` – Get lyrics for editing
|
||
- `POST /api/update_song` – Save song changes or create new
|
||
|
||
## Testing
|
||
|
||
Run the test suite:
|
||
```bash
|
||
python -m tests.test_integration
|
||
```
|
||
|
||
## License
|
||
|
||
[Add your license here]
|