Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(settings): searchable language picker that names what is selected

eneseb0d262a583a
diff --git a/CLAUDE.md b/CLAUDE.md
index f951fb8c0..8a580e836 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2328,6 +2328,28 @@ Voice-to-text input captured via microphone, turned into terminal text via on-de
- **Service seam** (`src/core/speech/`) — `SpeechService` (core) + `PlatformSpeechProvider` interface + shell implementations (`PlatformElectron` / `PlatformServer`). Models are stored under `${dataDir}/speech-models/`, with fenced downloads + orphan sweep (`removeUnusedModels`). Core validates license: **tiny** free (always); **base·small·large-v3-turbo** Pro (via `isPremium()`). One model loaded at a time (FIFO memory management), lazy smart-whisper import degrades to a friendly error if the native dep is unavailable (`"Local whisper is unavailable…"`).
- **Cloud contract (iOS parity)** — `/v1/transcribe` multipart endpoint (not built yet; SDK `transcribe()` call matches iOS byte-for-byte) for future remote transcription. IPC channels `speech:*` (in `src/shared/ipc.ts`) wired in **both** Electron and Server: `speech:transcribe` (returns `Promise<{text}>`), `speech:models`, `speech:model-download`, `speech:model-delete`, `speech:progress` (main/server → renderer download-progress broadcast), and `speech:mic-consent` (Electron mic-prompt only, server always true). There is no `speech:synthesize` / `speech:cancel` and no audio in the reply.
- **Renderer capture** — `PcmCapture` AudioWorklet (16kHz single-channel PCM, WebAudio or fallback SPN) + DictationOverlay (⌘⇧D dock mic / Cmd key; Settings → Speech section for model choice + progress). **Send** appends text + Enter to the terminal; **Insert** sends text-only via `sendText(…, {enter: false})`. **Nothing auto-submits** (user always decides when to send).
+- **Language** — `SPEECH_LANGUAGES` (`src/shared/speech.ts`) is whisper's own `LANGUAGES` table
+ (tokenizer.py) verbatim: 100 entries carrying the code, CLDR's English name, the endonym and the
+ alternate spellings people type (whisper's own name where it differs, plus its documented alias
+ table); Cantonese is flagged `sinceV3`, the one entry the pre-large-v3 models have no token for.
+ It replaced a **7-entry array inside `SpeechSection`** which was the ONLY limit in the whole
+ stack (issue #586): `SpeechSettings.language` is a free string nothing validates on the way to
+ disk and whisper.cpp takes any code, so `"language": "pl"` hand-edited into settings.json
+ transcribed Polish correctly while the dropdown rendered **blank** and overwrote it on the next
+ click in the row. Three rules come out of that:
+ - The control is the app's **searchable menu idiom** (`SpeechLanguageSelect` — `.bind-select`
+ trigger + portaled `.tab-menu` with a pinned filter over a scrolling list, the Source Control
+ branch quick-pick's shape), never a `<select>`: 101 rows with no search, unreachable by typing
+ "polski", is not a picker. Rows are the pure `renderer/lib/speechLanguageRows.ts`.
+ - **A code we cannot name is still the user's setting.** `speechLanguageLabel` returns an unknown
+ code AS-IS (not `''`) and the picker gives it its own row, so a display gap can never become
+ data loss the way the `<select>` made it.
+ - **The cloud `locale` is passed through unchanged, `auto` included.** `register-ipc.ts` used to
+ send `language === 'auto' ? 'en' : language`, so on the Cloud engine "Auto-detect" was a hard,
+ silent English — on the one engine where a missing language could not be worked around at all.
+ `/v1/transcribe` does not exist yet, so `auto` = detect is our contract to write.
+ Deliberately NOT done here: seeding the initial value from the system locale (issue #586 §3) —
+ the default is still `auto`. **Mobile** keeps its own list, tracked separately as issue #591.
- **Browser constraints** — `getUserMedia` requires HTTPS or `localhost`; mic permission prompt is the browser's own (not handled by nodeterm). Model downloads land on the **server's data dir** (accessible across sessions).
- **Electron + native dep** — smart-whisper is externalized + `asarUnpack`'d (not bundled); `postinstall` rebuilds it against Electron's ABI. Device verification of the ABI rebuild is not yet exercised on a dev machine — test paths exist but have not been run in CI.
diff --git a/src/renderer/components/settings/SpeechLanguageSelect.test.tsx b/src/renderer/components/settings/SpeechLanguageSelect.test.tsx
new file mode 100644
index 000000000..aa432c1ac
--- /dev/null
+++ b/src/renderer/components/settings/SpeechLanguageSelect.test.tsx
@@ -0,0 +1,126 @@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { SpeechLanguageSelect } from './SpeechLanguageSelect'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let host: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+ host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ // jsdom implements neither of these; useMenuFlip observes the menu and the cursor effect
+ // scrolls the active row into view. Both are layout niceties, stubbed rather than exercised.
+ Element.prototype.scrollIntoView = vi.fn()
+ ;(globalThis as { ResizeObserver?: unknown }).ResizeObserver = class {
+ observe(): void {}
+ unobserve(): void {}
+ disconnect(): void {}
+ }
+})
+
+afterEach(() => {
+ act(() => root.unmount())
+ host.remove()
+ document.body.innerHTML = ''
+})
+
+function render(value: string, onChange = vi.fn()): { onChange: ReturnType<typeof vi.fn> } {
+ act(() => root.render(<SpeechLanguageSelect value={value} onChange={onChange} />))
+ return { onChange }
+}
+
+const trigger = (): HTMLButtonElement =>
+ host.querySelector('.speech-lang__trigger') as HTMLButtonElement
+const filter = (): HTMLInputElement =>
+ document.querySelector('.tab-menu__filter') as HTMLInputElement
+const rowLabels = (): string[] =>
+ [...document.querySelectorAll('.speech-lang__name')].map((n) => n.textContent ?? '')
+
+function open(): void {
+ act(() => trigger().dispatchEvent(new MouseEvent('click', { bubbles: true })))
+}
+function type(text: string): void {
+ const el = filter()
+ act(() => {
+ // React's onChange rides the native input event; set the value through the descriptor so the
+ // synthetic event sees it.
+ Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(el, text)
+ el.dispatchEvent(new Event('input', { bubbles: true }))
+ })
+}
+function key(k: string): void {
+ act(() => filter().dispatchEvent(new KeyboardEvent('keydown', { key: k, bubbles: true })))
+}
+
+describe('SpeechLanguageSelect', () => {
+ it('names the current language on the trigger, with its endonym', () => {
+ render('pl')
+ expect(trigger().textContent).toContain('Polish')
+ expect(trigger().textContent).toContain('polski')
+ })
+
+ it('shows a stored code it cannot name, instead of rendering blank', () => {
+ // The old <select> showed nothing here and the next click overwrote the value (issue #586).
+ render('xx-custom')
+ expect(trigger().textContent).toContain('xx-custom')
+ open()
+ expect(rowLabels()).toContain('xx-custom')
+ })
+
+ it('finds Polish by its endonym and picks it with Enter', () => {
+ const { onChange } = render('auto')
+ open()
+ type('polski')
+ expect(rowLabels()[0]).toBe('Polish')
+ key('Enter')
+ expect(onChange).toHaveBeenCalledWith('pl')
+ // Picking closes the menu.
+ expect(document.querySelector('.tab-menu__filter')).toBeNull()
+ })
+
+ it('moves the cursor with the arrow keys and wraps at the ends', () => {
+ const { onChange } = render('auto')
+ open()
+ type('pol') // Polish, then Polish's substring matches
+ key('ArrowDown')
+ key('ArrowUp')
+ key('ArrowUp') // wrap to the last row
+ const last = rowLabels().at(-1)
+ key('Enter')
+ expect(onChange).toHaveBeenCalledTimes(1)
+ expect(last).toBeDefined()
+ })
+
+ it('says so when nothing matches, rather than showing an empty menu', () => {
+ render('auto')
+ open()
+ type('zzzz')
+ expect(rowLabels()).toEqual([])
+ expect(document.querySelector('.speech-lang__empty')?.textContent).toContain('zzzz')
+ })
+
+ it('closes on Escape without changing the value, and keeps it off the Settings dialog', () => {
+ const { onChange } = render('auto')
+ const seen: KeyboardEvent[] = []
+ document.addEventListener('keydown', (e) => seen.push(e as KeyboardEvent))
+ open()
+ key('Escape')
+ expect(document.querySelector('.tab-menu__filter')).toBeNull()
+ expect(onChange).not.toHaveBeenCalled()
+ // stopPropagation: the dialog's own Escape handler must not also fire and close Settings.
+ expect(seen).toHaveLength(0)
+ })
+
+ it('closes on a backdrop click', () => {
+ render('auto')
+ open()
+ const backdrop = document.querySelector('.tab-backdrop') as HTMLElement
+ act(() => backdrop.dispatchEvent(new MouseEvent('click', { bubbles: true })))
+ expect(document.querySelector('.tab-menu__filter')).toBeNull()
+ })
+})
diff --git a/src/renderer/components/settings/SpeechLanguageSelect.tsx b/src/renderer/components/settings/SpeechLanguageSelect.tsx
new file mode 100644
index 000000000..0f41bc9a4
--- /dev/null
+++ b/src/renderer/components/settings/SpeechLanguageSelect.tsx
@@ -0,0 +1,151 @@
+import { useEffect, useRef, useState, type MouseEvent } from 'react'
+import { createPortal } from 'react-dom'
+import { speechLanguage, speechLanguageLabel } from '@shared/speech'
+import { useMenuFlip } from '@renderer/ui/useMenuFlip'
+import { moveRow, speechLanguageRows } from '@renderer/lib/speechLanguageRows'
+
+/**
+ * Speech-language picker: the app's own dropdown idiom (`.bind-select` trigger + a portaled
+ * `.tab-menu` with a pinned filter over a scrolling list — the same shape as the Source Control
+ * branch quick-pick), NOT a native `<select>`.
+ *
+ * A `<select>` was the whole reason issue #586 existed. With whisper's real language set it would
+ * be a 101-row scroll with no search, unreachable by typing an endonym; and a stored code it does
+ * not carry renders as an EMPTY row, which the next click in the field then overwrites — so the
+ * control that cannot display a value also destroys it. Here the current value always has a row.
+ */
+export function SpeechLanguageSelect({
+ value,
+ onChange
+}: {
+ value: string
+ onChange: (code: string) => void
+}): React.JSX.Element {
+ const [menu, setMenu] = useState<{
+ top: number
+ left: number
+ width: number
+ base: number
+ } | null>(null)
+ const known = speechLanguage(value)
+
+ const open = (e: MouseEvent<HTMLButtonElement>): void => {
+ const r = e.currentTarget.getBoundingClientRect()
+ // `base` is the trigger's TOP edge, so a list that would overflow the viewport flips to open
+ // ABOVE the trigger rather than above the 4px gap (see useMenuFlip).
+ setMenu({ top: r.bottom + 4, left: r.left, width: r.width, base: r.top })
+ }
+
+ return (
+ <>
+ <button
+ type="button"
+ className="bind-select speech-lang__trigger"
+ aria-label="Speech language"
+ onClick={open}
+ >
+ <span className="bind-select__val">{speechLanguageLabel(value)}</span>
+ {known && known.endonym.toLowerCase() !== known.label.toLowerCase() ? (
+ <span className="speech-lang__endonym">{known.endonym}</span>
+ ) : null}
+ <span className="bind-select__chev">⌄</span>
+ </button>
+ {menu && (
+ <LanguageMenu
+ anchor={menu}
+ value={value}
+ onPick={(code) => {
+ onChange(code)
+ setMenu(null)
+ }}
+ onClose={() => setMenu(null)}
+ />
+ )}
+ </>
+ )
+}
+
+function LanguageMenu({
+ anchor,
+ value,
+ onPick,
+ onClose
+}: {
+ anchor: { top: number; left: number; width: number; base: number }
+ value: string
+ onPick: (code: string) => void
+ onClose: () => void
+}): React.ReactPortal {
+ // Hook lives in its own component so it isn't called conditionally in the trigger above.
+ const flip = useMenuFlip(anchor.top, anchor.left, anchor.base)
+ const [query, setQuery] = useState('')
+ const [active, setActive] = useState(0)
+ const rows = speechLanguageRows(query, value)
+ const listRef = useRef<HTMLDivElement>(null)
+
+ // A new query renumbers the rows, so the cursor goes back to the best match.
+ useEffect(() => setActive(0), [query])
+
+ // Keep the keyboard cursor in view — with 101 rows the highlight is otherwise off-screen the
+ // moment you arrow past the visible few.
+ useEffect(() => {
+ listRef.current?.children[active]?.scrollIntoView({ block: 'nearest' })
+ }, [active])
+
+ return createPortal(
+ <>
+ <div className="tab-backdrop" style={{ zIndex: 78 }} onClick={onClose} />
+ <div
+ ref={flip.ref}
+ className="tab-menu speech-lang__menu"
+ style={{ top: flip.top, left: flip.left, minWidth: anchor.width, zIndex: 80 }}
+ >
+ <input
+ className="tab__edit tab-menu__filter"
+ placeholder="Search languages — name, code or “polski”"
+ value={query}
+ autoFocus
+ spellCheck={false}
+ onChange={(e) => setQuery(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === 'Escape') {
+ // The Settings dialog closes on Escape too; the picker gets this one.
+ e.stopPropagation()
+ onClose()
+ return
+ }
+ if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+ e.preventDefault()
+ setActive((a) => moveRow(a, e.key === 'ArrowDown' ? 1 : -1, rows.length))
+ return
+ }
+ if (e.key === 'Enter' && rows[active]) onPick(rows[active].code)
+ }}
+ />
+ {/* --scroll on the LIST only, so the filter input never scrolls away. */}
+ <div ref={listRef} className="tab-menu__list tab-menu--scroll" role="listbox">
+ {rows.length === 0 ? (
+ <div className="speech-lang__empty">No language matches “{query.trim()}”.</div>
+ ) : (
+ rows.map((r, i) => (
+ <button
+ type="button"
+ key={r.code}
+ role="option"
+ aria-selected={r.code === value}
+ className={i === active ? 'speech-lang__row is-active' : 'speech-lang__row'}
+ onMouseEnter={() => setActive(i)}
+ onClick={() => onPick(r.code)}
+ >
+ <span className="tab-menu__check">{r.code === value ? '✓' : ''}</span>
+ <span className="speech-lang__name">{r.label}</span>
+ {r.hint ? <span className="speech-lang__hint">{r.hint}</span> : null}
+ </button>
+ ))
+ )}
+ </div>
+ </div>
+ </>,
+ document.body
+ )
+}
diff --git a/src/renderer/components/settings/sections/SpeechSection.tsx b/src/renderer/components/settings/sections/SpeechSection.tsx
index ef2d0f53a..4e0c52c6d 100644
--- a/src/renderer/components/settings/sections/SpeechSection.tsx
+++ b/src/renderer/components/settings/sections/SpeechSection.tsx
@@ -1,6 +1,16 @@
import { useCallback, useEffect, useState } from 'react'
import type { SpeechModelInfo } from '@shared/types'
-import { hasSpeechModel, modelAfterDelete, modelAfterDownload, SPEECH_MODEL_NONE } from '@shared/speech'
+import {
+ hasSpeechModel,
+ modelAfterDelete,
+ modelAfterDownload,
+ SPEECH_LANGUAGES,
+ SPEECH_MODEL_NONE
+} from '@shared/speech'
+import {
+ speechLanguageSummary,
+ speechLanguageWarning
+} from '@renderer/lib/speechLanguageRows'
import { formatShortcut, isHoldChord } from '@shared/shortcut'
import { dictationBinding } from '../../../lib/keybindingOverrides'
import { useSettings } from '../../../state/settings'
@@ -8,7 +18,7 @@ import { useEntitlement } from '../../../state/entitlement'
import { SettingsSection } from '../SettingsSection'
import { SearchableRow } from '../SearchableRow'
import { FieldRow } from '../FieldRow'
-import { Select } from '@renderer/ui/Select'
+import { SpeechLanguageSelect } from '../SpeechLanguageSelect'
import { SegmentedPill } from '@renderer/ui/SegmentedPill'
import { Button } from '@renderer/ui/Button'
import type { SettingsSectionId } from '../nav'
@@ -44,31 +54,22 @@ const ROWS = {
},
language: {
title: 'Language',
+ // Every language name and endonym is a keyword, DERIVED from the catalogue rather than
+ // retyped: someone who searches Settings for "polish" (or "polski") should be shown the row
+ // that can give it to them. The old nine-word list is exactly the kind that goes stale the
+ // day an entry is added.
keywords: [
'language',
'locale',
'auto',
- 'english',
- 'turkish',
- 'german',
- 'french',
- 'spanish',
- 'japanese'
+ 'dictation',
+ 'whisper',
+ ...SPEECH_LANGUAGES.flatMap((l) => [l.label, l.endonym, l.code, ...(l.aliases ?? [])])
]
}
}
const ENTRIES = Object.values(ROWS)
-const LANGUAGES: { value: string; label: string }[] = [
- { value: 'auto', label: 'Auto-detect' },
- { value: 'en', label: 'English' },
- { value: 'tr', label: 'Turkish' },
- { value: 'de', label: 'German' },
- { value: 'fr', label: 'French' },
- { value: 'es', label: 'Spanish' },
- { value: 'ja', label: 'Japanese' }
-]
-
/** `1600` -> `"1.6 GB"`, `142` -> `"142 MB"`. Used for both the approximate (undownloaded) and
* real (downloaded) size, so the two read consistently in the same row. */
function formatSize(mb: number): string {
@@ -352,19 +353,12 @@ export function SpeechSection({
<SearchableRow {...ROWS.language}>
<FieldRow
label="Language"
- description="A hint for transcription; auto-detect works well for mixed speech."
+ // The copy names what is SELECTED, not just what the field is for: with a searchable
+ // menu of 100 languages the trigger is the only other place that says so.
+ description={speechLanguageSummary(settings.speech.language)}
+ note={speechLanguageWarning(settings.speech.language, settings.speech.model)}
control={
- <Select
- aria-label="Speech language"
- value={settings.speech.language}
- onChange={(e) => setLanguage(e.target.value)}
- >
- {LANGUAGES.map((l) => (
- <option key={l.value} value={l.value}>
- {l.label}
- </option>
- ))}
- </Select>
+ <SpeechLanguageSelect value={settings.speech.language} onChange={setLanguage} />
}
/>
</SearchableRow>
diff --git a/src/renderer/lib/speechLanguageRows.test.ts b/src/renderer/lib/speechLanguageRows.test.ts
new file mode 100644
index 000000000..2fd28dd78
--- /dev/null
+++ b/src/renderer/lib/speechLanguageRows.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import {
+ moveRow,
+ speechLanguageRows,
+ speechLanguageSummary,
+ speechLanguageWarning
+} from './speechLanguageRows'
+
+const codes = (q: string, current = 'auto'): string[] =>
+ speechLanguageRows(q, current).map((r) => r.code)
+
+describe('speechLanguageRows', () => {
+ it('pins Auto-detect above the catalogue when nothing is typed', () => {
+ const rows = speechLanguageRows('', 'auto')
+ expect(rows[0]).toMatchObject({ code: 'auto', label: 'Auto-detect' })
+ expect(rows).toHaveLength(101) // auto + whisper's 100
+ })
+
+ it('does not let Auto-detect outrank what the user is clearly typing', () => {
+ // "de" is a substring of "auto-detect"; a `.includes` match would have pinned Auto-detect
+ // above German for it.
+ expect(codes('de')[0]).toBe('de')
+ expect(codes('de')).not.toContain('auto')
+ // It is still reachable by its own name.
+ expect(codes('au')[0]).toBe('auto')
+ expect(codes('detect')).toEqual(['auto'])
+ })
+
+ it('finds Polish by code, English name and endonym', () => {
+ expect(codes('pl')[0]).toBe('pl')
+ expect(codes('polish')[0]).toBe('pl')
+ expect(codes('polski')[0]).toBe('pl')
+ })
+
+ it('keeps a stored code the catalogue does not know selectable', () => {
+ // The state that used to render blank and get overwritten on the next click.
+ const rows = speechLanguageRows('', 'xx-custom')
+ expect(rows[1]).toMatchObject({ code: 'xx-custom', label: 'xx-custom' })
+ expect(codes('xx', 'xx-custom')).toContain('xx-custom')
+ // A known code never gets the extra row.
+ expect(speechLanguageRows('', 'pl').filter((r) => r.code === 'pl')).toHaveLength(1)
+ })
+
+ it('shows the endonym and code, and drops an endonym that only repeats the label', () => {
+ const pl = speechLanguageRows('pl', 'auto').find((r) => r.code === 'pl')
+ expect(pl?.hint).toBe('polski · pl')
+ const la = speechLanguageRows('latin', 'auto').find((r) => r.code === 'la')
+ expect(la?.hint).toBe('la')
+ })
+})
+
+describe('moveRow', () => {
+ it('wraps in both directions and survives an empty list', () => {
+ expect(moveRow(0, 1, 3)).toBe(1)
+ expect(moveRow(2, 1, 3)).toBe(0)
+ expect(moveRow(0, -1, 3)).toBe(2)
+ expect(moveRow(0, 1, 0)).toBe(0)
+ expect(moveRow(0, -1, 0)).toBe(0)
+ })
+})
+
+describe('speechLanguageSummary', () => {
+ it('names the selected language, with its endonym when that adds something', () => {
+ expect(speechLanguageSummary('pl')).toBe('Transcribing as Polish (polski).')
+ expect(speechLanguageSummary('la')).toBe('Transcribing as Latin.')
+ expect(speechLanguageSummary('xx')).toBe('Transcribing as “xx”.')
+ expect(speechLanguageSummary('auto')).toMatch(/^Auto-detect: /)
+ })
+})
+
+describe('speechLanguageWarning', () => {
+ it('says nothing for an ordinary pairing', () => {
+ expect(speechLanguageWarning('auto', 'tiny')).toBeUndefined()
+ expect(speechLanguageWarning('pl', 'tiny')).toBeUndefined()
+ expect(speechLanguageWarning('yue', 'large-v3-turbo')).toBeUndefined()
+ })
+
+ it('flags a code this build cannot name, without suggesting it was dropped', () => {
+ const w = speechLanguageWarning('xx', 'tiny')
+ expect(w).toContain('kept exactly as set')
+ })
+
+ it('flags Cantonese under a pre-large-v3 model, but not while dictation is off', () => {
+ expect(speechLanguageWarning('yue', 'small')).toContain('large-v3')
+ expect(speechLanguageWarning('yue', '')).toBeUndefined()
+ })
+})
diff --git a/src/renderer/lib/speechLanguageRows.ts b/src/renderer/lib/speechLanguageRows.ts
new file mode 100644
index 000000000..632193a1d
--- /dev/null
+++ b/src/renderer/lib/speechLanguageRows.ts
@@ -0,0 +1,93 @@
+import {
+ filterSpeechLanguages,
+ hasSpeechModel,
+ modelKnowsV3Languages,
+ SPEECH_LANGUAGE_AUTO,
+ speechLanguage,
+ type SpeechLanguage
+} from '@shared/speech'
+
+/** One row of the speech-language picker. `hint` is the muted right-hand text. */
+export interface SpeechLanguageRow {
+ code: string
+ label: string
+ hint?: string
+}
+
+/**
+ * Auto-detect matches only a prefix of its own name (or the whole word "detect"), never a bare
+ * substring. `'auto-detect'.includes(q)` would have put it above German for the query "de" — the
+ * pinned row must not compete with what the user is obviously typing.
+ */
+function autoMatches(q: string): boolean {
+ return q === '' || 'auto-detect'.startsWith(q) || 'automatic'.startsWith(q) || q === 'detect'
+}
+
+/**
+ * The rows to show for `query`, with the current value always reachable.
+ *
+ * Two rows are pinned above the catalogue, and both exist for a reason:
+ * - **Auto-detect** is not one of whisper's languages (it means "no hint"), so it is not in the
+ * table and has to be added here.
+ * - **A stored code this build does not know** gets its own row. `SpeechSettings.language` is a
+ * free string nothing validates, so a hand-edited settings.json can hold one; without the row
+ * the picker would have no way to show what is selected, which is how the old `<select>` came
+ * to render blank and then overwrite the user's value.
+ */
+export function speechLanguageRows(query: string, current: string): SpeechLanguageRow[] {
+ const q = query.trim().toLowerCase()
+ const rows: SpeechLanguageRow[] = []
+ if (autoMatches(q)) {
+ rows.push({ code: SPEECH_LANGUAGE_AUTO, label: 'Auto-detect', hint: 'Whisper guesses' })
+ }
+ const unknown =
+ current !== SPEECH_LANGUAGE_AUTO && current !== '' && !speechLanguage(current) ? current : null
+ if (unknown && (q === '' || unknown.toLowerCase().includes(q))) {
+ rows.push({ code: unknown, label: unknown, hint: 'not in this list' })
+ }
+ for (const l of filterSpeechLanguages(query)) rows.push({ code: l.code, label: l.label, hint: hintFor(l) })
+ return rows
+}
+
+/** The endonym plus the code — minus the endonym when it only repeats the English name (Latin,
+ * Afrikaans, Filipino and a handful more), where printing it twice reads as a rendering bug. */
+function hintFor(l: SpeechLanguage): string {
+ return l.endonym.toLowerCase() === l.label.toLowerCase() ? l.code : `${l.endonym} · ${l.code}`
+}
+
+/** Wrapping cursor movement over the rows — `Math.max(1, …)` so an empty list can't divide by 0. */
+export function moveRow(active: number, delta: number, count: number): number {
+ const n = Math.max(1, count)
+ return (((active + delta) % n) + n) % n
+}
+
+/**
+ * The sentence under the Language field naming what is actually selected. The old row said only
+ * "A hint for transcription; auto-detect works well for mixed speech" — true of the 7-entry list,
+ * and useless once the control is a searchable menu whose trigger you have to look at twice.
+ */
+export function speechLanguageSummary(code: string): string {
+ if (code === SPEECH_LANGUAGE_AUTO) {
+ return 'Auto-detect: Whisper guesses from the first seconds of audio. Dictation clips are short, so it does misjudge them — name your language if it gets yours wrong.'
+ }
+ const lang = speechLanguage(code)
+ if (!lang) return `Transcribing as “${code}”.`
+ const native = lang.endonym.toLowerCase() === lang.label.toLowerCase() ? '' : ` (${lang.endonym})`
+ return `Transcribing as ${lang.label}${native}.`
+}
+
+/**
+ * The warn-coloured caveat, or nothing. Two cases, and both are states the picker can reach:
+ * a code this build cannot name (say so rather than silently keep it), and Cantonese under a
+ * model whose vocabulary predates it.
+ */
+export function speechLanguageWarning(code: string, model: string): string | undefined {
+ if (code !== SPEECH_LANGUAGE_AUTO && code !== '' && !speechLanguage(code)) {
+ return `“${code}” isn’t a language this build recognises. It is kept exactly as set and passed to the engine unchanged — pick from the list to replace it.`
+ }
+ const lang = speechLanguage(code)
+ if (lang?.sinceV3 && hasSpeechModel(model) && !modelKnowsV3Languages(model)) {
+ return `${lang.label} was added in Whisper large-v3 — the model selected above has no token for it. Choose Large V3 Turbo, or use Chinese.`
+ }
+ return undefined
+}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 7859f558e..4a0bae2be 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -11391,3 +11391,46 @@ body.focus-mode .dock:hover {
border: 1px solid var(--warn);
background: transparent;
}
+
+/* ---- Settings → Speech: the language picker (issue #586) ---- */
+/* Whisper knows 100 languages, so this is the app's searchable menu idiom (`.bind-select`
+ trigger + portaled `.tab-menu` with a pinned filter) rather than a native <select>, which
+ can neither be searched nor show a code it does not carry. */
+.speech-lang__trigger {
+ width: 260px;
+}
+.speech-lang__endonym {
+ margin-left: auto;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ color: var(--muted);
+}
+.speech-lang__menu {
+ width: 320px;
+ max-width: calc(100vw - 24px);
+}
+.speech-lang__row {
+ gap: 8px;
+}
+/* Keyboard cursor. Same fill as :hover so arrowing and pointing look like one thing. */
+.speech-lang__row.is-active {
+ background: var(--panel-header);
+}
+.speech-lang__name {
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+.speech-lang__hint {
+ margin-left: auto;
+ padding-left: 8px;
+ flex-shrink: 0;
+ color: var(--muted-2);
+ font-size: 12px;
+}
+.speech-lang__empty {
+ padding: 8px 10px;
+ color: var(--muted);
+ font-size: 13px;
+}