Tara - sound library

Purpose#

/domains/tara/sounds is Tara's sound-workbench route. It lets a signed-in customer browse ambient soundscapes, apply preset ambient mixes, build a five-layer custom mix, save local custom presets, select a meditation bell, and play binaural beat generators. It also exposes a catalog of music metadata, but V1 does not ship real music recordings on this route; pressing a music play button shows an explicit no-recording notice instead of animating fake playback.

Entry points#

• Direct route/bookmark - /domains/tara/sounds renders the sound library inside the authenticated customer shell.
• Domain back-stack - page.tsx passes onBack={() => router.back()} into TaraSoundLibrary; the Playwright walk opens from /domains/tara, clicks the sound-library back button, and verifies the URL returns to /domains/tara.
• Sibling Tara routes - the route sits beside analytics, collections, courses, programs, search, and teachers. A polished /tara hub link remains product-dependent; the direct depth route is functional.

Layout regions#

page.tsx is a client wrapper around <TaraSoundLibrary onBack={() => router.back()} />.

Inside TaraSoundLibrary:

• Header - back button, "Sound Library" title, "sounds playing now" status pill, master volume control, and audio status notice.
• Tab strip - ambient, music, bells, and binaural tabs. Switching tabs clears the shared search query.
• Search - tab-scoped text search. Ambient searches name/description; music searches title/artist; bells search name/description/tone; binaural searches name/description.
• Ambient - category filters (all, nature, weather, urban, abstract), five default presets, 42 ambient cards, preview controls, favorite buttons, and add/remove-to-mixer controls.
• Mixer - fixed bottom panel with up to five ambient layers, per-layer range/mute controls, layer removal, empty state, custom preset save dialog, and close control.
• Music - 15 metadata rows with mood, duration, BPM, and an honest V1 no-recording disclosure when play is pressed.
• Bells - eight bell choices with explicit select buttons, preview buttons, duration/tone metadata, and persisted selected bell.
• Binaural - wave filters (delta, theta, alpha, beta, gamma), 12 generator cards, beat/carrier frequency metadata, brain-state copy, and play/stop controls.

Audio runtime#

• Ambient previews - real BFF WAV fetches from GET /v1/tara/sessions/sound-<soundId>/ambient.wav?durationSeconds=10 with buildBffAuthHeaders(). The E2E test waits for a real 200 audio/wav response for amb-rain-window.
• Ambient mixer layers - real looped BFF WAV fetches from the same endpoint with durationSeconds=90; the test waits for real 200 audio/wav responses while loading a preset and adding amb-rain to the mixer.
• Bells - synthesized in the browser with Web Audio additive partials (strikeBell) rather than fetched recordings.
• Binaural beats - synthesized in the browser with stereo oscillators at the displayed carrier/offset frequencies.
• Music - catalog rows are metadata only in V1. The UI discloses "<track> has no real recording in V1 - nothing was played" and does not set music playback state.

States Captured#

• Initial ambient tab - data-active-tab="ambient", 42 ambient cards, five default presets, mixer closed, and storage-key metadata.
• Reduced motion - suite-wide prefers-reduced-motion: reduce; the route-scoped CSS collapses the card animation duration to <= 1 ms.
• Master volume - real range input updates data-master-volume.
• Default preset load - Focus preset opens the mixer with Coffee Shop and Rain on Window layers at their default volumes.
• Ambient filtering/search - weather category narrows to 10 sounds; "streaming" search narrows to amb-rain-window.
• Ambient preview - preview button fetches a real BFF WAV, sets data-playing-preview, shows the 10-second preview indicator, and stops.
• Mixer at cap - five layers active; a sixth add button is disabled.
• Layer volume and mute - per-layer range updates volume; mute toggles the same layer to 0.00.
• Layer removal - removing a layer drops the mixer count and re-enables another sound's add button.
• Favorite - favorite state updates the card and persists the sound id.
• Custom preset save/delete - save dialog writes a local custom preset; custom delete removes it from the UI and localStorage.
• Music disclosure - music mood/search filters work, and play shows the honest V1 no-recording notice.
• Bell search/select/preview/persistence - crystal search filters to one bell; keyboard activation selects bell-crystal; preview toggles; reload preserves selectedBellId.
• Binaural filters/playback state - alpha filter narrows to three beats; bin-alpha-calm exposes 10 Hz metadata and toggles play/stop state.
• Back-stack - route back button returns to /domains/tara.
• Accessibility scans - focused axe scans cover the ambient/custom preset state and the music/bell/binaural state.

Interaction Contract#

Header#

• Back - data-tara-sounds-back; calls router.back().
• Master volume range - data-tara-sounds-volume-range="master"; updates masterVolume.
• Master mute - data-tara-sounds-volume-toggle="master"; toggles master volume between muted and an audible value.
• Audio notice - data-tara-sounds-audio-notice; used for music no-recording and audio failure disclosures.

Tabs and search#

• Tabs - data-tara-sounds-tab="ambient|music|bells|binaural"; set activeTab and clear search.
• Search input - data-tara-sounds-search-input; filters current tab.
• Clear search - data-tara-sounds-search-clear; clears current query.

Ambient and mixer#

• Category filters - data-tara-sounds-category; update selected category.
• Preset load - data-tara-sounds-preset-load="<presetId>"; loads preset layers into the mixer.
• Preset delete - data-tara-sounds-preset-delete="<presetId>"; removes custom presets.
• Favorite - data-tara-sounds-favorite="<soundId>"; toggles local favorite.
• Preview - data-tara-sounds-preview="<soundId>"; starts/stops a real 10-second BFF WAV preview for ambient sounds.
• Add/remove mix - data-tara-sounds-mixer-action="<soundId>"; adds or removes ambient layers, capped at five.
• Layer range - data-tara-sounds-volume-range="<soundId>"; adjusts layer volume.
• Layer mute - data-tara-sounds-volume-toggle="<soundId>"; toggles layer mute.
• Layer remove - data-tara-sounds-layer-remove="<soundId>"; removes one mixer layer.
• Save preset - data-tara-sounds-save-preset-open, data-tara-sounds-save-name, and data-tara-sounds-save-preset-confirm; writes a custom preset.

Music, bells, and binaural#

• Music mood - data-tara-sounds-mood; filters rows by mood.
• Music play - data-tara-sounds-music-play="<trackId>"; discloses that no real V1 recording exists.
• Bell select - data-tara-sounds-bell-select="<bellId>"; keyboard/click select persisted bell choice.
• Bell preview - data-tara-sounds-bell-preview="<bellId>"; starts/stops synthesized bell preview.
• Wave filters - data-tara-sounds-wave; filters binaural cards by wave.
• Binaural play - data-tara-sounds-binaural-play="<beatId>"; toggles stereo oscillator playback state.

Data and Contracts#

• In-file catalogs:
  • AMBIENT_SOUNDS - 42 ambient sound descriptors.
  • DEFAULT_PRESETS - five default ambient mixes.
  • MUSIC_TRACKS - 15 metadata-only music rows.
  • BELL_SOUNDS - eight synthesized bell choices.
  • BINAURAL_BEATS - 12 synthesized binaural generators.
• BFF endpoint:
  • GET /v1/tara/sessions/:sessionId/ambient.wav in apps/oshun/bff/src/tara/ambient-audio-routes.ts.
• localStorage key:
  • tara-sound-preferences.
• localStorage shape:
  • masterVolume: number
  • selectedBellId: string
  • savedPresets: SoundPreset[]
  • recentSounds: string[]
  • favoriteIds: string[]
• Auth:
  • route access is shell-authenticated;
  • ambient WAV fetches use the browser auth-token accessor through buildBffAuthHeaders().

E2E Evidence#

• apps/oshun/web/e2e/tara-sounds.spec.ts
  • signs in through real dev auth seeding;
  • exercises the live route, not a component mount;
  • waits for real BFF audio/wav responses for ambient preview and mixer;
  • verifies DOM state, persisted localStorage state, reduced motion, keyboard activation, back-stack, and scoped accessibility.

Cross-references#

• Sibling Tara routes:
  • tara.md, domains-tara-analytics.md, domains-tara-collections.md, domains-tara-courses-id.md, domains-tara-programs.md, domains-tara-search.md, domains-tara-teachers.md, domains-tara-teachers-id.md
• Component source:
  • apps/oshun/web/src/components/domains/tara/TaraSoundLibrary.tsx
• BFF audio source:
  • apps/oshun/bff/src/tara/ambient-audio-routes.ts
• Feature spec:
  • V1/features.md#tara

Open Questions / Known Gaps#

• Music rows remain metadata-only in V1. The route is honest about this, but no hosted music recording pipeline is attached here.
• Custom mixes, favorites, and selected bell are localStorage-only. The Playwright coverage proves browser persistence, not server/profile sync or propagation into other Tara surfaces such as meditation timer pre-roll.
• The browser test proves ambient BFF WAV responses and Web Audio state toggles, but it does not run a perceptual audio-quality assertion against speaker output.
• Mobile/touch ergonomics for the bottom mixer panel still need a dedicated mobile viewport pass when this route becomes a primary mobile workflow.