"""Tests for the TTS client wrappers (language handling and payloads).""" import io import json import tempfile import time import unittest import wave from contextlib import redirect_stdout from pathlib import Path from unittest.mock import MagicMock, patch from converter import config, tts from converter.converter import AudiobookConverter from converter.tts import ( AudioCppTTSClient, FasterTTSClient, QwenTTSClient, normalize_language, ) class NormalizeLanguageTests(unittest.TestCase): def test_display_names_case_insensitive(self): self.assertEqual(normalize_language("english"), "English") self.assertEqual(normalize_language("ENGLISH"), "English") self.assertEqual(normalize_language(" Japanese "), "Japanese") def test_auto_accepted(self): self.assertEqual(normalize_language("auto"), "Auto") self.assertEqual(normalize_language("Auto"), "Auto") def test_iso_aliases(self): self.assertEqual(normalize_language("en"), "English") self.assertEqual(normalize_language("ja"), "Japanese") self.assertEqual(normalize_language("zh"), "Chinese") self.assertEqual(normalize_language("ko"), "Korean") self.assertEqual(normalize_language("de"), "German") self.assertEqual(normalize_language("fr"), "French") self.assertEqual(normalize_language("ru"), "Russian") self.assertEqual(normalize_language("pt"), "Portuguese") self.assertEqual(normalize_language("es"), "Spanish") self.assertEqual(normalize_language("it"), "Italian") def test_all_supported_languages_round_trip(self): for name in tts.TTS_LANGUAGES: self.assertEqual(normalize_language(name.lower()), name) def test_unknown_language_rejected_with_guidance(self): with self.assertRaises(ValueError) as ctx: normalize_language("klingon") message = str(ctx.exception) self.assertIn("klingon", message) self.assertIn("English", message) def test_none_and_empty_rejected(self): with self.assertRaises(ValueError): normalize_language(None) with self.assertRaises(ValueError): normalize_language(" ") class QwenTTSClientLanguageTests(unittest.TestCase): """Language validation and defaults, without touching the network.""" def _make_client(self, **kwargs): with patch.object(QwenTTSClient, "_connect"): return QwenTTSClient(**kwargs) def test_default_follows_config_for_each_mode(self): custom = self._make_client(voice_mode=tts.VOICE_MODE_CUSTOM) self.assertEqual(custom.language, config.LANGUAGE) clone = self._make_client(voice_mode=tts.VOICE_MODE_CLONE, voice_clone_ref_audio="ref.wav") self.assertEqual(clone.language, config.LANGUAGE) def test_explicit_language_normalized(self): client = self._make_client(voice_mode=tts.VOICE_MODE_CUSTOM, language="ja") self.assertEqual(client.language, "Japanese") def test_invalid_language_fails_before_connect(self): with patch.object(QwenTTSClient, "_connect") as mock_connect: with self.assertRaises(ValueError): QwenTTSClient(language="klingon") mock_connect.assert_not_called() def test_api_url_override_stored(self): client = self._make_client(voice_mode=tts.VOICE_MODE_CUSTOM, api_url="http://10.0.0.5:7860") self.assertEqual(client.api_url, "http://10.0.0.5:7860") def test_api_url_override_used_by_connect(self): with patch.object(QwenTTSClient, "_init_client") as mk_init: client = QwenTTSClient.__new__(QwenTTSClient) client.voice_mode = tts.VOICE_MODE_CUSTOM client.api_url = "http://10.0.0.5:7860" client._connect() mk_init.assert_called_once_with("http://10.0.0.5:7860", clone=False) class SeedResolutionTests(unittest.TestCase): """CONSTANT_SEED: one seed per run, reused for every request, so the voice stays consistent across chunk boundaries (the servers re-sample the voice when the seed changes between generations).""" def _make_client(self, **kwargs): with patch.object(QwenTTSClient, "_connect"): return QwenTTSClient(**kwargs) def test_constant_seed_draws_one_nonnegative_seed(self): with patch.object(config, "CONSTANT_SEED", True), \ patch.object(config, "SEED", -1): client = self._make_client(voice_mode=tts.VOICE_MODE_CUSTOM) self.assertGreaterEqual(client._seed, 0) def test_explicit_seed_wins_over_constant_seed(self): with patch.object(config, "CONSTANT_SEED", True), \ patch.object(config, "SEED", 42): client = self._make_client(voice_mode=tts.VOICE_MODE_CUSTOM) self.assertEqual(client._seed, 42) def test_without_constant_seed_minus_one_is_forwarded(self): with patch.object(config, "CONSTANT_SEED", False), \ patch.object(config, "SEED", -1): client = self._make_client(voice_mode=tts.VOICE_MODE_CUSTOM) self.assertEqual(client._seed, -1) def test_resolved_seed_is_reused_across_requests(self): api_info = { "named_endpoints": { "/run_custom_voice": { "parameters": [{"parameter_name": "seed"}] } } } client = QwenTTSClient.__new__(QwenTTSClient) client.voice_mode = tts.VOICE_MODE_CUSTOM client.language = "English" client._seed = 1234 client.api_info = api_info client.client = MagicMock() client._generate_custom_voice("first text") client._generate_custom_voice("second text") seeds = [call.kwargs["seed"] for call in client.client.predict.call_args_list] self.assertEqual(seeds, [1234, 1234]) class PayloadLanguageTests(unittest.TestCase): """The language must reach the API payload in every endpoint variant.""" def setUp(self): self._tmp = tempfile.TemporaryDirectory() self.ref_audio = Path(self._tmp.name) / "reference.wav" self.ref_audio.write_bytes(b"x") def tearDown(self): self._tmp.cleanup() def _custom_client(self, language, endpoint, api_info=None): client = QwenTTSClient.__new__(QwenTTSClient) client.voice_mode = tts.VOICE_MODE_CUSTOM client.language = language client._seed = config.SEED client.api_info = api_info if api_info is not None else { "named_endpoints": {endpoint: {}} } client.client = MagicMock() return client def _clone_client(self, language, endpoint, api_info=None, ref_text="hello"): client = QwenTTSClient.__new__(QwenTTSClient) client.voice_mode = tts.VOICE_MODE_CLONE client.language = language client._seed = config.SEED client.voice_clone_ref_audio = str(self.ref_audio) client.voice_clone_ref_text = ref_text client.clone_api_info = api_info if api_info is not None else { "named_endpoints": {endpoint: {}} } client.clone_client = MagicMock() client._ref_audio_filedata = {"dummy": "payload"} return client def test_custom_voice_run_instruct_uses_language(self): client = self._custom_client("Japanese", "/run_instruct") client._generate_custom_voice("text") kwargs = client.client.predict.call_args.kwargs self.assertEqual(kwargs["lang_disp"], "Japanese") def test_custom_voice_alt_endpoint_uses_language(self): client = self._custom_client("French", "/run_custom_voice") client._generate_custom_voice("text") kwargs = client.client.predict.call_args.kwargs self.assertEqual(kwargs["language"], "French") def test_voice_clone_run_voice_clone_uses_language(self): client = self._clone_client("Japanese", "/run_voice_clone") client._generate_voice_clone("text") kwargs = client.clone_client.predict.call_args.kwargs self.assertEqual(kwargs["lang_disp"], "Japanese") def test_voice_clone_alt_endpoint_uses_language(self): client = self._clone_client("Korean", "/generate_voice_clone") client._generate_voice_clone("text") kwargs = client.clone_client.predict.call_args.kwargs self.assertEqual(kwargs["language"], "Korean") def test_voice_clone_alt_endpoint_includes_optional_params(self): api_info = { "named_endpoints": { "/generate_voice_clone": { "parameters": [ {"parameter_name": "model_size"}, {"parameter_name": "seed"}, ] } } } client = self._clone_client("English", "/generate_voice_clone", api_info=api_info) client._generate_voice_clone("text") kwargs = client.clone_client.predict.call_args.kwargs self.assertEqual(kwargs["model_size"], tts.MODEL_SIZE) self.assertEqual(kwargs["seed"], config.SEED) class FasterTTSClientHealthTests(unittest.TestCase): """Connection behavior of the faster-qwen3-tts client.""" def _health_response(self, model_loaded=True): response = MagicMock() response.__enter__.return_value = response response.read.return_value = json.dumps( {"status": "ok", "model_loaded": model_loaded}).encode("utf-8") return response def test_unreachable_server_raises_with_readme_pointer(self): import urllib.error with patch("converter.tts.urllib.request.urlopen", side_effect=urllib.error.URLError("Connection refused")): with self.assertRaises(RuntimeError) as ctx: FasterTTSClient() message = str(ctx.exception) self.assertIn("not reachable", message) self.assertIn("README", message) def test_model_not_loaded_raises(self): with patch("converter.tts.urllib.request.urlopen", return_value=self._health_response(model_loaded=False)): with self.assertRaises(RuntimeError) as ctx: FasterTTSClient() self.assertIn("not loaded", str(ctx.exception)) def test_healthy_server_defaults_from_config(self): with patch("converter.tts.urllib.request.urlopen", return_value=self._health_response()): client = FasterTTSClient() self.assertEqual(client.voice, config.FASTER_VOICE) self.assertEqual(client.api_url, config.FASTER_API_URL.rstrip("/")) def test_explicit_voice_and_url_override_config(self): with patch("converter.tts.urllib.request.urlopen", return_value=self._health_response()): client = FasterTTSClient(voice="narrator", api_url="http://10.0.0.5:9000/") self.assertEqual(client.voice, "narrator") self.assertEqual(client.api_url, "http://10.0.0.5:9000") class FasterTTSClientGenerateTests(unittest.TestCase): """Chunk generation: sub-chunking, WAV output, retries, bookkeeping.""" def setUp(self): self._tmp = tempfile.TemporaryDirectory() self._chunks = patch.object(tts, "CHUNKS_FOLDER", Path(self._tmp.name)) self._chunks.start() self._sleep = patch("converter.tts.time.sleep") self._sleep.start() def tearDown(self): self._sleep.stop() self._chunks.stop() self._tmp.cleanup() def _make_client(self): client = FasterTTSClient.__new__(FasterTTSClient) client.voice = "default" client.api_url = "http://127.0.0.1:8000" return client def _read_wav(self, path): with wave.open(str(path), "rb") as wav_file: return (wav_file.getnchannels(), wav_file.getsampwidth(), wav_file.getframerate(), wav_file.readframes(wav_file.getnframes())) def test_generate_chunk_writes_valid_wav(self): client = self._make_client() pcm = b"\x01\x00" * 100 with patch.object(client, "_request_pcm", return_value=pcm): result = client.generate_chunk("Hello world.", 1) self.assertIsNotNone(result) path = Path(result) self.assertEqual(path.name, "chunk_0001.wav") channels, sampwidth, framerate, frames = self._read_wav(path) self.assertEqual(channels, 1) self.assertEqual(sampwidth, 2) self.assertEqual(framerate, tts.SAMPLE_RATE) self.assertEqual(frames, pcm) def test_long_text_is_subchunked_and_concatenated_in_order(self): client = self._make_client() sentences = [" ".join(f"word{i}" for i in range(6)) + "." for _ in range(3)] text = " ".join(sentences) pcm_parts = [b"\x01\x00" * 10, b"\x02\x00" * 20, b"\x03\x00" * 30] with patch.object(config, "CHUNK_SIZE", 10), \ patch.object(client, "_request_pcm", side_effect=pcm_parts) as mock_pcm: result = client.generate_chunk(text, 1) self.assertEqual(mock_pcm.call_count, 3) _, _, _, frames = self._read_wav(Path(result)) self.assertEqual(frames, b"".join(pcm_parts)) def test_subchunk_size_follows_config_chunk_size(self): client = self._make_client() text = " ".join(f"word{i}" for i in range(8)) pcm = b"\x01\x00" * 10 with patch.object(config, "CHUNK_SIZE", 4), \ patch.object(client, "_request_pcm", return_value=pcm) as mock_pcm: result = client.generate_chunk(text, 1) # The sub-chunk split follows config.CHUNK_SIZE, so the whole # (8-word) text needs two 4-word requests here. self.assertEqual(mock_pcm.call_count, 2) self.assertIsNotNone(result) def test_stale_chunk_files_are_removed(self): stale = Path(self._tmp.name) / "chunk_0001.mp3" stale.write_bytes(b"old") client = self._make_client() with patch.object(client, "_request_pcm", return_value=b"\x01\x00"): client.generate_chunk("Hello.", 1) remaining = sorted(path.name for path in Path(self._tmp.name).glob("chunk_0001.*")) self.assertEqual(remaining, ["chunk_0001.wav"]) def test_transient_failure_is_retried(self): client = self._make_client() pcm = b"\x01\x00" * 10 with patch.object(client, "_request_pcm", side_effect=[RuntimeError("boom"), pcm]) as mock_pcm: result = client.generate_chunk("Hello.", 1) self.assertIsNotNone(result) self.assertEqual(mock_pcm.call_count, 2) def test_empty_pcm_response_is_treated_as_failure(self): client = self._make_client() pcm = b"\x01\x00" * 10 def _response(body): response = MagicMock() response.__enter__.return_value = response response.read.return_value = body return response with patch("converter.tts.urllib.request.urlopen", side_effect=[_response(b""), _response(pcm)]) as mock_urlopen: result = client.generate_chunk("Hello.", 1) self.assertIsNotNone(result) self.assertEqual(mock_urlopen.call_count, 2) _, _, _, frames = self._read_wav(Path(result)) self.assertEqual(frames, pcm) def test_exhausted_subchunk_retries_fail_the_chunk(self): client = self._make_client() with patch.object(client, "_request_pcm", side_effect=RuntimeError("down")) as mock_pcm: result = client.generate_chunk("Hello.", 1) self.assertIsNone(result) self.assertEqual(mock_pcm.call_count, config.MAX_RETRIES) def test_empty_text_fails_the_chunk(self): client = self._make_client() with patch.object(client, "_request_pcm") as mock_pcm: result = client.generate_chunk(" ", 1) self.assertIsNone(result) mock_pcm.assert_not_called() def test_request_payload_includes_voice_text_and_format(self): client = self._make_client() response = MagicMock() response.__enter__.return_value = response response.read.return_value = b"\x01\x00" * 10 with patch("converter.tts.urllib.request.urlopen", return_value=response) as mock_urlopen: pcm = client._request_pcm("Hello world.") self.assertEqual(pcm, b"\x01\x00" * 10) request = mock_urlopen.call_args[0][0] self.assertEqual(request.full_url, "http://127.0.0.1:8000/v1/audio/speech") payload = json.loads(request.data.decode("utf-8")) self.assertEqual(payload["input"], "Hello world.") self.assertEqual(payload["voice"], "default") self.assertEqual(payload["response_format"], "pcm") def test_full_length_pcm_passes(self): client = self._make_client() text = " ".join(f"word{i}" for i in range(12)) # 12 words -> expected 4.8s, half is 2.4s -> 2.5s of audio passes. pcm = b"\x01\x00" * int(2.5 * tts.SAMPLE_RATE) with patch.object(client, "_request_pcm", return_value=pcm): result = client.generate_chunk(text, 1) self.assertIsNotNone(result) class QwenTTSClientGenerateTests(unittest.TestCase): """Qwen chunk generation: sub-request splitting and concatenation.""" def setUp(self): self._tmp = tempfile.TemporaryDirectory() self._chunks = patch.object(tts, "CHUNKS_FOLDER", Path(self._tmp.name)) self._chunks.start() def tearDown(self): self._chunks.stop() self._tmp.cleanup() def _make_client(self): client = QwenTTSClient.__new__(QwenTTSClient) client.voice_mode = tts.VOICE_MODE_CUSTOM return client @staticmethod def _write_wav(path: Path, frames: bytes) -> Path: with wave.open(str(path), "wb") as wav_file: wav_file.setnchannels(1) wav_file.setsampwidth(2) wav_file.setframerate(tts.SAMPLE_RATE) wav_file.writeframes(frames) return path def _read_wav_frames(self, path: Path) -> bytes: with wave.open(str(path), "rb") as wav_file: return wav_file.readframes(wav_file.getnframes()) def test_single_request_copies_audio(self): client = self._make_client() source = self._write_wav(Path(self._tmp.name) / "server.wav", b"\x01\x00" * 50) with patch.object(client, "_generate_custom_voice", return_value=(str(source),)) as mock_generate: result = client.generate_chunk("Hello world.", 1) mock_generate.assert_called_once_with("Hello world.") path = Path(result) self.assertEqual(path.name, "chunk_0001.wav") self.assertEqual(self._read_wav_frames(path), b"\x01\x00" * 50) def test_oversized_input_is_split_and_concatenated_in_order(self): client = self._make_client() first = self._write_wav(Path(self._tmp.name) / "one.wav", b"\x01\x00" * 10) second = self._write_wav(Path(self._tmp.name) / "two.wav", b"\x02\x00" * 20) text = " ".join(f"word{i}" for i in range(12)) with patch.object(config, "CHUNK_SIZE", 5), \ patch.object(client, "_generate_custom_voice", side_effect=[(str(first),), (str(second),), (str(first),)]) as mock_generate: result = client.generate_chunk(text, 1) self.assertEqual(mock_generate.call_count, 3) path = Path(result) self.assertEqual(path.name, "chunk_0001.wav") self.assertEqual(self._read_wav_frames(path), b"\x01\x00" * 10 + b"\x02\x00" * 20 + b"\x01\x00" * 10) for call in mock_generate.call_args_list: self.assertLessEqual(len(call[0][0].split()), 5) def test_empty_text_fails_the_chunk(self): client = self._make_client() with patch.object(client, "_generate_custom_voice") as mock_generate: result = client.generate_chunk(" ", 1) self.assertIsNone(result) mock_generate.assert_not_called() class AudioCppTTSClientHealthTests(unittest.TestCase): """Connection behavior of the audio.cpp client.""" def setUp(self): # The default AUDIOCPP_MODEL_ID is empty (auto-select); these tests # exercise a configured single-model CustomVoice server, so pin a # concrete id whose "customvoice" substring marks it speaker-capable. patcher = patch.object( config, "AUDIOCPP_MODEL_ID", "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF") patcher.start() self.addCleanup(patcher.stop) @staticmethod def _json_response(payload): response = MagicMock() response.__enter__.return_value = response response.read.return_value = json.dumps(payload).encode("utf-8") return response def _get_responses(self, health=None, models=None, voices=None): """Side effect dispatching GET responses by URL.""" def _dispatch(request, **_kwargs): url = request if isinstance(request, str) else request.full_url if url.endswith("/health"): return self._json_response(health if health is not None else {"status": "ok"}) if url.endswith("/v1/models"): return self._json_response(models if models is not None else {"data": [{"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts"}]}) if "/v1/audio/voices" in url: if voices is Exception: raise Exception("voices endpoint down") return self._json_response(voices if voices is not None else {"voices": ["narrator"]}) raise AssertionError(f"unexpected URL: {url}") return _dispatch def _client(self, voice=None, language=None, model_id=None, **kwargs): with patch("converter.tts.urllib.request.urlopen", side_effect=self._get_responses(**kwargs)): return AudioCppTTSClient(voice=voice, language=language, model_id=model_id) def test_unreachable_server_raises_with_readme_pointer(self): import urllib.error with patch("converter.tts.urllib.request.urlopen", side_effect=urllib.error.URLError("Connection refused")): with self.assertRaises(RuntimeError) as ctx: AudioCppTTSClient() message = str(ctx.exception) self.assertIn("not reachable", message) self.assertIn("README", message) def test_unhealthy_status_raises(self): with self.assertRaises(RuntimeError) as ctx: self._client(health={"status": "starting"}) self.assertIn("starting", str(ctx.exception)) def test_unknown_model_id_raises_with_configured_ids(self): with self.assertRaises(RuntimeError) as ctx: self._client(models={"data": [{"id": "pocket-tts"}, {"id": "other"}]}) message = str(ctx.exception) self.assertIn(config.AUDIOCPP_MODEL_ID, message) self.assertIn("pocket-tts", message) self.assertIn("other", message) def test_healthy_server_speaker_mode_defaults(self): client = self._client() self.assertEqual(client.api_url, config.AUDIOCPP_API_URL.rstrip("/")) self.assertEqual(client.model_id, config.AUDIOCPP_MODEL_ID) self.assertEqual(client.language, config.LANGUAGE) self.assertEqual(client.voice, "Vivian") self.assertFalse(client.preset_mode) self.assertTrue(client.speaker_mode) def test_speaker_mode_uses_configured_speaker(self): with patch.object(config, "SPEAKER", "uncle_fu"): client = self._client() self.assertEqual(client.voice, "Uncle Fu") self.assertTrue(client.speaker_mode) def test_voice_speaker_name_selects_speaker_mode(self): # --voice naming a built-in CustomVoice speaker selects speaker # mode; the name is normalized to its wire (display) form and no # preset validation runs. client = self._client(voice="Uncle_Fu") self.assertEqual(client.voice, "Uncle Fu") self.assertFalse(client.preset_mode) self.assertTrue(client.speaker_mode) def test_voice_speaker_name_on_clone_entry_is_a_preset(self): # --voice on a clone-only (Base) entry is a server-side preset, # not a built-in speaker, so the name is validated against the # server's voice library. with self.assertRaises(RuntimeError) as ctx: self._client(voice="Ryan", model_id="Qwen3-TTS-12Hz-1.7B-Base-GGUF", models={"data": [ {"id": "Qwen3-TTS-12Hz-1.7B-Base-GGUF", "family": "qwen3_tts"}]}) message = str(ctx.exception) self.assertIn("'Ryan'", message) self.assertIn("--voice", message) def test_voice_speaker_name_does_not_reroute_to_clone_model(self): # A built-in speaker name on a CustomVoice primary selects speaker # mode without the AUDIOCPP_CLONE_MODEL_ID reroute. with patch.object(config, "AUDIOCPP_MODEL_ID", "Qwen3-TTS-CustomVoice"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"): client = self._client( voice="Ryan", models={"data": [{"id": "Qwen3-TTS-CustomVoice", "family": "qwen3_tts"}, {"id": "qwen3-tts-clone", "family": "qwen3_tts"}]}) self.assertEqual(client.model_id, "Qwen3-TTS-CustomVoice") self.assertTrue(client.speaker_mode) self.assertFalse(client.preset_mode) def test_no_voice_on_base_entry_raises_instead_of_silent_speaker(self): # The Base model has no built-in speakers: without --voice the run # fails fast instead of silently sending a speaker name that the # model ignores. with self.assertRaises(RuntimeError) as ctx: self._client(model_id="Qwen3-TTS-12Hz-1.7B-Base-GGUF", models={"data": [ {"id": "Qwen3-TTS-12Hz-1.7B-Base-GGUF", "family": "qwen3_tts"}]}) message = str(ctx.exception) self.assertIn("Base-GGUF", message) self.assertIn("--voice", message) def test_preset_mode_uses_requested_voice(self): client = self._client(voice="narrator") self.assertEqual(client.voice, "narrator") self.assertTrue(client.preset_mode) def test_preset_mode_validates_voice_against_server_list(self): with self.assertRaises(RuntimeError) as ctx: self._client(voice="ghost", voices={"voices": ["narrator", "obama"]}) message = str(ctx.exception) self.assertIn("ghost", message) self.assertIn("narrator", message) self.assertIn("obama", message) def test_preset_mode_skips_validation_when_voices_endpoint_fails(self): client = self._client(voice="narrator", voices=Exception) self.assertEqual(client.voice, "narrator") def test_invalid_language_fails_before_connect(self): with patch("converter.tts.urllib.request.urlopen") as mock_urlopen: with self.assertRaises(ValueError): AudioCppTTSClient(language="klingon") mock_urlopen.assert_not_called() def test_explicit_language_normalized(self): client = self._client(language="ja") self.assertEqual(client.language, "Japanese") def test_seed_resolved_once_per_run(self): with patch.object(config, "CONSTANT_SEED", True), \ patch.object(config, "SEED", -1): client = self._client() self.assertGreaterEqual(client._seed, 0) def test_preset_mode_routes_to_clone_model_when_configured(self): with patch.object(config, "AUDIOCPP_MODEL_ID", "qwen3-tts"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"): client = self._client( voice="narrator", models={"data": [{"id": "qwen3-tts"}, {"id": "qwen3-tts-clone"}]}) self.assertEqual(client.model_id, "qwen3-tts-clone") def test_preset_mode_falls_back_when_clone_model_not_on_server(self): with patch.object(config, "AUDIOCPP_MODEL_ID", "qwen3-tts"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"), \ self.assertLogs("converter.tts", level="WARNING") as logs: client = self._client( voice="narrator", models={"data": [{"id": "qwen3-tts", "family": "qwen3_tts"}, {"id": "pocket-tts"}]}) self.assertEqual(client.model_id, "qwen3-tts") self.assertTrue(any("qwen3-tts-clone" in line for line in logs.output)) def test_empty_model_id_auto_picks_single_server_entry(self): # A multi-model server used without editing config.py: an empty # --model resolves to the only hosted entry automatically. client = self._client( voice="narrator", model_id="", models={"data": [{"id": "higgs", "family": "higgs_audio_tts"}]}, voices={"voices": ["narrator"]}) self.assertEqual(client.model_id, "higgs") def test_empty_model_id_with_multiple_entries_requires_explicit_choice(self): with self.assertRaises(RuntimeError) as ctx: self._client( voice="narrator", model_id="", models={"data": [{"id": "higgs"}, {"id": "voxcpm2"}]}, voices={"voices": ["narrator"]}) message = str(ctx.exception) self.assertIn("--model", message) self.assertIn("higgs", message) self.assertIn("voxcpm2", message) def test_model_id_override_reaches_request(self): # --model overrides AUDIOCPP_MODEL_ID for the run. with patch.object(config, "AUDIOCPP_MODEL_ID", "qwen"): client = self._client( voice="narrator", model_id="higgs", models={"data": [{"id": "higgs", "family": "higgs_audio_tts"}]}, voices={"voices": ["narrator"]}) self.assertEqual(client.model_id, "higgs") def test_clone_model_id_ignored_for_speaker_mode(self): # Speaker mode (no --voice on a CustomVoice entry) never reroutes to # AUDIOCPP_CLONE_MODEL_ID — that reroute is a preset-mode concern. with patch.object(config, "AUDIOCPP_MODEL_ID", "Qwen3-TTS-CustomVoice"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"): client = self._client( models={"data": [{"id": "Qwen3-TTS-CustomVoice", "family": "qwen3_tts"}, {"id": "qwen3-tts-clone", "family": "qwen3_tts"}]}) self.assertEqual(client.model_id, "Qwen3-TTS-CustomVoice") def test_clone_model_id_equal_to_primary_is_noop(self): with patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", config.AUDIOCPP_MODEL_ID): client = self._client(voice="narrator") self.assertEqual(client.model_id, config.AUDIOCPP_MODEL_ID) def test_preset_mode_with_clone_only_server_uses_clone_model(self): with patch.object(config, "AUDIOCPP_MODEL_ID", "qwen3-tts"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"): client = self._client( voice="narrator", models={"data": [{"id": "qwen3-tts-clone"}]}) self.assertEqual(client.model_id, "qwen3-tts-clone") def test_speaker_mode_with_clone_only_server_suggests_voice(self): with patch.object(config, "AUDIOCPP_MODEL_ID", "qwen3-tts"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"): with self.assertRaises(RuntimeError) as ctx: self._client(models={"data": [{"id": "qwen3-tts-clone"}]}) message = str(ctx.exception) self.assertIn("qwen3-tts", message) self.assertIn("--voice", message) def test_preset_mode_with_no_matching_model_lists_both_ids(self): # Neither the primary nor the clone id is on the server, so the # family is unknown and no degradation warning is logged — the # requirement error lists both configured ids instead. with patch.object(config, "AUDIOCPP_MODEL_ID", "qwen3-tts"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"), \ self.assertNoLogs("converter.tts", level="WARNING"): with self.assertRaises(RuntimeError) as ctx: self._client(voice="narrator", models={"data": [{"id": "pocket-tts"}]}) message = str(ctx.exception) self.assertIn("qwen3-tts", message) self.assertIn("qwen3-tts-clone", message) self.assertIn("pocket-tts", message) class AudioCppTaskDetectionTests(unittest.TestCase): """Task auto-detection (tts/clon/vdes) and voice design validation.""" def setUp(self): # Pin a CustomVoice id so the default (no-voice) path is speaker # mode; individual tests override family/task to exercise other paths. patcher = patch.object( config, "AUDIOCPP_MODEL_ID", "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF") patcher.start() self.addCleanup(patcher.stop) @staticmethod def _json_response(payload): response = MagicMock() response.__enter__.return_value = response response.read.return_value = json.dumps(payload).encode("utf-8") return response def _client(self, voice=None, instructions=None, request_options=None, models=None): if models is None: models = {"data": [{"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts"}]} def _dispatch(request, **_kwargs): url = request if isinstance(request, str) else request.full_url if url.endswith("/health"): return self._json_response({"status": "ok"}) if url.endswith("/v1/models"): return self._json_response(models) if "/v1/audio/voices" in url: return self._json_response({"voices": ["narrator"]}) raise AssertionError(f"unexpected URL: {url}") with patch("converter.tts.urllib.request.urlopen", side_effect=_dispatch): return AudioCppTTSClient(voice=voice, instructions=instructions, request_options=request_options) def test_missing_task_falls_back_to_tts(self): # Servers that predate the task field hosted plain TTS models. client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts"}]}) self.assertEqual(client.task, tts.AUDIOCPP_TASK_TTS) self.assertFalse(client.design_mode) def test_task_detected_from_models_endpoint(self): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts", "task": "vdes"}]}, instructions="A warm adult narrator") self.assertEqual(client.task, tts.AUDIOCPP_TASK_VDES) self.assertTrue(client.design_mode) def test_clon_task_entry_connects_in_preset_mode(self): client = self._client(voice="narrator", models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "chatterbox", "task": "clon"}]}) self.assertEqual(client.task, "clon") self.assertFalse(client.design_mode) self.assertTrue(client.preset_mode) def test_unsupported_task_rejected_with_available_entries(self): with self.assertRaises(RuntimeError) as ctx: self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_asr", "task": "asr"}, {"id": "tts-1", "family": "qwen3_tts", "task": "tts"}]}, instructions="unused") message = str(ctx.exception) self.assertIn("'asr'", message) self.assertIn("--model", message) self.assertIn("tts-1", message) def test_vdes_without_instructions_requires_description(self): with self.assertRaises(RuntimeError) as ctx: self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts", "task": "vdes"}]}) message = str(ctx.exception) self.assertIn("voice design", message) self.assertIn("--instructions", message) def test_vdes_with_voice_rejected(self): with self.assertRaises(RuntimeError) as ctx: self._client(voice="narrator", models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts", "task": "vdes"}]}, instructions="A warm adult narrator") self.assertIn("--voice", str(ctx.exception)) self.assertIn("--instructions", str(ctx.exception)) def test_vdes_with_instructions_connects_in_design_mode(self): buf = io.StringIO() with redirect_stdout(buf): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts", "task": "vdes"}]}, instructions="A warm adult narrator") self.assertTrue(client.design_mode) self.assertEqual(client.instructions, "A warm adult narrator") out = buf.getvalue() self.assertIn("voice design", out) self.assertIn("A warm adult narrator", out) def test_instructions_without_voice_on_generic_family_connects(self): # Families without built-in speakers can get their voice from the # instruction alone (e.g. OmniVoice voice design). buf = io.StringIO() with redirect_stdout(buf): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "omnivoice", "task": "tts"}]}, instructions="female, young adult, moderate pitch") self.assertFalse(client.design_mode) self.assertTrue(client.instruction_voice) self.assertIn("instruction voice", buf.getvalue()) def test_instructions_with_builtin_speaker_family_stays_speaker_mode(self): buf = io.StringIO() with redirect_stdout(buf): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts", "task": "tts"}]}, instructions="Very happy.") self.assertFalse(client.design_mode) self.assertFalse(client.instruction_voice) self.assertIn("speaker 'Vivian'", buf.getvalue()) def test_config_instructions_used_when_flag_omitted(self): with patch.object(config, "AUDIOCPP_INSTRUCTIONS", "A calm elderly storyteller"): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts", "task": "vdes"}]}) self.assertEqual(client.instructions, "A calm elderly storyteller") def test_explicit_instructions_override_config_default(self): with patch.object(config, "AUDIOCPP_INSTRUCTIONS", "from config"): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "qwen3_tts", "task": "vdes"}]}, instructions="from flag") self.assertEqual(client.instructions, "from flag") class AudioCppFamilyDetectionTests(unittest.TestCase): """Family auto-detection and per-family adaptations.""" def setUp(self): patcher = patch.object(config, "AUDIOCPP_MODEL_ID", "qwen") patcher.start() self.addCleanup(patcher.stop) @staticmethod def _json_response(payload): response = MagicMock() response.__enter__.return_value = response response.read.return_value = json.dumps(payload).encode("utf-8") return response def _client(self, voice="narrator", models=None): def _dispatch(request, **_kwargs): url = request if isinstance(request, str) else request.full_url if url.endswith("/health"): return self._json_response({"status": "ok"}) if url.endswith("/v1/models"): return self._json_response(models) if "/v1/audio/voices" in url: return self._json_response({"voices": [voice] if voice else []}) raise AssertionError(f"unexpected URL: {url}") with patch("converter.tts.urllib.request.urlopen", side_effect=_dispatch): return AudioCppTTSClient(voice=voice) def test_family_detected_from_models_endpoint(self): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "higgs_audio_tts"}]}) self.assertEqual(client.family, "higgs_audio_tts") self.assertIs(client.profile, tts.AUDIOCPP_DEFAULT_FAMILY_PROFILE) def test_missing_family_uses_generic_profile(self): # A missing family is unknown (not guessed as qwen3_tts): it falls # through to the generic clone-only profile. client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID}]}) self.assertEqual(client.family, "") self.assertIs(client.profile, tts.AUDIOCPP_DEFAULT_FAMILY_PROFILE) def test_unknown_family_uses_generic_profile(self): client = self._client(models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "future_tts"}]}) self.assertEqual(client.family, "future_tts") self.assertIs(client.profile, tts.AUDIOCPP_DEFAULT_FAMILY_PROFILE) self.assertEqual(client.profile.language_style, tts.AUDIOCPP_LANG_OMIT) def test_speaker_mode_rejected_for_clone_only_family(self): client = None try: client = self._client(voice=None, models={"data": [ {"id": config.AUDIOCPP_MODEL_ID, "family": "voxcpm2"}]}) except RuntimeError as exc: message = str(exc) self.assertIn("voxcpm2", message) self.assertIn("--voice", message) self.assertIn("no built-in speakers", message) self.assertIsNone(client) def test_speaker_mode_allowed_for_customvoice_entry(self): # A Qwen3-TTS entry whose id names CustomVoice is speaker-capable; # no --voice is needed. with patch.object(config, "AUDIOCPP_MODEL_ID", "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF"): client = self._client(voice=None, models={"data": [ {"id": "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF", "family": "qwen3_tts"}]}) self.assertEqual(client.family, "qwen3_tts") def test_speaker_mode_rejected_for_qwen_base_entry(self): # A Qwen3-TTS entry whose id names Base (not CustomVoice) is # clone-only, even though its family has built-in speakers on other # entries: without --voice it fails fast. client = None try: client = self._client(voice=None, models={"data": [ {"id": "Qwen3-TTS-12Hz-1.7B-Base-GGUF", "family": "qwen3_tts"}]}) except RuntimeError as exc: message = str(exc) self.assertIn("Base-GGUF", message) self.assertIn("--voice", message) self.assertIsNone(client) def test_clone_model_id_of_different_family_is_ignored(self): with patch.object(config, "AUDIOCPP_MODEL_ID", "higgs"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen-clone"), \ self.assertLogs("converter.tts", level="WARNING") as logs: client = self._client(models={"data": [ {"id": "higgs", "family": "higgs_audio_tts"}, {"id": "qwen-clone", "family": "qwen3_tts"}]}) self.assertEqual(client.model_id, "higgs") self.assertTrue(any("different family" in line.lower() or "hosts family" in line.lower() for line in logs.output)) def test_clone_model_id_missing_on_non_qwen_server_is_debug_only(self): with patch.object(config, "AUDIOCPP_MODEL_ID", "higgs"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen-clone"), \ self.assertNoLogs("converter.tts", level="WARNING"): client = self._client(models={"data": [ {"id": "higgs", "family": "higgs_audio_tts"}]}) self.assertEqual(client.model_id, "higgs") def test_clone_model_id_missing_on_qwen_server_still_warns(self): with patch.object(config, "AUDIOCPP_MODEL_ID", "qwen3-tts"), \ patch.object(config, "AUDIOCPP_CLONE_MODEL_ID", "qwen3-tts-clone"), \ self.assertLogs("converter.tts", level="WARNING") as logs: client = self._client(models={"data": [ {"id": "qwen3-tts", "family": "qwen3_tts"}, {"id": "pocket-tts", "family": "pocket_tts"}]}) self.assertEqual(client.model_id, "qwen3-tts") self.assertTrue(any("qwen3-tts-clone" in line for line in logs.output)) def test_iso_language_code_helper(self): self.assertEqual(tts.LANGUAGE_ISO_CODES["English"], "en") self.assertIsNone(tts.LANGUAGE_ISO_CODES.get("Auto")) class AudiocppEntryVoiceCapabilityTests(unittest.TestCase): """The per-entry voice capability resolver (speaker/clone/design).""" def _cap(self, family="", task="tts", model_id=""): return tts.audiocpp_entry_voice_capability(family, task, model_id) def test_vdes_task_is_design(self): self.assertEqual(self._cap("qwen3_tts", "vdes", "Qwen3-TTS-VoiceDesign-GGUF"), tts.AUDIOCPP_VOICE_DESIGN) def test_qwen_customvoice_entry_is_speaker(self): self.assertEqual(self._cap("qwen3_tts", "tts", "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF"), tts.AUDIOCPP_VOICE_SPEAKER) def test_qwen_base_entry_is_clone(self): self.assertEqual(self._cap("qwen3_tts", "tts", "Qwen3-TTS-12Hz-1.7B-Base-GGUF"), tts.AUDIOCPP_VOICE_CLONE) def test_qwen_unidentified_entry_is_clone(self): self.assertEqual(self._cap("qwen3_tts", "tts", "qwen"), tts.AUDIOCPP_VOICE_CLONE) def test_other_families_are_clone(self): self.assertEqual(self._cap("higgs_audio_tts", "tts", "higgs"), tts.AUDIOCPP_VOICE_CLONE) def test_missing_family_is_clone(self): self.assertEqual(self._cap("", "tts", "legacy"), tts.AUDIOCPP_VOICE_CLONE) def test_customvoice_match_is_case_insensitive(self): self.assertEqual(self._cap("qwen3_tts", "tts", "Qwen3-TTS-12Hz-1.7B-CUSTOMVOICE-GGUF"), tts.AUDIOCPP_VOICE_SPEAKER) def test_customvoice_id_in_other_family_is_not_speaker(self): # The "customvoice" substring only marks a speaker for the qwen3_tts # family; another family with a lookalike id stays clone-only. self.assertEqual(self._cap("future_tts", "tts", "Qwen3-TTS-CustomVoice"), tts.AUDIOCPP_VOICE_CLONE) class AudioCppTTSClientRequestTests(unittest.TestCase): """The /v1/audio/speech payload and response validation.""" def setUp(self): self._tmp = tempfile.TemporaryDirectory() self._chunks = patch.object(tts, "CHUNKS_FOLDER", Path(self._tmp.name)) self._chunks.start() self._sleep = patch("converter.tts.time.sleep") self._sleep.start() def tearDown(self): self._sleep.stop() self._chunks.stop() self._tmp.cleanup() @staticmethod def _make_client(preset_mode=False, voice="Vivian", language="English", seed=-1, family="qwen3_tts", task="tts", instructions=None, request_options=None): client = AudioCppTTSClient.__new__(AudioCppTTSClient) client.api_url = "http://127.0.0.1:8080" client.model_id = config.AUDIOCPP_MODEL_ID client.preset_mode = preset_mode client.voice = voice client.language = language client._seed = seed client.family = family client.task = task client.profile = tts.AUDIOCPP_FAMILY_PROFILES.get( family, tts.AUDIOCPP_DEFAULT_FAMILY_PROFILE) client.instructions = instructions or "" client.request_options = dict(request_options or {}) client.design_mode = task == tts.AUDIOCPP_TASK_VDES # Mirrors the connect-time rule: an instruction-defined voice on a # clone-capable entry with no --voice (design mode takes precedence). capability = tts.audiocpp_entry_voice_capability( family, task, client.model_id) client.instruction_voice = ( not preset_mode and not client.design_mode and capability == tts.AUDIOCPP_VOICE_CLONE and bool(client.instructions)) return client @staticmethod def _wav_bytes(frames=b"\x01\x00" * 10, rate=tts.SAMPLE_RATE): buffer = io.BytesIO() with wave.open(buffer, "wb") as wav_file: wav_file.setnchannels(1) wav_file.setsampwidth(2) wav_file.setframerate(rate) wav_file.writeframes(frames) return buffer.getvalue() def _post_response(self, body): response = MagicMock() response.__enter__.return_value = response response.read.return_value = body return response def test_payload_includes_model_input_voice_language_and_seed(self): client = self._make_client(preset_mode=True, voice="narrator", language="Japanese", seed=1234) with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello world.") request = mock_urlopen.call_args[0][0] self.assertEqual(request.full_url, "http://127.0.0.1:8080/v1/audio/speech") payload = json.loads(request.data.decode("utf-8")) self.assertEqual(payload["model"], config.AUDIOCPP_MODEL_ID) self.assertEqual(payload["input"], "Hello world.") self.assertEqual(payload["voice"], "narrator") self.assertEqual(payload["language"], "Japanese") self.assertEqual(payload["seed"], 1234) self.assertNotIn("instructions", payload) def test_negative_seed_omitted_from_payload(self): client = self._make_client(preset_mode=True, voice="narrator", seed=-1) with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello world.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertNotIn("seed", payload) def test_request_timeout_is_the_configured_api_timeout(self): client = self._make_client() long_text = " ".join(f"word{i}" for i in range(1500)) with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav(long_text) timeout = mock_urlopen.call_args[1]["timeout"] self.assertEqual(timeout, config.API_TIMEOUT) def test_speaker_mode_sends_instruct(self): client = self._make_client(preset_mode=False) with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertEqual(payload["instructions"], config.INSTRUCT) def test_explicit_instructions_replace_config_instruct(self): # --instructions overrides the INSTRUCT default in speaker mode. client = self._make_client(preset_mode=False, instructions="Read whisper quiet.") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertEqual(payload["instructions"], "Read whisper quiet.") def test_preset_mode_sends_instructions_alongside_voice(self): # Clone + style control: both the server-side voice and the # instruction reach the model. client = self._make_client(preset_mode=True, voice="narrator", instructions="Calm and steady.") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertEqual(payload["voice"], "narrator") self.assertEqual(payload["instructions"], "Calm and steady.") def test_design_mode_payload_omits_voice_and_sends_instructions(self): client = self._make_client(task="vdes", instructions="A warm adult narrator") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertNotIn("voice", payload) self.assertEqual(payload["instructions"], "A warm adult narrator") def test_design_mode_language_follows_family_profile(self): # The VoiceDesign package is family qwen3_tts, whose language field # takes Qwen display names like the other variants. client = self._make_client(task="vdes", language="Japanese", instructions="A warm adult narrator") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertEqual(payload["language"], "Japanese") def test_instruction_voice_payload_omits_voice(self): # Instruction-defined voice on a family without built-in speakers: # no speaker name is invented, the instruction carries the voice. client = self._make_client(family="omnivoice", instructions="female, young adult") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertNotIn("voice", payload) self.assertNotIn("language", payload) # generic profile: omitted self.assertEqual(payload["instructions"], "female, young adult") def test_request_options_forwarded_in_payload(self): client = self._make_client(preset_mode=True, voice="narrator", request_options={"emotion": "neutral", "speed": "1.1"}) with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertEqual(payload["options"], {"emotion": "neutral", "speed": "1.1"}) def test_empty_request_options_omit_options_field(self): client = self._make_client(preset_mode=True, voice="narrator") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertNotIn("options", payload) def test_generic_family_omits_language_and_instructions(self): # Clone-only families (higgs_audio_tts, voxcpm2, ...) detect the # language themselves and take no style instruction. client = self._make_client(preset_mode=False, family="higgs_audio_tts") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertNotIn("language", payload) self.assertNotIn("instructions", payload) def test_iso_family_sends_language_code(self): client = self._make_client(preset_mode=True, voice="narrator", language="Japanese", family="index_tts2") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertEqual(payload["language"], "ja") def test_iso_family_auto_omits_language(self): client = self._make_client(preset_mode=True, voice="narrator", language="Auto", family="index_tts2") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertNotIn("language", payload) def test_qwen_language_display_name_still_sent(self): client = self._make_client(preset_mode=True, voice="narrator", language="Japanese", family="qwen3_tts") with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(self._wav_bytes())) as mock_urlopen: client._request_wav("Hello.") payload = json.loads(mock_urlopen.call_args[0][0].data.decode("utf-8")) self.assertEqual(payload["language"], "Japanese") def test_non_wav_response_rejected(self): client = self._make_client() for body in (b"", b"RIFFxxxx", b"MP3DATA-MP3DATA", b"RIFF\x00\x00\x00\x00mpeg"): with patch("converter.tts.urllib.request.urlopen", return_value=self._post_response(body)): with self.assertRaises(RuntimeError): client._request_wav("Hello.") def test_http_error_body_surfaced(self): import urllib.error client = self._make_client() error = urllib.error.HTTPError( "http://127.0.0.1:8080/v1/audio/speech", 500, "Server Error", {}, io.BytesIO(b'{"error":"bad voice"}')) with patch("converter.tts.urllib.request.urlopen", side_effect=error): with self.assertRaises(RuntimeError) as ctx: client._request_wav("Hello.") self.assertIn("500", str(ctx.exception)) self.assertIn("bad voice", str(ctx.exception)) def test_transient_failure_is_retried(self): client = self._make_client() wav = self._wav_bytes() with patch.object(client, "_request_wav", side_effect=[RuntimeError("boom"), wav]) as mock_request: result = client.generate_chunk("Hello.", 1) self.assertIsNotNone(result) self.assertEqual(mock_request.call_count, 2) def test_exhausted_retries_fail_the_chunk(self): client = self._make_client() with patch.object(client, "_request_wav", side_effect=RuntimeError("down")) as mock_request: result = client.generate_chunk("Hello.", 1) self.assertIsNone(result) self.assertEqual(mock_request.call_count, config.MAX_RETRIES) def test_empty_text_fails_the_chunk(self): client = self._make_client() with patch.object(client, "_request_wav") as mock_request: result = client.generate_chunk(" ", 1) self.assertIsNone(result) mock_request.assert_not_called() def test_generate_chunk_writes_valid_wav(self): client = self._make_client() frames = b"\x01\x00" * 100 with patch.object(client, "_request_wav", return_value=self._wav_bytes(frames)): result = client.generate_chunk("Hello world.", 1) self.assertIsNotNone(result) path = Path(result) self.assertEqual(path.name, "chunk_0001.wav") with wave.open(str(path), "rb") as wav_file: self.assertEqual(wav_file.getnchannels(), 1) self.assertEqual(wav_file.getsampwidth(), 2) self.assertEqual(wav_file.getframerate(), tts.SAMPLE_RATE) self.assertEqual(wav_file.readframes(wav_file.getnframes()), frames) def test_long_text_is_subchunked_and_concatenated_in_order(self): client = self._make_client() sentences = [" ".join(f"word{i}" for i in range(6)) + "." for _ in range(3)] text = " ".join(sentences) parts = [self._wav_bytes(b"\x01\x00" * 10), self._wav_bytes(b"\x02\x00" * 20), self._wav_bytes(b"\x03\x00" * 30)] with patch.object(config, "CHUNK_SIZE", 10), \ patch.object(client, "_request_wav", side_effect=parts) as mock_request: result = client.generate_chunk(text, 1) self.assertEqual(mock_request.call_count, 3) with wave.open(str(Path(result)), "rb") as wav_file: self.assertEqual(wav_file.readframes(wav_file.getnframes()), b"\x01\x00" * 10 + b"\x02\x00" * 20 + b"\x03\x00" * 30) def test_stale_chunk_files_are_removed(self): stale = Path(self._tmp.name) / "chunk_0001.mp3" stale.write_bytes(b"old") client = self._make_client() with patch.object(client, "_request_wav", return_value=self._wav_bytes()): client.generate_chunk("Hello.", 1) remaining = sorted(path.name for path in Path(self._tmp.name).glob("chunk_0001.*")) self.assertEqual(remaining, ["chunk_0001.wav"]) class AudioCppHeartbeatTests(unittest.TestCase): """The heartbeat reports chunk progress while a request generates.""" def setUp(self): self._tmp = tempfile.TemporaryDirectory() self._chunks = patch.object(tts, "CHUNKS_FOLDER", Path(self._tmp.name)) self._chunks.start() def tearDown(self): self._chunks.stop() self._tmp.cleanup() @staticmethod def _client(): client = AudioCppTTSClient.__new__(AudioCppTTSClient) client.api_url = "http://127.0.0.1:8080" client.model_id = config.AUDIOCPP_MODEL_ID client.preset_mode = False client.voice = "Vivian" client.language = "English" client._seed = -1 client.family = "qwen3_tts" client.profile = tts.AUDIOCPP_DEFAULT_FAMILY_PROFILE return client @staticmethod def _wav_bytes(): buffer = io.BytesIO() with wave.open(buffer, "wb") as wav_file: wav_file.setnchannels(1) wav_file.setsampwidth(2) wav_file.setframerate(tts.SAMPLE_RATE) wav_file.writeframes(b"\x01\x00" * 10) return buffer.getvalue() def _run(self): client = self._client() def slow_request(*_args, **_kwargs): time.sleep(0.12) return self._wav_bytes() buf = io.StringIO() with patch.object(config, "HEARTBEAT_INTERVAL_SECONDS", 0.03), \ patch.object(client, "_request_wav_with_retry", side_effect=slow_request), \ redirect_stdout(buf): result = client.generate_chunk("Hello.", 1) self.assertTrue(result) return buf.getvalue() def test_heartbeat_reports_chunk_progress(self): out = self._run() self.assertIn("Chunk 1 still generating", out) class AudioCppTTSClientTruncationTests(unittest.TestCase): """Audio far shorter than its text implies fails the request.""" def setUp(self): self._tmp = tempfile.TemporaryDirectory() self._chunks = patch.object(tts, "CHUNKS_FOLDER", Path(self._tmp.name)) self._chunks.start() def tearDown(self): self._chunks.stop() self._tmp.cleanup() def _make_client(self): client = AudioCppTTSClient.__new__(AudioCppTTSClient) client.api_url = "http://127.0.0.1:8080" client.model_id = config.AUDIOCPP_MODEL_ID client.preset_mode = True client.voice = "narrator" client.language = "English" client._seed = -1 client.family = "qwen3_tts" client.profile = tts.AUDIOCPP_FAMILY_PROFILES["qwen3_tts"] return client @staticmethod def _wav_bytes(frames): buffer = io.BytesIO() with wave.open(buffer, "wb") as wav_file: wav_file.setnchannels(1) wav_file.setsampwidth(2) wav_file.setframerate(tts.SAMPLE_RATE) wav_file.writeframes(frames) return buffer.getvalue() def test_full_length_wav_passes(self): client = self._make_client() text = " ".join(f"word{i}" for i in range(12)) # 12 words -> expected 4.8s, half is 2.4s -> 2.5s of audio passes. wav = self._wav_bytes(b"\x01\x00" * int(2.5 * tts.SAMPLE_RATE)) with patch.object(client, "_request_wav", return_value=wav): result = client.generate_chunk(text, 1) self.assertIsNotNone(result) class AudioCppUnloadModelsTests(unittest.TestCase): """Before generating, the client asks the server to drop loaded models.""" @staticmethod def _client(): client = AudioCppTTSClient.__new__(AudioCppTTSClient) client.api_url = "http://127.0.0.1:8080" return client @staticmethod def _response(body): response = MagicMock() response.__enter__.return_value = response response.read.return_value = body return response def test_posts_to_unload_all_models(self): client = self._client() with patch("converter.tts.urllib.request.urlopen", return_value=self._response(b'{"unloaded": ["qwen"]}')) as mock_urlopen: client._unload_server_models() request = mock_urlopen.call_args[0][0] self.assertEqual(request.full_url, "http://127.0.0.1:8080/v1/tasks/unload_all_models") self.assertEqual(request.method, "POST") self.assertEqual(request.data, b"") def test_reports_unloaded_ids(self): client = self._client() buf = io.StringIO() with patch("converter.tts.urllib.request.urlopen", return_value=self._response(b'{"unloaded": ["a", "b"]}')), \ redirect_stdout(buf): client._unload_server_models() self.assertIn("Unloaded 2 model(s)", buf.getvalue()) self.assertIn("a, b", buf.getvalue()) def test_no_loaded_models_is_silent(self): client = self._client() buf = io.StringIO() with patch("converter.tts.urllib.request.urlopen", return_value=self._response(b'{"unloaded": []}')), \ redirect_stdout(buf): client._unload_server_models() self.assertEqual(buf.getvalue(), "") def test_http_error_warns_and_continues(self): client = self._client() buf = io.StringIO() with patch("converter.tts.urllib.request.urlopen", side_effect=tts.urllib.error.HTTPError( "http://127.0.0.1:8080/v1/tasks/unload_all_models", 404, "Not Found", None, io.BytesIO())), \ redirect_stdout(buf): client._unload_server_models() out = buf.getvalue() self.assertIn("[WARNING]", out) self.assertIn("404", out) def test_connection_error_warns_and_continues(self): client = self._client() buf = io.StringIO() with patch("converter.tts.urllib.request.urlopen", side_effect=tts.urllib.error.URLError("refused")), \ redirect_stdout(buf): client._unload_server_models() self.assertIn("[WARNING]", buf.getvalue()) def test_connect_unloads_before_returning(self): client = AudioCppTTSClient.__new__(AudioCppTTSClient) client.api_url = "http://127.0.0.1:8080" client.model_id = config.AUDIOCPP_MODEL_ID client.preset_mode = True client.voice = "narrator" client.language = "English" client._seed = -1 client.family = "qwen3_tts" client.task = tts.AUDIOCPP_TASK_TTS client.profile = tts.AUDIOCPP_FAMILY_PROFILES["qwen3_tts"] client.design_mode = False client.instruction_voice = False client.speaker_mode = False client.instructions = "" with patch.object(client, "_check_health"), \ patch.object(client, "_list_models", return_value=[{"id": client.model_id, "family": "qwen3_tts", "task": "tts"}]), \ patch.object(client, "_auto_pick_model_id"), \ patch.object(client, "_select_model"), \ patch.object(client, "_require_model_id"), \ patch.object(client, "_resolve_family"), \ patch.object(client, "_resolve_task"), \ patch.object(client, "_check_voice"), \ patch.object(client, "_unload_server_models") as mock_unload: client._connect() mock_unload.assert_called_once() def test_connect_skips_unload_when_disabled(self): client = AudioCppTTSClient.__new__(AudioCppTTSClient) client.api_url = "http://127.0.0.1:8080" client.model_id = config.AUDIOCPP_MODEL_ID client.preset_mode = True client.voice = "narrator" client.language = "English" client._seed = -1 client.family = "qwen3_tts" client.task = tts.AUDIOCPP_TASK_TTS client.profile = tts.AUDIOCPP_FAMILY_PROFILES["qwen3_tts"] client.design_mode = False client.instruction_voice = False client.speaker_mode = False client.instructions = "" with patch.object(client, "_check_health"), \ patch.object(client, "_list_models", return_value=[{"id": client.model_id, "family": "qwen3_tts", "task": "tts"}]), \ patch.object(client, "_auto_pick_model_id"), \ patch.object(client, "_select_model"), \ patch.object(client, "_require_model_id"), \ patch.object(client, "_resolve_family"), \ patch.object(client, "_resolve_task"), \ patch.object(client, "_check_voice"), \ patch.object(tts.config, "AUDIOCPP_UNLOAD_MODELS", False), \ patch.object(client, "_unload_server_models") as mock_unload: client._connect() mock_unload.assert_not_called() class BackendWiringTests(unittest.TestCase): """AudiobookConverter wiring for the --backend selector.""" def test_faster_backend_uses_faster_client_without_reference(self): with patch("converter.converter.FasterTTSClient") as mock_faster, \ patch("converter.converter.QwenTTSClient") as mock_qwen, \ patch("converter.converter.AudioCppTTSClient") as mock_audiocpp: AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_FASTER, voice="narrator") mock_faster.assert_called_once_with(voice="narrator", api_url=None) mock_qwen.assert_not_called() mock_audiocpp.assert_not_called() def test_audiocpp_backend_with_voice_uses_audiocpp_client(self): with patch("converter.converter.FasterTTSClient") as mock_faster, \ patch("converter.converter.QwenTTSClient") as mock_qwen, \ patch("converter.converter.AudioCppTTSClient") as mock_audiocpp: AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_AUDIOCPP, voice="narrator", language="ja") mock_audiocpp.assert_called_once_with(voice="narrator", language="Japanese", model_id=None, instructions=None, request_options={}, api_url=None) mock_faster.assert_not_called() mock_qwen.assert_not_called() def test_audiocpp_backend_without_voice_uses_audiocpp_client(self): with patch("converter.converter.AudioCppTTSClient") as mock_audiocpp: AudiobookConverter(voice_mode=tts.VOICE_MODE_CUSTOM, backend=tts.BACKEND_AUDIOCPP) mock_audiocpp.assert_called_once_with(voice=None, language=config.LANGUAGE, model_id=None, instructions=None, request_options={}, api_url=None) def test_audiocpp_backend_model_id_is_wired_through(self): with patch("converter.converter.AudioCppTTSClient") as mock_audiocpp: AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_AUDIOCPP, voice="narrator", model_id="higgs") mock_audiocpp.assert_called_once_with( voice="narrator", language=config.LANGUAGE, model_id="higgs", instructions=None, request_options={}, api_url=None) def test_audiocpp_backend_instructions_and_options_are_wired_through(self): with patch("converter.converter.AudioCppTTSClient") as mock_audiocpp: AudiobookConverter(voice_mode=tts.VOICE_MODE_CUSTOM, backend=tts.BACKEND_AUDIOCPP, instructions="A warm adult narrator", request_options={"emotion": "neutral", "speed": "1.1"}) mock_audiocpp.assert_called_once_with( voice=None, language=config.LANGUAGE, model_id=None, instructions="A warm adult narrator", request_options={"emotion": "neutral", "speed": "1.1"}, api_url=None) def test_qwen_backend_uses_qwen_client(self): with patch("converter.converter.FasterTTSClient") as mock_faster, \ patch("converter.converter.QwenTTSClient") as mock_qwen, \ patch("converter.converter.AudioCppTTSClient") as mock_audiocpp: AudiobookConverter(voice_mode=tts.VOICE_MODE_CUSTOM, backend=tts.BACKEND_QWEN) mock_qwen.assert_called_once() mock_faster.assert_not_called() mock_audiocpp.assert_not_called() def test_qwen_clone_mode_still_requires_reference(self): with patch("converter.converter.QwenTTSClient"): with self.assertRaises(ValueError): AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_QWEN) def test_api_url_override_reaches_each_client(self): # A remote conversion threads api_url through to the selected client. with patch("converter.converter.AudioCppTTSClient") as mock_audiocpp: AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_AUDIOCPP, voice="narrator", api_url="http://10.0.0.5:8080") mock_audiocpp.assert_called_once_with( voice="narrator", language=config.LANGUAGE, model_id=None, instructions=None, request_options={}, api_url="http://10.0.0.5:8080") with patch("converter.converter.FasterTTSClient") as mock_faster: AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_FASTER, voice="narrator", api_url="http://10.0.0.5:8000") mock_faster.assert_called_once_with(voice="narrator", api_url="http://10.0.0.5:8000") with patch("converter.converter.QwenTTSClient") as mock_qwen: AudiobookConverter(voice_mode=tts.VOICE_MODE_CUSTOM, backend=tts.BACKEND_QWEN, api_url="http://10.0.0.5:7860") mock_qwen.assert_called_once_with( voice_mode=tts.VOICE_MODE_CUSTOM, voice_clone_ref_audio=None, voice_clone_ref_text=None, skip_transcription=False, language=config.LANGUAGE, api_url="http://10.0.0.5:7860") def test_audiocpp_clone_mode_does_not_require_reference(self): # Cloning is server-side for the audiocpp backend, so the # clone-mode voice can be selected without local reference audio. with patch("converter.converter.AudioCppTTSClient"): converter = AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_AUDIOCPP, voice="narrator") self.assertIsNone(converter.voice_clone_ref_audio) def test_chapter_chunks_audiocpp_splits(self): converter = self._audiocpp_converter(voice="narrator") text = " ".join(f"word{i}" for i in range(50)) with patch.object(config, "CHUNK_SIZE", 10): chunks = converter._chapter_chunks(text) self.assertGreater(len(chunks), 1) self.assertTrue(all(len(chunk.split()) <= 10 for chunk in chunks)) def test_chapter_chunks_qwen_always_splits(self): with patch("converter.converter.QwenTTSClient"): converter = AudiobookConverter(voice_mode=tts.VOICE_MODE_CUSTOM, backend=tts.BACKEND_QWEN) text = " ".join(f"word{i}" for i in range(50)) with patch.object(config, "CHUNK_SIZE", 10): chunks = converter._chapter_chunks(text) self.assertGreater(len(chunks), 1) def test_faster_backend_still_validates_other_settings(self): with patch("converter.converter.FasterTTSClient"): with self.assertRaises(ValueError): AudiobookConverter(backend=tts.BACKEND_FASTER, speed=0) with self.assertRaises(ValueError): AudiobookConverter(backend=tts.BACKEND_FASTER, language="klingon") def test_audiocpp_backend_still_validates_other_settings(self): with patch("converter.converter.AudioCppTTSClient"): with self.assertRaises(ValueError): AudiobookConverter(backend=tts.BACKEND_AUDIOCPP, speed=0) with self.assertRaises(ValueError): AudiobookConverter(backend=tts.BACKEND_AUDIOCPP, language="klingon") def _faster_converter(self, voice=None): with patch("converter.converter.FasterTTSClient"): return AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, backend=tts.BACKEND_FASTER, voice=voice) def _audiocpp_converter(self, voice=None): with patch("converter.converter.AudioCppTTSClient"): return AudiobookConverter( voice_mode=tts.VOICE_MODE_CLONE if voice else tts.VOICE_MODE_CUSTOM, backend=tts.BACKEND_AUDIOCPP, voice=voice) def test_narrator_tag_uses_faster_voice_name(self): converter = self._faster_converter(voice="male_richard_poe") self.assertEqual(converter._narrator_tag(), "male_richard_poe") def test_narrator_tag_falls_back_to_config_voice(self): converter = self._faster_converter() self.assertEqual(converter._narrator_tag(), config.FASTER_VOICE) def test_narrator_tag_audiocpp_uses_voice_name(self): converter = self._audiocpp_converter(voice="female_narrator") self.assertEqual(converter._narrator_tag(), "female_narrator") def test_narrator_tag_audiocpp_falls_back_to_speaker(self): converter = self._audiocpp_converter() self.assertEqual(converter._narrator_tag(), "Vivian") def test_banner_and_narrator_work_without_reference_audio(self): converter = self._faster_converter(voice="male_richard_poe") converter._print_banner() # must not raise (regression: Path(None)) self.assertIsNone(converter.voice_clone_ref_audio) def test_audiocpp_banner_prints_without_reference_audio(self): converter = self._audiocpp_converter(voice="narrator") converter._print_banner() # must not raise converter = self._audiocpp_converter() converter._print_banner() def test_audiocpp_banner_prints_model_family(self): from contextlib import redirect_stdout converter = self._audiocpp_converter(voice="narrator") converter.tts.family = "higgs_audio_tts" buffer = io.StringIO() with redirect_stdout(buffer): converter._print_banner() self.assertIn("higgs_audio_tts", buffer.getvalue()) def test_non_faster_narrator_tag_unchanged(self): with tempfile.TemporaryDirectory() as tmp: ref = Path(tmp) / "ref.wav" ref.write_bytes(b"x") with patch("converter.converter.QwenTTSClient"): converter = AudiobookConverter(voice_mode=tts.VOICE_MODE_CLONE, voice_clone_ref_audio=str(ref), backend=tts.BACKEND_QWEN) self.assertEqual(converter._narrator_tag(), "ref") if __name__ == "__main__": unittest.main()