Skip to content

Wear OS Companion

Jump to bottom
Kenneth LaCroix edited this page Apr 13, 2026 · 1 revision

Wear OS Companion

The MoodHaven Journal Wear OS companion is a separate Android/Wear OS app that captures voice reflections and mood taps from your wrist, forwarding them to the desktop app for transcription and journaling.

For the general overview → README

What the Watch Does

  • Records voice memos up to 10 minutes (16 kHz mono AAC-LC)
  • Tags recordings with a quick mood tap (4 levels)
  • Transfers audio to the phone over Wear OS ChannelAPI
  • Optionally captures health context (heart rate, activity) at time of recording
  • Offline queue: memos are held locally and retried when phone is in range

What the Watch Does NOT Do

  • Store journal entries
  • Connect to any cloud service
  • Send audio anywhere except the paired phone

Architecture

Wear OS Watch
    │  1. Tap to record → tap to stop
    │  2. Audio: 16 kHz mono AAC-LC (≤10 min, ≈2.4 MB max)
    │  3. Optional mood tap via MessageAPI
    │  4. Audio: 4-byte-header ChannelAPI transfer
    │  5. AudioQueue: persist-and-retry if phone out of range
    ▼
Android Phone (WearListenerService)
    │  6. Receives ChannelAPI transfer
    │  7. bridgeVoiceMemo() writes file to {app_data}/voice_memos_incoming/
    │  8. Intent broadcast to Tauri WebView
    ▼
MoodHaven Journal Desktop App
    │  9. useWearVoiceMemos hook picks up incoming file
    │  10. store_voice_memo: moves to permanent storage, creates DB record
    │  11. transcribe_voice_memo: whisper.cpp sidecar → transcription text
    │  12. User reviews, edits, creates journal entry
    │  13. link_voice_memo_to_entry: links memo to entry

Audio never leaves your devices. There is no upload step.

Audio Transfer Protocol (ChannelAPI)

  1. Watch opens a channel: channelClient.openChannel(nodeId, "/audio_transfer")
  2. Sends a 4-byte header: [0x4D, 0x42, duration_ms_as_2_bytes] (MB magic + duration)
  3. Audio bytes follow
  4. Channel closes when transfer completes
  5. AudioQueue retries if phone is out of range (exponential backoff)

Mood Signal Flow (MessageAPI)

  1. Watch: messageClient.sendMessage(nodeId, "/signal", payload_bytes)
  2. Phone WearListenerService receives MESSAGE_RECEIVED intent
  3. Desktop create_signal command stores record with source = 'wear_os', signal_type = 'mood_tap'
  4. link_signal_to_entry can later associate the signal with a journal entry

Health Context

At recording time the watch captures a health snapshot (heart rate, step count, activity level), stored as health_json on the voice memo. This context is:

  • Stored unencrypted alongside memo metadata (not in journal content)
  • Optionally surfaced in Writing view as a health badge
  • Never sent to any AI service

Desktop Integration — Tauri Commands

Command Purpose
store_voice_memo Move incoming file to permanent storage, create DB record
list_voice_memos List memos awaiting review
get_voice_memo Get a single memo by ID
delete_voice_memo Delete memo and audio file
patch_voice_memo_transcription Update transcription text after STT
link_voice_memo_to_entry Associate memo with a created journal entry
transcribe_voice_memo Run whisper.cpp sidecar on the audio file
create_signal Store a mood tap or health snapshot from the watch
list_entry_signals Get signals linked to an entry

Watch Screens

Record Screen — Main screen. Tap to record, tap to stop. Circular arc fills over 10 minutes (amber at 8 min, red at 9:30). Long-press while recording to discard.

Mood Tap Screen — Four emoji mood options. One tap sends a mood signal to the desktop.

Breathe Screen (Phase 2) — Guided breathing exercise with expand/contract animation.

History Screen (Phase 2) — Recent voice memos with transfer status and transcription preview.

Setup Requirements

  • Wear OS 3.0+ watch
  • Android 11+ phone with Bluetooth pairing to the watch
  • MoodHaven Journal desktop app v0.7.0+
  • MoodHaven Journal companion APK installed on phone and watch

Roadmap

Phase Status Summary
1 — Core Recording Complete Recording UI, AudioQueue, ChannelAPI transfer, desktop receipt
2 — UX Polish In progress Record arc, breathe screen, nav improvements
3 — Phone Integration Upcoming Journal creation from watch, sync status on watch
4 — Deep Integration Upcoming Watch-side entry preview, mood correlation, activity badges
5 — Watch Gateway Planned Watch as LAN sync relay for the full peer sync network

Full reference: docs/watch-companion.md

Clone this wiki locally