---
path: /domains/tara/sounds
surface: customer
domain: tara
auth: signed-in
source: apps/oshun/web/src/app/domains/tara/sounds/page.tsx
status: walked
last_walked:
  '2026-06-29 focused real-infra Playwright walk - ambient BFF WAV previews,
  preset loading, mixer cap, range/mute controls, favorite persistence, custom
  preset save/delete, music no-recording disclosure, bell selection/persistence,
  binaural state, reduced motion, scoped axe scans, and back-stack. Evidence:
  apps/oshun/web/e2e/tara-sounds.spec.ts and
  WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md#195-2026-06-29-tara-sound-library-coverage'
---

# 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

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