Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(voice): explain browser STT conversion failures (#1554)

Bingxi Zhao (Frank)2757302fee96
diff --git a/README.md b/README.md
index 275d8487b..47293bf57 100644
--- a/README.md
+++ b/README.md
@@ -300,6 +300,8 @@ deeptutor start # starts backend + frontend; keep the terminal open
After `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.py
index b5b034eb6..1b849bbee 100644
--- a/deeptutor/services/voice/adapters/dashscope.py
+++ b/deeptutor/services/voice/adapters/dashscope.py
@@ -13,6 +13,7 @@ import uuid
import aiohttp
import httpx
+from deeptutor.services.voice.audio import FFMPEG_STT_INSTALL_HINT
from 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.py
index 6543b8ecb..1ed53ef35 100644
--- a/deeptutor/services/voice/audio.py
+++ b/deeptutor/services/voice/audio.py
@@ -10,6 +10,10 @@ import wave
from .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 exc
try:
_, stderr = await asyncio.wait_for(process.communicate(), timeout=60)
diff --git a/tests/services/test_voice.py b/tests/services/test_voice.py
index 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_wav
from deeptutor.services.voice.base import (
VoiceProviderError,
build_auth_headers,
@@ -41,6 +42,30 @@ from deeptutor.services.voice.config import STTConfig, TTSConfig
from 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.tsx
index 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 input
area, no pill borders — quiet text/icon buttons that surface
on hover. */}