Repository navigation
Panes Spec
Part of the Relay design spec. See the contents.
Pane 1
A plain alarm is still two taps away. What an alarm does when it fires is a choice.
- Sorted by next fire time (v0.5 sorted by hour and minute). Each row shows time, repeat summary, label, a target icon (bell / timer / relay / stopwatch) and an on/off toggle.
- Tap a row to edit it. Create with +: the time picker comes first, as in the stock app.
| Target | On fire | Config |
|---|---|---|
| Ring (default) | Full-screen ringing: Dismiss / Snooze | Sound, vibration, volume ramp, snooze length, max snoozes |
| Notify | A heads-up notification with its usual sound; no ringing screen, no snooze (§10b) | None |
| Timer | Starts a run. Example: a countdown starting exactly at 17:00 | A named library timer, or an inline anonymous duration |
| Relay | Starts a run. Example: a snooze-less wake-up of five timers with escalating sounds | A named library relay, or an inline anonymous script (same editor as §05) |
| Stopwatch | Creates and starts a stopwatch at that moment. Example: counting from 16:00, lap whenever | Optional name, optional t₀ |
Anonymous targets don't exist beforehand: the schedule creates them. A label is optional and is shown when it rings. Save to library turns an inline target into a normal library definition, which the schedule then references.
- Time. Either one-off (the next occurrence, or a picked date) or repeating on a set of weekdays.
- One-off after firing: delete, or keep and disable.
- Repeat end: never, an end date, or after N occurrences.
- Exceptions: skip, or retime, a single date or a date range. You can apply one exception to several alarms at once (for example a vacation week).
-
Full-screen over the lock screen and wakes the screen, with big Dismiss / Snooze controls.
new -
Rings continuously until you act on it or a ring timeout passes, and other notifications can't cut it off.
new - Gradually increasing volume (configurable ramp) and vibration.
new - Snooze length and max-snooze count are per alarm. When snoozes run out, Snooze is hidden.
keep -
Upcoming-alarm notification a configurable lead time before firing (stock default: 2 h), with "Dismiss now". On a repeating alarm, that adds a one-off skip exception.
new - If it fires late (device off, clock change), it rings with a clear "delayed from 07:00" notice instead of silently skipping. That applies up to 60 minutes late. Anything older only gets a "missed alarm" notification, since a 07:00 alarm ringing at 15:00 helps nobody.
- When the ring timeout passes unanswered, the alarm stops and leaves a notification saying so. It counts as dismissed.
As built: a non-ringing target starts quietly at the alarm time (no ringing screen); its own run or stopwatch notification shows up as when started by hand. A start cue (beep, chime, … or silent, chosen per alarm) plays as it starts. If it can't start (the saved timer was deleted, the relay is broken), the alarm rings instead and says why: a scheduled start never fails silently. A one-off's "after it fires" choice applies the moment it starts.
Snooze only applies to the Ring target. For Timer, Relay and Stopwatch targets, the run's own controls take over when it fires. Their "snooze" is simply the relay itself (see the wake-up example in §06).
Pane 2
- Active runs at the top: one card per run, each with its own countdown and controls.
- Library below: named timers and relays. Each card shows the label, the kind and the total duration, plus a ▶ start button.
- The library can be sorted by the user, with named headers: headers move up and down, and blocks drag freely under any header.
- The existing three: New timer, New relay, New header.
-
Quick starts sit as four small buttons to the left of the +, default
1m5m10m15m(configurable in Settings). One tap starts an anonymous timer run. (v1.0 had them inside the + menu; v1.1 moved them out to save a tap.)
- Fields: optional label, duration (one duration in the relay language:
25m,1h30m,90), sound (tune, vibration), and a warning (v1.1). -
Length keypad (v1.1): the duration comes first and is typed on the app's own keypad: digits,
hms, backspace (long-press clears), and+1m+5m+10m. Android can't restrict the system keyboard to those keys, hence a drawn keypad, as in the stock app. It writes the same relay-language text; a keyboard icon swaps to the full keyboard for anything else (RANDOM(5, 10)). A new timer opens with an empty length and the keypad up. -
Warned timer (v1.1): "Warn before the end" (Off, 30s, 1m, 2m, 5m, custom seconds) and a cue. The plan becomes two steps, length − warning then warning, with a seamless cue between: the same machinery as a relay
(19m, 1m)set to "Continue by itself", so the firing path is unchanged. The run still shows one countdown to the real end. Inside a relay a timer's warning is ignored: the relay's boundaries rule. -
Saved labels are script names: letters, digits and
_, starting with a letter, not a keyword, and unique across timers and relays. Renaming a saved block updates every relay that uses it. Unsaved labels are free text. - The config screen has Start (an unsaved run, keeping its label) and Save (to the library, requires a unique label). Saving doesn't start it. Start it from the library card.
- Editing works on a draft: the editor opens a copy, and the definition only changes on Save. Anything started in the meantime (by hand or by a schedule) uses the saved version.
- Parallel runs: starting "Test" while "Test" is running spawns an independent second run, labelled "Test · 2".
- Run controls: pause/resume, reset, +1 min, stop.
- At zero, it rings through the firing module (§13), showing its label, with Stop / Restart / +1 min. Stop on an unsaved run discards it. On a saved run, Stop just ends that run.
- Fields: optional label, script (§06), default sound (for anonymous steps), transition mode, seamless-transition tone.
keep - Steps can be anonymous durations, named timers, or other named relays.
-
Transition mode, per relay: seamless plays a short cue (beep, double beep, chime, pip, or silent) and continues. Interaction required rings the ending step's sound until you tap Continue (or Stop relay).
keep - Terminal completion: Stop / Restart / +1 min. Restart goes back to the relay's first step. +1 min extends only the last step.
-
Per-step override of sound and transition mode for the boundary after a given step, so one relay can vary its own cues ("seamless into Break, but confirm before Work"). Unlisted steps keep the relay defaults. To set one, tap a step in the relay's live preview, then choose its sound and outgoing transition (provisional: confirm in the prototype).
new
- Auto-closes
(.new - Enter after
(or a separator auto-indents.new - Commas and newlines are both valid separators.
-
newAutocomplete: while you type a name, a drop-down lists named timers and relays that match. It leaves out the relay being edited and anything that would create a cycle. - Live preview: resolved steps and total duration, recomputed as you type. Errors appear inline, with position.
- A syntax help sheet, since the language is powerful but unfamiliar to most people. That's accepted.
- Start is enabled only for a valid relay; Save only for a valid relay with a valid label. The beep-between-steps choice is hidden when every boundary waits for you.
- A relay can never contain itself, directly or indirectly. Saving is rejected, and the cycle path is shown (Workday → Session → Workday).
Pane 3
- Any number of stopwatches at once, each a card in a list, running or paused, until deleted.
- Per card: lap (while running), pause/resume, restart (to t₀), rename, delete.
- Optional name, optional t₀ start offset, which may be negative: −2 m counts up from −2:00 through zero and on (a v0.5 accident worth keeping).
- Laps show both the delta and the cumulative time. The first lap's delta is measured from t₀.
-
Each lap can take a free-text note, added or edited at any time.
new -
Tags: each stopwatch has its own tag list (e.g. "run", "break"; no shared pool). Laps take any of them, alongside the note. While running there's one Lap button per tag, for one-tap tagged laps.
new -
Lap corrections fix tapping mistakes without changing the total: remove a lap (merges into the previous one, which keeps its note and tags; lap 1 merges into lap 2), insert a lap a given time into an existing one, or adjust a lap's end by a signed amount (
5= seconds,5s,2m,-5s,1:30; units h/m/s only). No lap may end up shorter than zero. Each correction can carry a label, and a ★ marks laps it changed.new -
History, undo and redo: corrections are listed per stopwatch, including removed laps. Undo and redo walk that list without limit; undone entries stay greyed until a new correction drops them. Taking new laps doesn't break undo. Restart clears laps and history.
new -
Lap chart: from the stopwatch's header, bars per lap in lap order, filterable by tag, with count, average, fastest and slowest above.
new - A lap list header names the columns: Lap, Lap time, Total.
- Export laps (CSV).
later - State:
accumulated+startedAt?. The elapsed time is computed, never ticked. -
Persisted in Room
changed. This is needed for scheduled starts, and it removes v0.5's unresolved "seed row" workaround. The cost is small. - An ongoing notification with Lap / Pause while one is running.
new
Pane 4
Laid out like the stock app: one large styled clock on top, a list of locations below. This replaces v0.5's "library of clocks".
- Main clock: local time, large, with seconds, in the user's chosen style. It's the tap target for every widget.
- Locations list: city name, time, day and offset relative to local ("Tomorrow, +9 h"). Add a location through city search. Swipe to delete, drag to reorder.
- Optional stock-style home clock: when you're travelling outside your home time zone (set in Settings), the home time is shown automatically.
new
- Font: system · serif · mono · 7-segment · display face
- Format: follow setting / 12 h / 24 h
- Seconds: on / off
- Date: off / pattern
- Colors: digits, secondary, background
- Hand style: thick · thin · dot
- Marks: none · minutes (60, bolder hours) · hours (12) · quarters (12/3/6/9)
- Face: none · ring · filled · numerals
- Second hand: on / off
- Colors: each hand, ticks, face, background
Colors come from the theme palette, plus a custom picker for any element.
One renderer is shared: it draws on a plain Android canvas, used through Compose in the app and into a bitmap for widgets, so both always agree. The 7-segment face (DSEG7) and the display face (Fraunces) are bundled fonts under the SIL Open Font Licence; the licence texts ship in assets/licenses/.
Home screen
- Each placed widget is its own instance with its own ClockStyle (digital or analogue) and location (local by default, or any time zone, with an optional city label).
- A configure screen appears on placement, and you can reconfigure through the long-press "Widget settings". Removing a widget deletes its config.
- Extra widget-only axes: background (transparent / follow theme / solid / gradient), corner shape, border.
- Each widget is drawn as one bitmap from its own settings: Glance can't use bundled fonts, gradients or a canvas, and a bitmap makes the widget look exactly like the in-app clock.
- Minute granularity, from a non-wakeup exact alarm at each minute boundary: no battery cost with the screen off, and the pending tick lands as soon as the phone wakes. Tapping the widget opens the app like its icon does, on the pane last used (v1.1; v1.0 opened the Clock pane).
- A world-clock list widget and a "next alarm" widget.
later
Pane 6?
Not in 1.0. The goal is replacing the stock app entirely. Feasibility varies per piece. What the stock app does through private Google integrations isn't open to us.
| Stock feature | Feasible? | How |
|---|---|---|
| Bedtime schedule + reminder notification | Yes | Just a schedule with a notification target |
| Linked wake-up alarm | Yes | A schedule, which can target a relay (for example Wake) |
| Do Not Disturb during bedtime | Yes |
AutomaticZenRule / notification policy access. The user grants it once |
| Sunrise alarm (screen brightens before the alarm) | Probably | A full-screen activity started N minutes early, ramping brightness. Needs device testing |
| Sleep sounds | Yes, but big scope | Media playback with a sleep timer |
| Grayscale / wind-down (Digital Wellbeing bedtime mode) | Likely no | No public API known. Verify |
| Sleep tracking | Maybe | Google Play services Sleep API. Verify, low priority |
Pane 2. Planning: events, reminders, and later other actions (#14)
The Calendar pane is where timed things are planned; the Alarms pane stays where alarms are kept. Calendar replaces Settings in the bottom bar (Alarms, Calendar, Timers, Stopwatch, Clock); Settings opens from a gear in every pane header, next to the guide's ?.
- A month grid (six weeks, first day of week from Settings) with up to three dots on days that have entries. Arrows and a sideways swipe change month; Today jumps back. Each day reads its date and item count to TalkBack, so dots are never the only signal.
- Below it, the selected day's entries: all-day first, then by time. Tapping one opens its editor (an alarm opens the alarm editor).
- Calendars (#34): every item and every alarm belongs to one. Each has a name, a colour and defaults for new items (reminder lead and target, repeat); one is where new alarms go. The v9 update made Personal (items), Birthdays (yearly) and Alarms (alarms, unticked unless "Everything scheduled" was on); their blank names show translated. The pane's layers button lists them with show/hide ticks, edit and add; deleting one asks where its items and alarms move, and the last can't go. An item can override its calendar's colour. Alarms show from today on (a count-limited one stops after its remaining count).
- Colour everywhere: dots, day-list row bars, widget labels and rows, the Alarms list's row bar. The palette has twelve colours that carry white text at 4.5:1, plus custom.
- Multi-day items (#35) are one bar across their days in the grid (wrapping at week ends, packed into lanes) and listed once, as "Mon 10 – Wed 12", in the day list and the agenda.
- + offers New event and New reminder, on the selected day.
- Tapping the month's name opens a month/year picker: a year with arrows, twelve months, and Today.
Phone calendars (#16)
Through Android's CalendarContract, not the Google REST API: no account, OAuth or network code in Relay; the phone's calendar apps sync.
-
Read-in: the calendars sheet's "On this phone" lists the visible phone calendars (needs
READ_CALENDAR, asked for only there). Each has its own tick (stored as a set of ids in settings; in widgets asphone:<id>keys among the calendar ids) and its provider colour. Their occurrences come fromCalendarContract.Instances(repeats expanded), shown read-only and never stored; a tap opens the event in its calendar app. A ContentObserver re-reads on any change. -
Write-out: a Relay calendar can copy its items to a writable phone calendar (
exportCalendarId, needsWRITE_CALENDAR). Saving an item writes or updates its copy (providerEventId), deleting removes it, and changing or clearing the target re-syncs the whole calendar. One-offs get DTSTART/DTEND; repeats get DURATION and an RRULE (WEEKLY;BYDAY, MONTHLY;BYMONTHDAY, YEARLY;BYMONTH;BYMONTHDAY, UNTIL in UTC). All-day items are UTC midnight to midnight. A copy that can't be written never fails the save. - Relay's own copies are left out of the read-in, so nothing shows twice.
Calendar files (#33)
-
Import: opening or sharing a
text/calendarfile into Relay (an exported activity that checks what it's given: content or file addresses only, at most 2 MB), or Import file in the calendars sheet. Our own RFC 5545 reader (no library): unfolds lines, unescapes text, reads DTSTART/DTEND/DURATION as dates, floating, UTC or TZID times into the phone's zone, RRULE, the first VALARM's relative trigger; skips cancelled and malformed events; at most 5000 events. The screen shows what it found and asks which calendar; Import saves throughEventRepository, so copies and reminders behave as for typed items. -
Re-import: an event's UID (
icsUid) is matched within the target calendar, so an item is updated in place (id, colour and copy kept) rather than duplicated. A file's reminder replaces the item's; without one it keeps its own. - Repeats: a rule in the #43 set is kept (simple ones as the old fields); any other becomes the first date, with a line in the note naming the rule.
- Export: a whole calendar (its edit dialog) or one item (the editor's share button) as an .ics through the share sheet, via a FileProvider over a cache folder. UIDs are kept or made from the item's id, repeats use the same RRULE mapping as #16, reminders become VALARMs.
-
Subscription: Subscribe in the calendars sheet takes an https:// or webcal:// address (webcal read as https; nothing else accepted) and makes a read-only calendar (
subscriptionUrl). Relay fetches it on subscribe, on Refresh now, and when the app is opened ifrefreshedAtMillisis over 6 h old; never for anything that rings. Fetches have a 15 s timeout and the 2 MB cap, and send nothing but the request. This is Relay's only network use (INTERNET), and the dialog says so. A refresh replaces the calendar's items: matched by UID and updated in place, the rest removed; no reminders are kept. Its name and colour can change, nothing else: it can't take new items or alarms or be a copy target, a tap on its item shows a toast (a widget tap opens its day), and deleting it removes its items.
Widgets (#15)
Native Glance, not bitmaps, so text stays crisp; the frame (background, corners, border) is drawn behind them as on the clock widget. Each widget has its own settings in widget_configs: which calendars it shows and the frame. A widget from before calendars shows what it did until edited. Text colour follows the theme, or contrasts with a chosen background.
- Calendar: next 7 days: a scrollable list under day headings. Row → that item's editor; heading → the pane on that day; + → new event today.
- Calendar: month: like Google Calendar's month widget. Each day lists its entries as small labels with their titles in their colours, multi-day items as bars across their days (up to two lanes a week, sized from the widget's width since Glance can't span cells), with "+n" for what doesn't fit; how many fit follows the widget's height. ‹ › turn the month in place (Glance action callback); a day or the month's name opens the pane there.
- They refresh when items, schedules or settings change (the app process follows the data and redraws), at midnight (one non-wakeup alarm a day while any is placed), and after a reboot, a clock or time-zone change, or an app update.
- Widget taps go through MainActivity extras, which are checked before use: ids must exist, days must be sane.
| Kind | Fields | Reminder |
|---|---|---|
| Event | Title, date, start time or all day, optional end time, optional last day, note, repeat | Optional. Timed: at start, 5, 15 (default), 30 min, 1 h, 1 day before. All day: 09:00 on the day (default) or 09:00 the day before |
| Reminder | Title, date, time, note, repeat | Always, at its time |
- What a reminder does uses the alarm editor's "When it goes off" section: Notify (default for calendar items), Ring, or start a timer, relay or stopwatch.
- Repeat (#43): none, daily, weekly on chosen weekdays, monthly or yearly, every N of them. Monthly and yearly land on the date, the same weekday ("the second Tuesday", up to the 4th), the last such weekday, or the last day, as the item's date allows. Ends never, on a date, or after N times. Never before the item's date. A month without the date has no occurrence (BYMONTHDAY's rule too); the editor warns ("Skips months that have no day 31", "Only in leap years").
- Storage: repeats the old fields can hold (weekly, monthly or yearly on the date, every one, no count) keep them; everything else is RepeatKind.CUSTOM with an RFC 5545 rule (
repeatRule, without UNTIL, which stays inuntilEpochDay). The supported set: DAILY/WEEKLY/MONTHLY/YEARLY, INTERVAL, COUNT, BYDAY with ordinals, BYMONTHDAY (negative from the end), BYMONTH. One pure evaluator (RruleDates) gives the dates for the grid, the widgets and the reminder schedule, which carries the rule too, so they agree. A rule outside the set (from a calendar file) is kept as is and shown as such until changed. - A multi-day event shows on every day it covers, marked "Continues" after the first.
- Editors are modal (Save or Discard). Delete asks first and says the reminder goes too.
An item's reminder is an ordinary schedule with eventId pointing back at it. The schedule carries everything firing needs (date or repeat, start bound, monthly/yearly day, lead time), so §13 never reads the events table, and snooze, boot re-arming and late fires work unchanged. Edge rules:
- A one-off reminder whose time has passed is saved but not armed ("Reminder time has passed"); unlike a one-off alarm, it is never moved to tomorrow. After it fires it is kept, switched off, not deleted.
- Notify posts a heads-up notification (channel "Reminders") with the title, day, time and note; tap opens Calendar. No ringing screen, no snooze, and no "upcoming" notice before it. Also offered for alarms.
- Reminder schedules don't appear in the Alarms list or in its "also apply to" exception list.
| Piece | Feasible? | How |
|---|---|---|
| Edit or skip one occurrence of a repeating item | Yes | Exceptions on the reminder schedule, plus an item-level exception for the grid |
| Repeat count, several reminders per item, monthly by weekday ("2nd Tuesday") | Yes | More columns; NextFire math for the weekday rule |
| Other actions (webhooks, Tasker) | Yes | New targets (#19) |
| Full two-way sync | Possible, not worth it | Conflict handling for edits on both sides |
| Ringing for Google Calendar events | Maybe | Opt-in per calendar; re-query on ACTION_PROVIDER_CHANGED (#42) |
The gear in every pane header (not in the bottom bar since §10b)
- Theme: system / light / dark / AMOLED
- Clock format: 12 h / 24 h
- First day of week: DayOfWeek
-
Home time zone: ZoneId
new - Language: system / en / nb
-
Default snooze length: min
keep -
Default alarm sound: Uri
new -
Volume ramp: off / seconds
new -
Ring timeout: default 10 min
new -
Upcoming-alarm lead time: off / duration
new
-
Quick-start durations (4): 1m 5m 10m 15m
new -
Default timer sound: Uri
new -
Max plan size: ≤ 1000
keep -
Long-relay warning: duration
new
- Haptics: on / off
-
Assistant / app control: on / off
later - Reset all data: with confirmation
- App version: from git tag
Hands-free
Future feature, not in 1.0. The design is kept here so the command layer can be shaped for it from the start. Only the command layer itself (one internal API that the UI also uses) is built in 1.0.
"Five wake-up alarms, five minutes apart" shouldn't need a loop in the relay language, which would be hard to build and hard to use. An assistant can do the looping instead. Relay just needs a clean API for it.
All three entry points call one internal command layer, the same one the UI uses. So validation is identical: scripts are parsed, cycle-checked and size-checked no matter who submits them.
| Entry point | What it covers | Status |
|---|---|---|
Standard Android clock intents: ACTION_SET_ALARM, ACTION_SET_TIMER, ACTION_SHOW_ALARMS, ACTION_SHOW_TIMERS, ACTION_DISMISS_ALARM, ACTION_SNOOZE_ALARM
|
What Gemini and other assistants already send to "the clock app" for "set an alarm for 7". One plain alarm or timer per intent, but an assistant can send several. A label passes through as the run label | Future. Well-established API, the first to build |
Batch import: a JSON document, received by share-to-Relay (text or .json) or a VIEW intent |
Any number of schedules, timers and relays, including scheduled relay targets. Works with any AI app that can produce text | Future |
AppFunctions (androidx.appfunctions, Android 16+) |
Typed functions (createSchedules, startTimer, listAlarms, …) that on-device agents discover and call directly, with no text round-trip |
Future, after a spike. Newest and least certain. First verify that Gemini actually calls third-party AppFunctions on your device |
{
"relay": 1,
"schedules": [
{ "time": "06:30", "repeat": ["MO","TU","WE","TH","FR"], "label": "wake_1", "target": { "ring": {} } },
{ "time": "06:35", "repeat": ["MO","TU","WE","TH","FR"], "label": "wake_2", "target": { "ring": {} } },
{ "time": "17:00", "target": { "relay": { "ref": "Workday" } } }
],
"library": [
{ "kind": "timer", "label": "Tea", "duration": "4m" },
{ "kind": "relay", "label": "Wake", "script": "(Nudge, Nudge, Loud)", "transition": "interaction" }
]
}
-
JSON, formatted for people too: short keys, times and durations as plain strings (
"06:30","4m"), and relay content written in the relay language. You can hand-edit it as easily as an assistant can generate it. - Becoming the handler: assistants send standard intents to whichever app handles them. A one-time onboarding hint explains how to make Relay that app. Verify how Gemini picks the handler when this is built.
- A human confirms every batch: the preview shows each item, and you can untick items. Nothing is written until you tap Create.
- Deleting or bulk-disabling through any entry point always asks for confirmation in the app. Standard intents that only create or show things need no extra step, matching stock behaviour.
- Everything created externally gets a small "added by <app>" marker, so it's easy to find and undo.
- One Settings switch turns all external control off.
- The JSON schema is published in the app's help and in the repo, so any assistant can be pointed at it.
Relay · spec v1.0 · clean-restart baseline, update as screens get built