# 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

### Manual Start
```bash
cd src
python3 main.py
```

### Using Run Script
```bash
chmod +x run_player.sh
./run_player.sh
```

## 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.