Kiwy-Signage/README.md

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:

   chmod +x install.sh
   ./install.sh
   

2. Configure the player: Edit config/app_config.json with your server details:

   {
     "server_ip": "your-server-ip",
     "port": "5000",
     "screen_name": "your-player-name",
     "quickconnect_key": "your-quickconnect-code"
   }
   

Usage

Manual Start

cd src
python3 main.py

Using Run Script

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.