picframe next generation

[helgeerbe]

Actual im thinking about a fundamental change of picframe architecture

[sapnho]

Care to share a bit more? Curious nature I am...

[helgeerbe]

Architecture Solution Document: Picframe Next Gen. Modernization

1. Executive Summary

This document outlines the comprehensive architectural redesign of the picframe project. The goal is to transition from a tightly coupled, synchronous script to a modern, modular, and highly performant system. This modernization leverages Clean Architecture (Hexagonal) and a Strict Event-Driven Architecture (EDA) to support dynamic configuration via a FastAPI/Vue.js stack, robust state management, and hardware-accelerated video playback using GStreamer alongside pi3d for image transitions.

2. Architectural Concept & Reasoning

The Picframe Next Gen. architecture is built upon several advanced software design patterns to ensure strict testability, maintainability, and thread safety in a concurrent Python environment.

2.1 Clean Architecture (Hexagonal)

• Concept: The system is divided into strict, concentric layers (Domain, Application, Adapters, Infrastructure) where dependencies only point inwards. The core business logic has no knowledge of the UI, databases, or external frameworks.
• Reasoning & Benefits: This decouples the core media orchestration from the presentation and control layers. It allows us to swap out the UI (e.g., Vue.js instead of a local GUI) or the database (SQLite instead of YAML) without touching the core logic. It also enables pure unit testing of the business rules by mocking the outer layers. To enforce this, legacy "God Objects" are dismantled into dedicated services:
  • HardwareInputService (Control Plane): Monitors GPIO (PIR sensors, buttons) and publishes HardwareEvents.
  • ImageProcessingService (Application Layer): Handles CPU-intensive image matting and caching before rendering.
  • DisplayPowerManager (Infrastructure Layer): Manages OS-level screen power (vcgencmd, xset) independently of the pixel renderer.

2.2 Strict Event-Driven Architecture (EDA) & PriorityQueue

• Concept: Components communicate exclusively by publishing and subscribing to events via a central Event Bus, implemented using a custom, thread-safe queue.PriorityQueue.
• Reasoning & Benefits: In a multithreaded environment where FastAPI and MQTT run in background threads while pi3d requires the Main Thread, direct method calls cause blocking and crashes. The Event Bus acts as a safe bridge. The PriorityQueue ensures that critical commands (like an immediate user "Pause" or "Next" request) bypass standard background state updates, providing a highly responsive user experience.

2.3 Interface Segregation Principle (ISP)

• Concept: The Event Bus does not expose a monolithic interface. Instead, it is split into IEventPublisher (for sending events) and IEventSubscriber (for receiving events).
• Reasoning & Benefits: This prevents cross-talk and enforces strict boundaries. A component like the FastAPI backend only needs to publish commands and subscribe to state changes; it cannot accidentally consume commands meant for the rendering engine. This makes the contracts between components explicit and easier to mock in tests.

2.4 Command Pattern & Immutable DTOs

• Concept: All data passed through the Event Bus is encapsulated in Data Transfer Objects (DTOs) defined as @dataclass(frozen=True).
• Reasoning & Benefits: Immutability guarantees thread safety. Once an event (e.g., CommandEvent, StateEvent) is created by a background thread, it cannot be altered while sitting in the queue or being processed by the Main Thread. This eliminates race conditions and makes the system's state highly predictable and easy to debug.

2.5 Separation of Concerns (SoC): Orchestration

• Concept: The monolithic state machine is split into two distinct components:
  • PlaylistManager: Handles media querying, filtering, shuffling, and history.
  • PlaybackEngine: Manages the playback state (Playing, Paused, Transitioning) and timing.
• Reasoning & Benefits: Prevents the creation of a "God Object." The PlaylistManager can be tested purely for its logic (e.g., "does shuffle work?"), while the PlaybackEngine can be tested purely for its state transitions (e.g., "does it pause correctly?"), reducing cognitive load and test complexity.

2.6 Dual-Database Strategy (Repository Pattern)

• Concept: Configuration and media metadata are strictly separated into config.db3 (persistent user settings) and media_cache.db3 (ephemeral media metadata).
• Reasoning & Benefits: Prevents lifecycle conflicts. Rebuilding the media cache (which happens frequently) will never risk corrupting user configuration. The Repository Pattern abstracts the SQLite implementation, allowing the business logic to interact with simple Python objects rather than SQL queries.

2.7 Decoupling Presentation from Domain Logic (SRP)

• Concept: The Presentation Layer (Pi3dRenderer) is strictly a "dumb" component responsible only for drawing pixels. It receives a RenderCommand and executes it. All domain logic, including metadata extraction and publication, is handled by the PlaybackEngine.
• Reasoning & Benefits: Violations of the Single Responsibility Principle (SRP), such as having the render loop extract and publish metadata, cause unpredictable latency and frame drops. By shifting this responsibility to the PlaybackEngine, the Main Thread remains unblocked. The PlaybackEngine retrieves an immutable MediaItem DTO from the PlaylistManager, instructs the renderer, and immediately publishes a MediaChangedEvent to the Event Bus. Background threads (FastAPI, MQTT) consume this event asynchronously, ensuring network I/O never pollutes the synchronous render loop.

2.8 Asynchronous Media Monitoring

• Concept: A dedicated MediaMonitorService (utilizing watchdog) runs in a background thread to detect file system changes (Create, Modify, Delete) in configured media directories. It publishes immutable FileChangeEvent DTOs to the Event Bus.
• Reasoning & Benefits: Eliminates the need for synchronous, blocking directory scans during playback. When a FileChangeEvent is consumed by the Media Orchestrator, it asynchronously triggers the MetadataExtractor to update the ephemeral media_cache.db3 and signals the PlaylistManager to adjust the active playlist. This ensures the system reacts to new media in real-time without interrupting the render loop.

2.9 Hardware Abstraction Layer (HAL) & Cross-Platform Ports

• Concept: To support native execution across Raspberry Pi (Wayland/X11), Ubuntu, and macOS, OS-specific interactions are abstracted behind strict Port interfaces (e.g., IDisplayPower, IHardwareInput, ISystemManager).
• Reasoning & Benefits: The core application logic must remain OS-agnostic. By defining Ports in the Application layer and implementing OS-specific Adapters in the Infrastructure layer (e.g., WaylandDisplayPower, MacDisplayPower, MockHardwareInput), the Composition Root (main.py) can detect the host OS at startup and inject the correct concrete implementation. This prevents if os.name == '...' spaghetti code from polluting the domain logic and allows developers to run and test the core engine on macOS/Ubuntu without requiring physical Raspberry Pi hardware.

3. System Diagrams

3.1 Component Architecture

This diagram illustrates the strict layers and dependencies of the system, highlighting how the Composition Root wires the application together and how the Event Bus acts as the central nervous system.

graph TD
    subgraph ControlPlane [Background Threads]
        API[FastAPI / Uvicorn]
        UI[Vue.js SPA]
        MQTT[MQTT Client]
        MON[MediaMonitorService]
        HW[HardwareInputService]
        SCH[SchedulerService]
    end

    subgraph EventBus [Thread-Safe PriorityQueue]
        PUB[IEventPublisher]
        SUB[IEventSubscriber]
    end

    subgraph MediaOrchestrator [Main Thread]
        PE[PlaybackEngine]
        PM[PlaylistManager]
        IPS[ImageProcessingService]
    end

    subgraph PresentationLayer [Main Thread / Subprocess]
        PI3D[Pi3dRenderer]
        GST[GstVideoRenderer]
        DPM[DisplayPowerManager]
        SYS[SystemManager]
    end

    subgraph DataLayer [Repositories]
        DB_CONF[(config.db3)]
        DB_MEDIA[(media_cache.db3)]
    end

    %% Relationships
    UI <-->|REST / WebSockets| API
    API -->|Publish Commands| PUB
    MQTT -->|Publish Commands| PUB
    MON -->|Publish FileEvents| PUB
    HW -->|Publish HardwareEvents| PUB
    SCH -->|Publish Commands| PUB
    
    PUB -->|Route Events| SUB
    
    SUB -->|Consume Commands| PE
    SUB -->|Consume Commands| DPM
    SUB -->|Consume Commands| SYS
    PE <-->|Request Media| PM
    PE <-->|Process Images| IPS
    
    PE -->|Render Commands| PI3D
    PE -->|Render Commands| GST
    
    PM -->|Query| DB_MEDIA
    API -->|Read/Write| DB_CONF
    
    %% Styling
    classDef thread fill:#f9f,stroke:#333,stroke-width:2px;
    classDef main fill:#bbf,stroke:#333,stroke-width:2px;
    class PE,PM,IPS,PI3D main;
    class API,MQTT,MON,HW,SCH thread;

Loading

3.2 Concurrency & Event Flow

This sequence diagram demonstrates the lifecycle and flow of immutable events between the background threads (Control Plane), the Event Bus, and the synchronous Main Thread (Orchestrator & Renderers).

sequenceDiagram
    participant User as User / UI
    participant API as FastAPI (Background Thread)
    participant Bus as PriorityQueue Event Bus
    participant PE as PlaybackEngine (Main Thread)
    participant PM as PlaylistManager (Main Thread)
    participant Render as Pi3dRenderer (Main Thread)

    User->>API: POST /control/next
    Note over API: Create Immutable DTO<br/>CommandEvent(NEXT)
    API->>Bus: publish(CommandEvent(NEXT), priority=1)
    
    loop Main Thread Render Loop
        PE->>Bus: poll() (Non-blocking)
        Bus-->>PE: CommandEvent(NEXT)
        
        Note over PE: Process High-Priority Command
        PE->>PM: get_next_media()
        PM-->>PE: MediaItem(image.jpg)
        
        PE->>PE: Update State to TRANSITIONING
        PE->>Render: execute(RenderCommand(image.jpg))
        Render-->>PE: Render Complete
        
        PE->>PE: Update State to PLAYING
        Note over PE: Create Immutable DTO<br/>StateEvent(PLAYING, image.jpg)
        PE->>Bus: publish(StateEvent)
    end
    
    Bus-->>API: StateEvent (via WebSocket Subscriber)
    API-->>User: WebSocket Update (State: PLAYING)

Loading

4. Gap Analysis Resolutions & Mitigation Strategies

4.1 The Main Loop Concurrency Conflict

• The Problem: pi3d (OpenGL) must run in the Main Thread. FastAPI/Uvicorn also typically expects the Main Thread. Running both synchronously causes blocking and crashes.
• The Mitigation: The Main Thread is owned exclusively by the pi3d render loop and the PlaybackEngine event consumer. FastAPI/Uvicorn and the MQTT client run in isolated background threads. The PriorityQueue Event Bus bridges them safely.

4.2 Configuration Migration Adapter

To prevent data loss for existing users, a Migration Adapter will run on startup. If config.db3 is missing, it will parse the legacy configuration.yaml, populate the database, and rename the YAML file to indicate successful migration.

4.3 Event Bus "Poison Pill" Handling

To ensure system resilience, the PlaybackEngine will implement a global exception boundary. If a corrupted event (e.g., a bad media file) causes an error, the exception is caught, a SystemErrorEvent is published (for the UI), and the state machine resets to IDLE, preventing the Main Thread from crashing.

4.4 Dynamic Overlays & Clock Management

• The Problem: The legacy viewer_display.py managed a live clock that updated every minute. If the Pi3dRenderer is strictly "dumb" and only updates when the PlaybackEngine sends a new image (e.g., every 10 minutes), the clock will freeze.
• The Mitigation: The RenderCommand will include an OverlayConfig DTO. The Pi3dRenderer is permitted to manage its own internal 1-second tick exclusively for updating the clock string on the screen. This keeps the Event Bus free of high-frequency, low-value traffic while maintaining the live clock feature.

4.5 Audio & Volume Control

• The Problem: Video playback includes audio, and the legacy system allowed volume control via MQTT.
• The Mitigation: The CommandEvent DTO will include a SET_VOLUME variant. The PlaybackEngine routes this command to the GstVideoRenderer, which implements the GStreamer volume properties to adjust audio output dynamically.

4.6 Cross-Platform Rendering (pi3d)

• The Problem: pi3d relies on EGL/OpenGL ES, which behaves differently across Raspberry Pi (Wayland vs. X11), Ubuntu, and macOS.
• The Mitigation: The Pi3dRenderer will utilize a factory pattern to instantiate the correct pi3d.Display backend based on the OS detected by the Composition Root. On macOS/Ubuntu, it will default to a windowed X11/SDL2 context for development, while on Raspberry Pi, it will attempt native Wayland/DRM fullscreen contexts.

[helgeerbe]

Frontend Specification: Picframe Next Gen. (Vue.js SPA)

1. Executive Summary

This document outlines the frontend architecture and user interface specification for the Picframe Next Gen Single Page Application (SPA). Built with Vue.js 3, the SPA serves as the primary control plane for the digital picture frame, communicating with the FastAPI backend via REST APIs for configuration and WebSockets for real-time playback state.

2. Technology Stack

• Framework: Vue.js 3 (Composition API, <script setup>)
• Build Tool: Vite (for fast HMR and optimized production builds)
• State Management: Pinia (replaces Vuex for modular, type-safe state)
• Routing: Vue Router 4
• Styling: Tailwind CSS (for responsive, utility-first design) + Headless UI components (e.g., modals, toggles)
• Map Integration: Leaflet.js (leaflet and @vue-leaflet/vue-leaflet) for OpenStreetMap rendering.
• Network: axios (REST API) and native browser WebSocket API.

3. Core Architecture & Data Flow

3.1 State Management (Pinia Stores)

• usePlayerStore: Manages the WebSocket connection to ws://<ip>/ws/state. It holds the current MediaItem DTO, playback status (playing/paused), and current brightness. It automatically updates the UI when the backend broadcasts a MediaChangedEvent or StateEvent.
• useConfigStore: Manages REST API interactions (GET /api/config, PUT /api/config) for the Administrative Dashboard.
• useSystemStore: Handles maintenance operations and system state commands (Reboot, Shutdown).

3.2 Responsive Design Strategy

The UI follows a mobile-first approach. On mobile devices, the layout stacks vertically (Media Player on top, Metadata below). On desktop/tablet, it utilizes a multi-column grid (Media Player on the left, Metadata/Map on the right).

---

4. View 1: Media Player Interface ("The Remote")

This view acts as the real-time remote control and information display for the currently playing media.

4.1 Media Display & Playback Controls

• Current Media Preview: A responsive image/video container displaying a low-resolution thumbnail or the actual image currently rendered on the Pi.
• Transport Controls: A sticky or prominent control bar featuring:
  • Previous (Skip to previous media)
  • Play/Pause (Toggle playback state, icon changes dynamically based on WebSocket state)
  • Next (Skip to next media)
• Display Brightness: A horizontal slider component bound to the backend brightness state. Dragging the slider emits a CommandEvent(SET_BRIGHTNESS) via WebSocket or REST.

4.2 Metadata Panel

A dedicated panel surfacing the MediaItem DTO properties:

• File Info: Filename, directory, resolution, file size, and media type.
• EXIF Data: Camera Make/Model, Aperture, Shutter Speed, ISO, Focal Length, and original capture Date/Time.
• Caption/Tags: Any associated IPTC tags or user-defined captions.

4.3 Dynamic OpenStreetMap Component

• Trigger: Conditionally rendered only if the current MediaItem DTO contains valid latitude and longitude properties.
• Implementation: Uses Leaflet.js to embed an interactive OpenStreetMap.
• Features:
  • Centers the map on the media's coordinates.
  • Places a custom marker at the exact location.
  • Displays reverse-geocoded location text (e.g., "Berlin, Germany") fetched from the metadata above the map.

---

5. View 2: Administrative Dashboard ("Settings")

This view provides robust configuration and system management, protected by basic authentication if configured.

5.1 Configuration Management

A comprehensive form interface mapping to the config.db3 schema.

• Sections: Grouped logically (e.g., Directories, Playback Settings, MQTT, Display).
• Actions:
  • Save Changes: Sends a PUT /api/config request.
  • Export Configuration: Triggers a download of the current configuration as a JSON or YAML file.
  • Import Configuration: A file upload component that accepts a JSON/YAML file, parses it, and overwrites the current settings via POST /api/config/import.

5.2 Advanced Maintenance Operations

A dedicated "Danger Zone" or Maintenance tab for system-level operations. All actions here require a confirmation modal to prevent accidental clicks.

• Database Management:
  • Purge Media Database: Sends a command to drop all tables in media_cache.db3 and triggers a full background rescan. Useful if the database is corrupted or out of sync.
• Cache Management:
  • Clear Image Cache: Deletes all pre-processed matting images and resized thumbnails from the disk cache, freeing up space.
• System Power States:
  • Reboot System: Sends a CommandEvent(REBOOT) to the SystemManager.
  • Shutdown System: Sends a CommandEvent(SHUTDOWN) to the SystemManager.

6. API Integration Contract

6.1 WebSockets (/ws/state)

• Incoming (from Backend): { "type": "MediaChangedEvent", "media": { "file_path": "...", "exif": {...}, "location": {"lat": 52.5, "lon": 13.4} } }
• Outgoing (from UI): { "command": "NEXT" }, { "command": "PAUSE" }, { "command": "SET_BRIGHTNESS", "value": 0.8 }

6.2 REST Endpoints

• GET /api/config -> Returns full configuration JSON.
• PUT /api/config -> Updates configuration.
• POST /api/maintenance/purge-db -> Triggers database rebuild.
• POST /api/maintenance/clear-cache -> Clears image cache.
• POST /api/system/reboot -> Reboots host OS.

[sapnho]

Quite a list! Is it more of an architectural change, or where do you see the biggest benefits for the average user? Improving high-res video playback would come to my mind.

[helgeerbe]

1. First of all, the code has to become maintanable again. Well this is not for the average user, but hopefulliy avoid too much head ache for the developers in the future.
2. Responsive UI (without home assistant, you will get a nice media player. remote controll)
3. Config changes will have instant effect and will survive restarts.
4. no more messing around with the yaml config files.

high-res video playback depends on the gpu capabilities of the raspberry. I haven't testet gstreamer in combination with pi3d yet. But I hope we can use the hardware more effectively.

[sapnho]

Wonderful! Thank you for the initiative. Last time I checked, my Pi 5 got so hot during 4k playback that it was basically unusable. But I must admit that having video in between images is quite appealing.

[helgeerbe]

I will write a small test script for video playing. Would be good if you can run this on your pi5. I'm still using pi3.

[helgeerbe]

This is my actual Work Breakdown Structure:

5. Work Breakdown Structure (WBS)

Note: This WBS is structured into Vertical Slices. Each phase delivers a functional, testable increment of the product, ensuring continuous usability rather than relying on a final "big bang" integration.

Phase 0: Technical Spike (Video Handoff PoC)

Goal: De-risk the most complex technical challenge by proving the seamless EGL/OpenGL context handoff between pi3d and GStreamer on target hardware before building the full architecture.

• Task 0.1: Develop a standalone Python script accepting an image, a video, and display dimensions.
• Task 0.2: Implement the pi3d rendering loop to load the image and alpha-blend into the extracted first frame of the video.
• Task 0.3: Integrate a GStreamer pipeline (enforcing hardware decoding e.g., v4l2h264dec) and manage window Z-order/layering to ensure it renders correctly relative to pi3d.
• Task 0.4: Implement an IPC/Bus watch mechanism to detect the GStreamer End of Stream (EOS) signal.
• Task 0.5: Trigger the pi3d alpha-blend from the extracted last frame of the video to the next image upon EOS.
• Task 0.6: Capture and output performance metrics (pi3d FPS during blend, transition latency, CPU/RAM usage).

Phase 1: Core Image MVP (The "Walking Skeleton")

Goal: A functional, headless digital picture frame that reads from SQLite and renders images via pi3d in a continuous loop.

• Task 1.1: Modernize packaging (PEP 621): Migrate to pyproject.toml, setuptools_scm, and configure developer tooling (pytest, mypy, ruff).
• Task 1.2: Implement the thread-safe PriorityQueue Event Bus with IEventPublisher/IEventSubscriber interfaces and define core Immutable DTO Events.
• Task 1.3: Implement the Dual-Database Repositories (IConfigRepository, IMediaRepository) using SQLite.
• Task 1.4: Implement the Unified MetadataExtractor (Strategy Pattern for images) and decouple GeoReverse API calls.
• Task 1.5: Implement the PlaylistManager (media querying, filtering, shuffle logic) and ImageProcessingService (matting/caching).
• Task 1.6: Refactor ViewerDisplay into a decoupled Pi3dRenderer that only responds to RenderCommands.
• Task 1.7: Implement the PlaybackEngine (State Machine) and the Composition Root (main.py) to wire dependencies and start the main render loop.

Phase 2: Control Plane & UI

Goal: Make the MVP controllable via a modern Web UI, MQTT, and physical buttons, with real-time state reflection.

• Task 2.1: Implement the FastAPI backend (running on Uvicorn) with REST API endpoints and WebSocket routing for real-time state updates.
• Task 2.2: Develop the Vue.js Single Page Application (SPA) according to the Frontend_Specification.md (Media Player with OSM integration, Admin Dashboard).
• Task 2.3: Refactor the MQTT client to publish CommandEvents to the Event Bus instead of direct method calls.
• Task 2.4: Define the IHardwareInput port and implement the HardwareInputService with OS-specific adapters (e.g., RPiGPIOAdapter, MockInputAdapter for macOS).

Phase 3: Video Engine Integration

Goal: Add multimedia support with seamless transitions between images and hardware-accelerated video.

• Task 3.1: Extend MetadataExtractor with the VideoMetadataStrategy (using ffprobe).
• Task 3.2: Create the GstVideoRenderer script utilizing hardware-accelerated pipelines (v4l2h264dec).
• Task 3.3: Implement IPC command handling and bus message monitoring (EOS, ERROR) for the GStreamer subprocess.
• Task 3.4: Implement the precise handoff logic in the PlaybackEngine (pi3d alpha to 0 -> GStreamer PLAYING).

Phase 4: Advanced System Services & Polish

Goal: Feature-complete, production-ready system with background monitoring, scheduling, and legacy migration support.

• Task 4.1: Implement the MediaMonitorService (using watchdog) to run in a background thread and publish FileChangeEvents.
• Task 4.2: Implement the SchedulerService to handle time-based display sleep/wake schedules.
• Task 4.3: Define the IDisplayPower port and implement the DisplayPowerManager with OS-specific adapters (WaylandPower, XsetPower, MacPower).
• Task 4.4: Define the ISystemManager port and implement OS-specific adapters for reboot/shutdown commands.
• Task 4.5: Implement the Configuration Migration Adapter (YAML to config.db3).
• Task 4.6: Comprehensive integration testing, verify "Poison Pill" error handling, and clean up legacy code (remove VLC dependencies, old setup.py).

[sapnho]

Happy to provide testing support anytime!

[paddywwoof]

Sounds good and I'm happy to be allocated a slice once I'm home in a week or two, sensible to do the vertical split to start with.

Reading the mutability issues you're working round makes me think we should have written picframe in Rust (much nicer and faster than python, but probably too late now!) I did convert much of the core functionality of pi3d to Rust, but it still uses the same OpenGL system behind the scenes.

Anyway, I'll keep an eye out as the ideas form.

Paddy

[paddywwoof]

PS having an event engine running separately makes it possible to have 'oversight' of components crashing so they can be restarted and logged even in the event of unforeseen exceptional issues.

[paddywwoof]

Also, I think we need to test at an early stage that the lighter weight, low memory raspberry Pis, such a zero, can run the JavaScript OK. I vaguely remember that being an issue somewhere. We can probably abandon the v. 1 and 2 Pis, but some of the modern web architecture assumes a reasonably 'meaty' setup for the client, albeit in a mobile device.

[paddywwoof]

Another thing that I've intended to do in pi3d for a long time is make a system to enable testing. It would have to set the display dimensions to a standard value, use a standard image and geometry then screen capture and compare with a previously recorded image.

[paddywwoof]

Helge, you're making brilliant progress on this project.

I wonder if this might be a good time to update the pi3d_Renderer scope and functionality. We have four parts to the pi3d stuff: image, text, clock and overlay. For tidyness these could all be in their own classes (and files, so pi3d_Image_Renderer etc) as pi3d will return an instance of the Display object if one has already been created in the current application (self.__display = pi3d.Display.Display.INSTANCE). Done this way the engine would then have to render each of them. I have thought for a while that it might be tidier for picframe render loop to operate a little more as a state machine as there is messy conditional block code with the image fading, text fading in and out and ken_burns transition. If the total slide duration is too short things start to overlap and go wrong.

I don't think this needs to be on the main event bus as the render loop can't afford the luxury of being asynchronous or having arbitrary delays, but it could be done with a pi3d renderer (in the engine?) local service of PriorityQueue objects. There aren't too many events I think: externally:
a restart due to a BACK, NEXT or following image in normally play, maybe this isn't needed as it's the same as doing execute() and managed by the engine? But the text, clock etc animation states would need to be reset. Internal events would be to signal from the image renderer that transition and ken burns were complete and text animation could start and probably also from the text renderer when that animation was finished. Is the engine _run_loop() where you intend to check if clock.sprite or overlay need to be redrawn?

Although pi3d was mainly envisioned as a synchronous loop with blocking delay in the Display.loop_running() method. It doesn't have to be. If nothing is changing in the rendered output then the display buffer will just stay there. I don't know that this is a worthwhile benefit for energy saving or processor load, but while a video is playing over the pi3d image the loop_running() could definitely be skipped. If we did this for normal image rendering then this where we would need the event that all animations had finished.

[helgeerbe]

Hi @paddywwoof,

Thank you so much for reaching out as your insights are incredibly valuable, and I completely agree with your assessment of the current rendering architecture.

Your suggestions align perfectly with the goals for the upcoming Phase 2C (Rendering Parity & Enhancements) of the modernization effort. I'm going to directly implement your proposed architectural changes for the rendering engine.

Here is a breakdown of how I plan to implement your suggestions:

1. Componentization of Renderers: We will split the monolithic Pi3dRenderer into distinct, focused classes (ImageRenderer, TextRenderer, ClockRenderer, OverlayRenderer). As you suggested, they will all share the same pi3d.Display singleton but handle their own specific drawing logic. The main Pi3dRenderer will act as a facade/manager for these components.
2. Render Loop State Machine: We are moving away from the messy conditional blocks for fading and Ken Burns effects. Instead, we will implement a formal state machine within the render loop to handle the lifecycle of a slide cleanly (e.g., Transitioning -> KenBurnsActive -> TextFadingIn -> Static). This will prevent overlapping animations when slide durations are short.
3. Local Render Event Queue: We will introduce a local PriorityQueue specifically for the rendering engine. This will keep high-frequency, synchronous render events (like "image transition complete, start text fade") off the main application EventBus, ensuring the render loop doesn't suffer from asynchronous delays.
4. CPU/Energy Optimization: By tracking the overall animation state, the engine will be able to skip pi3d.Display.loop_running() when the screen is completely static (all animations finished) or when a video is playing over the pi3d layer. This should significantly reduce CPU load and power consumption.

[helgeerbe]

The mvp is working. But i have still over 30 Tickets open. Much more work as I thought. As soon I reach alpha status, it would be very helpful, if you could start testing, and translating (english, german). For a first release I want feature parity. But somtimes it's hard to find the features, as the are hidden all over the legacy code.

Sneak preview.

• multiple languages
• config and settings persistently stored in a database
• Eventdriven. So all changes in the ui are instantly visable in the picframe
• Beside MQTT I implemented a REST API

[sapnho]

Wow!

[pyrced]

This is very exciting, I'd love to try and test it when it's ready to go.