Skip to content

README.md

Latest commit

 

History

History
259 lines (179 loc) · 7.96 KB

README.md

File metadata and controls

259 lines (179 loc) · 7.96 KB

Stream Deck iCal Plugin

Version License Tests

Display your calendar events on Elgato Stream Deck. Visual countdowns and color warnings help you stay on schedule.

Plugin Example

Download from Stream Deck Store · Latest Release · Report Bug

Quick Start

  1. Install the plugin from Stream Deck Store (search "iCal")
  2. Get your calendar URL (Google | Outlook | Apple)
  3. Add a button - Drag "Smart Calendar" to your Stream Deck
  4. Configure - Click Settings → Add Calendar → Paste URL → Save

That's it! Your next meeting countdown appears on the button.

Actions

Action Best For Description
Smart Calendar ⭐ Most users Auto-switches between countdown modes. Shows "Time Left" during meetings, "Next Meeting" otherwise.
Next Meeting Anticipating upcoming Always shows countdown to next meeting. Tap for meeting title.
Time Left During meetings Shows time remaining in current meeting. Supports concurrent meetings.

💡 Recommendation: Start with Smart Calendar - it combines both modes intelligently.

Features

📅 Multiple Calendars

Set up named calendars (Work, Personal, Family) and assign different calendars to different buttons.

⏰ Visual Warnings

  • Orange when meeting is approaching (default: 5 min, configurable)
  • Red when meeting is imminent (default: 30 sec, configurable)

🔄 Recurring Events

Full support for daily, weekly, monthly patterns (RRULE) with exceptions (EXDATE).

🌍 Timezone Smart

Automatic conversion between Windows and IANA timezones. Works globally.

⚡ Quick Actions

  • Tap to show meeting title (scrolling marquee)
  • Double-tap to force refresh calendar
  • Tap during meeting to cycle through concurrent meetings

Supported Calendars

Provider Status Notes
Google Calendar ✅ Full support Including Workspace
Microsoft Outlook ✅ Full support Outlook.com & Office 365
Apple Calendar ✅ Full support iCloud sharing
Any iCal URL ✅ Works RFC 5545 compatible

Getting Your Calendar URL

Google Calendar
  1. Open Google Calendar
  2. Click ⋮ next to your calendar → Settings and sharing
  3. Scroll to "Integrate calendar"
  4. Copy "Secret address in iCal format"

⚠️ Use the "Secret address" - the public address won't show private events.

Microsoft Outlook / Office 365
  1. Open Outlook Calendar
  2. Click ⚙️ Settings → View all Outlook settings
  3. Go to Calendar → Shared calendars
  4. Under "Publish a calendar", select your calendar
  5. Click Publish and copy the ICS link
Apple Calendar / iCloud
  1. Open Calendar app on Mac
  2. Right-click calendar → Share Calendar
  3. Check "Public Calendar" and copy the URL
  4. Replace webcal:// with https:// when pasting

Configuration

Settings Overview

Click Settings in the Property Inspector to access:

Setting Description Default
Calendars Add/remove named calendars -
Default Calendar Used when button has no selection First added
Orange Warning Minutes before meeting 5 min
Red Warning Seconds before meeting 30 sec
Title Duration How long to show meeting title 15 sec
Flash on Start Visual alert when meeting begins Off

Per-Button Options

Each button can use a different calendar from your library - just select it from the dropdown in the Property Inspector.

Troubleshooting

No events showing
  1. Verify URL is correct (test in browser - should download .ics file)
  2. Check events are within time window (default: 3 days)
  3. Double-tap button to force refresh
  4. Check if "Exclude all-day events" is filtering them out
Wrong times displayed
  1. Verify your computer's timezone is correct
  2. For Outlook: Plugin auto-converts Windows timezones
  3. Try force refresh after timezone change
Button stuck on "Loading"
  1. Check internet connection
  2. Verify calendar URL is accessible
  3. Restart Stream Deck software
  4. Check Settings for error messages

What's New in v2.4

  • Stability Fixes - Capped RRULE expansion, fetch timeouts, concurrent update guards (#26)
  • DST-Aware Recurrence - Fixed RECURRENCE-ID matching across daylight saving transitions (#27)
  • Export Diagnostics - One-click diagnostic report for easier bug reporting
  • Error Isolation - Bad events no longer break the entire calendar

See full changelog for all versions.

Development

Tech Stack

Technology Purpose
TypeScript Type-safe plugin code
Node.js SDK v2 Stream Deck integration
Vitest 572 unit tests
Rollup Bundle optimization
rrule Recurring event expansion
Luxon Timezone handling

Contributing

See CONTRIBUTING.md for:

  • Development setup
  • Architecture overview
  • Testing guidelines
  • Pull request process

Changelog

v2.4.4 (2026)

  • 🔧 Upgraded @elgato/streamdeck SDK from v1.4.1 to v2.0.2 for DRM compatibility
  • 🐛 Fixed Elgato Marketplace rejection due to manifest reading in DRM-encrypted plugins

v2.4.2 (2026)

  • 🐛 Fixed Export Diagnostics not copying to clipboard (caused "No response from plugin" false alarm)
  • 🔧 Robust clipboard fallback: execCommand → Clipboard API → manual textarea

v2.4.1 (2026)

  • 🐛 Fixed buttons showing "Loading iCal" on every background calendar refresh
  • 🐛 Background refresh failures now preserve cached data instead of clearing events

v2.4.0 (2026)

  • 🐛 Fixed CPU spike from unbounded RRULE expansion (#26)
  • 🐛 Fixed RECURRENCE-ID mismatch across DST boundaries (#27)
  • ✨ Export Diagnostics button for one-click bug reports
  • ✨ 30-second fetch timeout to prevent hangs
  • ✨ Concurrent update guard prevents stacking requests
  • ✨ Per-event error isolation for resilient parsing
  • ✨ Enhanced debug logging (500-entry buffer, error filtering)

v2.3.0 (2026)

  • ✨ Named Calendars with friendly names
  • ✨ Per-button calendar selection
  • ✨ Configurable warning thresholds
  • ✨ Graceful calendar deletion handling
  • 🐛 Fixed calendar selection persistence

v2.2.0 (2026)

  • ✨ Smart Calendar action (auto-switching)

v2.1.0 (2026)

  • ✨ Configurable title display duration
  • ✨ Flash on meeting start option
  • 🐛 Fixed startup race conditions

v2.0.0 (2026)

  • ✨ Recurring events (RRULE/EXDATE)
  • ✨ Configurable time window
  • ✨ Improved timezone handling
  • ✨ Force refresh feature

v1.1.0

  • 🎉 Initial release

License

MIT License - see LICENSE

Author

Created by Pedro Fuentes

Report Bug · Discussions · Contribute