Media Player Electron

A cross-platform digital signage/media player built with Electron and Vue 3. This app is designed to display scheduled media content (video, image, HTML) on screens, with remote configuration, automatic updates, and device monitoring.

Features

• Electron + Vue 3: Modern UI with native desktop capabilities.
• Content Scheduling: Plays playlists of videos, images, and HTML content based on server schedule.
• Remote Configuration: Device settings and content are managed remotely via API and MQTT.
• Offline Support: Downloads and caches content for offline playback.
• Device Monitoring: Sends device status, logs, and play history to the server.
• Auto Update: Supports automatic application updates.
• Multi-Platform: Supports Windows, macOS, and Linux.

Project Structure

├── electron/         # Electron main process code (backend)
│   ├── main.js       # Electron app entry point
│   ├── data/         # Data storage, MQTT, API, file system
│   ├── info/         # Device and app info utilities
│   ├── logic/        # Main business logic (playlist, play, config)
│   ├── preload/      # Preload script for secure renderer-main communication
│   ├── services/     # Background intervals, MQTT subscriptions
│   └── utils/        # Utility functions
├── src/              # Vue 3 renderer process (frontend)
│   ├── App.vue
│   ├── main.js
│   ├── pages/        # Home, Config, Player pages
│   ├── components/   # Vue components
│   ├── router/       # Vue Router setup
│   └── utils/        # Frontend utilities
├── dist-electron/    # Electron build output
├── dist-vue/         # Vue build output
├── package.json      # Project scripts and dependencies
├── electron-builder.json # Electron build config
└── vite.config.js    # Vite config for Vue

High-Level Flow

1. Startup

   • Electron launches, creates a BrowserWindow, loads Vue UI.
   • Main process initializes intervals, MQTT, auto-launch, updater, and device checks.

2. Device Registration

   • On first run, device generates a unique ID and requests a token from the server via MQTT.
   • Device waits for user to bind it via the portal (displaying a code).

3. Configuration Fetch

   • Device fetches configuration and playlist from the server.
   • Downloads default content and scheduled playlist files.

4. Content Playback

   • Plays scheduled content (video/image/HTML) according to the playlist.
   • If no content is scheduled, plays default content.

5. Monitoring & Reporting

   • Periodically sends device status, play logs, and summaries to the server.
   • Handles remote commands via MQTT (restart, clear cache, update, etc).

6. Error Handling

   • Reports errors (network, playback, download) to the server and logs them.

Functional Step-by-Step Flow

This section explains how the Media Player Electron app works, from first launch to daily operation.

1. First Launch & Device Registration

• When you start the app for the first time, it checks if the device is registered.
• If not registered, the app generates a unique device ID and displays a registration code on the screen.
• You (or an admin) must enter this code in the web portal to bind the device to your organization.

2. Fetching Configuration

• After registration, the app connects to the server using API and MQTT.
• It downloads the latest configuration, including:
  • Device settings (volume, schedule, etc.)
  • Playlists and content files (videos, images, HTML)

3. Content Download & Caching

• The app downloads all scheduled media files and caches them locally.
• This ensures playback continues even if the internet connection is lost.

4. Content Playback

• The app automatically starts playing content based on the current schedule.
• It can play videos, images, or HTML content in a loop or according to a playlist.
• If no scheduled content is available, it plays default content.

5. Remote Control & Updates

• The server can send remote commands (via MQTT) to:
  • Change the playlist or settings
  • Restart the app or device
  • Trigger an update or clear the cache
• The app listens for these commands and responds automatically.

6. Monitoring & Reporting

• The app regularly sends status updates to the server, including:
  • Device health (online/offline, errors)
  • Playback logs (what content was played and when)
  • Screenshots or summaries (if enabled)

7. Error Handling

• If there’s a problem (e.g., network error, file missing), the app:
  • Logs the error locally
  • Reports the error to the server
  • Tries to recover by playing default content or retrying downloads

8. Configuration Changes

• If you need to change device settings (like volume, screen orientation, or schedule), you can do this remotely from the web portal.
• The app will automatically receive and apply these changes via MQTT or during its next configuration fetch.

9. Automatic Updates

• When a new version of the app is released, the server can notify the device.
• The app will download and install updates automatically, then restart to apply the new version.
• This ensures all devices stay up-to-date with the latest features and security fixes.

10. Offline Mode

• If the device loses internet connectivity:
  • The app continues playing cached content without interruption.
  • It will keep trying to reconnect in the background.
  • Once the connection is restored, it syncs logs and downloads any new content or updates.

11. Device Maintenance

• For troubleshooting or maintenance, you can:
  • Restart the app or device from the web portal.
  • Clear the cache to force a fresh content download.
  • View logs and device status remotely.

Typical User Journey

1. Install and launch the app on your device.
2. Register the device using the code shown on the screen and the web portal.
3. Wait for the device to fetch configuration and download content.
4. The device starts playing scheduled content automatically.
5. Monitor and control the device remotely as needed via the web portal.
6. The device updates itself and reports status without user intervention.

Summary Table

| Step | What Happens? | User Action Needed? | |---------------------|---------------------------------------------------------|--------------------------| | 1. Registration | Device shows code, waits for portal binding | Yes (bind via portal) | | 2. Config Fetch | Downloads settings and playlists | No | | 3. Content Download | Downloads and caches media files | No | | 4. Playback | Plays scheduled content automatically | No | | 5. Remote Control | Responds to server commands (update, restart, etc.) | No | | 6. Monitoring | Sends status and logs to server | No | | 7. Error Handling | Logs and reports errors, tries to recover | No |

That’s it!
The system is designed to be as hands-off as possible after initial setup, making it easy for beginners and scalable for large deployments.

Tip:
Once registered, the app is fully automatic. You only need to interact with it if you want to re-register, update, or troubleshoot.

Main Components

• electron/main.js: Electron app entry, window creation, and event wiring.
• electron/logic/init.js: Initializes background intervals and MQTT.
• electron/logic/playerPage/playContent.js: Core playback logic.
• src/pages/home/Home.vue: Home screen UI, device registration flow.
• src/pages/config/Config.vue: Device configuration UI.
• src/pages/player/Player.vue: Media playback UI.

Development

Prerequisites

• Node.js (v18+ recommended)
• npm

Install

npm install

Run in Development

npm run dev

• This runs both the Vue frontend and Electron main process in development mode.

Build for Production

# Build Vue renderer
npm run build:renderer

# Build Electron main process
npm run build:main

# Package for your OS (macOS, Windows, Linux)
npm run dist:mac
npm run dist:win
npm run dist:linux

Customization

• API endpoints: Controlled by environment (see electron/data/apiService.js).
• MQTT topics: See electron/data/mqttClient.js.
• Default content: Managed via server config and downloaded on device.

Troubleshooting

• Logs: Check logs in the console or log files.
• Network: Ensure device has internet access for registration and updates.
• MQTT: Device must be able to connect to the MQTT broker.

Security Notes

• Do not expose your MQTT credentials or API tokens publicly.
• The app disables web security in development for convenience; enable it for production.

License

This project is proprietary to StickEarn.

Contributors

• StickEarn Engineering Team