Skip to content

backup and sync

the backup & sync screen lets you export your whole library, move it to another device, or keep a local/WebDAV copy in sync.

what is synced

synced data includes:

  • meditations (with their segments, tags, and breathing-exercise references), sessions, and tags
  • bells, soundscapes, binaural beats, generated soundscapes, breathing exercises, image backgrounds, and color presets
  • lists, audio lists, and reminders
  • meditation defaults, journal/mood settings, and the other settings stored in the app's database

easy mode settings and watch-only recitation input settings are not synced.

breathing-exercise references travel as stable sync ids. if a synced segment's reference is missing or cannot be resolved — for example a bundle written by an older app version — the segment keeps its existing selection instead of being reset. breathing segments without a selection play box breathing.

backup

backups are separate from sync. they always use the fixed file name know_that_you_are_breathing_backup.zip in a directory you choose. backups created by the old version of the app (know_you_are_breathing_backup.zip) can still be opened with restore from file.

  1. open settings > backup & sync.
  2. turn on automatically back up once a day if you want a daily backup.
  3. tap backup directory and choose a folder.
  4. tap back up now to write know_that_you_are_breathing_backup.zip.
  5. tap restore from file and pick any *.zip to restore. restoring brings back what the backup holds, including items you deleted on this device after the backup was made (deleted sessions stay deleted).

when auto-backup is on and a directory is set, the app writes a backup whenever more than 23 hours have passed since the last backup.

sync

sync performs a two-way merge with a remote copy. the sync directory is separate from the backup directory.

only one sync provider can be active at a time. if local sync is already on and you turn on webdav sync, the app disables local sync automatically, and vice versa. the watch (Data Layer) sync is always available on Android when a paired watch is connected and does not conflict with local or WebDAV sync. automatic backup is independent and is not affected.

local sync

  1. turn on local sync (the switch is labelled on).
  2. tap sync directory and choose a folder.
  3. the app merges with the unzipped files in that folder: manifest.json, data/*.json, and media/*.
  4. tap test local sync at any time for a manual sync.

watch sync (Wearable Data Layer)

when a Wear OS watch is paired with your Android phone, the watch section of backup & sync shows the paired watch status and the last sync. tap sync with watch to merge bundles with the watch immediately.

Data Layer sync transfers:

  • meditations, sessions, tags, and settings from the phone to the watch
  • completed watch sessions back to the phone for Health Connect logging
  • user-imported sounds as part of the bundle when needed

a transfer larger than about 10 mb over a metered or cellular connection shows the same mobile-data confirmation prompt as WebDAV sync. built-in sounds are referenced by stable ids and are not re-transferred.

WebDAV sync

  1. turn on webdav sync (the switch is labelled on).
  2. enter your WebDAV directory url, username, and password.
  3. optionally enter a webdav subfolder path (for example kobol or know-you-are-breathing/sync) to sync inside a subfolder instead of the root of the url.
  4. the app merges with the unzipped files on the server: manifest.json, data/*.json, and media/*.
  5. the password field always starts hidden and is never pre-filled with a saved password. an eye icon appears while you are typing so you can show or hide the password you are entering. the saved password is stored in the os keychain/keystore and is not shown on screen.
  6. WebDAV sync needs an active network connection. if the device is offline, the app shows a status error and an option to open network settings.
  7. tap test webdav sync for a manual sync.

mobile data prompt

WebDAV sync can use a lot of data. the warn before large mobile data syncs switch asks for confirmation when a sync would transfer more than about 10 mb over a cellular or metered wi-fi connection.

  • automatic syncs show the prompt at most once per hour.
  • manual syncs always show the prompt if the transfer is large.
  • the prompt is off by default. turning it on protects you from unexpectedly using mobile data, but syncs are skipped if you do not confirm.

local sync does not use the network, so this setting does not affect it.

when sync runs

sync is automatic when it is enabled. it runs on:

  • app startup and resume
  • network becoming available after being offline
  • app pause or exit
  • the manual sync buttons (mostly for testing)

a short debounce keeps the app from syncing too often, and only one sync runs at a time. if a sync fails, it is retried silently with a longer delay each time.

backup status, local sync status, and WebDAV sync status are shown separately so a failure in one does not hide the state of the others.

when a sync or backup fails, the status card turns red and shows the error message. tap error details to see the full message and stack trace. this is useful for diagnosing connection, authentication, or filesystem problems.

conflicts

if the same meditation, tag, or setting is changed on two devices, the most recent change wins. when the app cannot decide automatically, the sync status shows the number of conflicts. the data is still merged using the newest timestamp.

sound, image, and audio prompt file names

imported sounds, background images, and recorded audio prompts are saved with names based on the display name you give them, plus a short five-character disambiguator. the format is <name>_<5-chars>.<ext>. renaming a sound, image, or audio prompt label in the app also renames the file on disk.

when you sync, the app sends the media bytes using the entity's stable sync id as the bundle key, so a rename is treated as an update to the same item and does not create a duplicate copy on another device.

deletions

when you delete a meditation, tag, or sound, a tombstone is recorded. tombstones are kept for 180 days so other devices know the item was deleted. after that, they are removed automatically.