makiolaj
fbc3a192bf
Timers vibrated by the alarm vibration default and never ramped. Both are now the timers' own app-wide settings, next to the default timer sound in Settings > Timers: a Vibrate switch and the same Gradual volume picker alarms use. Timer.resolveSettings reads them instead of the alarm default and the old TimerRing.RAMP_SECONDS constant. A fresh install starts with timer vibration off, as Google Clock does, and no ramp. An existing install keeps what its timers did: a one-shot DataStore migration writes the new key from the alarm vibration default before the first read, so nobody's kitchen timer silently stops buzzing on update. A fresh install is told apart by an empty store (anything that has run once has written its boot id); the migration writes the default there too, so it never runs twice. Backups carry both new fields. A file without them restores the alarm vibration default as the timers' (what that install's timers did) and a flat ring. Silent plus vibration off still signals: Silent gives the player no sources, and its onSilenced callback starts the vibrator whatever the setting says. The settings row says so. Fixes #22
163 lines
6.9 KiB
Markdown
163 lines
6.9 KiB
Markdown
# Clockula backup format
|
|
|
|
`clockula-backup-v1.json` is a documented, versioned JSON export of Clockula's
|
|
own data, written to (and read from) a user-chosen folder via SAF
|
|
(`docs/PLAN.md` §7). This file is the schema's source of truth; the codec
|
|
(`data/backup/BackupDto.kt`, `BackupCodec.kt`) implements exactly what is
|
|
written here.
|
|
|
|
## Top level
|
|
|
|
```json
|
|
{
|
|
"format": "clockula-backup",
|
|
"version": 1,
|
|
"exportedAt": 1700000000000,
|
|
"alarms": [ … ],
|
|
"timers": [ … ],
|
|
"worldClocks": [ … ],
|
|
"settings": { … }
|
|
}
|
|
```
|
|
|
|
- `format`: must be exactly `"clockula-backup"`.
|
|
- `version`: must be exactly `1`. Any other value rejects the whole file:
|
|
Clockula does not guess at a schema it has not implemented.
|
|
- `exportedAt`: epoch milliseconds, informational only (not re-imported).
|
|
|
|
## Parsing rules
|
|
|
|
- **Tolerant of unknown fields, at any level.** An older or newer client's
|
|
extra field is ignored, never an error.
|
|
- **Strict about known fields.** A malformed value in a field this schema
|
|
defines (`format`, `version`, an alarm's `hour`/`minute`, a world clock's
|
|
`zone_id`, a timer's `duration_millis`) rejects the **whole file** with a
|
|
specific reason. Nothing is imported half-way.
|
|
- Settings values (snooze minutes, volume ramp, …) are
|
|
**not** range-checked at parse time; they pass through the same clamps
|
|
`ClockPrefs`/`SettingsPrefs` already apply on every write, so a value from
|
|
a future, more permissive version degrades to the nearest valid one instead
|
|
of failing the import.
|
|
- An alarm's own `snooze_minutes`, `snooze_limit` and `volume_ramp_seconds`
|
|
are clamped at parse time to the same ranges as the defaults they
|
|
override, and a timer's `duration_millis` to the setup range (1 second to
|
|
24 hours). Room has no clamp of its own, so this is where it happens.
|
|
- A missing `default_timer_vibrate` (a file from before timers had their own
|
|
vibration setting) restores `default_vibrate` in its place: that is what
|
|
the exporting install's timers vibrated by. A missing
|
|
`default_timer_volume_ramp_seconds` restores 0, the ring timers had then.
|
|
- A missing `timer_presets` keeps the built-in presets. An empty list is a
|
|
user who removed them all, and is imported as such.
|
|
- An enum field with a name this version does not recognise (a `dismiss_
|
|
challenge` or `theme_mode` from a future version, say) degrades to that
|
|
field's default, the same forgiving-read posture `AlarmMapper` already uses
|
|
for a corrupt Room row. It does not fail the import.
|
|
- Import and export are limited to 8 MiB. Import also rejects more than 10,000
|
|
alarms, 10,000 timers, 1,000 world clocks, oversized labels or ringtone URIs,
|
|
and more than 1,000 timer presets. These limits keep a picked document from
|
|
exhausting memory or creating an impractical number of rows.
|
|
|
|
## Import semantics
|
|
|
|
Import **replaces all state**: alarms, timers and world clocks are deleted
|
|
and re-created from the file, and every setting the file carries is written
|
|
over the current value. This is not a merge, and the backup screen says so
|
|
before the user confirms. Settings are written in one DataStore transaction;
|
|
the three Room tables are replaced in one database transaction. The live ring
|
|
and timer services are paused while the tables change. If the database replace
|
|
fails, the old rows remain, the previous settings are restored, and the ring
|
|
and timer registrations are resumed. Scheduling is reconciled after either
|
|
outcome. An imported timer always starts idle.
|
|
|
|
Export writes a complete temporary document before removing an older backup.
|
|
If the provider refuses the final rename, the complete temporary document is
|
|
kept in the chosen folder and the app reports the failure with its filename.
|
|
|
|
Every imported alarm and timer gets a **fresh id and fresh timestamps**.
|
|
The backup carries no id and no `created_at`/`updated_at`, since those are
|
|
local-database facts, not portable ones.
|
|
|
|
## Alarms
|
|
|
|
One object per row of `alarms`, config only:
|
|
|
|
| Field | Type | Notes |
|
|
|---|---|---|
|
|
| `hour` | Int | 0..23. Out of range rejects the whole file. |
|
|
| `minute` | Int | 0..59. Out of range rejects the whole file. |
|
|
| `label` | String | |
|
|
| `enabled` | Boolean | |
|
|
| `repeat_days` | Int | The 7-bit mask (`RepeatDays`); bit *n* is ISO day *n+1*. |
|
|
| `skip_next_occurrence` | Boolean | |
|
|
| `ringtone_uri` | String? | Exported as-is. See "Ringtone URIs" below. |
|
|
| `vibrate` | Boolean? | `null` = inherit the app default. |
|
|
| `snooze_minutes` | Int? | `null` = inherit. |
|
|
| `snooze_limit` | Int? | `null` = inherit. |
|
|
| `volume_ramp_seconds` | Int? | `null` = inherit. |
|
|
| `dismiss_challenge` | String? | `NONE`/`MATH`/`HOLD`, or `null` = inherit. |
|
|
| `delete_after_use` | Boolean | A transient, contract-created alarm. |
|
|
|
|
**Not exported:** the `alarm_states` ring-state table (snooze/ringing/handled-
|
|
occurrence bookkeeping). It is volatile, per-device state, not configuration,
|
|
and `docs/ARCHITECTURE.md` §4/§6 are explicit that it must never appear here.
|
|
|
|
## Timers
|
|
|
|
One object per row of `timers`, config only:
|
|
|
|
| Field | Type | Notes |
|
|
|---|---|---|
|
|
| `label` | String | |
|
|
| `duration_millis` | Long | ≥ 0. Negative rejects the whole file. |
|
|
| `ringtone_uri` | String? | |
|
|
| `sort_order` | Int | |
|
|
| `delete_after_use` | Boolean | |
|
|
|
|
**Not exported:** `state`, `remaining`, the elapsed-realtime anchors, or
|
|
`ends_at_wall_clock`. A timer's running state is meaningless on another
|
|
device or after a reboot (`docs/PLAN.md` §5). Every imported timer lands
|
|
`IDLE`, with `remaining` equal to `duration`.
|
|
|
|
## World clocks
|
|
|
|
| Field | Type | Notes |
|
|
|---|---|---|
|
|
| `zone_id` | String | Must be a zone id the *exporting* device's IANA tzdata knows (`Zones.isValid`). A bad id rejects the whole file. |
|
|
| `label` | String? | |
|
|
| `sort_order` | Int | |
|
|
|
|
## Settings
|
|
|
|
```json
|
|
"settings": {
|
|
"theme_mode": "SYSTEM",
|
|
"dynamic_color": true,
|
|
"default_snooze_minutes": 10,
|
|
"default_snooze_limit": 3,
|
|
"default_vibrate": true,
|
|
"default_volume_ramp_seconds": 15,
|
|
"default_alarm_ringtone_uri": null,
|
|
"default_timer_ringtone_uri": null,
|
|
"default_timer_vibrate": false,
|
|
"default_timer_volume_ramp_seconds": 0,
|
|
"default_dismiss_challenge": "NONE",
|
|
"home_zone_id": null,
|
|
"timer_presets": [60000, 120000, 180000, 300000, 600000, 900000, 1800000, 3600000]
|
|
}
|
|
```
|
|
|
|
Field names mirror `ClockPrefs`'/`SettingsPrefs`' own on-disk keys. Older
|
|
files may also carry `default_timer_duration_millis`, from a default timer
|
|
length setting that has since been removed; it is ignored on import like any
|
|
other unknown field. Every
|
|
numeric/duration value is clamped on *apply* using the same ranges and encoding
|
|
as the existing preference setters, never on parse.
|
|
|
|
## Ringtone URIs
|
|
|
|
Exported exactly as stored (a `content://` URI, typically). On import the
|
|
URI is written back unchanged; if the *importing* device cannot resolve it
|
|
at ring/preview time, the existing ringtone-resolution fallback already used
|
|
elsewhere in the app applies (falls through to the device default). This is
|
|
not special-cased in the backup path itself.
|