diff --git a/documentation/GUIDE__AE_Events_Onsite_Runbook.md b/documentation/GUIDE__AE_Events_Onsite_Runbook.md new file mode 100644 index 00000000..7fd7df1e --- /dev/null +++ b/documentation/GUIDE__AE_Events_Onsite_Runbook.md @@ -0,0 +1,85 @@ +# Guide — Aether Events: Onsite Runbook + +This guide covers the human-centric logistics and "In the Heat of the Moment" support for onsite event operations using Presentation Management and the Launcher. + +--- + +## Speaker Ready Room (SRR) + +The SRR is the central hub for content management and presenter support. + +### SRR Practice Stations +Stations mirror the session room setup exactly: +- Same Mac laptop model and adapter/dongle configuration as the podiums. +- Projector and screen (where possible). +- Launcher running in **Native** mode — ensures verification matches the podium experience. + +### Staffing Roles + +| Role | Access Level | Typical Tasks | +|---|---|---| +| **OSIT Staff** | `trusted_access` | Manage devices, monitor via VNC, deep troubleshooting. | +| **Client Staff** | `authenticated_access` | Upload files, view session lists, assist presenters. | +| **Presenter** | `authenticated_access` | Self-upload via QR link (if enabled). | + +### SRR Workflow — Day-of-Show +1. **Check-in:** Staff looks up the presenter's session in Presentation Management. +2. **Upload:** File is uploaded to the presenter/session record. +3. **Verification:** Staff opens the file on a practice station to confirm rendering. +4. **Launcher Sync:** File propagates to the podium. Use **Force Sync Location** in the Launcher config if immediate full-room caching is needed. +5. **Proceed:** Presenter walks to the room; the podium kiosk already has the file cached. + +--- + +## Onsite Operation (Managing Parallel Rooms) + +### SRR Overview Page +The Pres Mgmt overview (`/events/[id]/pres_mgmt`) is the "Command Center": +- Monitor file status per session. +- Filter by location and time block to stay ahead of active sessions. + +### Per-Room Monitoring +- Use **VNC or RustDesk** to monitor all podium screens in real time from the SRR. +- Confirm "Native Sync" status chip in the bottom-left of the Launcher is green/idle before sessions start. + +### Session Transitions +- **Timing:** Ideally, sessions show/hide based on `datetime_start`. +- **Manual Control:** In looser schedules, use Launcher controls to manually select the current session. + +--- + +## Pre-Show Checklist + +### 1–2 Weeks Before +- [ ] Event created with correct dates and timezone. +- [ ] `mod_pres_mgmt_json` configured for client needs. +- [ ] Locations (rooms) created and named. +- [ ] Sessions created, assigned to locations, and timed. +- [ ] Launcher devices (`event_device`) registered with correct codes. +- [ ] Device-to-location assignments confirmed. + +### Day Before (SRR Setup) +- [ ] Mac laptops at podiums booted; Electron app running. +- [ ] Each podium confirms it loaded the correct room's Launcher. +- [ ] SRR practice stations confirmed (matching hardware). +- [ ] Run **Force Sync Location** on all podiums to pre-cache all day-1 content. +- [ ] VNC/RustDesk connections established to all podiums. + +### Day of Show +- [ ] Confirm all session times are accurate before the first block. +- [ ] Monitor SRR queue and verify every file on a practice station. +- [ ] Check VNC wall to ensure all podiums are online and synced. + +--- + +## Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| Session not in Launcher | Datetime wrong or Location unassigned. | Verify session metadata in Pres Mgmt. | +| File uploaded but missing | Polling lag or attached at wrong level. | Wait 30s; check if file is at Session vs Presenter level. | +| File opens slowly | Not in native cache yet. | Check "Native Sync" chip; use Force Sync in config. | +| File won't open | Corrupt upload or missing Mac codec. | Test on SRR station; convert or re-upload. | +| Drifted schedule | Room timing shifted. | Use Launcher controls to manually select the active session. | +| `lock_config` resets changes | Remote config is forced. | Edit the master `mod_pres_mgmt_json` in Event Settings. | +| Move laptop to new room | Hardware reassignment. | Update `location_id` in `event_device` record; restart Electron. | diff --git a/documentation/MODULE__AE_Events_Launcher.md b/documentation/MODULE__AE_Events_Launcher.md new file mode 100644 index 00000000..f2aa85e8 --- /dev/null +++ b/documentation/MODULE__AE_Events_Launcher.md @@ -0,0 +1,79 @@ +# Aether Events — Launcher (Podium Display) + +The Launcher module provides the podium display interface that runs on each session room's kiosk machine. It is designed to work in standard browsers but is optimized for the **Aether Desktop (Electron)** native shell. + +--- + +## Operational Modes + +| Mode | Use Case | File Handling | +|---|---|---| +| **Default** | Browser on any machine | Files downloaded on demand via browser. | +| **Onsite** | Browser on event network | Faster polling; browser-managed files. | +| **Native** | Electron app on podium Mac | Background pre-cache; atomic file handover. | + +For production onsite use, **Native mode on Mac laptops** is the target. The Electron +app pre-caches all session files in the background so presentations open instantly without +a network round-trip at the moment of launch. + +--- + +## Launcher Display Views + +| View | Shown When | +|---|---| +| **Session view** | Active session with session-level files. | +| **Presentation view** | Active session with named presentations. | +| **Presenter view** | Presentation selected; shows presenter bio/photo. | +| **Poster/group view** | Special layout for poster sessions. | +| **Screensaver** | No active session; idle state. | + +--- + +## Sync Engine & File Handling + +### Background Sync (File Warming) +When a user navigates to a session in the Launcher UI, the background engine automatically warms the cache for that specific session by downloading all associated files. + +### Force Sync Location +To ensure full room readiness (e.g., during SRR setup or overnight), operators can trigger a **Force Sync Location** via the configuration menu. This performs a recursive fetch of all sessions, presentations, and presenters for the room and queues every file for the day for download. + +### Download Priority & Room Readiness +To ensure the podium is ready for the day's first sessions, the Launcher sync engine uses a 4-tier chronological sorting priority: + +1. **Global Assets:** Event and Location level files (branding, walk-in slides) are cached first. +2. **Session Schedule:** Files for the earliest sessions in the room are prioritized. +3. **Presentation Order:** Within a session block, speakers are prioritized by their scheduled start time. +4. **First-In Fairness:** When times are equal, older uploads are prioritized over late revisions (respecting on-time presenters). + +### Native File Opening (Safe Handover) +1. Verify SHA-256 hash in permanent cache. +2. Atomic copy to system `[tmp]` directory. +3. Rename to original filename (e.g., `Abstract_101.pptx`). +4. OS opens the file via a **Launch Profile** (AppleScript or Shell command). + +--- + +## Device & Native Integration + +Each Launcher kiosk is registered as an `event_device` record in Aether. The technical specifications for the Electron bridge, hashed cache protocol, and hardware actuators are documented in: +👉 **[MODULE__AE_Events_Launcher_Native.md](./MODULE__AE_Events_Launcher_Native.md)** + +--- + +## Route Map (Display) + +| URL | Purpose | +|---|---| +| `/events/[id]/launcher` | Launcher home — select location | +| `/events/[id]/launcher/[location_id]` | Launcher display for a specific room | + +--- + +## Access Levels + +| Feature | Minimum Access | +|---|---| +| View Launcher display | `authenticated_access` | +| Manual session selection | `trusted_access` | +| Advanced Config / Sync Control | `trusted_access` (via Configuration Drawer) | diff --git a/documentation/PROJECT__AE_Events_Launcher_Native_integration.md b/documentation/MODULE__AE_Events_Launcher_Native.md similarity index 99% rename from documentation/PROJECT__AE_Events_Launcher_Native_integration.md rename to documentation/MODULE__AE_Events_Launcher_Native.md index df4ee945..eaca93b3 100644 --- a/documentation/PROJECT__AE_Events_Launcher_Native_integration.md +++ b/documentation/MODULE__AE_Events_Launcher_Native.md @@ -1,7 +1,7 @@ -# Aether Events Launcher: Native Electron Integration +# Aether Events — Launcher: Native Integration -> **Status:** Operational / Phase 5 Implementation -> **Last Updated:** 2026-05-11 +> **Status:** Operational / Permanent Reference +> **Last Updated:** 2026-05-21 (Reorganized) > **Primary Platform:** macOS (Darwin) > **Fallback Platform:** Linux / Windows diff --git a/documentation/MODULE__AE_Events_Presentation_Management.md b/documentation/MODULE__AE_Events_Presentation_Management.md new file mode 100644 index 00000000..efb669e4 --- /dev/null +++ b/documentation/MODULE__AE_Events_Presentation_Management.md @@ -0,0 +1,139 @@ +# Aether Events — Presentation Management + +The Presentation Management module handles the full lifecycle of conference content: sessions, presentations, presenters, presentation files, and room/location assignments. It serves as the "Back Office" interface for event staff. + +--- + +## Data Model + +### Object Hierarchy + +```text +Event +├── Event File (walk-in/out, hold slides for the whole event) +├── Location (physical room — assigned to Sessions, not the other way around) +├── Track (optional grouping; rarely used) +└── Session (time block; Location assigned here, but may be unset initially) + ├── Session File (moderator slides, group/hold slides for this session) + └── Presentation (a talk within the session; must belong to exactly one Session) + └── Presenter (belongs to exactly one Presentation) + └── Presenter File (their slides/materials — the common case) +``` + +> **Import note:** When program data is initially imported (sessions, presentations, +> presenters), Locations are often not assigned to Sessions yet — rooms may not be +> finalized or the venue's room list may not be set up in Aether. Location assignment +> typically happens as a separate step once the room list is confirmed. + +### Relationships + +- **Session → Location:** Many-to-one. A Session is assigned to one Location; a Location + hosts many Sessions across the event timeline. Location may be null initially. +- **Presentation → Session:** Many-to-one. A Presentation belongs to exactly one Session. + A Session can have many Presentations (or none, for session-only setups). +- **Presenter → Presentation:** Many-to-one. A Presenter belongs to exactly one Presentation. + Optionally linked to an `event_person_id` for cross-referencing the person record. +- **Event File:** Can be attached at any level — Presenter, Presentation, Session, + Location, or Event. See the File Attachment Levels table. + +### File Attachment Levels + +Files (`event_file`) can be attached at five levels: + +| Level | When Used | Typical Content | +|---|---|---| +| **Presenter** | 99% of the time for individual speakers | Their PowerPoint/PDF/video | +| **Session** | Moderator slides; group/hold content for a specific session | "Session 3 — Group Discussion.pptx" | +| **Location** | Walk-in/out or hold slides for a room across all sessions | Looped PPTX playing between sessions | +| **Event** | Walk-in/out or hold slides used everywhere | Looped PPTX; branding overlay | +| **Presentation** | File attached to the presentation record itself (less common) | Varies | + +### Key Objects + +| Object | Table | Purpose | +|---|---|---| +| Session | `event_session` | Time block; Location and datetime range assigned here | +| Location | `event_location` | Physical room | +| Presentation | `event_presentation` | A talk within a session; belongs to exactly one Session | +| Presenter | `event_presenter` | Person linked to exactly one Presentation | +| Event Person | `event_person` | Person record within the event context | +| Event File | `event_file` | Uploaded file; attached at Presenter, Presentation, Session, Location, or Event level | + +--- + +## Client Setup Variation + +There are no rigid "modes" — events are configured with as much or as little structure +as needed. The platform handles the full range: + +**Minimal setup (BGH):** +Sessions have room and time info. No Presentations or Presenters defined. +Staff upload files directly at the session or location level onsite. + +**Mid-range setup:** +Sessions defined with named Presentations. Presenters may or may not be tracked. +Mix of pre-uploaded and onsite files. QR codes may be used for quick session/presenter lookup. + +**Full setup (LCI):** +Sessions, Presentations, Presenters all defined and managed. External ID labeling +(e.g., "LCI Member ID"). Agreement tracking for presenters. Files managed per-presenter. + +The config that drives this is `event.mod_pres_mgmt_json` — see the Configuration section. + +--- + +## Configuration — `mod_pres_mgmt_json` + +The event's Presentation Management behavior is controlled by `event.mod_pres_mgmt_json`. + +### Convention + +| Prefix | Default state | Meaning | +|---|---|---| +| `hide__` | `false` = visible | Feature is ON by default; set `true` to suppress | +| `show__` | `false` = hidden | Feature is OFF by default; set `true` to enable | + +### Common Config Keys + +| Key | Default | Notes | +|---|---|---| +| `lock_config` | `false` | `true` = force remote→local sync; prevents user overrides of local config | +| `hide__session_code` | `false` | Hide session code column/field | +| `hide__session_description` | `false` | Hide session description field | +| `hide__session_location` | `false` | Hide location field on session view | +| `hide__session_datetime` | `false` | Hide datetime fields | +| `hide__presentation_code` | `false` | Hide presentation code | +| `hide__presenter_code` | `false` | Hide presenter code | +| `hide__location_code` | `false` | Hide location code | +| `show__launcher_link` | `false` | Show direct Launcher link in session view | +| `show__session_qr` | `false` | Show QR code for session (SRR lookup) | +| `show__presenter_qr` | `false` | Show QR code for presenter (SRR lookup) | +| `label__person_external_id` | `null` | Override label for external ID field (e.g., `"Member ID"`) | +| `label__session_poc_name` | `null` | Override label for session POC (e.g., `"Champion"`) | +| `file_purpose_option_kv` | `{}` | Key-value map of file purpose options (e.g., `{"ppt": "PowerPoint", "pdf": "PDF"}`) | + +--- + +## Route Map (Administration) + +| URL | Purpose | +|---|---| +| `/events/[id]/pres_mgmt` | Overview — sessions list, search, filter by location | +| `/events/[id]/pres_mgmt/config` | Config editor (admin only) | +| `/events/[id]/session/[session_id]` | Session detail — files, presentations, timing, alert | +| `/events/[id]/presenter/[presenter_id]` | Presenter detail — bio, files, agreement, alert | +| `/events/[id]/location/[location_id]` | Location detail — session schedule for this room, alert | +| `/events/[id]/locations` | All locations list | +| `/events/[id]/reports` | Reports — sessions, presenters, files | + +--- + +## Access Levels + +| Feature | Minimum Access | +|---|---| +| View pres_mgmt overview | `authenticated_access` | +| Upload files | `authenticated_access` | +| Edit sessions / presentations | `trusted_access` | +| Edit config | `administrator_access` + `edit_mode` | +| Device management | `administrator_access` | diff --git a/documentation/MODULE__AE_Events_PressMgmt_Launcher.md b/documentation/MODULE__AE_Events_PressMgmt_Launcher.md deleted file mode 100644 index 761ec16b..00000000 --- a/documentation/MODULE__AE_Events_PressMgmt_Launcher.md +++ /dev/null @@ -1,508 +0,0 @@ -# Aether Events — Presentation Management & Launcher - -Notes on setup, workflow, configuration, and onsite operation for the Events Presentation -Management module and the companion Launcher (podium display) system. - ---- - -## Overview - -The Presentation Management (Pres Mgmt) module handles the full lifecycle of conference -content: sessions, presentations, presenters, presentation files, and room/location -assignments. The Launcher module provides the podium display interface that runs on each -session room's kiosk machine. - -These two modules are deployed together — Pres Mgmt is the back office, Launcher is the -front-of-house display. Every client show is at least slightly customized. Some clients -have extensive presenter/presentation data; others just have sessions and files. The -platform is flexible enough to handle the full range. - -**Reference clients (current/repeat):** -- **BGH** (Business Group on Health) — most basic setup; session-only, no named Presenters -- **LCI** (Lean Construction Institute) — most complex current setup -- **AAPOR**, **ASCM**, **CMSC** — other active/repeat clients - -**Module paths:** -- Pres Mgmt: `/events/[event_id]/pres_mgmt` -- Launcher: `/events/[event_id]/launcher` - -**Key source directories:** -- `src/routes/events/[event_id]/(pres_mgmt)/` -- `src/routes/events/[event_id]/(launcher)/` -- `src/lib/ae_events/` — data types and API functions for all event objects - ---- - -## Data Model - -### Object Hierarchy - -```text -Event -├── Event File (walk-in/out, hold slides for the whole event) -├── Location (physical room — assigned to Sessions, not the other way around) -├── Track (optional grouping; rarely used — see note below) -└── Session (time block; Location assigned here, but may be unset initially) - ├── Session File (moderator slides, group/hold slides for this session) - └── Presentation (a talk within the session; must belong to exactly one Session) - └── Presenter (belongs to exactly one Presentation) - └── Presenter File (their slides/materials — the common case) -``` - -> **Import note:** When program data is initially imported (sessions, presentations, -> presenters), Locations are often not assigned to Sessions yet — rooms may not be -> finalized or the venue's room list may not be set up in Aether. Location assignment -> typically happens as a separate step once the room list is confirmed. - -### Relationships - -- **Session → Location:** Many-to-one. A Session is assigned to one Location; a Location - hosts many Sessions across the event timeline. Location may be null initially. -- **Presentation → Session:** Many-to-one. A Presentation belongs to exactly one Session. - A Session can have many Presentations (or none, for session-only setups). -- **Presenter → Presentation:** Many-to-one. A Presenter belongs to exactly one Presentation. - Optionally linked to an `event_person_id` for cross-referencing the person record. -- **Event File:** Can be attached at any level — Presenter, Presentation, Session, - Location, or Event. See the File Attachment Levels table. - -### File Attachment Levels - -Files (`event_file`) can be attached at five levels: - -| Level | When Used | Typical Content | -|---|---|---| -| **Presenter** | 99% of the time for individual speakers | Their PowerPoint/PDF/video | -| **Session** | Moderator slides; group/hold content for a specific session | "Session 3 — Group Discussion.pptx" | -| **Location** | Walk-in/out or hold slides for a room across all sessions | Looped PPTX playing between sessions | -| **Event** | Walk-in/out or hold slides used everywhere | Looped PPTX; branding overlay | -| **Presentation** | File attached to the presentation record itself (less common) | Varies | - -### Key Objects - -| Object | Table | Purpose | -|---|---|---| -| Session | `event_session` | Time block; Location and datetime range assigned here | -| Location | `event_location` | Physical room; the Launcher's primary unit of display | -| Presentation | `event_presentation` | A talk within a session; belongs to exactly one Session | -| Presenter | `event_presenter` | Person linked to exactly one Presentation; optionally linked to `event_person` | -| Event Person | `event_person` | Person record within the event context | -| Event File | `event_file` | Uploaded file; attached at Presenter, Presentation, Session, Location, or Event level | -| Event Device | `event_device` | Registered Launcher kiosk (Electron native instance) | -| Event Track | `event_track` | Optional content grouping (see note below) | - -### Event Tracks - -The API supports Event Tracks — an optional grouping layer above Sessions. Used twice -historically; could have been omitted both times. Tracks may become genuinely useful for -larger events running many parallel Locations where thematic grouping helps navigation. -Not in active use currently and not wired into the standard Pres Mgmt UI workflow. - -### Session → Location - -The Launcher's primary display unit is the Location. It shows the active Session for that -Location based on `datetime_start` / `datetime_end` or manual selection. A Location hosts -many Sessions over the event's run; typically only one is active at a time. - ---- - -## Client Setup Variation - -There are no rigid "modes" — events are configured with as much or as little structure -as needed. The platform handles the full range: - -**Minimal setup (BGH):** -Sessions have room and time info. No Presentations or Presenters defined. -Staff upload files directly at the session or location level onsite. - -**Mid-range setup:** -Sessions defined with named Presentations. Presenters may or may not be tracked. -Mix of pre-uploaded and onsite files. QR codes may be used for quick session/presenter lookup. - -**Full setup (LCI):** -Sessions, Presentations, Presenters all defined and managed. External ID labeling -(e.g., "LCI Member ID"). Agreement tracking for presenters. Files managed per-presenter. -Launcher linked from Pres Mgmt views. - -The config that drives this is `event.mod_pres_mgmt_json` — see the Configuration section. - ---- - -## Speaker Ready Room (SRR) - -The Speaker Ready Room is a dedicated space where presenters check in and staff manage -content before it goes live in the session rooms. Setup varies by client: - -- **Small/private:** Only a few client staff and OSIT. Not open to presenters at large. -- **Open SRR:** Open to all presenters as long as sessions are running. People come and go - all day — reviewing silently, editing with a group, practicing at a station. - -### SRR Practice Stations - -Stations mirror the session room setup exactly: -- Same Mac laptop model and adapter/dongle configuration as the podiums -- Projector and screen (same as session rooms where possible) -- Launcher running in Native (Electron) mode — cached files open immediately -- Full dry-run capability: load their file, start the deck, confirm everything works - -### Remote Monitoring - -SRR staff typically monitor the session room Launchers in real time via **VNC or RustDesk**. -This lets one person watch multiple podium displays simultaneously without being in each room. - -### QR Codes (Session and Presenter) - -QR codes are available for Sessions and Presenters and have been useful onsite for quick -lookups — scanning a code takes staff directly to the session or presenter record. -Whether to enable this depends on the SRR flow for each show. It gets toggled on or off -per event via config. - -### SRR Staffing Roles - -| Role | Access Level | Typical Tasks | -|---|---|---| -| OSIT Staff | `trusted_access` or higher | Upload files, edit sessions/presentations, manage devices, monitor via VNC | -| Client Staff | `authenticated_access` | Upload files, view session list | -| Presenter (self-service) | `authenticated_access` (if enabled) | Upload their own files via QR link | - -### SRR Workflow — Day-of-Show - -1. **Presenter checks in** — staff looks up their session(s) in Pres Mgmt -2. **File upload** — staff or presenter uploads file to the correct presenter/session record -3. **File verification** — staff opens the file on a practice station to confirm it renders -4. **Launcher Sync** — file appears in the Launcher within the next polling cycle. Staff can use the **Force Sync Location** button in the Launcher config to immediately queue all files for the room's schedule. -5. **Presenter proceeds to room** — podium kiosk already has the file cached. - ---- - -## File Upload Workflows - -### Pre-Show (Remote / Staff Ahead of Time) - -Files can be uploaded anytime before the event via the Pres Mgmt web UI: -1. Navigate to the presenter, session, or appropriate level -2. Use the file upload panel (drag & drop or browse) -3. File is stored server-side and immediately available to the Launcher - -Some clients enable presenter self-upload via a direct link (requires `authenticated_access`). -Controlled per-event via config. - -### Day Before — SRR Setup - -For higher-volume shows, the SRR opens the day before the event: -- Pre-uploaded files are already loaded and can be verified -- Early-arriving presenters check in; staff upload their files -- Electron Launcher instances on podium Macs begin pre-caching files overnight -- Problems (corrupt files, wrong format, wrong codec) surface with time to fix them - -### Live Onsite Upload - -For late arrivals and last-minute changes: -1. Presenter arrives at SRR (or sends file via USB/email to staff) -2. Staff uploads via Pres Mgmt web UI -3. File propagates to Launcher within one polling cycle (~30 seconds on fast networks) -4. VNC or RustDesk confirms the podium received the file before the presenter walks in - ---- - -## Onsite Operation — Managing 4–12 Parallel Rooms - -### Overview Page - -The Pres Mgmt overview (`/events/[event_id]/pres_mgmt`) shows: -- All sessions, filterable by location and time -- File status per session -- Quick links to each session's file management - -For events with multiple parallel rooms, filtering by location and time block is essential -for SRR staff staying on top of what's active right now. - -### Per-Room Workflow - -Each room/location has its own Launcher display: -- `/events/[event_id]/launcher` → select location → Launcher for that room -- The Launcher shows the active session based on the current time or manual selection -- VNC/RustDesk gives SRR staff a real-time view of all podiums simultaneously - -### Session Display Timing - -Ideally, sessions would automatically show and hide based on `datetime_start` / -`datetime_end` — appearing a configurable number of minutes before the session starts -and disappearing after it ends. This is a planned/desired behavior. In practice: - -- Some clients run tight schedules and could rely on time-based transitions -- Others drift significantly from the published schedule; time-based auto-advance - would cause more problems than it solves -- Currently, session transitions can be managed manually via Launcher controls - -> **TODO (future):** Configurable `show_before_minutes` / `hide_after_minutes` per event -> so well-run shows can automate transitions while looser shows stay manual. - -### Device (Laptop) Assignment - -Each Launcher kiosk Mac is registered as an `event_device` and typically assigned to one -Location for the duration of the event. However, laptops do get moved: -- Venues add or lose rooms as spaces are reconfigured -- A session room may open for one day only -- Devices can be reassigned to a different Location in the `event_device` record as needed - -The Electron app reads its location assignment from the API at startup, so reassigning a -device takes effect on the next launch (or app restart). - ---- - -## Alert Fields - -Sessions, Presenters, and Locations each have alert fields that can display a visible -notice in the Pres Mgmt UI and/or the Launcher. - -Useful for: -- "Presenter requested no recording" -- "Room change — moved to Hall B" -- "File not received — follow up" -- "AV note: needs confidence monitor" - -> **Status:** Alert fields exist but the implementation and display behavior needs review -> and cleanup. Not a blocking issue for BGH next week — revisit for a future show. - ---- - -## Launcher Module - -### Operational Modes - -| Mode | Use Case | File Handling | -|---|---|---| -| **Default** | Browser on any machine | Files downloaded on demand | -| **Onsite** | Browser on event network | Faster polling; browser-managed files | -| **Native** | Electron app on dedicated podium Mac | Background pre-cache; atomic file handover | - -For production onsite use, **Native mode on Mac laptops** is the target. The Electron -app pre-caches all session files in the background so presentations open instantly without -a network round-trip at the moment of launch. - -### Download Priority & Room Readiness - -To ensure the podium is ready for the day's first sessions, the Launcher sync engine uses a -4-tier chronological sorting priority: - -1. **Global Assets:** Event and Location level files (branding, walk-in slides) are cached first. -2. **Session Schedule:** Files for the earliest sessions in the room are prioritized. -3. **Presentation Order:** Within a session block, speakers are prioritized by their scheduled start time. -4. **First-In Fairness:** When times are equal, older uploads are prioritized over late revisions. - -Operators can manually trigger a full pre-sync of all location materials via the **Force Sync Location** button in the Launcher configuration (Sync Engine section). - -### Native Mode — Electron App - -- **Repo:** `~/OSIT_dev/aether_app_native_electron/` -- **Platform:** macOS (primary); Linux/Windows as fallback -- **Seed config:** `seed.json` (Device ID + API key) — loaded at startup -- **File cache:** `~/Library/Caches/OSIT/file_cache/` (hashed by SHA-256) -- **Doc:** `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` - -The Electron app zero-configs itself: -1. Reads `seed.json` → gets device code -2. Calls Aether API → pulls device config and location assignment -3. Navigates directly to the Launcher for that location -4. Begins pre-caching session files in the background - -### Launcher Display Views - -| View | Shown When | -|---|---| -| Session view | Active session with session-level files | -| Presentation view | Active session with named presentations | -| Presenter view | Presentation selected; shows presenter bio/photo | -| Poster/group view | Special layout for poster sessions | -| Screensaver | No active session; idle state | - -### File Opening (Native Mode) — Safe Handover - -1. Verify SHA-256 hash in permanent cache -2. Atomic copy to system `[tmp]` directory -3. Rename to original filename (e.g., `Abstract_101.pptx`) -4. OS opens the file (Keynote, PowerPoint, Preview, etc.) - -**Configurable launch behavior:** The file-open behavior is driven by a Launch Profile, not -just a command string. Profiles are stored per file extension in -`event_device.data_json.launch_profiles` (device-level config) or -`event.launcher.launch_profiles` (event-level fallback). The built-in Svelte defaults are the -final fallback and are documented below. A profile can choose the app, display mode, open -command, and post-open automation. The resolved native template uses `{{path}}` as the file -path placeholder; AppleScript or `shell:` prefixed commands are both supported. No Electron -rebuild is required to change how files open — edit config in Aether and it applies -immediately. See `PROJECT__AE_Events_Launcher_Native_integration.md` Section 8. - -### Built-In Default Launch Profiles - -These are the initial built-in defaults shipped with the Launcher. They are the Svelte-side -fallbacks used when neither device config nor event config defines a profile for the file -extension. Each canonical profile can have multiple extension aliases. `post_delay_ms` is part -of the profile object, so a device-specific `launch_profiles[profile].post_delay_ms` override can -tune it later without changing the profile table. - -| Profile name | Extension aliases | Default app | Display mode | Post delay | Notes | -|---|---|---|---|---|---| -| `powerpoint_mac_extend` | `pptx`, `ppt` | Microsoft PowerPoint for macOS | `extend` | `1000ms` | Open in the presentation app and extend to an external display if one is present. | -| `keynote_mac_extend` | `key` | Keynote | `extend` | `1000ms` | Keynote slideshow on the external display if available. Post-script polls `count of documents > 0` before starting — handles slow file load on cold start. | -| `libreoffice_mac_extend` | `odp` | LibreOffice for macOS | `extend` | `1000ms` | LibreOffice Impress for OpenDocument presentations. | -| `acrobat_mac_mirror` | `pdf` | Adobe Acrobat for macOS | `mirror` | `1000ms` | PDF handout / deck view uses mirrored display. | -| `vlc_mirror` | `mp4`, `mkv`, `mp3`, `m4v`, `m4a`, `webm`, `wav`, `aac`, `flac`, `mov`, `mpeg`, `avi`, `flv`, `ogg`, `ogv`, `wmv` | VLC for macOS | `mirror` | `1000ms` | Media playback is mirrored so the room sees the same output as the operator. Uses `--no-play-and-exit` so playback ends on the last frame instead of closing video output. | -| `powerpoint_win_extend` | `pptxwin`, `pptwin` | PowerPoint for Windows (Parallels) | `extend` | `1500ms` | Windows PowerPoint profile for Parallels-based rooms. Higher base delay to account for Parallels VM startup latency. | -| `libreoffice_win_extend` | `odpwin` | LibreOffice for Windows | `extend` | `1500ms` | Windows LibreOffice profile for Parallels-based rooms. | -| `acrobat_win_mirror` | `pdfwin` | Adobe Acrobat for Windows (Parallels) | `mirror` | `1500ms` | Windows PDF profile for mirrored display rooms. | -| `url_web` | `url` | Browser / Event File web presentation | `extend` | `n/a` | Web-based presentations are handled as Event File URLs rather than cached local files. | - -> **Post-open automation timing:** All profiles with a `post_script` use a polling loop rather than a fixed sleep — the AppleScript waits up to ~7.5 s for the target process to become frontmost before firing the automation keystroke. The `post_delay_ms` value is a minimum baseline before polling begins. Overridable per profile via `launch_profiles[profile].post_delay_ms` in `event_device.data_json`. - -Versioning is handled automatically: when a presenter uploads an updated file, the new -hash is cached separately and the old one remains intact. - ---- - -## Configuration — `mod_pres_mgmt_json` - -The event's Pres Mgmt behavior is controlled by `event.mod_pres_mgmt_json`. - -> **Note:** The config schema is being cleaned up — see -> `documentation/PROJECT__AE_Events_PressMgmt_Config_Cleanup.md` for the canonical -> `PressMgmtRemoteCfg` interface and naming conventions. - -### Convention - -| Prefix | Default state | Meaning | -|---|---|---| -| `hide__` | `false` = visible | Feature is ON by default; set `true` to suppress | -| `show__` | `false` = hidden | Feature is OFF by default; set `true` to enable | - -### Common Config Keys - -| Key | Default | Notes | -|---|---|---| -| `lock_config` | `false` | `true` = force remote→local sync; prevents user overrides of local config | -| `hide__session_code` | `false` | Hide session code column/field | -| `hide__session_description` | `false` | Hide session description field | -| `hide__session_location` | `false` | Hide location field on session view | -| `hide__session_datetime` | `false` | Hide datetime fields | -| `hide__presentation_code` | `false` | Hide presentation code | -| `hide__presenter_code` | `false` | Hide presenter code | -| `hide__location_code` | `false` | Hide location code | -| `show__launcher_link` | `false` | Show direct Launcher link in session view | -| `show__session_qr` | `false` | Show QR code for session (SRR lookup) | -| `show__presenter_qr` | `false` | Show QR code for presenter (SRR lookup) | -| `label__person_external_id` | `null` | Override label for external ID field (e.g., `"Member ID"`) | -| `label__session_poc_name` | `null` | Override label for session POC (e.g., `"Champion"`) | -| `file_purpose_option_kv` | `{}` | Key-value map of file purpose options (e.g., `{"ppt": "PowerPoint", "pdf": "PDF"}`) | - -### Per-Show Config Examples - -**BGH (session-only, minimal; no named Presentations or Presenters):** -```json -{ - "lock_config": false, - "hide__presentation_code": true, - "hide__presenter_code": true -} -``` - -**LCI (full setup, member ID label, Launcher link enabled):** -```json -{ - "lock_config": true, - "label__person_external_id": "LCI Member ID", - "show__launcher_link": true -} -``` - -> Admin must currently edit `mod_pres_mgmt_json` directly in the DB or via the event -> settings page. A proper Config UI is planned — see `PROJECT__AE_Events_PressMgmt_Config_Cleanup.md`. - ---- - -## Route Map - -| URL | Purpose | -|---|---| -| `/events/[id]/pres_mgmt` | Overview — sessions list, search, filter by location | -| `/events/[id]/pres_mgmt/config` | Config editor (admin only) | -| `/events/[id]/session/[session_id]` | Session detail — files, presentations, timing, alert | -| `/events/[id]/presenter/[presenter_id]` | Presenter detail — bio, files, agreement, alert | -| `/events/[id]/location/[location_id]` | Location detail — session schedule for this room, alert | -| `/events/[id]/locations` | All locations list | -| `/events/[id]/reports` | Reports — sessions, presenters, files | -| `/events/[id]/launcher` | Launcher home — select location | -| `/events/[id]/launcher/[location_id]` | Launcher display for a specific room | - ---- - -## Device Management - -Each Electron kiosk is registered as an `event_device` record: -- `code` — matches the device's `seed.json` code -- `name` — human-readable (e.g., "Ballroom A Podium") -- `data_json.location_id` — the `event_location_id` this device is assigned to - -Devices can be managed in Pres Mgmt (`/events/[id]/device/device`). Location reassignment -takes effect on the next Electron app launch. - ---- - -## Access Levels - -| Feature | Minimum Access | -|---|---| -| View pres_mgmt overview | `authenticated_access` | -| Upload files | `authenticated_access` | -| Edit sessions / presentations | `trusted_access` | -| Edit config | `administrator_access` + `edit_mode` | -| View Launcher display | `authenticated_access` | -| Manual session selection in Launcher | `trusted_access` | -| Device management | `administrator_access` | - ---- - -## Pre-Show Checklist - -### 1–2 Weeks Before - -- [ ] Event created in Aether with correct dates -- [ ] `mod_pres_mgmt_json` configured for this client's needs -- [ ] Locations (rooms) created and named -- [ ] Sessions created, assigned to locations, datetime ranges set -- [ ] If using Presentations/Presenters: records imported or entered -- [ ] File purpose options configured in `file_purpose_option_kv` -- [ ] Launcher devices registered (`event_device` records with correct codes) -- [ ] Device-to-location assignments confirmed -- [ ] Decide: QR codes for Sessions / Presenters needed? Enable/disable in config - -### Day Before (SRR Setup) - -- [ ] Mac laptops at podiums booted and Electron app running -- [ ] Each podium confirms it loaded the correct location's Launcher -- [ ] SRR practice stations confirmed — projector, same Mac/dongle setup as session rooms -- [ ] Pre-loaded files verified in Launcher (open at least one per room to test Safe Handover) -- [ ] SRR staff briefed on upload workflow and VNC/RustDesk monitoring setup -- [ ] VNC/RustDesk connections established to all podium displays - -### Day of Show - -- [ ] Confirm all session times in Aether are accurate before first session -- [ ] Monitor SRR queue — upload files as presenters check in -- [ ] Verify each file opens on a practice station before the presenter walks to their room -- [ ] Monitor podium displays via VNC/RustDesk — flag any stuck or offline devices - ---- - -## Troubleshooting - -| Symptom | Cause | Fix | -|---|---|---| -| Session not showing in Launcher | Session datetime wrong or location not assigned | Verify session location and datetime range | -| File uploaded but not in Launcher | Polling cycle lag; or file attached at wrong level | Wait one cycle; check that file is attached to session/location (not just a presenter record) if using session-only setup | -| Electron app shows wrong location | Device code mismatch or stale device config | Re-check `event_device` record; restart Electron app | -| File opens slowly at podium | Not in native cache yet | Check background sync in Launcher; pre-cache may not have completed | -| File won't open | Corrupt upload, wrong format, or missing codec on Mac | Test on SRR practice station; re-upload or convert | -| Session out of sync with schedule | Timing drifted; manual advance needed | Use Launcher controls to manually select the current session | -| Alert field not showing | Alert fields need implementation review | Known — lower priority than active operations | -| `lock_config: true` resets local changes | Expected behavior — remote config wins | Change the remote config in `mod_pres_mgmt_json` | -| Device needs to move to different room | Location reassigned mid-event | Update `data_json.location_id` on `event_device` record; restart Electron app on that machine | diff --git a/src/routes/events/[event_id]/(launcher)/README.md b/src/routes/events/[event_id]/(launcher)/README.md deleted file mode 100644 index d8d6ee70..00000000 --- a/src/routes/events/[event_id]/(launcher)/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Aether (AE) Event Launcher Module (v3) - -This directory contains the files for the new Event Launcher module (v3). Detailed documentation to follow. - -This should be able to run in 3 modes: - -- Default - What most users will see for demo purposes -- Onsite - This is what is set onsite, usually just in the Speaker Ready Room -- Native App - This is for the native app version of Aether and used on the MacBook laptops in each of the session rooms