Skip to content

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

feat: add native MiniMax speech synthesis

octo-patch8ae821e41da7
diff --git a/README.md b/README.md
index ac0f77733..4bfad7449 100644
--- a/README.md
+++ b/README.md
@@ -846,6 +846,9 @@ 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.
+**MiniMax speech** — in Settings → Voice, choose MiniMax for text-to-speech and select `speech-2.8-hd`. Configure a MiniMax API key and a system or custom voice ID; the default voice is `English_expressive_narrator`. The API base defaults to `https://api.minimax.io/v1`; for the China region use `https://api.minimaxi.com/v1`. Read-aloud and voice previews use the native speech endpoint, with MP3, WAV, FLAC or PCM output, sample rate, speed and language controls. See the [MiniMax speech API](https://platform.minimax.io/docs/api-reference/speech-t2a-http) for voice IDs and account availability.
+
+
**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..1d37d2b04 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] = {
+ "minimax": VoiceProviderSpec(
+ label="MiniMax",
+ default_api_base="https://api.minimax.io/v1",
+ adapter="minimax",
+ default_model="speech-2.8-hd",
+ default_voice="English_expressive_narrator",
+ ),
"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..31cc12374 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.minimax import MiniMaxTTSAdapter
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] = {
+ "minimax": MiniMaxTTSAdapter(),
"volcengine": VolcengineTTSAdapter(),
"openai_compat": OpenAICompatTTSAdapter(),
"openrouter_tts": OpenRouterTTSAdapter(),
diff --git a/deeptutor/services/voice/adapters/minimax.py b/deeptutor/services/voice/adapters/minimax.py
new file mode 100644
index 000000000..6f090f742
--- /dev/null
+++ b/deeptutor/services/voice/adapters/minimax.py
@@ -0,0 +1,91 @@
+"""Native MiniMax synchronous speech synthesis with hex-encoded audio."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import httpx
+
+from deeptutor.services.voice.base import BaseTTSAdapter, VoiceProviderError, join_audio_path
+from deeptutor.services.voice.config import TTSConfig
+
+
+class MiniMaxTTSAdapter(BaseTTSAdapter):
+ """Synthesize audio through the MiniMax text-to-audio HTTP API."""
+
+ async def synthesize(self, text: str, config: TTSConfig) -> tuple[bytes, str]:
+ """Return decoded audio only after successful, complete synthesis."""
+ if not config.api_key or config.api_key == "***":
+ raise VoiceProviderError("Configure a MiniMax API key for speech synthesis.")
+ if not config.voice:
+ raise VoiceProviderError("Choose a MiniMax voice ID for speech synthesis.")
+ if not text.strip() or len(text) >= 10000:
+ raise VoiceProviderError("MiniMax speech input must contain 1 to 9999 characters.")
+ fmt = config.response_format or "mp3"
+ if fmt not in {"mp3", "wav", "flac", "pcm"}:
+ raise VoiceProviderError("MiniMax TTS supports mp3, wav, flac, or pcm.")
+ if config.sample_rate not in {8000, 16000, 22050, 24000, 32000, 44100}:
+ raise VoiceProviderError("Unsupported MiniMax TTS sample rate.")
+ voice: dict[str, Any] = {"voice_id": config.voice}
+ if config.speed is not None:
+ if not math.isfinite(config.speed) or not 0.5 <= config.speed <= 2:
+ raise VoiceProviderError("MiniMax speech speed must be between 0.5 and 2.")
+ voice["speed"] = config.speed
+ payload = {
+ "model": config.model,
+ "text": text,
+ "stream": False,
+ "output_format": "hex",
+ "voice_setting": voice,
+ "audio_setting": {
+ "format": fmt,
+ "sample_rate": config.sample_rate,
+ "channel": 1,
+ },
+ "language_boost": config.language or "auto",
+ }
+ headers = {
+ **config.extra_headers,
+ "Authorization": f"Bearer {config.api_key}",
+ "Content-Type": "application/json",
+ }
+ url = join_audio_path(config.base_url, "t2a_v2")
+ try:
+ async with httpx.AsyncClient(timeout=config.request_timeout) as client:
+ response = await client.post(url, headers=headers, json=payload)
+ if response.status_code >= 400:
+ raise VoiceProviderError(
+ f"MiniMax TTS request failed (HTTP {response.status_code})."
+ )
+ result = response.json()
+ except httpx.HTTPError as exc:
+ raise VoiceProviderError("MiniMax TTS connection failed or timed out.") from exc
+ except ValueError as exc:
+ raise VoiceProviderError("Malformed MiniMax TTS response.") from exc
+ if not isinstance(result, dict):
+ raise VoiceProviderError("Malformed MiniMax TTS response.")
+ status = result.get("base_resp")
+ if not isinstance(status, dict) or status.get("status_code") != 0:
+ # Provider bodies can echo private text or credentials; do not expose them.
+ raise VoiceProviderError(
+ "MiniMax TTS synthesis failed; check the credentials, model and voice."
+ )
+ data = result.get("data")
+ if not isinstance(data, dict) or data.get("status") != 2:
+ raise VoiceProviderError("MiniMax TTS synthesis did not complete.")
+ encoded = data.get("audio")
+ if not isinstance(encoded, str):
+ raise VoiceProviderError("Malformed MiniMax TTS audio response.")
+ try:
+ audio = bytes.fromhex(encoded)
+ except ValueError as exc:
+ raise VoiceProviderError("Malformed MiniMax TTS audio response.") from exc
+ if not audio:
+ raise VoiceProviderError("MiniMax TTS returned empty audio.")
+ return audio, {
+ "mp3": "audio/mpeg",
+ "wav": "audio/wav",
+ "flac": "audio/flac",
+ "pcm": f"audio/pcm;rate={config.sample_rate};channels=1",
+ }[fmt]
diff --git a/deeptutor/services/voice/options.py b/deeptutor/services/voice/options.py
index 84ab11779..8de2dd03c 100644
--- a/deeptutor/services/voice/options.py
+++ b/deeptutor/services/voice/options.py
@@ -41,6 +41,27 @@ def preset(model: str, *, voices=None, languages=None, formats=None, **kwargs) -
def _tts_models(provider: str) -> tuple[list[dict], str]:
+ if provider == "minimax":
+ return [
+ preset(
+ model,
+ voices=choices(["English_expressive_narrator"]),
+ languages=choices(["auto", "Chinese", "English"]),
+ formats=["mp3", "wav", "flac", "pcm"],
+ sample_rates=[8000, 16000, 22050, 24000, 32000, 44100],
+ speed={"min": 0.5, "max": 2, "step": 0.05},
+ )
+ for model in [
+ "speech-2.8-hd",
+ "speech-2.8-turbo",
+ "speech-2.6-hd",
+ "speech-2.6-turbo",
+ "speech-02-hd",
+ "speech-02-turbo",
+ "speech-01-hd",
+ "speech-01-turbo",
+ ]
+ ], "https://platform.minimax.io/docs/api-reference/speech-t2a-http"
openai = [
preset(
"gpt-4o-mini-tts",
@@ -188,7 +209,9 @@ def voice_options(provider: str, service: str) -> dict:
formats=OPENAI_FORMATS,
language_note="Language follows the text and selected voice.",
)
- if provider == "volcengine_speech":
+ if provider == "minimax":
+ fallback = {**deepcopy(models[0]), "id": "", "voices": []}
+ elif provider == "volcengine_speech":
fallback = {**deepcopy(models[0]), "id": "", "voices": [], "instructions": False}
elif provider == "dashscope":
fallback = {**deepcopy(models[0]), "id": "", "voices": [], "instructions": False}
diff --git a/tests/services/test_minimax_voice.py b/tests/services/test_minimax_voice.py
new file mode 100644
index 000000000..2a87857a9
--- /dev/null
+++ b/tests/services/test_minimax_voice.py
@@ -0,0 +1,238 @@
+"""MiniMax native speech wire format, failure handling and catalog integration."""
+
+from copy import deepcopy
+import json
+
+import httpx
+import pytest
+
+from deeptutor.services.config.provider_runtime import TTS_PROVIDERS, resolve_tts_runtime_config
+from deeptutor.services.voice import synthesize_speech
+from deeptutor.services.voice.adapters.minimax import MiniMaxTTSAdapter
+from deeptutor.services.voice.base import VoiceProviderError
+from deeptutor.services.voice.config import TTSConfig
+from deeptutor.services.voice.options import voice_model_options, voice_options
+
+
+def transport(monkeypatch, handler):
+ """Intercept actual HTTP requests without calling the speech service."""
+ original = httpx.AsyncClient
+ monkeypatch.setattr(
+ httpx, "AsyncClient", lambda **kw: original(transport=httpx.MockTransport(handler), **kw)
+ )
+
+
+def config(**overrides):
+ """Build a speech configuration with non-secret test credentials."""
+ values = {
+ "model": "speech-2.8-hd",
+ "api_key": "test-key",
+ "base_url": "https://api.minimax.io/v1",
+ "voice": "custom-voice",
+ }
+ return TTSConfig(**(values | overrides))
+
+
+def success(audio="494433"):
+ """Return the documented non-streaming completion envelope."""
+ return {"base_resp": {"status_code": 0}, "data": {"status": 2, "audio": audio}}
+
+
+ "base_url",
+ [
+ "https://api.minimax.io/v1",
+ "https://api.minimaxi.com/v1/",
+ "https://api.minimax.io/v1/t2a_v2",
+ ],
+)
+ "fmt,mime",
+ [
+ ("mp3", "audio/mpeg"),
+ ("wav", "audio/wav"),
+ ("flac", "audio/flac"),
+ ("pcm", "audio/pcm;rate=16000;channels=1"),
+ ],
+)
+async def test_native_request_and_decoded_audio(monkeypatch, base_url, fmt, mime):
+ def handle(request):
+ assert request.method == "POST"
+ assert request.url.path == "/v1/t2a_v2"
+ assert request.url.host == httpx.URL(base_url).host
+ assert request.headers["authorization"] == "Bearer test-key"
+ assert request.headers["x-request-source"] == "test"
+ assert json.loads(request.content) == {
+ "model": "speech-2.8-hd",
+ "text": "Hello",
+ "stream": False,
+ "output_format": "hex",
+ "voice_setting": {"voice_id": "custom-voice", "speed": 1.25},
+ "audio_setting": {"format": fmt, "sample_rate": 16000, "channel": 1},
+ "language_boost": "English",
+ }
+ return httpx.Response(200, json=success())
+
+ transport(monkeypatch, handle)
+ assert await MiniMaxTTSAdapter().synthesize(
+ "Hello",
+ config(
+ base_url=base_url,
+ response_format=fmt,
+ sample_rate=16000,
+ speed=1.25,
+ language="English",
+ extra_headers={"X-Request-Source": "test"},
+ ),
+ ) == (b"ID3", mime)
+
+
+ "body",
+ [
+ None,
+ [],
+ {},
+ {"base_resp": None},
+ {"base_resp": {"status_code": 1004, "status_msg": "private-text test-key"}},
+ {"base_resp": {"status_code": 0}, "data": None},
+ {"base_resp": {"status_code": 0}, "data": {"status": 1, "audio": "494433"}},
+ success(None),
+ success(""),
+ success(" "),
+ success("not-hex"),
+ success("123"),
+ ],
+)
+async def test_rejects_failed_partial_empty_and_malformed_responses(monkeypatch, body):
+ transport(monkeypatch, lambda r: httpx.Response(200, text=json.dumps(body)))
+ with pytest.raises(VoiceProviderError) as caught:
+ await MiniMaxTTSAdapter().synthesize("private-text", config())
+ assert "private-text" not in str(caught.value)
+ assert "test-key" not in str(caught.value)
+
+
[email protected]("status,body", [(401, "private-text test-key"), (200, "not-json")])
+async def test_http_and_invalid_json_failures_do_not_echo_body(monkeypatch, status, body):
+ transport(monkeypatch, lambda r: httpx.Response(status, text=body))
+ with pytest.raises(VoiceProviderError) as caught:
+ await MiniMaxTTSAdapter().synthesize("private-text", config())
+ assert body not in str(caught.value)
+
+
+async def test_timeout_is_a_voice_provider_error(monkeypatch):
+ def handle(request):
+ raise httpx.ReadTimeout("private-text", request=request)
+
+ transport(monkeypatch, handle)
+ with pytest.raises(VoiceProviderError, match="timed out"):
+ await MiniMaxTTSAdapter().synthesize("Hello", config())
+
+
+ "overrides",
+ [
+ {"api_key": ""},
+ {"api_key": "***"},
+ {"voice": ""},
+ {"response_format": "aac"},
+ {"sample_rate": 48000},
+ {"speed": 0.25},
+ {"speed": 2.1},
+ {"speed": float("nan")},
+ ],
+)
+async def test_invalid_settings_fail_before_http(monkeypatch, overrides):
+ def handle(request):
+ pytest.fail("Invalid configuration must not issue an HTTP request")
+
+ transport(monkeypatch, handle)
+ with pytest.raises(VoiceProviderError):
+ await MiniMaxTTSAdapter().synthesize("Hello", config(**overrides))
+
+
[email protected]("text", ["", " ", "a" * 10000])
+async def test_invalid_text_fails_before_http(monkeypatch, text):
+ def handle(request):
+ pytest.fail("Invalid text must not issue an HTTP request")
+
+ transport(monkeypatch, handle)
+ with pytest.raises(VoiceProviderError):
+ await MiniMaxTTSAdapter().synthesize(text, config())
+
+
+def catalog():
+ """Use the same provider connection shape as Settings."""
+ return {
+ "version": 1,
+ "connections": [{"id": "speech", "provider": "minimax", "api_key": "test-key"}],
+ "services": {
+ "tts": {
+ "active_profile_id": "p",
+ "active_model_id": "m",
+ "profiles": [
+ {
+ "id": "p",
+ "provider_ref": {"connection_id": "speech", "binding": "minimax"},
+ "models": [{"id": "m", "model": "speech-2.8-hd"}],
+ }
+ ],
+ }
+ },
+ }
+
+
+async def test_catalog_defaults_drive_read_aloud_and_request_overrides(monkeypatch):
+ c = catalog()
+ before = deepcopy(c)
+ resolved = resolve_tts_runtime_config(c)
+ assert resolved.adapter == resolved.provider_name == "minimax"
+ assert resolved.model == TTS_PROVIDERS["minimax"].default_model == "speech-2.8-hd"
+ assert resolved.base_url == "https://api.minimax.io/v1"
+ assert resolved.voice == "English_expressive_narrator"
+ assert resolved.response_format == "mp3"
+
+ def handle(request):
+ body = json.loads(request.content)
+ assert body["text"] == "Hello world"
+ assert body["voice_setting"] == {"voice_id": "custom-voice"}
+ assert body["audio_setting"]["format"] == "wav"
+ assert body["language_boost"] == "auto"
+ return httpx.Response(200, json=success())
+
+ transport(monkeypatch, handle)
+ assert await synthesize_speech(
+ "# Hello **world**",
+ catalog=c,
+ voice="custom-voice",
+ response_format="wav",
+ math_speak=False,
+ ) == (b"ID3", "audio/wav")
+ assert c == before
+
+
+def test_settings_offer_speech_models_and_constrain_unknown_models():
+ options = voice_options("minimax", "tts")
+ assert [model["id"] for model in options["models"]] == [
+ "speech-2.8-hd",
+ "speech-2.8-turbo",
+ "speech-2.6-hd",
+ "speech-2.6-turbo",
+ "speech-02-hd",
+ "speech-02-turbo",
+ "speech-01-hd",
+ "speech-01-turbo",
+ ]
+ assert options["docs_url"] == "https://platform.minimax.io/docs/api-reference/speech-t2a-http"
+ fallback = voice_model_options("minimax", "tts", "private-model")
+ assert fallback["formats"] == ["mp3", "wav", "flac", "pcm"]
+ assert fallback["voices"] == []
+ assert fallback["speed"]["min"] == 0.5
+ assert fallback["speed"]["max"] == 2