user guide

how to use know that you are breathing, feature by feature. for how the code works, see docs/dev-guide/ instead.

the app has four main tabs: home (easy mode), meditations (your saved library), insights (history and stats), and settings.

welcome tour and help

the first time the app opens, a short welcome tour explains the three modes, the main session options, and lets you pick a theme, an accent color, and accessibility preferences — every page is skippable and the whole tour can be dismissed with the × button. to watch it again later, open settings > welcome tour.

this guide also ships inside the app: settings > help opens a searchable index of every topic, and the ? button on the home tab jumps straight to it. while reading a topic, the arrows at the bottom step through the document in order, the topics menu in the app bar jumps to any section in the guide, and the back button returns to the index.

easy mode

easy mode is the home tab: a quick single-segment session. you can choose between meditation, recitation, and breathing modes, and the app remembers your last session's settings.

meditation and recitation modes

duration using an h:m:s wheel picker (meditation) or target count (recitation)
an optional bell that plays at the start and end of the session (bell names include their duration)
an optional soundscape — its volume slider appears once one is picked

breathing mode

pick a breathing exercise and number of cycles (a session without a selection uses box breathing)
an optional bell that plays at the start and end of the session
optional inhale, exhale, and hold bells
an optional soundscape — its volume slider appears once one is picked

both hold phases (the hold after inhale and the hold after exhale) share the same hold bell.

tap start session to open the player. easy-mode sessions play through the same engine as saved meditations, so prompts and session features behave the same way.

while a session runs, the timer sits inside the progress ring for the circle visualizer and just below the animation for the other styles (or on its own when the visualizer is off); on the watch it stays centred. every label and icon on the player carries a soft dark shadow so it stays readable over the animation and your background image.

the meditation library and editor

the meditations tab lists your saved meditations. tap the + button to create one, or tap an existing meditation to edit it. each meditation can have:

multiple meditation, recitation, or breathing segments
a per-segment start/end bell, with an option to wait for the bell
for breathing segments, optional inhale, exhale, and hold bells and haptics
a per-segment interval trigger — a bell and/or haptic that repeats every n seconds (meditation segments), every n breaths (breathing segments), or every n recitations (recitation segments). by default a segment uses the per-mode app default from settings → meditation defaults → interval bells and haptics; turn the switch off on a segment to set its own interval
lists of prompts or single-prompt phrases (with optional text-to-speech)
soundscapes, which fade in at the start and out at the end automatically. the play button in a segment's soundscapes section previews all of its soundscapes together; while the preview plays, the volume sliders adjust the mix live
tags and a color theme
journal toggles and an optional mood-preset list

the duration of each segment is configured with the same h:m:s wheel picker used in easy mode. a meditation can also be archived (hidden from the list without deleting it) and, on Android, flagged for sync to a paired watch.

the list itself can be searched, filtered by tag, and ordered with the sort button in the app bar — by recently updated (the default), recently used (when a session last started on this device), newest or oldest first, or name. tapping the star on a row or in the editor marks a meditation as a favorite; favorites pin to the top under every sort order.

session start screen

tapping play on a saved meditation, recitation, or breathing practice opens a start screen before the session begins. it doubles as a preview of what you are about to run — and as a way to adjust this run without editing the saved practice:

soundscape sits on top and always shows. a practice with its own soundscapes defaults to as configured; none silences them for this run, or pick any soundscape from the library to play it on every segment with a volume slider — handy when you find yourself somewhere noisier than usual. a practice without soundscapes defaults to none; pick one to add it for this run.
segments each get a row showing the label and length — the duration for timed segments, the count for recitations, the cycle count for breathing. tap the pencil to change it with the usual wheel picker. a timed segment may only run open-ended when it is the last one.
play stays pinned to the bottom of the screen; when the segment list is too long to fit, it scrolls and the button rides at the end.

every change on this screen applies only to the session you are starting — the saved practice is never modified.

session options and mood presets

both global defaults and per-meditation overrides control whether the app asks for a mood or journal entry before or after a session.

settings > meditation defaults > journal: the global defaults (used by easy mode).
meditation editor > journal: the per-meditation override, including an optional mood-preset list. new meditations default all prompts to off and fall back to the global presets when an emoji picker is shown.

when a mood prompt is enabled, the picker shows the active preset emojis plus a + option to choose any emoji for that single session. the journal prompts are plain text fields.

session completion and parting words

every session ends with a quiet completion screen instead of dropping straight back to the start — whether the session ran to its end, was stopped early, was discarded, or wasn't saved to history at all: a drop lands in a pond, rings spread outward, and a headline above reads "you have known you are breathing for n minutes" (sessions under a minute drop the duration clause). a randomly picked parting word — a short closing phrase — appears below the pond, and a restart button sits at the bottom. with reduced motion on, the pond is a still image. on the watch the headline sits over the pond and the screen is compact and omits the parting word. the pond uses your theme colors, with softly shaded water, a highlighted falling drop, a small splash, and layered ripples that gradually settle — the same gentle, illustrated style as the tree and wave visualizers. between drops, the water clears without a lingering center dot or fixed rings.

parting words come from a text list, so they are fully configurable:

a built-in default parting words list ships in the list library (settings > library > lists) and can be edited like any list.
settings > meditation defaults > player experience > parting words picks the list used app-wide.
meditation editor > player experience > parting words overrides it per meditation, or uses the app default.

any post-session mood or journal check-in appears after you leave the completion screen, and only when the session was actually saved — a discarded or unsaved run still gets the moment, just no check-in.

bell shortcuts in spoken prompts

bell shortcuts let you embed bell sounds inside spoken (text-to-speech) prompts. when the app speaks a prompt aloud, any emoji that is assigned as a bell shortcut is replaced by that bell's sound instead of being spoken as text.

assigning a shortcut

go to settings > library > bells to open the bell library.
each bell tile has an emoji button on the left (showing the assigned emoji, or 🔇 if none is set).
tap the emoji button to open the shortcut picker.
choose any emoji to assign it as that bell's shortcut, or select no shortcut to clear it.

each emoji can only be assigned to one bell at a time. if you assign an emoji that is already in use, it is automatically removed from the other bell.

three built-in bells come with default shortcuts:

🔔 — medium bell
🥣 — large bowl
🛎️ — little bell

using shortcuts in prompts

when writing a meditation prompt, simply type the assigned emoji anywhere in the text. for example:

breathe deeply 🔔 and let go of tension

when spoken aloud, the app will say "breathe deeply" and "and let go of tension" via the TTS engine, and play the medium bell in between. any emoji that is not assigned to a bell is silently stripped from the spoken text.

bell shortcuts work in both meditation mode and recitation mode, whenever text-to-speech is enabled for prompts.

when a segment bell and a spoken prompt are due at the same moment — for example a segment's start bell and its prompt — the prompt speaks first and the bell rings a beat after the utterance ends. with wait for start bell on, the segment still waits out the bell before its content begins, so the order is prompt → bell → content. to sound a bell before or inside a prompt instead, embed it with a shortcut.

binaural beats

binaural beats are generated live by the app rather than played from audio files. each beat plays a pure tone at the base frequency in one ear and a tone shifted by the beat frequency in the other ear; the difference between the two is perceived as a gentle pulsing.

headphones or earbuds are required. the effect only works when each ear hears a different frequency. through speakers the two tones blend together in the air, and no binaural beat is produced.
three built-in presets are included (alpha, theta, and delta). custom beats can be created in settings > library > binaural beats with a name, a base frequency, and a beat frequency.
binaural beats appear alongside the ambient soundscapes in the soundscape pickers. only one binaural beat can play in each segment — once a segment's soundscapes include a binaural beat, the remaining binaural options are greyed out in that segment's other pickers.
a binaural beat plays for the whole segment; there is no separate duration setting.

noise soundscapes

the app can generate four colors of noise live, each with its own character:

white noise — a flat, bright hiss.
pink noise — softer and more balanced, like steady rain.
brown noise — a deep, low rumble.
green noise — a mid-range wash centred around 500 Hz: softer than white noise without the low rumble of brown noise.

noise soundscapes are synthesized on the device rather than played from audio files, so they loop seamlessly, never need a download, and cost nothing to transfer to a paired watch.

they appear in every soundscape picker — the meditation editor, the player start screen, easy mode, and Wear OS — and like any other soundscape they can be mixed together with ambient recordings and binaural beats.

generated soundscapes

generated soundscapes are soundscapes you shape yourself. the app plays them live from a few settings instead of an audio file, so they never repeat exactly and take no storage. each one has up to three layers:

drone — a sustained tone under everything else. pitch sets its note, tone moves it from dark to bright, and space adds reverb, from close and dry to large and distant.
pulse — a soft, low beat. tempo sets its speed in beats per minute. to make it slow down (or speed up) during a session, pick an ending tempo and say how long the change takes: the pulse glides from one tempo to the other over that time and then stays there. for example, start at 66 bpm and end at 40 bpm to wind down gradually instead of starting out slower than you feel. there are two ways to set the length:
change tempo over a share of the session — a percentage of the time the soundscape plays, so the same soundscape fits a 10 minute and a 40 minute meditation. at 50%, the pulse reaches its ending tempo halfway through and holds it for the rest.
change tempo over a set time — a number of minutes. this is used when the share is off, and also when the length is not known ahead of time: open-ended meditations and recitations. with a share set and this at zero, the pulse stays steady in those sessions.
chimes — occasional notes above the drone. how often sets how many sound per minute, and scale chooses which notes they use. they arrive at random moments unless you turn on evenly spaced, which sounds them at a steady interval (the notes themselves still vary).

each layer has a level; set it to zero to turn that layer off.

four are built in: still drone, slow chimes, wind down (a pulse that slows from 66 to 40 bpm over the first half of the session, or over 10 minutes when the length is unknown), and steady pulse (a drone and an unchanging 60 bpm pulse with no chimes, for when you want a background with no surprises in it).
create or edit them in settings > library > generated soundscapes. the play button in the editor previews the sound, and every slider changes it while it plays, so you can tune it by ear. changing a tempo setting starts the tempo change again from its starting tempo. in a preview the tempo change takes at most 30 seconds, however long it is set to take, so you can hear where it ends up without waiting. each generated soundscape needs its own name. the check button saves; leaving any other way after changing something asks before the changes are discarded.
they appear alongside the other soundscapes in the soundscape pickers and can be mixed with ambient recordings, noise, and binaural beats. only one generated soundscape can play in each segment — once a segment has one, the others are greyed out in that segment's other pickers.
the tempo change follows the soundscape's playing time: pausing a session pauses it, and it carries on across segments as long as they use the same soundscapes. a segment with different soundscapes starts it again. a share of the session is measured over that same stretch: the segments in a row that use the same soundscapes, with any length you changed when starting the meditation. time spent speaking prompts is not counted.
deleting a generated soundscape removes it from every meditation that uses it.
on Wear OS, generated soundscapes are silent in the meditation player.

insights: history, stats, and graphs

the insights tab holds your history, journal, and stats.

history shows every session, complete or aborted. each row shows the meditation name, completion status, duration, mood emojis, and the first couple of tags. a search field matches journal text, meditation names, tags, and mood emojis, and rows show the matching journal excerpt; filter chips can keep only sessions with a journal entry or with a particular mood. tapping a row opens the full session detail, which includes pre-session and post-session mood emojis, both journals, and tags — and an edit action for correcting those check-in answers afterwards.

the journal tab lists every journal entry, newest first, with its own search field, so a single remembered word resurfaces the session it was written for.

stats include:

total sessions and minutes
split counts for completed and aborted sessions
current and longest daily streaks (streaks use all sessions by default; a toggle in settings > insights lets you count only completed sessions)
time-series graphs by day, week, and month
per-tag breakdowns
a by mood chart with the recorded pre- and post-session emoji counts plus the most common mood shifts
a recitations tab with total, completed, and streak metrics for counting sessions

settings > insights also holds daily and weekly goals: a target number of minutes, sessions, or recitations for the day or the week. any mix of the six can be set — "20 minutes a day", "3 sessions a week", "108 recitations a day". the stats tab shows a progress bar for each configured goal, and the session-complete screen notes when a session pushes a goal to reached. aborted sessions count toward goals unless the completed-only streaks toggle is on, and goals sync to other devices and the watch with backup & sync.

screen behavior and background playback

settings > meditation defaults > player experience > screen behavior: what happens to the screen while a session runs in the foreground: keep on, allow timeout, or turn off (where supported). the default is allow timeout to preserve battery.
meditation editor > player experience > screen behavior: each meditation can override the global setting, or use the app default. this is useful for guided meditations where you want to read prompts, or for sessions where you want the display to stay dark or switch off.
settings > meditation defaults > player experience > system volume (Android): set the device media volume while a session plays. off by default. the previous volume is restored when the session ends.
meditation editor > player experience > system volume (Android): each meditation can use the app default, stay off, or set a custom level. easy mode has no control and follows the app default.
sessions can continue to play audio after you turn the screen off or switch to another app. on Android, a media-player notification is shown while a session is running — on the lock screen and in the media controls area — with the current segment, a progress bar, and controls to pause, resume, skip to the previous or next segment, or stop. recitation sessions show the current count instead of a progress bar and offer only the stop control. the notification is removed when the session ends, whether it finished on its own or you stopped it.

haptics

each segment can trigger a haptic feedback event. in the editor, pick a pattern from any haptic dropdown. selecting a continuous pattern previews it for 5 seconds so you can feel how it repeats; one-shot patterns play once.

one-shot patterns fire once at the start of a segment, the end of a segment, or the start of a breathing phase. they are: short pulse, double pulse, long pulse, and triple pulse.
continuous patterns repeat for as long as the owning stage or phase is active. continuous options are listed below the one-shot options, separated by a non-selectable -- continuous -- header. they include dot, dash, slow dot, slow dash, glacial dot, glacial dash, ramp up, ramp down, continuous double pulse, continuous triple pulse, and raindrops. continuous haptics stop automatically when the segment, phase, or session ends.

ramp patterns change intensity over one second; glacial patterns wait ten seconds between pulses; raindrops uses a 200 ms pulse with small random intensity and random spacing.

recitation mode

recitation meditations count up to a target number of repetitions instead of timing down. you can create them in the editor by switching the mode toggle from meditation to recitation, then setting each segment's target count.

the player shows the current segment count, the total count, and the targets. tap the + and − buttons, or use enabled hardware input:

settings > meditation defaults > player experience > recitation input toggles which inputs are active.
physical keyboard: up/right arrow or space to increment, down/left arrow to decrement.
Android volume buttons: volume up increments, volume down decrements (must be enabled in settings; the app intercepts the key while a recitation session is active).
Android media buttons: play/pause/next increments, previous decrements.
Android camera button: increments.

counts are debounced to avoid accidental double counting. completed recitation sessions are recorded in history and stats.

lists and audio lists

lists are collections of prompts. a text list shows or speaks each item; an audio list plays your own recorded audio for each item. manage them from settings > library > lists and settings > library > audio lists.

lists can be exported and imported from the library screens, and a single list can be exported from the list editor:

tap the export icon on a library screen to share all lists of that kind as a single .zip file.
tap the import icon on a library screen to choose one or more .tls, .als, or .zip files. the system file picker does not visually filter by these custom extensions, but unsupported files are ignored after you select them.
tap the export option in a list editor's app bar menu to share that list.

text lists are exported as .tls files. each item starts with * and continuation lines that do not start with * are merged into the previous item. audio lists are exported as .als zip archives that contain the list data and the recorded audio files. importing an audio list copies the audio files into the app.

a single meditation can be exported as a .med package from the meditation editor's overflow menu. on Android and iOS, the file is sent to the system share sheet so you can save it, send it to another app, or upload it to a cloud provider. on Linux, a save dialog is shown instead.

breathing segments keep their exercise selection across .med exports and syncs: the reference travels as a stable sync id, and a segment whose exercise cannot be resolved on the importing device falls back to box breathing.

reminders, backup, sync, and Wear OS

these features have their own pages:

reminders — scheduled mindfulness notifications
backup & sync — full backups, local/WebDAV sync, and watch sync
Wear OS — using the watch app
faq & known issues — common problems, workarounds, and how to collect logs for a bug report