infoscreen-dev/PROGRESS_BAR_IMPLEMENTATION.md

# Progress Bar Implementation Summary

## Overview

The Display Manager now supports the scheduler's `page_progress` and `auto_progress` fields to control Impressive's progress bar features during presentations.

## Implementation Details

### Fields Supported

| Field | Type | Impressive Option | Description |
|-------|------|-------------------|-------------|
| `page_progress` | boolean | `--page-progress` (or `-q`) | Shows overall progress bar indicating position in presentation |
| `auto_progress` | boolean | `--auto-progress` (or `-k`) | Shows per-page countdown progress during auto-advance |

### Event Flow

1. **Scheduler sends event** with `page_progress` and `auto_progress` fields
2. **simclient.py receives** and stores complete event in `current_event.json` (no filtering)
3. **display_manager.py reads** event and extracts progress settings
4. **Impressive launches** with appropriate `--page-progress` and/or `--auto-progress` options

## Code Changes

### simclient.py

Enhanced documentation in `save_event_to_json()` to explicitly mention progress bar fields are preserved:

```python
def save_event_to_json(event_data):
    """Speichert eine Event-Nachricht in der Datei current_event.json
    
    This function preserves ALL fields from the incoming event data,
    including scheduler-specific fields like:
    - page_progress: Show overall progress bar in presentation
    - auto_progress: Show per-page auto-advance countdown
    - And any other fields sent by the scheduler
    """
```

### display_manager.py

Added support for reading and using progress fields in `start_presentation()`:

```python
# Get scheduler-specific progress display settings
page_progress = event.get('page_progress', False)  # Show overall progress bar
auto_progress = event.get('auto_progress', False)  # Show per-page auto-advance progress

# Later in Impressive command building:
if page_progress:
    cmd.append('--page-progress')
    logging.info("Page progress bar enabled (shows overall position in presentation)")

if auto_progress:
    cmd.append('--auto-progress')
    logging.info("Auto-progress bar enabled (shows per-page countdown during auto-advance)")
```

## Example Events

### With Page Progress Only

```json
{
  "id": 100,
  "group_id": 2,
  "page_progress": true,
  "auto_progress": false,
  "presentation": {
    "auto_advance": true,
    "slide_interval": 10,
    "loop": true,
    "files": [{"name": "slides.pdf"}]
  }
}
```

**Result:** Impressive shows overall progress bar at bottom: `[=====>    ] 50%`

### With Auto-Progress Only

```json
{
  "id": 101,
  "group_id": 2,
  "page_progress": false,
  "auto_progress": true,
  "presentation": {
    "auto_advance": true,
    "slide_interval": 10,
    "files": [{"name": "slides.pdf"}]
  }
}
```

**Result:** Impressive shows countdown bar for each slide during auto-advance

### With Both Progress Bars

```json
{
  "id": 102,
  "group_id": 2,
  "page_progress": true,
  "auto_progress": true,
  "presentation": {
    "auto_advance": true,
    "slide_interval": 10,
    "loop": true,
    "files": [{"name": "slides.pdf"}]
  }
}
```

**Result:** Both progress indicators visible simultaneously

### No Progress Bars (Default)

```json
{
  "id": 103,
  "group_id": 2,
  "presentation": {
    "auto_advance": true,
    "slide_interval": 10,
    "files": [{"name": "slides.pdf"}]
  }
}
```

**Result:** Clean presentation without progress indicators (fields default to `false`)

## Testing

### Interactive Test Script

```bash
cd ~/infoscreen-dev/scripts
./test-progress-bars.sh
```

This interactive script allows you to:
1. Select a progress bar configuration (none, page only, auto only, or both)
2. Sends test event to MQTT
3. Verifies Display Manager processes it correctly
4. Shows expected behavior

### Manual Testing with mosquitto_pub

```bash
# Test with both progress bars
mosquitto_pub -h localhost -t "infoscreen/events/2" -m '{
  "id": 999,
  "page_progress": true,
  "auto_progress": true,
  "presentation": {
    "auto_advance": true,
    "slide_interval": 5,
    "loop": true,
    "files": [{"name": "test.pdf"}]
  }
}'
```

### Verification

1. **Check Display Manager Log:**
   ```bash
   tail -f ~/infoscreen-dev/logs/display_manager.log
   ```
   
   Look for:
   ```
   Page progress bar enabled (shows overall position in presentation)
   Auto-progress bar enabled (shows per-page countdown during auto-advance)
   ```

2. **Check Impressive Command:**
   ```bash
   ps aux | grep impressive
   ```
   
   Should show command with appropriate options:
   ```
   impressive --fullscreen --nooverview --auto 5 --wrap --page-progress --auto-progress /path/to/file.pdf
   ```

3. **Visual Verification:**
   - Watch the presentation on the display
   - Page progress: Bar at bottom showing position
   - Auto-progress: Countdown overlay on each slide

## Impressive Command Examples

```bash
# No progress bars (default)
impressive --fullscreen --auto 10 --wrap presentation.pdf

# Page progress only
impressive --fullscreen --auto 10 --wrap --page-progress presentation.pdf
impressive --fullscreen --auto 10 --wrap -q presentation.pdf  # Short form

# Auto-progress only
impressive --fullscreen --auto 10 --wrap --auto-progress presentation.pdf
impressive --fullscreen --auto 10 --wrap -k presentation.pdf  # Short form

# Both progress bars
impressive --fullscreen --auto 10 --wrap --page-progress --auto-progress presentation.pdf
impressive --fullscreen --auto 10 --wrap -q -k presentation.pdf  # Short form
```

## Benefits

1. **User Feedback**: Viewers know where they are in the presentation
2. **Time Awareness**: Auto-progress shows how long until next slide
3. **Professional Look**: Progress indicators enhance presentation quality
4. **Flexible Control**: Scheduler can enable/disable per event
5. **Backward Compatible**: Fields default to `false`, existing events work unchanged

## Compatibility

- ✅ **Impressive**: Full support for both progress bar features
- ⚠️ **Evince/Okular**: Fallback viewers don't support progress bars (features ignored)
- ✅ **PDF Files**: Native support with no conversion needed
- ✅ **PPTX Files**: Automatic conversion to PDF, then progress bars work

## Documentation Updates

- ✅ README.md - Added progress bar field documentation
- ✅ SCHEDULER_FIELDS_SUPPORT.md - Updated with implementation details
- ✅ Code comments - Enhanced docstrings
- ✅ Test scripts - Created test-progress-bars.sh
- ✅ This summary document

## Logging

With `LOG_LEVEL=DEBUG`, you'll see:

```
[INFO] Event page_progress = true
[INFO] Event auto_progress = true
[INFO] Starting presentation: slides.pdf
[INFO] Auto-advance enabled (interval: 10s)
[INFO] Loop mode enabled (presentation will restart after last slide)
[INFO] Page progress bar enabled (shows overall position in presentation)
[INFO] Auto-progress bar enabled (shows per-page countdown during auto-advance)
[DEBUG] Full command: impressive --fullscreen --nooverview --auto 10 --wrap --page-progress --auto-progress /path/to/slides.pdf
```

## Summary

✅ **Implementation complete** - Progress bar fields are now fully supported  
✅ **Backward compatible** - Existing events without these fields work unchanged  
✅ **Well documented** - README, code comments, and test scripts updated  
✅ **Tested** - Interactive test script available  
✅ **Flexible** - Both options can be used independently or together  
✅ **Clean code** - Minimal changes, follows existing patterns