Guided Session Builder Help

Build guided wellness sessions with instructions, breathing cues, audio, and future video guidance.

Local/admin tool. Open the builder on the source server with ?admin=1 or from localhost.

Core concepts

TermMeaning
Guided SessionA complete wellness plan — title, metadata, and ordered steps.
StepOne editable part of the session (opening, practice, audio, closing, etc.).
PracticeA reusable exercise from the wellness library — e.g. Anulom Vilom, Bhramari, Kapalbhati, natural breathing, OM chanting, meditation, or yoga pose guidance.
Generated SegmentThe final timed item the Experience Player plays. One breath-cycle step may expand into many cue segments during preview.
One guided session has many steps. Built-in and source plans cannot be overwritten. To customize them, use Copy to Draft.

Basic workflow

A. Create from scratch

  1. Click Create New Guided Session.
  2. Fill plan details (title, level, target duration, description, tags).
  3. Add steps (opening → main content → closing).
  4. Save Draft (stored in this browser).
  5. Player Preview to test in the Experience Player.
  6. Export JSON if you need a file copy.

B. Copy an existing plan

  1. Find a built-in or source plan (read-only list).
  2. Click Copy to Draft.
  3. Open the draft from My Draft Plans.
  4. Rename the title (must be unique).
  5. Edit plan fields and steps.
  6. Save Draft → Player Preview.

Step types

segmentTypeWhen to use
openingWelcome and prepare the user at the start.
instructionSpoken and/or on-screen guidance between practices.
practiceMain breath work, meditation, pose, or chant — often with a practiceId.
separatorPause between practices; return to natural breathing.
safetyBefore Kapalbhati, breath retention, or other sensitive practices.
closing / thank_youEnd the session with gratitude or integration.
audio_trackOM, shankh, bell, mantra, or recorded guide — audio only (see below).

Instruction vs narration

FieldNormal stepsaudio_track steps
Screen instructionWhat the user reads.Text shown during audio — on screen while audio plays.
Spoken narrationWhat the user hears (TTS).Optional spoken intro — use sparingly.

Breathing-cycle steps

Set cueMode = breath_cycle and use the Breathing Cycle Editor on practice steps.

cycleType options

Rules

Expected cue examples

PracticeTypical spoken cues
Natural breathingExhale → Inhale
Anulom VilomExhale left → Inhale left → Exhale right → Inhale right
BhramariInhale → Exhale with a hum → Rest now
KapalbhatiExhale 1 → Exhale 2 → 3 → 4 → … → Rest now
Box breathingInhale → Hold gently → Exhale → Hold gently

Use Builder Cue Preview in the editor to verify timing before Player Preview.

Audio-track steps

audio_track = audio only. The step plays the selected audio file. Screen text may be shown. Blank spoken intro does not trigger TTS. For a spoken introduction, add a separate instruction step before the audio step. Background audio under narration is future work.

Audio step fields

FieldPurpose
audioIdPreferred — reference to approved catalog entry.
audioUrlDirect URL — local/admin testing only.
audioModee.g. play_once, loop_to_duration.
durationSecHow long the step runs in the session.
volumePlayback volume (0–1).
loopRepeat audio until step ends.
displayTextShort on-screen label (e.g. ॐ).
transcriptFull text, translation, or review notes.
Use audioId from the approved audio catalog whenever possible. Direct audioUrl values are for local/admin testing only.

Audio files & catalog

Approved audio choices are defined in:

web/data/wellness/wellness_audio_library.json

Example audio step (draft JSON)

{
  "segmentType": "audio_track",
  "cueMode": "audio_track",
  "audioId": "om_cycle_20s_opening",
  "audioMode": "play_once",
  "durationSec": 20,
  "instruction": "Listen quietly to the OM chant.",
  "displayText": "ॐ"
}

Current catalog entries (examples)

audioIdTitleLength
om_chanting_8sOM Chanting Cue8s
om_cycle_20s_openingOM Cycle Opening Cue20s
om_cycle_20s_closingOM Cycle Closing Cue20s
om_cycle_20s_practiceOM Cycle Practice Loop20s
shankh_3sShankh Opening Cue3s

Video / demo clips

Can we include video clips?

Yes.

Recommended current use

Future options

A. External video link — e.g. howToVideoUrl opens in a new tab.

B. Local video file — HTML5 video from a project media folder, e.g.:

Future video catalog (proposed)

web/data/wellness/wellness_video_library.json

{
  "videoId": "anulom_vilom_demo",
  "title": "Anulom Vilom — Hand Position Demo",
  "practiceId": "anulom_vilom",
  "category": "pranayama",
  "durationSec": 45,
  "fileUrl": "assets/wellness/video/anulom_vilom_demo.mp4",
  "thumbnailUrl": "assets/wellness/images/anulom_vilom_demo.jpg",
  "description": "Shows gentle nostril alternation without force.",
  "status": "reviewed"
}

Video catalog and in-session video playback are not implemented in the builder yet.

Files involved

Builder

Wellness data

Engines

Player

Media

What is safe to edit

Safe in the builder (drafts)

Use caution

Do not casually edit

Quick checklist (before preview)

Developer / local commands

Commands are for local/admin development. Run them from the terminal at the LifeLoveMe repo root. The browser shows copyable instructions only — it does not execute shell scripts.

Full catalog with deployment notes and pre-deploy checklist: Developer Commands · Dev Command Center