infoscreen-dev/IMPRESSIVE_INTEGRATION.md

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