DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(voice): explain browser STT conversion failures (#1554)
Bingxi Zhao (Frank)2757302fee96
diff --git a/README.md b/README.mdindex 275d8487b..47293bf57 100644--- a/README.md+++ b/README.md@@ -300,6 +300,8 @@ deeptutor start # starts backend + frontend; keep the terminal openAfter `deeptutor start`, open the frontend URL printed in the terminal — by default [http://127.0.0.1:3782](http://127.0.0.1:3782). Press `Ctrl+C` in that terminal to stop both backend and frontend. Skipping `deeptutor init` is fine for a quick trial; the app boots with default ports and empty model settings, configure them later in **Settings → Models**.+**Browser microphone transcription:** OpenAI-compatible STT adapters forward browser audio to the provider without local conversion. The native DashScope and Volcengine STT adapters convert browser WebM/Opus to 16 kHz WAV and require an `ffmpeg` executable on DeepTutor's `PATH`. A canonical 16 kHz mono PCM WAV bypasses this conversion. For Windows PyPI installations using either native adapter, install FFmpeg, add its `bin` directory to the service's `PATH`, then restart DeepTutor. Conversion failures appear below the chat input.+</details><details>diff --git a/deeptutor/services/voice/adapters/dashscope.py b/deeptutor/services/voice/adapters/dashscope.pyindex b5b034eb6..1b849bbee 100644--- a/deeptutor/services/voice/adapters/dashscope.py+++ b/deeptutor/services/voice/adapters/dashscope.py@@ -13,6 +13,7 @@ import uuidimport aiohttpimport httpx+from deeptutor.services.voice.audio import FFMPEG_STT_INSTALL_HINTfrom deeptutor.services.voice.base import (BaseSTTAdapter,BaseTTSAdapter,@@ -190,7 +191,8 @@ class DashScopeSTTAdapter(BaseSTTAdapter):)except OSError as exc:raise VoiceProviderError(- "ffmpeg is required to normalize audio for DashScope STT."+ "ffmpeg is required to normalize audio for DashScope STT. "+ + FFMPEG_STT_INSTALL_HINT) from exc_, stderr = await process.communicate()if process.returncode != 0:diff --git a/deeptutor/services/voice/audio.py b/deeptutor/services/voice/audio.pyindex 6543b8ecb..1ed53ef35 100644--- a/deeptutor/services/voice/audio.py+++ b/deeptutor/services/voice/audio.py@@ -10,6 +10,10 @@ import wavefrom .base import VoiceProviderError+FFMPEG_STT_INSTALL_HINT = (+ "Install FFmpeg, add its bin directory to DeepTutor's PATH, then restart DeepTutor."+)+def pcm_to_wav(audio: bytes, sample_rate: int = 24000) -> bytes:output = io.BytesIO()@@ -58,7 +62,7 @@ async def normalize_wav(audio: bytes) -> bytes:)except OSError as exc:raise VoiceProviderError(- "ffmpeg is required to convert this recording to WAV."+ "ffmpeg is required to convert this recording to WAV. " + FFMPEG_STT_INSTALL_HINT) from exctry:_, stderr = await asyncio.wait_for(process.communicate(), timeout=60)diff --git a/tests/services/test_voice.py b/tests/services/test_voice.pyindex f557eb746..796e6592a 100644--- a/tests/services/test_voice.py+++ b/tests/services/test_voice.py@@ -30,6 +30,7 @@ from deeptutor.services.voice.adapters.openai_compat import (OpenAICompatTTSAdapter,OpenRouterTTSAdapter,)+from deeptutor.services.voice.audio import normalize_wav, pcm_to_wavfrom deeptutor.services.voice.base import (VoiceProviderError,build_auth_headers,@@ -41,6 +42,30 @@ from deeptutor.services.voice.config import STTConfig, TTSConfigfrom deeptutor.services.voice.options import voice_options+async def test_browser_audio_names_missing_ffmpeg_but_canonical_wav_bypasses_it(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ async def missing_ffmpeg(*_args: object, **_kwargs: object) -> object:+ raise FileNotFoundError("ffmpeg")++ monkeypatch.setattr(+ "deeptutor.services.voice.audio.asyncio.create_subprocess_exec", missing_ffmpeg+ )+ monkeypatch.setattr(+ "deeptutor.services.voice.adapters.dashscope.asyncio.create_subprocess_exec",+ missing_ffmpeg,+ )+ canonical = pcm_to_wav(b"\x00\x00", sample_rate=16000)+ assert await normalize_wav(canonical) == canonical+ assert await DashScopeSTTAdapter()._prepare_wav(canonical, "clip.wav", "audio/wav") == canonical++ with pytest.raises(VoiceProviderError, match="Install FFmpeg.*PATH"):+ await normalize_wav(b"browser-webm")+ with pytest.raises(VoiceProviderError, match="Install FFmpeg.*PATH"):+ await DashScopeSTTAdapter()._prepare_wav(b"browser-webm", "clip.webm", "audio/webm")++def _capture_post(monkeypatch: pytest.MonkeyPatch, response: httpx.Response) -> dict[str, Any]:"""Patch ``httpx.AsyncClient.post`` to record args and return ``response``."""captured: dict[str, Any] = {}diff --git a/web/components/chat/home/ChatComposer.tsx b/web/components/chat/home/ChatComposer.tsxindex e4dc6b674..598243c75 100644--- a/web/components/chat/home/ChatComposer.tsx+++ b/web/components/chat/home/ChatComposer.tsx@@ -1079,6 +1079,12 @@ export default memo(function ChatComposer({</div>)}+ {recorder.error && (+ <div role="alert" className="px-4 pb-2 text-[11px] text-red-600">+ {recorder.error}+ </div>+ )}+{/* Claude-style chrome-free toolbar: no divider against the inputarea, no pill borders — quiet text/icon buttons that surfaceon hover. */}