Skip to content

Chat & Audio Experiences

This section covers DreamStream’s conversation and audio-first experiences, optimized for deep reflection and intention setting.

🎭 Interaction Modes

A supportive, Jungian-trained AI companion available 24/7. - Context: Uses up to the 10 most recent real dreams for context (samples/tutorial dreams are excluded). - Features: Threaded chat with image attachment support.

Speech-to-text inside chat for hands-free journaling. - UX: Tap mic → speak → stop → transcript appears in the input. - Tech: Records locally then transcribes via DreamStream’s AI transcription service.

Pre-sleep Whispers and Morning Uplift intention setting. - Goal: Improved dream recall and gentle morning grounding.

📊 Experience At a Glance

Experience Mode Best for Connectivity?
Dream Guide Chat Text Deep analysis, Jungian reflections Yes
Dictation (Chat) Speech-to-text Fast capture without typing Yes
Dream Whispers 60s Audio Pre-sleep relaxation Yes
Morning Uplift 60s Audio Waking motivation Yes
Read Aloud TTS Hands-free listening Optional

1) Dream Guide Chat

DreamStream’s chat experience is presented as Dream Guide: a supportive, reflective conversation space that can draw on your dream journal.

What users see

  • A chat screen with a message list (your messages + the Dream Guide’s replies).
  • Optional suggestion chips at the start (example prompts like “What patterns do you see in my dreams?”).
  • A New Chat button.
  • A Chat History button.
  • An Attach image button (one image at a time).
  • A mic button for dictation (tap to record, tap again to stop and transcribe).

Where Dream Guide can be opened from

Dream Guide can be entered in multiple ways:

  • Chat tab: the main entry point.
  • From a specific dream: the app can open Dream Guide “focused” on a particular dream.
  • Example: from Dream Detail’s menu (“Chat”).
  • Example: from certain insight prompts (like a reflective question), which can open chat with a pre-filled starting question.

Automatic first message (when opened from a dream)

When Dream Guide is opened with a dream context, DreamStream can automatically send an initial message such as:

  • “I’d like to discuss my dream \"…\". Here’s what happened: …”
  • Or, if a specific question is being carried into chat: “I’d like to explore this question about my dream \"…\": …”

This creates a smoother handoff from “reading insights” to “talking about them.”

How Dream Guide keeps context

Dream Guide tries to be helpful without asking you to re-explain everything:

  • If chat was opened from a dream, that dream becomes the current focus.
  • If you type something like “analyze my most recent dream,” DreamStream attempts to detect which dream you mean.
  • In text chat, the assistant includes up to 10 most recent real dreams for context on every response.
  • On the AI side, Dream Guide is designed to remember the conversation context across turns.

Important note shown to users

In the chat history modal, DreamStream explicitly states:

  • "Conversation context is stored to improve your experience."

This refers to Gemini's Interactions API, which maintains AI conversation context across turns. Retention duration depends on Google's tier (up to 55 days on paid tier, 1 day on free tier). Note: Chat transcripts are also stored in Supabase (therapist_chats, chat_sessions) with no automatic expiry.

Chat sessions and history

Dream Guide supports multiple saved conversations:

  • New Chat creates a fresh conversation.
  • Chat History shows up to 50 conversations, sorted by most recently updated.
  • Each conversation has a title. If the conversation starts with text, the title is derived from the first message (shortened). If it starts with an image, it may be titled “Image Chat.”
  • A conversation can be deleted from the history list (with confirmation).

Image sharing inside chat

Dream Guide supports a simple “image + text” mode.

  • You can attach one image at a time.
  • Only image files are accepted.
  • Max size is 5 MB.
  • The image appears in the chat bubble as a small preview.
  • You can remove the pending image before sending.

If you send only an image (no text), DreamStream still sends a message and asks the Dream Guide to respond to the image.

Streaming behavior (how replies appear)

Dream Guide replies appear in a “typing” style:

  • The app streams text in gradually (typewriter effect).
  • After streaming finishes, the message resolves to the full final text.

This is meant to feel responsive, like a real conversation.

Core flow (text chat)

flowchart TD
  A[User opens Dream Guide] --> B[Chat UI loads]
  B --> C["User sends message (optional image)"]
  C --> D[Message saved to database]
  D --> E[Dream Guide response streamed]
  E --> F[UI shows response as it arrives]
  F --> G[Response saved to database]
  G --> H[Conversation context updated for next message]

Edge cases & safeguards (text chat)

  • Sign-in required: sending a message requires an active authenticated session.
  • Image validation: non-image files are rejected; images >5MB are rejected.
  • Busy state: sending is disabled while a response is being generated.
  • Failure messaging: if the AI request fails, the user sees a friendly fallback message.

2) Dictation (speech-to-text inside Dream Guide)

Dictation is a lightweight “talk then edit” workflow inside chat.

What users see

  • Tap the mic to start recording.
  • Tap stop to end recording and begin transcription.
  • The input shows a “Transcribing…” state while the transcript is generated.
  • On success, the transcript is inserted into the chat input so the user can review and send.

Permissions

  • Dictation requires microphone access.
  • If microphone access fails/denied, DreamStream surfaces a friendly error and returns to normal typing.

Notes

  • Dictation records locally then sends the audio blob to the transcription service.
  • It does not stream audio or run a call-like “live voice” session.

3) Dream Whispers (pre-sleep audio)

Dream Whispers is a bedtime experience designed to feel like a short, calming personalized narration based on recent dream signs.

Where it appears

Dream Whispers appears as a card on the Home dashboard only when:

  • The user has at least 3 real dreams logged (sample dreams do not count).
  • The time is evening/night:
  • 5 PM through 4:59 AM (the app checks hour >= 17 or hour < 5).

What happens when a user taps it

  1. DreamStream generates a short spoken script based on up to the 7 most recent real dreams.
  2. DreamStream plays that script as audio using the Dream Guide’s voice.
  3. The user can stop the whisper at any time.

Script characteristics (what the AI is asked to generate)

The script is designed to:

  • Be about ~60 seconds.
  • Be under roughly 150 words.
  • Use second-person language (“you…”).
  • Include gentle pauses marked with ....

Dream Whispers flow

flowchart TD
  A[User taps Dream Whispers] --> B[Generate short bedtime script]
  B --> C[Connect to audio narrator]
  C --> D[Audio starts playing]
  D --> E[User stops or closes]

Edge cases & safeguards (Dream Whispers)

  • If audio playback is blocked or the session fails to start, DreamStream shows an error and returns to idle.

Silent Mode reminder

The UI includes a "Silent Mode" reminder. If the device is muted, users may not hear the audio.

4) Morning Uplift (morning intention audio)

Morning Uplift is the daytime counterpart to Dream Whispers: a short, energizing message that turns dream signs into a practical intention for the day.

Where it appears

Morning Uplift appears as a card on the Home dashboard only when:

  • The user has at least 3 real dreams logged.
  • The time is daytime:
  • 5 AM through 4:59 PM (shown whenever Dream Whispers is not shown).

What happens when a user taps it

  1. DreamStream generates a short script based on up to the 7 most recent real dreams.
  2. The script includes:
  3. 1–2 gentle reflections from dream signs (no jargon)
  4. One clear intention
  5. 2–3 small, doable actions
  6. DreamStream plays the script as audio.

Morning Uplift flow

flowchart TD
  A[User taps Morning Uplift] --> B[Generate short morning script]
  B --> C[Connect to audio narrator]
  C --> D[Audio starts playing]
  D --> E[User stops or closes]

Edge cases & safeguards (Morning Uplift)

  • If audio doesn’t start promptly, DreamStream uses a timeout and shows an error.
  • The UI includes a “Silent Mode” reminder.

5) Read Aloud (Text-to-Speech)

In some places, DreamStream offers a Read Aloud button so users can listen instead of reading.

What it’s used for

  • Hands-free listening (e.g., while walking, resting, or winding down).
  • Accessibility support.

How it behaves

  • Tapping Read Aloud starts speaking.
  • Tapping again (or leaving the screen) stops speaking.

DreamStream supports both web and native behavior:

  • Web: uses the browser’s built-in speech system.
  • Native app: uses a native Text-to-Speech plugin.

Troubleshooting signals (what Support/Product should know)

  • Dictation won’t start recording
  • Common causes: microphone permission denied, missing mic device, browser restrictions.
  • Dictation transcribe fails
  • Common causes: offline mode, auth/session expired, transcription service error.
  • Dream Whispers / Morning Uplift audio won’t start
  • Common causes: offline mode, auth/session expired, audio service instability.
  • Also check device volume.
  • iOS note: in WKWebView/WebKit, audio can be suppressed by the hardware Silent switch unless the app sets the browser audio session to playback (see services/liveGeminiService.ts).
  • Dream Whispers/Morning Uplift card not shown
  • Most common causes: fewer than 3 real dreams, time-of-day gating.
  • Image won’t attach
  • File is not an image, or exceeds 5MB.

Implementation map (for verification)

  • Dream Guide (text + history + image attach): components/TherapistChat.tsx
  • Dream Guide AI (Interactions API + streaming): services/geminiService.ts (chatWithTherapistInteraction)
  • Audio rituals engine (Dream Whispers / Morning Uplift): services/liveGeminiService.ts (modes: whisper, morning)
  • Audio rituals proxy (server): supabase/functions/gemini-live-proxy/
  • Dream Whispers UI: components/DreamWhispers.tsx
  • Morning Uplift UI: components/MorningUplift.tsx
  • Home time-of-day gating: components/HomeDashboard.tsx
  • Modals wiring: App.tsx
  • Read Aloud (TTS service): src/services/nativeService.ts
  • Read Aloud usage example: components/DreamDetail.tsx