154 lines
4.1 KiB
Markdown
154 lines
4.1 KiB
Markdown
# Projekcija besedil (Lyrics Projector)
|
||
|
||
A Tkinter-based song projector application with optional Flask web interface for remote control.
|
||
|
||
## 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
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
projekcija/
|
||
├── projector.py # Main Tkinter application
|
||
├── nastavitve.py # Settings defaults and initialization
|
||
├── add_song.py # Utility to import songs into database
|
||
├── songs.db # SQLite database with lyrics
|
||
├── settings.json # User configuration
|
||
├── web/ # Flask web server package
|
||
│ ├── __init__.py
|
||
│ ├── server.py # Flask app and API endpoints
|
||
│ ├── static/ # Web assets
|
||
│ │ ├── styles.css
|
||
│ │ └── script.js
|
||
│ └── templates/
|
||
│ └── index.html
|
||
├── tests/ # Test suite
|
||
│ ├── test_api.py
|
||
│ ├── test_integration.py
|
||
│ └── test_mock.py
|
||
└── startup.bat # Windows batch launcher
|
||
```
|
||
|
||
## Installation
|
||
|
||
### Requirements
|
||
- Python 3.8+
|
||
- Flask (for web interface)
|
||
- sqlite3 (included with Python)
|
||
|
||
### Setup
|
||
|
||
```bash
|
||
# Install Flask
|
||
pip install flask
|
||
|
||
# Create or import songs into database (optional)
|
||
python add_song.py
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Launch the Application
|
||
|
||
```bash
|
||
python projector.py
|
||
```
|
||
|
||
Or use the batch file:
|
||
```bash
|
||
startup.bat
|
||
```
|
||
|
||
### Keyboard Shortcuts
|
||
|
||
- **Enter**: Load song by number (when typing in keyboard mode)
|
||
- **+** (plus): Clear/dim the screen
|
||
- **-** (minus): Previous page
|
||
- **/** (slash): Search songs by title
|
||
|
||
### 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
|
||
}
|
||
```
|
||
|
||
### Web Interface
|
||
|
||
If `web_port` is configured and > 0, the web interface opens automatically:
|
||
|
||
```
|
||
http://127.0.0.1:<web_port>/
|
||
```
|
||
|
||
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
|
||
|
||
## Testing
|
||
|
||
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
|
||
- `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
|
||
|
||
### Threading
|
||
- Web server runs in a daemon thread
|
||
- Safe SQLite access with `check_same_thread=False`
|
||
|
||
## 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
|
||
|
||
## License
|
||
|
||
[Add your license here]
|