feat(tts): searchable voice picker, voice selection end-to-end

Replace the Voice gender (Female/Male) and gender-filtered Voice selects in
Settings → Voice with a single searchable VoicePicker (Popover + Command/cmdk)
that lists all voices — 22 curated Azure Neural voices plus (in dev) 184 macOS
system voices — with type-to-search filtering by name and id.

- Remove ttsVoiceGender from AppPreferences and preferences IPC (default, load,
  validation, set); drop gender props from App/SettingsScreen/TtsPanel.
- add ui/popover and ui/command primitives; deps cmdk, @radix-ui/react-popover.
- Voice model (TtsVoiceSource, TtsVoice.gender) and voices.ts: AZURE_VOICES,
  parseSayVoices, listVoices (dev-only macOS enumeration), normalizeSelectedVoiceId,
  voiceIsAzure. Thread selected voice through createTtsProvider -> azure/say.
- tts:list-voices + tts:test (independent TtsManager + audio output start/stop,
  fixes silent test and 'TTS is already running').
- tests/voices.test.ts (12 tests); docs updated. type-check, 80/80 tests, build,
  eslint, prettier all clean.

Author: muhammadhasnainsaeed

docs/ARCHITECTURE.md

@@ -355,12 +355,14 @@ from the environment:
 
 - `azure` (default) — Azure Speech TTS, same credentials as STT
   (`AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`). Uses `SpeechSynthesizer` from
-  `microsoft-cognitiveservices-speech-sdk` (already a dependency). Configurable
-  voice via `AZURE_TTS_VOICE` (default `en-US-JennyNeural`). Uses `null`
+  `microsoft-cognitiveservices-speech-sdk` (already a dependency). Voice from
+  the Settings selection (added 2026-09-03) beats `AZURE_TTS_VOICE`
+  (default `en-US-JennyNeural`). Uses `null`
   AudioConfig to get raw PCM from `result.audioData` (no system speaker
   output); audio is routed through `AudioOutputManager`.
 - `say` — macOS built-in `say` command. Zero dependencies, fully offline.
-  Uses `Samantha` voice at 200 wpm. `stop()` kills via `killall say`.
+  Voice from the Settings selection adds `-v <voice>` (default `Samantha`,
+  200 wpm). `stop()` kills via `killall say`.
   Platform-isolated for future Windows/Linux porting.
 - `mock` — 200 ms simulated delay. No audio output. For automated testing.
 - anything else / missing Azure keys — `tts:start` returns `{ok:false, message}`
@@ -545,6 +547,32 @@ Zoom / Google Meet / Microsoft Teams
   them into the central flow without rewriting business logic. Persistent
   recoverable state (missing device/config/permission) keeps its inline
   setup/panel UI, while transient failures surface as toasts.
+- **TTS voice selection (added 2026-09-03)**: the Settings → Voice section
+  selects a voice via a searchable combobox that persists through `preferences`
+  (`ttsVoiceId`) and is threaded into the existing TTS provider. Voice
+  enumeration (`src/main/services/tts/voices.ts`) is dev-vs-prod gated on
+  `!app.isPackaged`: packaged (production) builds expose a curated catalog of
+  real Azure Neural voices only; dev (unpackaged) builds additionally enumerate
+  macOS `say` system voices. The `SessionManager` receives the resolved voice
+  through an injected resolver (`setTtsVoiceIdResolver`), so the session service
+  stays free of `electron`/filesystem dependencies and remains unit-testable.
+  **Known limitation**: macOS `say` exposes no gender metadata, so system voice
+  gender is `unknown`. **Picker (2026-09-03)**: the picker (`VoicePicker.tsx`,
+  Popover + Command/cmdk) lists **all** voices in two groups — "Azure voices"
+  and "macOS system voices" (dev) — with type-to-search filtering by name and
+  id; the earlier Female/Male gender Select and gender-filtered Voice Select
+  were removed, and `ttsVoiceGender` was dropped from `AppPreferences`. This
+  "one source of truth" rule keeps the production Azure TTS path and the "no
+  parallel implementation" constraint intact — the Test Voice action reuses the
+  same `TtsManager.onTranslationText()` pipeline. **Voice routing (2026-09-03
+  fix)**: `createTtsProvider()` routes any non-Azure voice id (i.e. a macOS
+  system voice, dev-only) to the `say` provider, so a system voice is never sent
+  to the Azure SDK.
+  **Test Voice isolation (2026-09-03 fix)**: the `tts:test` handler runs on its
+  own `TtsManager` instance (not the shared session manager), starts the audio
+  output it needs, and self-terminates after the test phrase — so a test never
+  leaves TTS/audio active and never blocks a subsequent "/ Start Meeting" with
+  "already running".
 - **Microphone capture in the renderer, permission in the main process**
   (see "Microphone pipeline" above): zero native dependencies, exact
   deviceId matching, and macOS TCC handled via `systemPreferences`.

docs/CHANGELOG.md

@@ -3,6 +3,131 @@
 Every agent working on this repository MUST append a dated entry describing
 their changes after finishing work.
 
+## 2026-09-03 — Searchable Voice picker replaces the gender + voice selects
+
+- **Removed the Voice gender (Female/Male) Select and the gender-filtered Voice
+  Select** from the Settings → Voice section. `ttsVoiceGender` was dropped from
+  `AppPreferences` (`packages/shared/index.ts`) and from
+  `src/main/ipc/preferences.ts` (default, `loadPreferences`, and
+  `preferences:set` all updated); the `selectedGender`/`onSelectVoiceGender`
+  props were removed from `App.tsx`, `SettingsScreen.tsx`, and `TtsPanel.tsx`.
+- **Added a searchable voice picker** (`src/renderer/components/VoicePicker.tsx`,
+  built on new shadcn `ui/popover.tsx` + `ui/command.tsx` primitives pulled from
+  `@radix-ui/react-popover` and `cmdk`). It lists **all** voices in two groups —
+  **Azure voices** (22) and **macOS system voices** (184, dev) — with
+  type-to-search filtering by name **and** id. `TtsPanel.tsx` now renders just
+  the Voice label + `VoicePicker` + Test Voice.
+- **Verified via CDP**: Settings → Voice shows one Voice combobox (no "Voice
+  gender"); opening it shows Azure voices + macOS system voices; searching
+  "prabhat" returns only `Prabhat (IN)` and "alice" matches the Alice system
+  voice; selecting updates the trigger and persists `ttsVoiceId` (e.g.
+  `en-IN-NeerjaNeural`). Test Voice and Start Meeting still behave correctly.
+- **Validation**: type-check clean; tests 80/80; build OK; ESLint 0 errors
+  (removed the `cmdk-input-wrapper` attribute to satisfy `react/no-unknown-
+  property`); Prettier clean.
+- Added deps: `cmdk@^1.1.1`, `@radix-ui/react-popover@^1.1.23`.
+
+## 2026-09-03 — Make the Voice gender filter actually visible (Female/Male splits the list)
+
+- `TtsPanel` no longer mixes macOS system voices (gender `unknown`) into the
+  gender-filtered Azure list. **Female → only female Azure voices; Male → only
+  male Azure voices.** The only macOS voice shown is a currently persisted
+  system selection, kept so it is not lost.
+- Verified via CDP: with gender Male the Voice dropdown lists exactly Guy,
+  Christopher, Eric, Roger, Steffan, Tony, Ryan, Thomas, William, Prabhat (IN),
+  Liam (plus any retained macOS selection). Female uses the identical code
+  branch.
+- Validation: type-check, tests 80/80, build OK, ESLint 0 errors, Prettier
+  clean.
+
+## 2026-09-03 — Fix: silent Test Voice + "TTS is already running" on Start Meeting
+
+Follow-up bug fix to the voice-selection feature.
+
+- **No audio on Test Voice**: `AudioOutputManager.writeAudio()` silently drops
+  audio when the audio output manager is inactive, and `tts:test` never started
+  it. The handler now starts `audioOutput` (if not active) before speaking the
+  test phrase, so the selected voice is actually audible. Also, non-Azure/system
+  voice ids route to the `say` provider (never Azure).
+- **"TTS is already running" on Start Meeting**: `tts:test` used the shared
+  singleton `ttsManager` and left it active, so a later session start returned
+  "TTS is already running." `tts:test` now uses an **independent `TtsManager`**
+  that starts, speaks the test phrase, then self-terminates (`tts:spoken` →
+  `setImmediate` stop) and stops the audio output it started, emitting
+  `tts:stopped` so the renderer returns to Off. The shared session manager is
+  untouched by a test, so Start Meeting works without the error.
+- **Gender filter retained**: Filters the Azure voice list by documented Azure
+  gender; dev macOS system voices are appended regardless. Verified via CDP:
+  Settings → Voice → gender Male → select voice → Test Voice shows the text with
+  provider "Say", badge Active, then auto-returns to Off; Start Meeting
+  completes with no "TTS is already running" error.
+- **Validation**: type-check, tests 80/80, build OK, ESLint 0 errors, Prettier
+  clean.
+
+## 2026-09-03 — Fix: "Speech playback failed" when selecting/testing a voice
+
+Follow-up bug fix to the voice-selection feature.
+
+- **Root cause**: `createAzureTtsProvider` passed the selected voice id to the
+  Azure SDK unconditionally. A macOS `say` voice id (dev-only, selectable only
+  when a system voice is picked) is not an Azure voice — Azure rejected it →
+  `tts:error` → "Speech playback failed". Selecting an Azure voice without
+  `AZURE_SPEECH_KEY`/`AZURE_SPEECH_REGION` also threw immediately.
+- **Fix 1 — voice-aware provider routing**: `provider.ts`
+  `createTtsProvider(voiceId?)` routes any non-Azure voice id to the `say`
+  provider via new `voiceIsAzure()` (`voices.ts`), so a macOS system voice is
+  always synthesized locally and never reaches the Azure SDK. Dev-only;
+  production still exposes Azure voices only, so the production Azure path is
+  unchanged.
+- **Fix 2 — system voices selectable in dev**: `TtsPanel` lists macOS system
+  voices (marked "(macOS)", gender `unknown`) in the Voice dropdown in dev, so
+  users can test tones fully offline with `say` and no Azure keys. Azure voices
+  still need the Azure credential to synthesize.
+- **Tests**: 2 new `voiceIsAzure` tests; suite 80 passing (was 78).
+- **Validation**: type-check, tests 80/80, build OK, ESLint 0 errors, Prettier
+  clean. CDP-verified: selecting a macOS voice + Test Voice completes with no
+  error toast and no console errors.
+
+## 2026-09-03 — TTS voice selection: gender + voice dropdowns, Test Voice, dev system voices
+
+Voice selection feature for Settings → Voice (no commit/push).
+
+- **Shared types** (`packages/shared/index.ts`): `VoiceGender`
+  (`female | male | unknown`), `TtsVoiceSource` (`azure | system`), `TtsVoice`,
+  `ListVoicesResult`; `AppPreferences` gains `ttsVoiceGender` (default
+  `female`) and `ttsVoiceId` (default `null`); `ElectronAPI` gains
+  `getTtsVoices()` and `testTtsVoice()`.
+- **Voice catalog/enumeration** (`src/main/services/tts/voices.ts`):
+  curated `AZURE_VOICES` (22 real Azure Neural English voices with documented
+  gender, default `en-US-JennyNeural`); `parseSayVoices()` for `say -v '\?'`
+  (system voice gender is `unknown` — macOS exposes no gender metadata, so
+  system voices are excluded from the Female/Male filter, documented
+  limitation); `listVoices(development)` + `normalizeSelectedVoiceId()`
+  (production restricted to curated Azure ids; dev passes through). macOS
+  system voices exposed only when `!app.isPackaged` — Azure-only in packaged
+  builds.
+- **Provider voice threading**: `createTtsProvider(voiceId?)` → Azure
+  (`voiceId` beats `AZURE_TTS_VOICE`, fallback `en-US-JennyNeural`) and `say`
+  (`-v <voice>`, default `Samantha`); `TtsManager.start(..., voiceId?)`.
+- **IPC** (`src/main/ipc/tts.ts`): `tts:start` resolves the persisted voice;
+  new `tts:list-voices` and `tts:test` (stops active TTS, restarts with the
+  selected voice, then feeds a fixed test sentence through the existing
+  `ttsManager.onTranslationText(...)` pipeline — no parallel TTS path).
+  `resolveTtsVoiceId()` feeds the SessionManager via an injected resolver
+  (`setTtsVoiceIdResolver`), keeping the session service electron-free and
+  unit-testable.
+- **Preferences** (`src/main/ipc/preferences.ts`): exports `loadPreferences`,
+  persists `ttsVoiceGender`/`ttsVoiceId` so a selection survives restart.
+- **UI** (`TtsPanel.tsx`, `App.tsx`, `SettingsScreen.tsx`, new
+  `useTtsVoices.ts`): Voice gender Select (Female/Male) + Voice Select filtered
+  by gender + dev-only "system voices available in dev" label + **Test Voice**
+  button.
+- **Tests** (`tests/voices.test.ts`): 10 new tests; suite 78 passing (was 68).
+- **Validation**: type-check clean, tests 78/78, build OK, ESLint 0 errors,
+  Prettier clean; CDP-smoke at 480px (gender + voice dropdowns populate, male
+  filter shows male Azure voices, `getTtsVoices` returns 206 voices in dev,
+  no horizontal overflow, correct theme).
+
 ## [1.0.0] - 2026-08-28
 
 First public open-source release of the Urdu → English Voice Interpreter for

docs/CURRENT_STATE.md

@@ -2,6 +2,116 @@
 
 _Last updated: 2026-09-03_
 
+## TTS voice selection: searchable VoicePicker, Test Voice, dev system voices
+
+Completed (2026-09-03). Voice preference feature for the Settings → Voice section.
+
+### What is done
+- **Voice model (shared)** — `packages/shared/index.ts` adds `VoiceGender`
+  (`female | male | unknown`), `TtsVoiceSource` (`azure | system`),
+  `TtsVoice { id; name; gender; source }`, and `ListVoicesResult { ok; voices;
+  development; message? }`. `AppPreferences` retains only
+  `ttsVoiceId: string | null` (default `null`) — the gender preference was
+  removed. `ElectronAPI` (preload bridge) gains `getTtsVoices()` and
+  `testTtsVoice()`.
+- **Voice catalog + enumeration** — `src/main/services/tts/voices.ts`
+  - `AZURE_VOICES`: curated catalog of 22 real, documented Azure Neural English
+    voices (en-US/en-GB/en-AU/en-IN/en-CA) with their documented gender. Safe
+    default `en-US-JennyNeural` (female).
+  - `parseSayVoices()`: parses `say -v '\?'` output. macOS `say` exposes no
+    gender metadata, so **system voice gender is `unknown`** (documented
+    limitation, not guessed). Handles multi-word + parenthesized names ("Bad
+    News", "Eddy (English)") by locating the `xx_YY` locale token before `#`.
+  - `listVoices(development)`: Azure always + macOS system voices in dev only.
+  - `normalizeSelectedVoiceId(storedId, development)`: production restricts to
+    the curated Azure ids (stale dev system ids never reach production); empty
+    → default.
+- **Dev-vs-prod gating** — macOS system voices exposed only when
+  `!app.isPackaged` (dev/unpackaged). Production (packaged) lists Azure only.
+  Detection lives in the IPC layer (`isTtsDevelopment()`), keeping `voices.ts`
+  pure and unit-testable (no `require('electron')`).
+- **Provider voice threading** — `createTtsProvider(voiceId?)` flows the
+  selected id into Azure (`createAzureTtsProvider` — voiceId beats
+  `AZURE_TTS_VOICE`, fallback `en-US-JennyNeural`) and `say`
+  (`createSayTtsProvider` — `-v <voice>`, default `Samantha`). `TtsManager.start`
+  accepts `voiceId`.
+- **IPC** — `src/main/ipc/tts.ts`: `tts:start` resolves the persisted voice;
+  `tts:list-voices` returns `ListVoicesResult`; `tts:test` stops active TTS,
+  restarts with the selected voice, and feeds a fixed test sentence through the
+  existing TTS pipeline (`ttsManager.onTranslationText(...)`) — no parallel TTS
+  path. `resolveTtsVoiceId()` exported; the SessionManager is fed it via an
+  injected resolver (`setTtsVoiceIdResolver`) so the session service stays
+  electron-free and unit-testable.
+- **Preferences persistence** — `src/main/ipc/preferences.ts` (exports
+  `loadPreferences`) persists `ttsVoiceId`; `preferences:set` persists it so a
+  selection survives restart. (`ttsVoiceGender` removed.)
+- **UI — searchable VoicePicker** — `TtsPanel.tsx` Voice section now uses a
+  single searchable combobox (`VoicePicker.tsx`, built on `Popover` +
+  `Command`/cmdk) that lists **every** available voice — the **Voice gender**
+  Select and the gender-filtered **Voice** Select were both removed. The picker
+  groups voices into **"Azure voices"** (22) and, in dev, **"macOS system
+  voices"** (184); typing filters by name **and** id. A dev-only "system voices
+  available in dev" label shows when `development`, plus a **Test Voice** button
+  that calls `window.electron.testTtsVoice()`. Wired through `App.tsx` →
+  `SettingsScreen.tsx` via new `useTtsVoices()` hook (loads on mount) and the
+  existing `usePreferences()`.
+- **Tests** — `tests/voices.test.ts`: 12 tests for `parseSayVoices` (simple,
+  multi-word/parenthesized, missing locale, blank lines, gender `unknown`),
+  catalog validity, default voice, `normalizeSelectedVoiceId`
+  (dev passthrough / empty fallback / prod restriction), and `voiceIsAzure`.
+  Project suite: **80 tests pass**.
+- **Validation** — `npm run type-check` clean; `npm test` 80/80; `npm run build`
+  OK (`dist/renderer/index.html` present); ESLint 0 errors; Prettier clean.
+  CDP-smoke-tested against the running app at min width: Settings → Voice shows
+  one searchable Voice combobox, `getTtsVoices` returns **206** voices (22 Azure
+  + ~184 macOS system) with `development:true`, searching "prabhat" returns only
+  `Prabhat (IN)`, Test Voice + Start TTS buttons present, no horizontal overflow
+  (`scrollW == winW`), theme correct (dark).
+
+### What remains
+- None for this feature. Requires a real Azure credential to hear the Test Voice /
+  Meeting TTS with a selected Azure voice (provider path reused; already covered
+  by the existing TTS pipeline).
+- Manual tasting of a specific macOS `say` voice in dev (optional, via system
+  voice list).
+
+### Bug fix — "Speech playback failed" / "TTS is already running" when selecting/testing voices (2026-09-03)
+- **Root cause (A) — silent "Speech playback failed"**: `createAzureTtsProvider`
+  passes the selected voice id to the Azure SDK. (a) A macOS `say` voice id
+  (dev-only; never an Azure voice) sent to Azure is rejected by the SDK →
+  `tts:error`. (b) `AudioOutputManager.writeAudio()` **silently drops audio when
+  the audio output manager is inactive** (`if (!this.active || !this.provider)
+  return`), and the `tts:test` handler never started audio output — so the test
+  synthesizes text and shows it but nothing is audible.
+- **Root cause (B) — "TTS is already running"**: `tts:test` used the **shared
+  singleton `ttsManager`** and left it **active**. A subsequent `/ Start
+  Meeting` called session → `ttsManager.start()` again → `{ok:false,
+  message:'TTS is already running.'}` → session aborted at the TTS stage.
+- **Fix A (routing + audio)** — `provider.ts` routes any non-Azure voice id to
+  the `say` provider (`voiceIsAzure()` in `voices.ts`), and the `tts:test`
+  handler now starts `audioOutput` (if not already active) before feeding the
+  test phrase so the audio is actually played.
+- **Fix B (independent test manager)** — `tts:test` now creates its **own
+  `TtsManager`** instance (same provider path, no parallel TTS implementation)
+  that starts, speaks the test phrase, then **self-terminates** (`setImmediate`
+  on `tts:spoken` → `stop()`) and stops the audio output it started, emitting
+  `tts:stopped` so the renderer returns to idle. The shared meeting/session
+  `ttsManager` is never touched by a test, so starting a meeting no longer hits
+  "already running".
+- **Gender filter removed (2026-09-03)**: the Female/Male dropdown and the
+  gender-filtered Voice dropdown were both replaced by a single searchable
+  **VoicePicker** showing all voices (Azure + macOS in dev). No gender UI or
+  `ttsVoiceGender` preference remains.
+- **Verified via CDP (TTS_PROVIDER=say)**: Settings → Voice now shows a single
+  Voice combobox (no "Voice gender"); opening it lists two groups — **Azure
+  voices** (22) and **macOS system voices** (184); searching "prabhat" yields
+  only `Prabhat (IN)`, searching "alice" matches the Alice system voice; picking
+  a voice updates the trigger and persists `ttsVoiceId` (e.g.
+  `en-IN-NeerjaNeural`). **Test Voice** shows "Hello, this is a test…", provider
+  "macOS Say", badge Active, then auto-returns to Off; Start Meeting completes
+  with no "TTS is already running" error. Suite **80 passing**;
+  type-check/build/eslint/format clean.
+
 ## UX/UI infrastructure: Settings layout overflow fix + centralized error handling & toasts
 
 Completed (2026-09-03). Two-part task, both verified end-to-end.