Wear OS guide

the watch app is a separate build of the same Flutter project, produced by the wear Android product flavor. it is a standalone, offline-first Wear OS app with the same meditation engine as the phone and desktop apps.

building and running

you need a watch or emulator running Wear OS 3+ (API 30+). build and install with:

flutter run --flavor wear -t lib/main_wear.dart

to produce a release APK (always run a clean first because the Wear OS entry point can otherwise be cached as the phone one):

flutter clean
flutter build apk --flavor wear --release -t lib/main_wear.dart

the wear flavor sets minSdk = 30 and shares the phone app's application id, which the Wear OS Data Layer requires for phone/watch pairing.

home screen

the watch home screen lists the available entry points:

easy mode — quick-start meditation, recitation, or breathing session with mode-specific settings.
meditations — pick from your saved, non-archived meditations.
insights — current streak, sessions and minutes this week, the last session, and a short list of recent sessions.
settings — watch-specific and shared app settings, including Data Layer sync status and a manual sync now button.

the dedicated recitation entry was removed: recitation is reached through easy mode or by tapping a recitation meditation in the saved list.

the app icon is the first item in the scrollable home list. when the list is at the top it provides top padding, and it scrolls away with the menu so the entire vertical space is usable. the first and last entries can be scrolled into the round safe area. long labels are shrunk to a single line so they stay readable. tap an entry to open it. use the system back gesture to return to the home list.

meditations

the meditations screen shows only the meditations you have chosen to sync to your watch. each saved meditation has a sync to watch toggle in the phone editor that appears after the phone has connected to a watch before. only active, non-archived meditations with this toggle on are sent to the watch. they are synced through the Wearable Data Layer and stored in the local Drift database, so the list works offline. scroll the list with the crown or by swiping and tap a meditation to start it.

meditation mode opens the watch player.
recitation mode opens the watch recitation player.
breathing mode opens the watch player and play the guided breathing exercise.
meditations that mix different segment modes show a layered icon.
the list is read-only: you cannot create, edit, archive, or delete meditations from the watch.
long meditation names shrink to a single line so they stay readable on the round screen.
if you turn off sync to watch on the phone or archive a meditation, it disappears from the watch on the next sync.

easy mode

the watch easy mode screen lets you configure a quick session. tap the mode icon at the top to cycle through meditation, recitation, and breathing. the app icon sits above the mode toggle and scrolls away with the form:

meditation mode — pick duration with the three crown-scrolling wheels, plus a bell and optional soundscape.
recitation mode — pick a target count, plus a bell and optional soundscape.
breathing mode — pick the breathing exercise and number of cycles, plus a session bell, inhale, exhale, and hold bells and an optional soundscape.

scroll the screen with the crown or by swiping along the right edge to bring the start button into view, then tap it to begin. extra bottom padding lets the start button scroll into view. your choices are saved as watch easy-mode defaults so the next session starts with the same settings.

player

the watch player reuses the same meditation timing and bell scheduling as the phone app:

a large visualizer shows the remaining / elapsed time. the visualizer style (dot, tree, wave, circle, starfield, or dotted sphere) is picked from the current segment or the meditation default, matching the phone player. during breathing segments the ring is driven by the breath phase (it fills on inhale and shrinks on exhale) and the current phase (inhale, exhale, hold) is shown in the centre. meditation segments can also use dot/tree/wave visualizers with a synthetic 6-second breathing rhythm. labels stay centred over the visualizer — the round face leaves no room below it the way the phone has — and use a dark text shadow; each transport control icon uses the same shadow, so they stay readable over the animation without covering it.
the play, pause, and stop buttons sit just above the bottom of the ring so they do not cover the animated progress ring.
when playing, the pause and stop buttons sit close together and centered near the bottom of the screen.
tap the pause button to pause; the play button resumes.
tap the stop button to end the session manually. if the session was not completed, the watch asks whether to save or discard it.
before starting a saved meditation, a pencil button sits next to play. it opens a rotary-scrollable session setup screen — the soundscape choice on top (as configured / none / any library sound with a volume slider), then one row per segment showing its length. tapping a row swaps in the matching wheel — duration for timed segments, cycles for breathing — and the back gesture returns to the list first, then to the player. every edit applies only to the session being started; the synced meditation is never modified. easy mode skips the pencil because its own screen already sets these.
when a session ends — on its own, when you stop early, and whether you save or discard it — a compact completion screen appears: the headline over the pond animation, and restart/close buttons. the post-session mood and journal prompts show after you leave it, and only for sessions that were saved.
for multi-segment meditations, a next segment button appears while the session is running (disabled on the last segment). to keep the small watch face uncluttered there is no previous-segment button — the phone player has both directions. a skipped segment does not make the session incomplete: only the time actually sat is logged and the expected duration adjusts to match.
if the meditation or your global settings ask for a pre-session mood or journal, a small dialog appears before the session starts. the same happens after the session for post-session mood and journal. on the watch these use the same emoji and voice-to-text options as the phone.
the screen stays awake while the session is running and active if the meditation or your global screen behavior setting is set to keep on. it releases the wake lock when the session is paused, stopped, completed, or when the watch enters ambient mode.
starting a session may ask for notification permission — that powers the media controls card on the watch. if you deny it, the session still starts and runs normally; you just do not get the media card.
the session keeps running when the screen turns off or the watch dims into ambient mode: bells, soundscapes, prompts, and haptics continue, and raising the watch restores anything the system stopped. if a particular watch still suspends sessions, turn on keep awake in the watch settings — it holds a wake lock for the whole session at the cost of more battery.
text-to-speech prompts are spoken when the device has an available engine. if it is not available, the prompt text is shown on screen instead.
missing bells or soundscapes fall back to the first built-in sound in the same category and a one-line notice appears. this can happen if a user-imported sound has not yet synced to the watch.
a breathing segment without a usable exercise falls back to box breathing, matching the phone player.
completed or manually stopped sessions are saved locally as watch-origin sessions. health sync is not performed on the watch; the session is marked unsynced so the phone can relay it. sessions sync in both directions, so phone sessions also appear in the watch's insights after a sync.

recitation

the watch recitation player has the same multi-segment and count-direction support as the phone:

a large circular visualizer shows the current count and the segment target.
tap anywhere on the ring to count up. long-press anywhere on the ring to count down.
if the meditation or your watch settings enable the stem buttons or rotary crown, a hardware button press or crown tick also counts up or down.
a single de-bounce setting applies to both screen taps and hardware events, so rapid repeated input only advances the count once in each window.
the play button starts the session. while running, pause and stop appear near the bottom; pausing resumes from the same count. tapping stop before the target is reached asks whether to save or discard the incomplete session.
a pencil button next to play opens the same session setup screen as the meditation player: the soundscape choice on top, then one row per segment. tapping a row opens a count wheel so you can run a different number of recitations just this once without editing the saved practice.
when a segment reaches its target, the screen advances to the next segment with the configured end/start bells and text-to-speech prompt. when the final segment reaches its target, the session completes automatically.
for multi-segment recitations, a next segment button appears while the session is running (disabled on the last segment). skipping ahead logs only the recitations actually counted, and the expected total adjusts so the skipped segment does not leave the session incomplete.
the watch recitation input settings are watch-only; they are not synced to the phone, so each watch keeps its own stem/rotary and debounce preferences.

insights

the insights screen shows a compact summary of your practice:

streak — your current consecutive-days streak.
this week — how many sessions and minutes you have logged in the current calendar week.
last session — the date and time of your most recent session.
recent — a short list of the last few sessions with their name, date, duration, and whether each session was completed or stopped early.

the list is read-only on the watch. full history filtering, charts, and journal editing stay on the phone.

interaction

round screens — scrollable screens use the full height and only a small horizontal inset. an icon or short header at the round top pushes the first list item into the safe area, and bottom scroll padding lets the last item be scrolled into the safe area. text that would otherwise wrap or overflow is scaled down to a single line so it stays readable.
rotary input — lists scroll with the physical crown or bezel. crown rotation is translated into a scroll wheel signal, so it scrolls at the same speed and with the same feel as dragging the list with a finger. touch scrolling keeps working everywhere the crown does. in the recitation player, the crown can also count up or down when it is enabled in the watch recitation input settings.
stem buttons — when enabled in the watch recitation input settings, the watch's physical buttons (and the center stem button) can count up or down in the recitation player.
ambient mode / AOD — ambient mode appears only when the watch's Always-on display setting is on. the app stays on screen with the active UI dimmed by the system, and it posts a Wear OS OngoingActivity so it may also appear as a tappable chip on the watch face. when the watch wakes, the app is automatically brought back to the foreground. there is no custom ambient-mode timer UI; the active screen is simply dimmed by the system. a running session keeps going while dimmed — a foreground media service keeps the bells, soundscapes, and haptics alive, and returning to the active screen re-arms anything the OS suspended.

sync and Health Connect

the watch stays in sync with the paired phone through the Wearable Data Layer. open settings on the watch to see:

whether the watch is connected to a paired phone
a note that health sync is handled by the paired phone
silence watch — which device enters do not disturb while a session plays; tap it for details
the last successful Data Layer sync time
a sync now button
recitation input settings — enable the stem buttons and/or rotary crown as count inputs and set the debounce window. these are watch-only and do not sync to the phone.
keep awake — keeps the watch from sleeping so bells and haptics keep playing while the screen is off. use it if your watch still suspends sessions in ambient mode; it uses more battery and is watch-only.
an about tile with the app name and version.

choose which meditations sync to the watch from the phone editor. only active meditations with sync to watch enabled are sent, and the watch only receives the bells, soundscapes, lists, and tags used by those meditations. media that is no longer referenced is removed from the watch on the next sync. when the watch is downloading more than 2 mb of audio files, a brief syncing media snackbar appears. it is shown once per new batch of media — repeated syncs of unchanged media stay silent — and is dismissed when the sync finishes.

completed watch sessions are sent to the phone as soon as the session ends, and phone sessions are sent to the watch during the next Data Layer sync. the phone writes the session to Health Connect in the background if the required permission has already been granted. if the phone has not yet been granted Health Connect permission, the session is queued and written the next time you open the phone app and grant it.

you do not need to open the phone app for Health Connect logging to work, but Health Connect permission does need to be granted once from the phone.

notifications

mindfulness reminders scheduled on the phone are mirrored to the paired watch by Wear OS, as long as notification sync is enabled for the app on the watch. the watch does not schedule its own reminders, so you only manage your reminders from the phone.

do not disturb

sessions started on the watch honor the shared silence phone option:

when the watch has do not disturb access it silences itself for the session and restores the previous state when the session ends.
otherwise the paired phone enters do not disturb instead — watches that mirror the phone's do not disturb state follow automatically. the phone restores its previous state when the session ends; if the watch is disconnected when the session finishes, the phone still restores once the session's expiry passes or the devices next sync.

Wear OS does not offer a settings screen to grant a third-party app do not disturb access. to silence the watch itself, grant the permission once from a computer with adb:

adb shell cmd notification allow_dnd com.wesorick.john.knowthatyouarebreathing

the watch settings screen shows which mode is in effect under silence watch and repeats these instructions.

limitations

always-on display must be enabled — ambient mode only works when the watch's Always-on display setting is on. if AOD is off, the watch will sleep as usual and the app will not stay visible. sessions still continue in the background either way; if a watch cuts them off anyway, the keep awake setting holds a wake lock for the session.
go to watch face — the app posts an OngoingActivity to stay on screen, but Wear OS can still move to the watch face depending on the manufacturer's "go to watch face" timeout or gesture handling. on some devices the ongoing-activity chip on the watch face lets you one-tap back into the app; on others the system may return to the watch face regardless.
notification permission and watch faces — the ongoing-activity icon requires the POST_NOTIFICATIONS permission to be granted on Wear OS 4+ (API 33+), and the watch face must support third-party ongoing icons. some stock watch faces do not display the chip.

theme

the watch always uses a dark, amoled-friendly theme derived from the app's seed-color system. this is intentional for OLED watch displays and battery life. the Android launch window is also dark: the wear flavor ships its own styles.xml and launch_background drawables, so the splash that appears before Flutter can draw its first frame is never bright.