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:

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

impressive --fullscreen --nooverview --auto 5 --wrap presentation.pdf

For single playthrough:

impressive --fullscreen --nooverview --auto 5 --autoquit presentation.pdf

Event JSON Format

Looping Presentation (Typical for Events)

{
  "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

{
  "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)

{
  "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)

   ./scripts/test-impressive.sh
   

2. test-impressive-loop.sh - Test Impressive with loop mode

   ./scripts/test-impressive-loop.sh
   

3. test-display-manager.sh - Interactive testing with Display Manager

   ./scripts/test-display-manager.sh
   

   Then select option 2 (Create PRESENTATION test event)

Manual Testing

Create a test event:

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:

cd src && python3 display_manager.py

Installation Requirements

Impressive (Required)

sudo apt-get install impressive

LibreOffice (For PPTX Conversion)

sudo apt-get install libreoffice

Python Dependencies

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)