Skip to content

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

fix: support Xiaomi MiMo v2.5 preset speech

helloqhq40182fcbaba7
diff --git a/README.md b/README.md
index ac0f77733..8a1b0de78 100644
--- a/README.md
+++ b/README.md
@@ -846,6 +846,8 @@ The Memory Graph shows the whole pyramid — L3 synthesis at the centre, L2 in t
Settings is the operational control plane, opening on **General** for interface and model output language. Its searchable navigator links to independent pages: **Personal** covers Workspaces, Data migration, Appearance, and Usage statistics; **Learning & conversation** covers starting points, attachments, Video Learning, learner and guardian controls, Learning progress, and Memory; **Models & services** covers Providers, Language models, Task models, Embedding, Search, Voice, and Multimodal generation; **Features & integrations** covers tools, capability parameters, Partners & agents, and Knowledge & documents. **System** holds Network, Runtime status, and About; **Archived chats** lets you search, restore, or permanently delete archived conversations. Runtime status contains backend health, resident memory, and the **Readiness** matrix grading capability blockers, warnings, and suggestions. Workspaces keeps topic files and learning state separate, with verified migration and export under Data migration. A **provider** holds a vendor's address and credential for reuse by its service models; the model pages choose saved providers and configure model names and capabilities. **Task models** pin a small, fast model for background work — naming conversations and writing starting points — and resolve to the active default when empty. Voice groups speech synthesis and transcription; Multimodal generation groups image and video models. Partners & agents configures local harnesses and a remote Hermes gateway.
+**Xiaomi MiMo speech.** Add a Xiaomi MiMo provider with `https://api.xiaomimimo.com/v1` and its API key, then add `mimo-v2.5-tts` under Settings → Voice. Choose a preset such as `mimo_default`, `冰糖`, or `苏打`, use `wav` or `pcm16` output, and audition it before applying. Voice instructions control style and speaking speed. This adapter supports preset speech only; voice design and voice cloning require separate models and are not supported. If an older MiMo speech model was configured through the generic OpenAI-compatible adapter, recreate its speech entry using the Xiaomi MiMo provider so it uses the chat-completions protocol. See the [official MiMo speech guide](https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5).
+
**Video Learning** under Settings → Learning & conversation defaults to the official privacy-enhanced YouTube IFrame Player. To keep playback local, set the administrator-managed Invidious API origin (for example `http://127.0.0.1:3000`), test it, select Invidious, and save. New or reopened videos pick up the provider immediately with the same material ID and progress. Invidious media is streamed through DeepTutor's byte-range proxy; upstream URLs are neither exposed to the browser nor stored on disk. If the instance fails, DeepTutor stays offline from YouTube until the learner explicitly chooses the native YouTube fallback. Public-caption tutoring is optional: install `.[video-learning]`; playback continues without it, while transcript-based **Explain here** is disabled with a reason.
<div align="center">
diff --git a/deeptutor/services/config/provider_runtime.py b/deeptutor/services/config/provider_runtime.py
index 26ca30e73..58ad5667a 100644
--- a/deeptutor/services/config/provider_runtime.py
+++ b/deeptutor/services/config/provider_runtime.py
@@ -319,6 +319,13 @@ class VoiceProviderSpec:
# Voice providers either use the shared OpenAI-compatible adapter or a native
# protocol adapter registered by name (DashScope and Volcengine Speech TTS/STT).
TTS_PROVIDERS: dict[str, VoiceProviderSpec] = {
+ "xiaomi_mimo": VoiceProviderSpec(
+ label="Xiaomi MiMo",
+ default_api_base="https://api.xiaomimimo.com/v1",
+ adapter="mimo_tts",
+ default_model="mimo-v2.5-tts",
+ default_voice="mimo_default",
+ ),
"volcengine_speech": VoiceProviderSpec(
label="Volcengine Speech (Doubao)",
default_api_base="https://openspeech.bytedance.com/api/v3",
diff --git a/deeptutor/services/voice/adapters/__init__.py b/deeptutor/services/voice/adapters/__init__.py
index c12ab9606..196ce4054 100644
--- a/deeptutor/services/voice/adapters/__init__.py
+++ b/deeptutor/services/voice/adapters/__init__.py
@@ -12,6 +12,7 @@ from deeptutor.services.voice.adapters.dashscope import (
DashScopeSTTAdapter,
DashScopeTTSAdapter,
)
+from deeptutor.services.voice.adapters.mimo import MiMoTTSAdapter
from deeptutor.services.voice.adapters.openai_compat import (
OpenAICompatSTTAdapter,
OpenAICompatTTSAdapter,
@@ -21,6 +22,7 @@ from deeptutor.services.voice.adapters.volcengine import VolcengineSTTAdapter, V
from deeptutor.services.voice.base import BaseSTTAdapter, BaseTTSAdapter, VoiceProviderError
TTS_ADAPTERS: dict[str, BaseTTSAdapter] = {
+ "mimo_tts": MiMoTTSAdapter(),
"volcengine": VolcengineTTSAdapter(),
"openai_compat": OpenAICompatTTSAdapter(),
"openrouter_tts": OpenRouterTTSAdapter(),
diff --git a/deeptutor/services/voice/adapters/mimo.py b/deeptutor/services/voice/adapters/mimo.py
new file mode 100644
index 000000000..91a353e45
--- /dev/null
+++ b/deeptutor/services/voice/adapters/mimo.py
@@ -0,0 +1,67 @@
+"""MiMo preset speech through chat completions, with base64 audio output.
+
+Protocol: https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+
+import httpx
+
+from deeptutor.services.voice.adapters.openai_compat import _join_api_path, _raise_for_provider
+from deeptutor.services.voice.base import BaseTTSAdapter, VoiceProviderError, build_auth_headers
+from deeptutor.services.voice.config import TTSConfig
+
+
+class MiMoTTSAdapter(BaseTTSAdapter):
+ """Synthesize MiMo preset voices using non-streaming chat audio output."""
+
+ async def synthesize(self, text: str, config: TTSConfig) -> tuple[bytes, str]:
+ """Return decoded WAV or 24 kHz mono PCM16 audio."""
+ if config.model != "mimo-v2.5-tts":
+ raise VoiceProviderError("The MiMo preset speech adapter requires mimo-v2.5-tts.")
+ audio_format = (config.response_format or "wav").strip().lower()
+ if audio_format == "pcm":
+ audio_format = "pcm16"
+ if audio_format not in {"wav", "pcm16"}:
+ raise VoiceProviderError("MiMo TTS supports WAV or PCM16 in this adapter.")
+ if config.speed is not None:
+ raise VoiceProviderError("Use MiMo voice instructions to control speech speed.")
+ messages = []
+ if config.instructions:
+ messages.append({"role": "user", "content": config.instructions})
+ messages.append({"role": "assistant", "content": text})
+ payload = {
+ "model": config.model,
+ "messages": messages,
+ "audio": {"format": audio_format, "voice": config.voice or "mimo_default"},
+ "stream": False,
+ }
+ headers = {
+ "Content-Type": "application/json",
+ **build_auth_headers(config.auth_style, config.api_key),
+ **config.extra_headers,
+ }
+ try:
+ async with httpx.AsyncClient(timeout=config.request_timeout) as client:
+ response = await client.post(
+ _join_api_path(config.base_url, "chat/completions"),
+ headers=headers,
+ json=payload,
+ )
+ except httpx.HTTPError as exc:
+ raise VoiceProviderError("MiMo TTS connection failed or timed out.") from exc
+ _raise_for_provider(response, "MiMo TTS synthesis")
+ try:
+ encoded = response.json()["choices"][0]["message"]["audio"]["data"]
+ if not isinstance(encoded, str):
+ raise TypeError("Expected base64 audio data.")
+ audio = base64.b64decode(encoded, validate=True)
+ except (ValueError, KeyError, IndexError, TypeError, binascii.Error) as exc:
+ raise VoiceProviderError("MiMo TTS returned malformed base64 audio.") from exc
+ if not audio:
+ raise VoiceProviderError("MiMo TTS returned empty audio.")
+ content_type = "audio/wav" if audio_format == "wav" else "audio/pcm;rate=24000;channels=1"
+ return audio, content_type
diff --git a/deeptutor/services/voice/options.py b/deeptutor/services/voice/options.py
index 84ab11779..eb910ab96 100644
--- a/deeptutor/services/voice/options.py
+++ b/deeptutor/services/voice/options.py
@@ -41,6 +41,17 @@ def preset(model: str, *, voices=None, languages=None, formats=None, **kwargs) -
def _tts_models(provider: str) -> tuple[list[dict], str]:
+ if provider == "xiaomi_mimo":
+ return [
+ preset(
+ "mimo-v2.5-tts",
+ voices=choices(
+ ["mimo_default", "冰糖", "茉莉", "苏打", "白桦", "Mia", "Chloe", "Milo", "Dean"]
+ ),
+ formats=["wav", "pcm16"],
+ instructions=True,
+ )
+ ], "https://mimo.mi.com/docs/zh-CN/quick-start/usage-guide/audio/speech-synthesis-v2.5"
openai = [
preset(
"gpt-4o-mini-tts",
@@ -194,6 +205,8 @@ def voice_options(provider: str, service: str) -> dict:
fallback = {**deepcopy(models[0]), "id": "", "voices": [], "instructions": False}
elif provider == "groq":
fallback = preset("", formats=["wav"])
+ elif provider == "xiaomi_mimo":
+ fallback = preset("", formats=["wav", "pcm16"], instructions=True)
else:
ids = {
"openai": ["gpt-4o-mini-transcribe", "gpt-4o-transcribe", "whisper-1"],
diff --git a/tests/services/test_mimo_voice.py b/tests/services/test_mimo_voice.py
new file mode 100644
index 000000000..37440a045
--- /dev/null
+++ b/tests/services/test_mimo_voice.py
@@ -0,0 +1,165 @@
+"""Regression checks for MiMo's chat-based speech protocol."""
+
+import base64
+import json
+from pathlib import Path
+import tempfile
+from typing import Any
+import unittest
+from unittest.mock import patch
+
+import httpx
+
+from deeptutor.services.config.model_catalog import ModelCatalogService
+from deeptutor.services.config.provider_runtime import resolve_tts_runtime_config
+from deeptutor.services.voice.adapters import get_tts_adapter
+from deeptutor.services.voice.adapters.mimo import MiMoTTSAdapter
+from deeptutor.services.voice.base import VoiceProviderError, VoiceProviderHTTPError
+from deeptutor.services.voice.config import TTSConfig
+from deeptutor.services.voice.options import voice_model_options
+
+
+class MiMoTTSTests(unittest.IsolatedAsyncioTestCase):
+ """Exercise the MiMo wire protocol without making external requests."""
+
+ async def invoke(
+ self, config: TTSConfig, response: dict[str, Any], status: int = 200
+ ) -> tuple[tuple[bytes, str], list[httpx.Request]]:
+ requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ return httpx.Response(status, json=response)
+
+ client_class = httpx.AsyncClient
+ with patch(
+ "deeptutor.services.voice.adapters.mimo.httpx.AsyncClient",
+ side_effect=lambda **kwargs: client_class(
+ transport=httpx.MockTransport(handler), **kwargs
+ ),
+ ):
+ result = await MiMoTTSAdapter().synthesize("你好", config)
+ return result, requests
+
+ def config(self, **kwargs: Any) -> TTSConfig:
+ return TTSConfig(
+ model="mimo-v2.5-tts",
+ base_url="https://api.xiaomimimo.com/v1",
+ api_key="test-key",
+ response_format="wav",
+ **kwargs,
+ )
+
+ async def test_request_roles_voice_and_base64_decode(self) -> None:
+ audio = b"RIFF-test-audio"
+ result, requests = await self.invoke(
+ self.config(voice="苏打", instructions="用平静的语气朗读"),
+ {"choices": [{"message": {"audio": {"data": base64.b64encode(audio).decode()}}}]},
+ )
+ self.assertEqual(result, (audio, "audio/wav"))
+ self.assertEqual(len(requests), 1)
+ request = requests[0]
+ self.assertEqual(str(request.url), "https://api.xiaomimimo.com/v1/chat/completions")
+ self.assertEqual(request.headers["Authorization"], "Bearer test-key")
+ self.assertEqual(
+ json.loads(request.content),
+ {
+ "model": "mimo-v2.5-tts",
+ "messages": [
+ {"role": "user", "content": "用平静的语气朗读"},
+ {"role": "assistant", "content": "你好"},
+ ],
+ "audio": {"format": "wav", "voice": "苏打"},
+ "stream": False,
+ },
+ )
+
+ async def test_pcm_alias_and_default_voice(self) -> None:
+ config = self.config()
+ config.base_url += "/chat/completions"
+ config.response_format = "pcm"
+ result, requests = await self.invoke(
+ config, {"choices": [{"message": {"audio": {"data": "AAABAA=="}}}]}
+ )
+ self.assertEqual(result, (b"\x00\x00\x01\x00", "audio/pcm;rate=24000;channels=1"))
+ self.assertEqual(
+ json.loads(requests[0].content)["audio"], {"format": "pcm16", "voice": "mimo_default"}
+ )
+ self.assertEqual(str(requests[0].url), config.base_url)
+
+ async def test_bad_audio_and_http_failure(self) -> None:
+ for response in [
+ {},
+ {"choices": []},
+ {"choices": [{"message": {"audio": {"data": "not-base64!"}}}]},
+ {"choices": [{"message": {"audio": {"data": ""}}}]},
+ {"choices": [{"message": {"audio": {"data": None}}}]},
+ ]:
+ with self.subTest(response=response), self.assertRaises(VoiceProviderError):
+ await self.invoke(self.config(), response)
+ with self.assertRaises(VoiceProviderHTTPError) as raised:
+ await self.invoke(self.config(), {"error": {"message": "unauthorized"}}, 401)
+ self.assertEqual(raised.exception.status_code, 401)
+
+ async def test_unsupported_parameters_fail_before_request(self) -> None:
+ for field, value in (
+ ("model", "mimo-v2.5-tts-voiceclone"),
+ ("response_format", "mp3"),
+ ("speed", 1.2),
+ ):
+ config = self.config()
+ setattr(config, field, value)
+ with self.subTest(field=field):
+ with patch("deeptutor.services.voice.adapters.mimo.httpx.AsyncClient") as client:
+ with self.assertRaises(VoiceProviderError):
+ await MiMoTTSAdapter().synthesize("你好", config)
+ client.assert_not_called()
+
+ def test_linked_catalog_selects_native_adapter_and_defaults(self) -> None:
+ ref = {"connection_id": "mimo", "binding": "xiaomi_mimo"}
+ catalog = {
+ "connections": [
+ {
+ "id": "mimo",
+ "provider": "xiaomi_mimo",
+ "source_service": "llm",
+ "base_url": "https://api.xiaomimimo.com/v1",
+ "api_key": "test-key",
+ }
+ ],
+ "services": {
+ "tts": {
+ "active_profile_id": "profile",
+ "active_model_id": "model",
+ "profiles": [
+ {
+ "id": "profile",
+ "provider_ref": ref,
+ "models": [
+ {
+ "id": "model",
+ "model": "mimo-v2.5-tts",
+ "provider_ref": ref,
+ }
+ ],
+ }
+ ],
+ }
+ },
+ }
+ with tempfile.TemporaryDirectory() as directory:
+ service = ModelCatalogService(Path(directory) / "catalog.json")
+ config = resolve_tts_runtime_config(catalog, service=service)
+ self.assertEqual(config.provider_name, "xiaomi_mimo")
+ self.assertEqual(config.adapter, "mimo_tts")
+ self.assertEqual(config.voice, "mimo_default")
+ self.assertEqual(config.response_format, "wav")
+ self.assertEqual(config.api_key, "test-key")
+ self.assertIsInstance(get_tts_adapter(config.adapter), MiMoTTSAdapter)
+ options = voice_model_options("xiaomi_mimo", "tts", config.model)
+ self.assertIn("苏打", [v["id"] for v in options["voices"]])
+ self.assertTrue(options["instructions"])
+
+
+if __name__ == "__main__":
+ unittest.main()