feat: add Discussion TTS with per-agent voice assignment

[wyuc]

Summary

Add TTS (text-to-speech) support to the discussion phase, enabling every agent to speak with distinct voices during classroom discussions.

• Per-agent voice config: Each agent can have a different TTS provider + voice, configured via the AgentBar voice picker with preview
• Discussion TTS playback: New useDiscussionTTS hook manages per-segment audio queue with ordered playback
• Bubble hold: StreamBuffer waits for TTS audio to finish before advancing to next segment/agent
• Audio indicator: Equalizer bar animation on roundtable bubble (amber = generating, agent color = playing)
• Cross-provider: Agents can use different TTS providers (e.g., teacher on Qwen, student on OpenAI)
• LLM voice selection: Auto-generated agents get voice matching their persona via LLM
• Settings simplification: TTS settings reduced to toggle + provider config; voice config moved to AgentBar
• Playback speed: Discussion TTS respects speed setting, switchable in real-time

Files changed (17 files, +1027 -597)

Area	Files
Core	lib/hooks/use-discussion-tts.ts (new), lib/audio/voice-resolver.ts (new), lib/buffer/stream-buffer.ts
UI	components/agent/agent-bar.tsx, components/roundtable/audio-indicator.tsx (new), components/roundtable/index.tsx
Integration	components/stage.tsx, components/chat/chat-area.tsx, components/chat/use-chat-sessions.ts
Settings	components/settings/audio-settings.tsx, components/generation/media-popover.tsx, components/canvas/canvas-toolbar.tsx
Data	lib/orchestration/registry/types.ts, lib/orchestration/registry/store.ts
Generation	app/api/generate/agent-profiles/route.ts, app/generation-preview/page.tsx

Tracking: #39, #27, #109

Test plan

• Preset mode: configure per-agent voices in AgentBar, verify each agent speaks with selected voice in discussion
• Auto mode: generate a course, verify LLM assigns voices matching agent personas
• Teacher voice: verify teacher uses the same voice in discussion as in lecture
• Browser native TTS: verify it works when no server provider is configured
• Audio indicator: verify amber bars during generation, agent-color bars during playback
• Bubble hold: verify bubble stays until TTS finishes before switching to next segment
• Speed control: change playback speed during discussion, verify audio speed changes immediately
• TTS toggle: disable TTS in settings, verify no audio plays and voice pills show disabled state
• Volume control: verify toolbar volume slider works during discussion playback
• Preview: click speaker icon in voice picker, verify preview plays with course language text

🤖 Generated with Claude Code

[cosarah]

Code Review — feat: add Discussion TTS with per-agent voice assignment

整体评价

很不错的 PR，架构清晰，功能完整。per-agent voice 的设计思路合理——通过 voiceConfig 持久化到 agent registry，fallback 到 deterministic index-based 选择。useDiscussionTTS hook 和 StreamBuffer 的 shouldHoldAfterReveal 集成干净。Settings 页面精简后把 voice 配置移到 AgentBar 是正确的方向。

Strengths

• 架构分层清晰：voice-resolver.ts 封装了 voice 解析逻辑，useDiscussionTTS 封装了队列+播放，audio-indicator.tsx 封装了可视化——每层职责明确
• StreamBuffer hold 机制：通过 shouldHoldAfterReveal callback 实现 TTS 等待，不侵入 buffer 核心逻辑，只增加了一个可选回调。非常干净
• Playback speed 实时同步：useEffect 监听 playbackSpeed 并直接同步到 audioRef.current.playbackRate，用户体验好
• i18n 覆盖完整：新增的文案都有中英文对照
• Settings 精简：audio-settings.tsx 删掉了 ~400 行冗余的 voice picker UI，改为指引到 AgentBar——减少了维护面

Issues

Important

1. handlePreview 中 server TTS 请求缺少 abort 机制

   • components/agent/agent-bar.tsx:98-124
   • 当用户快速切换 voice preview 时，stopPreview() 只停止了 browser TTS 和已创建的 Audio，但 server fetch 请求没有被 abort。如果网络慢，多个 fetch 可能并发，旧的响应可能覆盖新的状态
   • 建议：加一个 AbortController，在 stopPreview 中 abort

2. processQueue 中 error handler 的递归风险

   • lib/hooks/use-discussion-tts.ts:150-163
   • audio.error 和 catch block 中都调用 processQueueRef.current()。如果队列中连续多个 item 都触发 error（比如 API key 失效），会形成快速递归调用链
   • 建议：用 queueMicrotask 或 setTimeout(…, 0) 延迟调用 processQueueRef.current()，避免同步递归栈溢出

3. resolveAgentVoice 的 voiceConfig 校验过于严格

   • lib/audio/voice-resolver.ts:22-26
   • getServerVoiceList 对 browser-native-tts 返回空数组，导致 agent 配置了 browser-native-tts voice 时会 fallback 到 deterministic 选择，丢失用户配置
   • 建议：对 browser-native-tts 直接返回 voiceConfig 而不走 getServerVoiceList 校验

Minor

4. Roundtable 中直接调用 useAgentRegistry.getState() 在 render 中

   • components/roundtable/index.tsx:1000-1004, components/roundtable/index.tsx:504-506
   • 多处在 JSX render 函数内直接调用 useAgentRegistry.getState().getAgent(…)，这不会触发 re-render。目前因为父组件传入的 props 会触发重渲染所以碰巧能工作，但不够 robust
   • 建议：用 useAgentRegistry((s) => s.getAgent(id)) 或提前在组件顶部解析

5. agentIndexMap 可能出现 stale 引用

   • lib/hooks/use-discussion-tts.ts:57-62
   • agentIndexMap 是个 ref，通过 useEffect 更新。如果 agents 变化后 resolveVoiceForAgent 在同一个渲染周期内被调用，可能读到旧的 map
   • 影响较小（agents 列表变化不频繁），但可以考虑用 useMemo 替代

6. AgentVoicePill 的 preview 文案硬编码

   • components/agent/agent-bar.tsx:82-83
   • 'Welcome to AI Classroom' 和 '欢迎来到AI课堂' 硬编码，未走 i18n
   • 建议移到 i18n strings 中

7. sealLastText 中的 onSegmentSealed 回调使用 this.currentAgentId

   • lib/buffer/stream-buffer.ts:420
   • 如果 seal 发生在 agent_end 之后（push 顺序问题），currentAgentId 可能已经改变。当前 push 流程中 sealLastText 在 pushAgentEnd 之前被调用所以没问题，但这个隐含依赖不够明显
   • 建议加个注释说明 seal 的 ordering invariant

Assessment

Ready to merge: With fixes

核心架构扎实，Important #1（preview abort）和 #2（递归风险）建议修复后合并。#3 可以作为 follow-up。Minor issues 不影响功能正确性。

[cosarah]

Re-review after latest updates

Good improvements since the last round — preview abort controller, queueMicrotask for error recovery, volume sync, teacher voice pill, buffer-level pause with spacebar shortcut, and the sealLastText ordering comment. Here's where things stand.

Fixed since last review

• Preview abort: previewAbortRef added to AgentVoicePill, stopPreview aborts in-flight fetch.
• Recursive queue drain: error/ended handlers use queueMicrotask() instead of direct calls.
• Teacher voice pill: Teacher row in AgentBar now renders AgentVoicePill.
• sealLastText ordering: Comment explains why this.currentAgentId is safe.
• Volume sync: useDiscussionTTS respects ttsVolume/ttsMuted changes in real-time.
• Buffer-level pause: pauseActiveLiveBuffer/resumeActiveLiveBuffer with livePausedRef sticky intent that survives buffer recreation across turns. Spacebar shortcut in Roundtable is a nice UX touch.

Remaining issues

Worth documenting / deciding on

1. Browser-native TTS is invisible when any server provider is configured

   Two things going on here:

   In agent-bar.tsx:266-279, availableProviders is built with an either/or approach — if getAvailableProvidersWithVoices() returns any server providers, browser-native voices are excluded entirely. Users can't pick a browser voice for any agent as long as they have at least one server TTS provider configured with an API key. Browser voices only appear as a fallback when zero server providers are available.

   Separately, in voice-resolver.ts:21-26, resolveAgentVoice validates a saved voiceConfig by checking getServerVoiceList(providerId), which returns [] for browser-native-tts (browser voices are dynamic, not in the static registry). So if a user previously selected a browser voice (while no server providers were configured), then later adds a server provider, the saved browser voiceConfig silently fails validation and falls through to the deterministic server-voice fallback.

   Not necessarily a bug if the intent is "browser-native is purely a degraded fallback", but worth calling out since the behavior is non-obvious. If mixed mode (some agents on server TTS, some on browser) should be supported in the future, both places need changes.

Minor

2. useAgentRegistry.getState() called inside render bodies

   • components/roundtable/index.tsx — multiple places (AudioIndicator color, HoverCard content, student loop, ProactiveCard)
   • getState() reads imperatively without subscribing — works today because parent prop changes trigger re-renders, but would break if those subtrees get memoized later. Not urgent since agent config rarely changes mid-session.

3. Preview text not i18n'd

   • components/agent/agent-bar.tsx:83-86 — hardcoded 'Welcome to AI Classroom' / '欢迎来到AI课堂' with a direct localStorage read for generationLanguage. Bypasses the i18n system.

4. agentIndexMap ref could go stale within a render

   • lib/hooks/use-discussion-tts.ts:57-62 — ref updated via useEffect (runs after render). If agents changes and resolveVoiceForAgent fires in the same render cycle, it reads the old map. Unlikely in practice since agents rarely change, but useMemo would be strictly correct.

Verdict

Ready to merge. The browser-native TTS behavior (#1) is worth a design decision but isn't blocking — it works fine as a fallback-only mode, just needs to be an intentional choice rather than an accident. The rest are minor cleanup items for follow-ups.

[cosarah]

LGTM