How clockley/emsmediasystem works
1. Top-level shape
- This repo is an Electron desktop application for media presentation, not a web app.
- The product is split into a control/management window and a separate presentation window shown on a selected display.
2. Electron entrypoint and app shell
- The core runtime is in src/main.mjs, which is the Electron main-process entry.
- It likely owns app startup, window creation, display selection, and coordination between the two windows.
- src/app.js appears to hold shared application-level behavior or bootstrapping logic used by the renderer side.
3. Dual-window architecture
- src/index.html is the main control surface.
- src/media.html is the clean presentation surface for the audience.
- The architecture is intentionally separated so operators manage media in one window while content appears distraction-free in another.
4. Renderer-side modules
- The UI and interaction logic are split across ES modules such as:
- src/media.mjs for the presentation window
- src/app.js / src/settings.mjs for control state and configuration
- src/streamPlayer.mjs for stream/video playback behavior
- src/audioFx.mjs for audio processing or effects
- src/switcher.js and src/queue_switch_dialog.html for switching/queue-related UI
- These modules form the application logic layer inside the renderer process.
5. Secure preload boundaries
- Multiple preload scripts exist:
- src/app_preload.mjs
- src/help_preload.mjs
- src/media_preload.js
- src/queue_switch_dialog_preload.mjs
- This indicates context-isolated Electron windows, where the preload layer exposes a narrow IPC/API surface to the HTML pages.
- Architecturally, this is the boundary between privileged Electron capabilities and the UI code.
6. Media playback responsibilities
- The app supports local video/audio, images, and YouTube live stream integration per the README.
- streamPlayer.mjs is the likely media controller for streaming and playback orchestration.
- audioFx.mjs suggests optional audio enhancement/filtering integrated into playback.
7. Presentation output and display selection
- The system includes display targeting for the presentation window, so the control window and output window can be placed on different monitors.
- src/switcher.js and the queue switch dialog imply operator-driven switching between queued media items or sources.
- This makes the output pipeline: operator action in control window -> IPC/state update -> presentation window updates media shown on the selected display.
8. Bible-related subsystem
- There is a separate bibleBackend/ directory with:
- main.go
- go.mod / go.sum
- bible-sqlite.db
- This is a distinct Go + SQLite subsystem, likely for local scripture lookup or content retrieval used by the app’s Bible features.
- It acts as a data-backed service/engine rather than part of the Electron UI itself.
9. WASM/Go runtime in the renderer
- src/main.wasm and src/wasm_exec.js indicate a Go WebAssembly component bundled into the frontend runtime.
- That suggests some logic is executed in-browser/renderer via Go WASM, likely for computational or data-access tasks that need to run inside the Electron renderer environment.
- The architecture therefore includes both native Electron code and embedded Go runtime artifacts.
10. Static UI pages and auxiliary windows
- src/about.html, src/help.html, and their preload scripts indicate small dedicated utility windows or dialogs.
- These are separate UI entrypoints rather than overlays inside the main app shell.
11. Assets and styling
- src/main.css and the fonts/Adwaita/ directory provide the visual presentation layer.
- The styling is packaged with the app so the control and presentation windows render consistently across platforms.
12. Build and packaging
- The repository includes package.json, Makefile, .github/workflows/eslint.yml, and BUILD.md, indicating a packaged desktop build pipeline.
- build-scripts/embed-css.ps1 suggests part of the build process transforms or embeds CSS into the distributed app.
- The presence of release instructions for Windows and Linux AppImage in the README confirms cross-platform desktop distribution.
13. Overall data flow
- User interacts with the control window.
- Renderer logic updates app state and issues IPC through preload boundaries.
- The Electron main process coordinates the presentation window and display choice.
- Media content is rendered in the separate presentation window, while optional Bible data comes from the Go/SQLite subsystem and any Go WASM component.
14. Architecture summary for diagramming
- A good diagram would show:
- Electron main process at the center
- Control renderer and presentation renderer as two separate frontends
- Preload/IPC bridges between them and main
- Go + SQLite Bible backend as a local data subsystem
- Go WASM runtime as an embedded runtime artifact used by the renderer
- Static assets/fonts/build tooling as supporting infrastructure
Main entry points: main.mjs Main process · index.html Control UI · media.html Presentation UI · app.js App logic
Components 24
Electron app
Main process and window coordination
- Main process · Creates windows, manages app lifecycle, and coordinates display/output
src/main.mjs
Renderer UI
Control, presentation, and dialog entrypoints
- Control UI · Operator-facing app window and primary interaction surface
src/index.html - Presentation UI · Clean audience-facing output window
src/media.html - App logic · Shared renderer behavior and app-level state
src/app.js - Settings · Configuration and persisted UI/application settings
src/settings.mjs - Media runtime · Presentation-side media orchestration and rendering logic
src/media.mjs - Stream player · Handles stream and video playback behavior
src/streamPlayer.mjs - Audio FX · Audio processing and effects used during playback
src/audioFx.mjs - Switcher · Queue and source switching logic for operator actions
src/switcher.js - Queue dialog · Dedicated UI for queue switching interactions
src/queue_switch_dialog.html - About window · Small auxiliary about dialog/window
src/about.html - Help window · Help/info window for the application
src/help.html - App preload · Preload API boundary for the main control window
src/app_preload.mjs - Media preload · Preload API boundary for the presentation window
src/media_preload.js - Help preload · Preload API boundary for the help window
src/help_preload.mjs - Queue preload · Preload API boundary for the queue switch dialog
src/queue_switch_dialog_preload.mjs - Bible bridge · Bible-related renderer integration and lookup logic
src/Bible.mjs
Local data
Bible backend and embedded runtime artifacts
- Go backend · Local Go subsystem backing Bible/content features
bibleBackend/main.go - Bible DB · Local SQLite database used by the Bible backend
bibleBackend/bible-sqlite.db - WASM runtime · Go WebAssembly runtime artifact used in the renderer
src/main.wasm - WASM loader · JavaScript support for running Go WASM in the renderer
src/wasm_exec.js
Support
Assets and build pipeline
- Styles · Shared application styling for all windows
src/main.css - Fonts · Bundled Adwaita font assets
fonts/Adwaita - Build scripts · CSS embedding and release/build automation
build-scripts/embed-css.ps1
Connections 30
- Control UI → App preload: preload · Control window loads its isolated bridge
- Presentation UI → Media preload: preload · Presentation window loads its isolated bridge
- About window → Help preload: preload · About window loads its bridge
- Help window → Help preload: preload · Help window loads its bridge
- Queue dialog → Queue preload: preload · Queue switch dialog loads its bridge
- Main process → Control UI: creates · Main process opens the control window
- Main process → Presentation UI: creates · Main process opens the presentation window
- Main process → About window: opens · Main process can open the about window
- Main process → Help window: opens · Main process can open the help window
- Main process → Queue dialog: opens · Main process can open the queue switch dialog
- App preload → Main process: ipc · Control UI communicates privileged actions through IPC
- Media preload → Main process: ipc · Presentation window receives coordination via IPC
- Queue preload → Main process: ipc · Queue dialog sends switch actions through IPC
- App logic → Settings: reads/writes · Renderer logic manages settings and application state
- App logic → Switcher: coordinates · App logic drives queue and switch operations
- Switcher → Queue dialog: drives · Switcher logic feeds the queue switch dialog
- App logic → Bible bridge: uses · Renderer app integrates Bible features
- Bible bridge → Go backend: calls · Bible renderer integration relies on the Go backend
- Go backend → Bible DB: stores · Go backend reads from local SQLite Bible data
- Media runtime → Stream player: uses · Presentation runtime delegates playback to stream player
- Media runtime → Audio FX: uses · Presentation runtime applies audio effects during playback
- Media runtime → WASM runtime: embeds · Renderer includes the Go WASM component
- WASM runtime → WASM loader: runs with · WASM code depends on the Go runtime shim
- Control UI → Styles: styled by · Control window uses shared styling
- Presentation UI → Styles: styled by · Presentation window uses shared styling
- Control UI → Fonts: assets · Control UI is packaged with bundled fonts
- Presentation UI → Fonts: assets · Presentation UI is packaged with bundled fonts
- Build scripts → Styles: builds · Build tooling embeds or packages CSS
- Build scripts → Control UI: packages · Build pipeline produces the control application
- Build scripts → Presentation UI: packages · Build pipeline produces the presentation application