Initial import: clean snapshot from /home/olafn/infoscreen-dev (2025-10-25)
This commit is contained in:
RobbStarkAustria
272
IMPRESSIVE_INTEGRATION.md
Normal file
272
IMPRESSIVE_INTEGRATION.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Impressive Integration - Display Manager
|
||||
|
||||
## Overview
|
||||
|
||||
The Display Manager now uses **Impressive** as the primary presentation tool for auto-advancing slideshows. This provides a robust, reliable solution for kiosk-mode presentations with native loop and auto-quit support.
|
||||
|
||||
## Why Impressive?
|
||||
|
||||
After testing multiple approaches (xdotool + LibreOffice, video conversion, etc.), Impressive proved to be the best solution:
|
||||
|
||||
✅ **Native auto-advance** - No need for xdotool hacks or window management
|
||||
✅ **Loop support** - Built-in `--wrap` parameter for infinite looping
|
||||
✅ **Auto-quit** - Built-in `--autoquit` parameter to exit after last slide
|
||||
✅ **Reliable** - Works consistently on Raspberry Pi without focus issues
|
||||
✅ **Simple** - Clean command-line interface, no complex scripting needed
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. File Conversion (PPTX → PDF)
|
||||
|
||||
When a PPTX/PPT/ODP file is detected:
|
||||
```bash
|
||||
libreoffice --headless --convert-to pdf --outdir presentation/ file.pptx
|
||||
```
|
||||
|
||||
The converted PDF is cached and reused if the source file hasn't changed.
|
||||
|
||||
### 2. Impressive Presentation
|
||||
|
||||
For loop mode (most events):
|
||||
```bash
|
||||
impressive --fullscreen --nooverview --auto 5 --wrap presentation.pdf
|
||||
```
|
||||
|
||||
For single playthrough:
|
||||
```bash
|
||||
impressive --fullscreen --nooverview --auto 5 --autoquit presentation.pdf
|
||||
```
|
||||
|
||||
## Event JSON Format
|
||||
|
||||
### Looping Presentation (Typical for Events)
|
||||
```json
|
||||
{
|
||||
"id": "event_123",
|
||||
"start": "2025-10-01 14:00:00",
|
||||
"end": "2025-10-01 16:00:00",
|
||||
"presentation": {
|
||||
"files": [
|
||||
{
|
||||
"name": "slides.pptx",
|
||||
"url": "https://server/files/slides.pptx"
|
||||
}
|
||||
],
|
||||
"auto_advance": true,
|
||||
"slide_interval": 10,
|
||||
"loop": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result:** Slides advance every 10 seconds, presentation loops infinitely until event end time.
|
||||
|
||||
### Single Playthrough
|
||||
```json
|
||||
{
|
||||
"id": "event_456",
|
||||
"presentation": {
|
||||
"files": [{"name": "welcome.pptx"}],
|
||||
"auto_advance": true,
|
||||
"slide_interval": 5,
|
||||
"loop": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result:** Slides advance every 5 seconds, Impressive exits after last slide.
|
||||
|
||||
### Manual Advance (No Auto-Advance)
|
||||
```json
|
||||
{
|
||||
"presentation": {
|
||||
"files": [{"name": "manual.pptx"}],
|
||||
"auto_advance": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result:** Presentation displays but doesn't auto-advance (manual control only).
|
||||
|
||||
## Parameters Reference
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `auto_advance` | boolean | `false` | Enable automatic slide advancement |
|
||||
| `slide_interval` | integer | `10` | Seconds between slides (when auto_advance=true) |
|
||||
| `loop` | boolean | `false` | Loop presentation (vs. quit after last slide) |
|
||||
|
||||
## Display Manager Implementation
|
||||
|
||||
### Code Location
|
||||
`src/display_manager.py` - `start_presentation()` method
|
||||
|
||||
### Key Features
|
||||
|
||||
1. **Smart Caching**: Checks if PDF exists and is newer than source PPTX
|
||||
2. **Automatic Conversion**: Uses LibreOffice headless mode for PPTX→PDF
|
||||
3. **Fallback Support**: Falls back to evince/okular if Impressive not installed
|
||||
4. **Comprehensive Logging**: Logs all operations for debugging
|
||||
|
||||
### Process Flow
|
||||
```
|
||||
1. Receive presentation event
|
||||
2. Check file type (.pptx, .pdf, etc.)
|
||||
3. If PPTX:
|
||||
a. Check if PDF cache exists and is current
|
||||
b. Convert to PDF if needed (LibreOffice headless)
|
||||
4. Build Impressive command:
|
||||
- Always: --fullscreen --nooverview
|
||||
- If auto_advance: --auto <interval>
|
||||
- If loop: --wrap
|
||||
- If not loop: --autoquit
|
||||
5. Start Impressive process
|
||||
6. Monitor process and event timing
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Scripts Available
|
||||
|
||||
1. **test-impressive.sh** - Test Impressive with auto-quit (single playthrough)
|
||||
```bash
|
||||
./scripts/test-impressive.sh
|
||||
```
|
||||
|
||||
2. **test-impressive-loop.sh** - Test Impressive with loop mode
|
||||
```bash
|
||||
./scripts/test-impressive-loop.sh
|
||||
```
|
||||
|
||||
3. **test-display-manager.sh** - Interactive testing with Display Manager
|
||||
```bash
|
||||
./scripts/test-display-manager.sh
|
||||
```
|
||||
Then select option 2 (Create PRESENTATION test event)
|
||||
|
||||
### Manual Testing
|
||||
|
||||
Create a test event:
|
||||
```bash
|
||||
cat > src/current_event.json <<EOF
|
||||
{
|
||||
"id": "test_001",
|
||||
"start": "2025-01-01 00:00:00",
|
||||
"end": "2025-12-31 23:59:59",
|
||||
"presentation": {
|
||||
"files": [{"name": "LPUV4I_Folien_Nowitzki_Bewertungskriterien.pptx"}],
|
||||
"auto_advance": true,
|
||||
"slide_interval": 5,
|
||||
"loop": true
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Start Display Manager:
|
||||
```bash
|
||||
cd src && python3 display_manager.py
|
||||
```
|
||||
|
||||
## Installation Requirements
|
||||
|
||||
### Impressive (Required)
|
||||
```bash
|
||||
sudo apt-get install impressive
|
||||
```
|
||||
|
||||
### LibreOffice (For PPTX Conversion)
|
||||
```bash
|
||||
sudo apt-get install libreoffice
|
||||
```
|
||||
|
||||
### Python Dependencies
|
||||
```bash
|
||||
pip install python-dotenv paho-mqtt
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Presentation doesn't convert
|
||||
- Check LibreOffice is installed: `which libreoffice`
|
||||
- Check conversion logs in `logs/display_manager.log`
|
||||
- Verify presentation file exists in `presentation/` directory
|
||||
|
||||
### Impressive doesn't start
|
||||
- Check installation: `which impressive`
|
||||
- Install if missing: `sudo apt-get install impressive`
|
||||
- Check X11 DISPLAY variable: `echo $DISPLAY` (should be `:0`)
|
||||
|
||||
### Slides don't advance
|
||||
- Verify `auto_advance: true` in event JSON
|
||||
- Check `slide_interval` is set (defaults to 10 seconds)
|
||||
- Review logs for Impressive command being executed
|
||||
|
||||
### Presentation doesn't loop
|
||||
- Verify `loop: true` in event JSON
|
||||
- Check logs confirm `--wrap` parameter is used
|
||||
- Test with test-impressive-loop.sh script
|
||||
|
||||
### Conversion fails with timeout
|
||||
- Large PPTX files may take >60s to convert
|
||||
- Check disk space: `df -h`
|
||||
- Monitor conversion: `tail -f logs/display_manager.log`
|
||||
|
||||
## Abandoned Approaches
|
||||
|
||||
For historical context, these approaches were tried but didn't work reliably on Raspberry Pi:
|
||||
|
||||
❌ **xdotool + LibreOffice** (5 versions tested)
|
||||
- Problem: Window focus issues prevented reliable slide advancement
|
||||
- Versions: v1 (basic), v2 (enhanced focus), v3 (end detection), v4 (active window), v5 (hybrid)
|
||||
|
||||
❌ **Video Conversion**
|
||||
- Problem: Black screen issues, complex conversion process
|
||||
- Tool tested: LibreOffice export to video
|
||||
|
||||
❌ **evince + xdotool**
|
||||
- Problem: Same focus issues as LibreOffice approach
|
||||
|
||||
❌ **Modified PPTX Timings**
|
||||
- Problem: LibreOffice --show parameter doesn't work properly in fullscreen
|
||||
|
||||
## Architecture Benefits
|
||||
|
||||
### Separation of Concerns
|
||||
- **Display Manager**: Event timing, process management, file management
|
||||
- **LibreOffice**: PPTX→PDF conversion (headless, no GUI)
|
||||
- **Impressive**: Presentation display with native features
|
||||
|
||||
### Reliability
|
||||
- No window management hacks (xdotool)
|
||||
- No timing-dependent scripts
|
||||
- Native features = fewer failure points
|
||||
|
||||
### Maintainability
|
||||
- Simple, clean code in Display Manager
|
||||
- Well-documented Impressive parameters
|
||||
- Easy to debug with comprehensive logging
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Possible improvements for future versions:
|
||||
|
||||
1. **Slide Timing Metadata**: Extract slide timings from PPTX and pass to Impressive
|
||||
2. **Multi-Screen Support**: Extend for multiple display outputs
|
||||
3. **Transition Effects**: Utilize Impressive's transition capabilities
|
||||
4. **Remote Control**: Add MQTT commands to control presentation (pause/resume)
|
||||
5. **Thumbnail Cache**: Pre-generate thumbnails for dashboard previews
|
||||
|
||||
## References
|
||||
|
||||
- **Impressive Homepage**: http://impressive.sourceforge.net/
|
||||
- **Impressive Manual**: `man impressive` or `impressive --help`
|
||||
- **LibreOffice Headless**: https://help.libreoffice.org/Common/Starting_in_Headless_Mode
|
||||
- **Display Manager Code**: `src/display_manager.py`
|
||||
- **Test Scripts**: `scripts/test-impressive*.sh`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** October 2025
|
||||
**Status:** ✅ Production Ready
|
||||
**Tested On:** Raspberry Pi 5, Raspberry Pi OS (Bookworm)
|
||||
Reference in New Issue
Block a user