led-ticker-calendar

Calendar widget for led-ticker — displays upcoming events from any .ics feed as a rotating agenda, a live next-event countdown, or per-event two-row cards.

Prerequisites

• A working led-ticker install.
• A public .ics URL (Google Calendar "Secret address in iCal format", iCloud shared calendar link, or an Outlook/Office365 ICS link) — or a local file:// path.

Install

This plugin auto-registers via the led_ticker.plugins entry point — once the package is installed, no [plugins] config change is needed.

Into a containerized led-ticker (recommended): the plugin is already listed in config/requirements-plugins.example.txt. Copy that to the live file and rebuild:

# in your led-ticker checkout
cp config/requirements-plugins.example.txt config/requirements-plugins.txt
docker compose up -d --build

That example file lists every first-party plugin — trim the live copy to just the ones you want. The calendar line is:

led-ticker-calendar

Standalone (a venv that already has led-ticker):

pip install led-ticker-calendar

See the led-ticker Plugins docs for the constraint-based install the Docker image uses.

Once installed, the calendar.events widget is available automatically.

What it provides

One widget: type = "calendar.events" — an .ics feed subscriber with three layouts.

Layouts

• layout = "agenda" (default) — one scrolling line per upcoming event. Two-tone: the time phrase (Tomorrow 3:09 PM ·) renders in time_color; the event title renders in font_color. Events matching highlight appear in highlight_color (both segments, whole-line attention state). Up to max_events events from the next lookahead_days days.
• layout = "next" — a single live countdown to the soonest event (Standup · in 25m, Standup · now). The countdown phrase ticks down live every display cycle. All-day events today show · today.
• layout = "two_row" — one card per event: the held top row shows the day + time (Tomorrow 3:09 PM); the scrolling bottom row shows the event title. Supports the top_* per-row knobs below.

The widget is a Container: a background task polls the feed at update_interval; the display loop re-reads feed_stories on every pass so updates surface within one cycle without restarting.

Config

New to led-ticker configs? The first-config tutorial walks through the overall structure. The blocks below show only the calendar-specific keys.

Agenda (default)

[[playlist.section]]
mode = "swap"
content_height = 16
hold_time = 8

[[playlist.section.widget]]
type = "calendar.events"
ics_url = "https://calendar.google.com/calendar/ical/.../basic.ics"
layout = "agenda"
timezone = "America/New_York"
time_format = "12h"
max_events = 5
lookahead_days = 7
highlight = ["1:1", "interview"]
time_color = [0, 200, 255]
font_color = "rainbow"

Two-row cards (bigsign)

The held day+time row can overflow at default_scale = 4 (only 64 logical pixels wide). Drop to scale = 2 to give each row more room, and use a smaller font:

[[playlist.section]]
mode = "swap"
scale = 2
content_height = 24
hold_time = 10

[[playlist.section.widget]]
type = "calendar.events"
ics_url = "https://calendar.google.com/calendar/ical/.../basic.ics"
layout = "two_row"
timezone = "America/New_York"
time_format = "12h"
max_events = 5
font = "Inter-Regular"
font_size = 16
font_threshold = 80
time_color = [255, 200, 60]
font_color = [255, 255, 255]
highlight = ["1:1", "interview"]

Next (live countdown)

[[playlist.section]]
mode = "swap"
content_height = 16
hold_time = 20

[[playlist.section.widget]]
type = "calendar.events"
ics_url = "https://calendar.google.com/calendar/ical/.../basic.ics"
layout = "next"
timezone = "America/New_York"
font_color = [255, 255, 255]
time_color = "rainbow"
empty_text = "No upcoming events"

Field reference

ics_url is the only required field — everything below is optional tuning.

top_row_height, top_text_y_offset, and bottom_text_y_offset apply only with layout = "two_row" — they are silently ignored under other layouts.

Development

led-ticker isn't on PyPI, so this plugin resolves it from a sibling checkout. Clone both side by side:

~/projects/.../led-ticker
~/projects/.../led-ticker-calendar

uv sync --extra dev      # resolves led-ticker from ../led-ticker
uv run pytest -q
uv run ruff check src tests

Tests that need a headless canvas obtain one via HeadlessBackend(...).create_canvas() from led_ticker.plugin (the shipped headless backend in led-ticker-core ≥ 2.1) — no rgbmatrix stub or PYTHONPATH plumbing required.

The plugin imports only the public led_ticker.plugin surface — tests/test_import_purity.py enforces it.

Links

• led-ticker — the core project
• Docs site · Plugin system