152 lines
4.4 KiB
Markdown
152 lines
4.4 KiB
Markdown
# Kivy Signage Player
|
|
|
|
A modern digital signage player built with Kivy framework that displays content from DigiServer playlists.
|
|
|
|
## Features
|
|
|
|
- **Cross-platform**: Runs on Linux, Windows, and macOS
|
|
- **Modern UI**: Built with Kivy framework for smooth graphics and animations
|
|
- **Multiple Media Types**: Supports images (JPG, PNG, GIF, BMP) and videos (MP4, AVI, MKV, MOV, WEBM)
|
|
- **Server Integration**: Fetches playlists from DigiServer with automatic updates
|
|
- **Player Feedback**: Reports status and playback information to server
|
|
- **Fullscreen Display**: Optimized for digital signage displays
|
|
- **Touch Controls**: Mouse/touch-activated control panel
|
|
- **Auto-restart**: Continuous playlist looping
|
|
- **Error Handling**: Robust error handling with server feedback
|
|
|
|
## Installation
|
|
|
|
1. **Install system dependencies:**
|
|
```bash
|
|
chmod +x install.sh
|
|
./install.sh
|
|
```
|
|
|
|
2. **Configure the player:**
|
|
Edit `config/app_config.json` with your server details:
|
|
```json
|
|
{
|
|
"server_ip": "your-server-ip",
|
|
"port": "5000",
|
|
"screen_name": "your-player-name",
|
|
"quickconnect_key": "your-quickconnect-code"
|
|
}
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Recommended: Using Start Script (with Virtual Environment)
|
|
```bash
|
|
chmod +x start.sh
|
|
./start.sh
|
|
```
|
|
This script automatically:
|
|
- Activates the Python virtual environment
|
|
- Checks for configuration
|
|
- Starts the player
|
|
|
|
### Alternative: Using Run Script
|
|
```bash
|
|
chmod +x run_player.sh
|
|
./run_player.sh
|
|
```
|
|
|
|
### Manual Start
|
|
```bash
|
|
# With virtual environment
|
|
source .venv/bin/activate
|
|
cd src
|
|
python3 main.py
|
|
|
|
# Without virtual environment
|
|
cd src
|
|
python3 main.py
|
|
```
|
|
|
|
## Controls
|
|
|
|
- **Mouse/Touch Movement**: Shows control panel for 3 seconds
|
|
- **Previous (⏮)**: Go to previous media item
|
|
- **Pause/Play (⏸/▶)**: Toggle playback
|
|
- **Next (⏭)**: Skip to next media item
|
|
- **Settings (⚙)**: View player configuration and status
|
|
- **Exit (⏻)**: Close the application
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
Kiwi-signage/
|
|
├── src/
|
|
│ ├── main.py # Main Kivy application
|
|
│ └── get_playlists.py # Playlist management and server communication
|
|
├── config/
|
|
│ └── app_config.json # Player configuration
|
|
├── media/ # Downloaded media files (auto-generated)
|
|
├── playlists/ # Playlist cache (auto-generated)
|
|
├── requirements.txt # Python dependencies
|
|
├── install.sh # Installation script
|
|
├── run_player.sh # Run script
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
### app_config.json
|
|
- `server_ip`: IP address or domain of DigiServer
|
|
- `port`: Port number of DigiServer (default: 5000)
|
|
- `screen_name`: Unique identifier for this player
|
|
- `quickconnect_key`: Authentication key for server access
|
|
|
|
## Features Comparison with Tkinter Player
|
|
|
|
| Feature | Kivy Player | Tkinter Player |
|
|
|---------|-------------|----------------|
|
|
| Cross-platform | ✅ Better | ✅ Good |
|
|
| Modern UI | ✅ Excellent | ❌ Basic |
|
|
| Touch Support | ✅ Native | ❌ Limited |
|
|
| Video Playback | ✅ Built-in | ✅ VLC Required |
|
|
| Performance | ✅ GPU Accelerated | ❌ CPU Only |
|
|
| Animations | ✅ Smooth | ❌ None |
|
|
| Mobile Ready | ✅ Yes | ❌ No |
|
|
|
|
## Server Integration
|
|
|
|
The player communicates with DigiServer via REST API:
|
|
|
|
- **Playlist Fetch**: `GET /api/playlists`
|
|
- **Player Feedback**: `POST /api/player-feedback`
|
|
|
|
Status updates sent to server:
|
|
- Playlist check and update notifications
|
|
- Current playback status
|
|
- Error reports
|
|
- Playlist restart notifications
|
|
|
|
## Troubleshooting
|
|
|
|
### Installation Issues
|
|
- Make sure system dependencies are installed: `./install.sh`
|
|
- For ARM devices (Raspberry Pi), ensure proper SDL2 libraries
|
|
|
|
### Playback Issues
|
|
- Check media file formats are supported
|
|
- Verify network connection to DigiServer
|
|
- Check player configuration in settings
|
|
|
|
### Server Connection
|
|
- Verify server IP and port in configuration
|
|
- Check quickconnect key is correct
|
|
- Ensure DigiServer is running and accessible
|
|
|
|
## Development
|
|
|
|
Based on the proven architecture of the tkinter signage player with modern Kivy enhancements:
|
|
|
|
- **Playlist Management**: Inherited from `get_playlists.py`
|
|
- **Media Playback**: Kivy's built-in Video and AsyncImage widgets
|
|
- **Server Communication**: REST API calls with feedback system
|
|
- **Error Handling**: Comprehensive exception handling with server reporting
|
|
|
|
## License
|
|
|
|
This project is part of the DigiServer digital signage system. |