Overview
MMM-GDriveAmbient is a module for MagicMirror² that displays random photos from a Google Drive folder as an ambient slideshow. It authenticates via a Google Service Account, handles HEIC-to-JPEG conversion server-side, and extracts photo metadata for timeline integration.
Key Features
- Google Drive integration — Fetches random images from a specified folder using a Service Account
- HEIC/HEIF support — Automatically converts iPhone photos to JPEG for browser compatibility
- Ambient color theming — Samples the dominant color from each photo and exposes it as a CSS variable (
--ambient-color) - Timeline sync — Sends date metadata to MMM-Timeline for live timeline highlighting
- Cached file listing — Reduces API calls with a 5-minute cache
Architecture
| Layer | Technology | Role |
|---|---|---|
| Frontend | MagicMirror Module API | Renders image, samples color, sends notifications |
| Backend | Node.js (NodeHelper) | Google Drive auth, file download, HEIC conversion |
| Integration | Socket notifications | Bi-directional frontend ↔ backend communication |
Technical Stack
- Runtime: Node.js
- APIs: Google Drive API v3 (Service Account auth)
- Libraries:
googleapis,heic-convert - Communication: MagicMirror socket notifications
Source Code
Full documentation, installation guide, and source code available on GitHub: github.com/CuzImHarry/MMM-GDriveAmbient