Skip to content

Commit fdbcf96

Browse files
authored
fix(voices): combine endpoint accepts weighted syntax, matching speech endpoints (#285) (#512)
1 parent 316409d commit fdbcf96

7 files changed

Lines changed: 80 additions & 106 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Per-PR attribution and contributor credits are published automatically on the co
1010
- `MAX_INPUT_LENGTH` (default 1_000_000) caps characters of text per request.
1111
- `MAX_TOTAL_PAUSE_S` (default 300) caps total `[pause:Ns]` / SSML `<break>` silence per request.
1212
- Native Windows installs (`start-cpu.ps1` etc) no longer need a C++ toolchain: `pyopenjtalk-plus` (a drop-in fork with prebuilt Windows wheels) replaces `pyopenjtalk` on win32 only (#508, proposed by @siliconfps). Needs a recent `uv`. Linux, macOS, and Docker are unchanged.
13+
- `/v1/audio/voices/combine` now accepts weighted syntax (`af_bella(2)+af_sky(1)`), matching the speech endpoints (#285).
1314

1415
## [v0.8.0] - 2026-08-14
1516
### Added

‎api/src/inference/voice_manager.py‎

Lines changed: 0 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22

33
from typing import Dict, List, Optional
44

5-
import aiofiles
65
import torch
76
from loguru import logger
87

@@ -60,33 +59,6 @@ async def load_voice(
6059
except Exception as e:
6160
raise RuntimeError(f"Failed to load voice {voice_name}: {e}")
6261

63-
async def combine_voices(
64-
self, voices: List[str], device: Optional[str] = None
65-
) -> torch.Tensor:
66-
"""Combine multiple voices.
67-
68-
Args:
69-
voices: List of voice names to combine
70-
device: Optional override for target device
71-
72-
Returns:
73-
Combined voice tensor
74-
75-
Raises:
76-
RuntimeError: If any voice not found
77-
"""
78-
if len(voices) < 2:
79-
raise ValueError("Need at least 2 voices to combine")
80-
81-
target_device = device or self._device
82-
voice_tensors = []
83-
for name in voices:
84-
voice = await self.load_voice(name, target_device)
85-
voice_tensors.append(voice)
86-
87-
combined = torch.mean(torch.stack(voice_tensors), dim=0)
88-
return combined
89-
9062
async def list_voices(self) -> List[str]:
9163
"""List available voice names.
9264

‎api/src/routers/openai_compatible.py‎

Lines changed: 10 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,11 @@
11
"""OpenAI-compatible router for text-to-speech"""
22

3-
import io
43
import json
54
import math
65
import os
76
import re
8-
import tempfile
97
from typing import AsyncGenerator, Dict, List, Optional, Tuple, Union
108

11-
import aiofiles
12-
import torch
139
from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request, Response
1410
from fastapi.responses import FileResponse, StreamingResponse
1511
from loguru import logger
@@ -739,19 +735,10 @@ async def list_voices(legacy: bool = False):
739735

740736
@router.post("/audio/voices/combine")
741737
async def combine_voices(request: Union[str, List[str]]):
742-
"""Combine multiple voices into a new voice and return the .pt file.
738+
"""Combine voices and return the .pt file.
743739
744-
Args:
745-
request: Either a string with voices separated by + (e.g. "voice1+voice2")
746-
or a list of voice names to combine
747-
748-
Returns:
749-
FileResponse with the combined voice .pt file
750-
751-
Raises:
752-
HTTPException:
753-
- 400: Invalid request (wrong number of voices, voice not found)
754-
- 500: Server error (file system issues, combination failed)
740+
Accepts the speech endpoints' voice syntax ("voice1+voice2",
741+
"voice1(2)+voice2(1)") or a list of voice names.
755742
"""
756743
# Check if local voice saving is allowed
757744
if not settings.allow_local_voice_saving:
@@ -765,50 +752,19 @@ async def combine_voices(request: Union[str, List[str]]):
765752
)
766753

767754
try:
768-
# Convert input to list of voices
769-
if isinstance(request, str):
770-
# Check if it's an OpenAI voice name
771-
mapped_voice = _openai_mappings["voices"].get(request)
772-
if mapped_voice:
773-
request = mapped_voice
774-
voices = [v.strip() for v in request.split("+") if v.strip()]
775-
else:
776-
# For list input, map each voice if it's an OpenAI voice name
777-
voices = [_openai_mappings["voices"].get(v, v) for v in request]
778-
voices = [v.strip() for v in voices if v.strip()]
779-
780-
if not voices:
781-
raise ValueError("No voices provided")
755+
if isinstance(request, list):
756+
request = "+".join(v.strip() for v in request if v.strip())
782757

783-
# For multiple voices, validate base voices exist
784758
tts_service = await get_tts_service()
785-
available_voices = await tts_service.list_voices()
786-
for voice in voices:
787-
if voice not in available_voices:
788-
raise ValueError(
789-
f"Base voice '{voice}' not found. Available voices: {', '.join(sorted(available_voices))}"
790-
)
791-
792-
# Combine voices
793-
combined_tensor = await tts_service.combine_voices(voices=voices)
794-
combined_name = "+".join(voices)
795-
796-
# Save to temp file
797-
temp_dir = tempfile.gettempdir()
798-
voice_path = os.path.join(temp_dir, f"{combined_name}.pt")
799-
buffer = io.BytesIO()
800-
torch.save(combined_tensor, buffer)
801-
async with aiofiles.open(voice_path, "wb") as f:
802-
await f.write(buffer.getvalue())
759+
voice_string = await process_and_validate_voices(request, tts_service)
760+
combined_name, voice_path = await tts_service.get_voices_path(voice_string)
761+
safe_name = re.sub(r"[^A-Za-z0-9._-]+", "_", combined_name).strip("._-")
803762

804763
return FileResponse(
805764
voice_path,
806765
media_type="application/octet-stream",
807-
filename=f"{combined_name}.pt",
808-
headers={
809-
"Content-Disposition": f"attachment; filename={combined_name}.pt",
810-
"Cache-Control": "no-cache",
811-
},
766+
filename=f"{safe_name or 'voice'}.pt",
767+
headers={"Cache-Control": "no-cache"},
812768
)
813769

814770
except ValueError as e:

‎api/src/services/tts_service.py‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ async def _load_voice_from_path(self, path: str, weight: float):
183183
logger.debug(f"Loading voice tensor from path: {path}")
184184
return torch.load(path, map_location="cpu", weights_only=True) * weight
185185

186-
async def _get_voices_path(self, voice: str) -> Tuple[str, str]:
186+
async def get_voices_path(self, voice: str) -> Tuple[str, str]:
187187
"""Get voice path, handling combined voices.
188188
189189
Args:
@@ -288,7 +288,7 @@ async def _split_multi_voice(
288288

289289
for segment_voice, segment_rate, segment_text in segments:
290290
if segment_voice not in resolved:
291-
resolved[segment_voice] = await self._get_voices_path(segment_voice)
291+
resolved[segment_voice] = await self.get_voices_path(segment_voice)
292292
voice_name, voice_path = resolved[segment_voice]
293293

294294
# request lang_code wins, else each speaker gets the pipeline their prefix implies
@@ -538,15 +538,6 @@ async def generate_audio(
538538
logger.error(f"Error in audio generation: {str(e)}")
539539
raise
540540

541-
async def combine_voices(self, voices: List[str]) -> torch.Tensor:
542-
"""Combine multiple voices.
543-
544-
Returns:
545-
Combined voice tensor
546-
"""
547-
548-
return await self._voice_manager.combine_voices(voices)
549-
550541
async def list_voices(self) -> List[str]:
551542
"""List available voices."""
552543
return await self._voice_manager.list_voices()
@@ -573,7 +564,7 @@ async def generate_from_phonemes(
573564
try:
574565
await self.model_manager.ensure_backend()
575566
backend = self.model_manager.get_backend()
576-
voice_name, voice_path = await self._get_voices_path(voice)
567+
voice_name, voice_path = await self.get_voices_path(voice)
577568

578569
if isinstance(backend, KokoroV1):
579570
# For Kokoro V1, use generate_from_tokens with raw phonemes

‎api/tests/conftest.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,6 @@ async def mock_voice_manager(mock_voice_tensor):
5252
manager.get_voice_path = MagicMock(return_value="/mock/path/voice.pt")
5353
manager.load_voice = AsyncMock(return_value=mock_voice_tensor)
5454
manager.list_voices = AsyncMock(return_value=["voice1", "voice2"])
55-
manager.combine_voices = AsyncMock(return_value="voice1_voice2")
5655
return manager
5756

5857

‎api/tests/test_openai_endpoints.py‎

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,6 @@ async def mock_stream(*args, **kwargs) -> AsyncGenerator[AudioChunk, None]:
252252

253253
service.generate_audio_stream = mock_stream
254254
service.list_voices.return_value = ["test_voice", "voice1", "voice2"]
255-
service.combine_voices.return_value = "voice1_voice2"
256255

257256
mock_get.return_value = service
258257
mock_get.side_effect = None
@@ -461,15 +460,71 @@ def test_list_voices(mock_tts_service):
461460

462461

463462
@patch("api.src.routers.openai_compatible.settings")
464-
def test_combine_voices(mock_settings, mock_tts_service):
463+
def test_combine_voices(mock_settings, mock_tts_service, tmp_path):
465464
"""Test combining voices endpoint"""
466465
# Enable local voice saving for this test
467466
mock_settings.allow_local_voice_saving = True
467+
pt_path = tmp_path / "voice1+voice2.pt"
468+
pt_path.write_bytes(b"mock tensor")
469+
mock_tts_service.get_voices_path.return_value = ("voice1+voice2", str(pt_path))
468470

469471
response = client.post("/v1/audio/voices/combine", json="voice1+voice2")
470472
assert response.status_code == 200
471473
assert response.headers["content-type"] == "application/octet-stream"
472-
assert "voice1+voice2.pt" in response.headers["content-disposition"]
474+
assert 'filename="voice1_voice2.pt"' in response.headers["content-disposition"]
475+
mock_tts_service.get_voices_path.assert_awaited_once_with("voice1+voice2")
476+
477+
478+
@patch("api.src.routers.openai_compatible.settings")
479+
def test_combine_voices_weighted(mock_settings, mock_tts_service, tmp_path):
480+
"""Weighted combine syntax is accepted, same grammar as the speech endpoints (#285)"""
481+
mock_settings.allow_local_voice_saving = True
482+
pt_path = tmp_path / "combined.pt"
483+
pt_path.write_bytes(b"mock tensor")
484+
mock_tts_service.get_voices_path.return_value = (
485+
"voice1(2.2)+voice2(2.8)",
486+
str(pt_path),
487+
)
488+
489+
response = client.post("/v1/audio/voices/combine", json="voice1(2.2)+voice2(2.8)")
490+
assert response.status_code == 200
491+
assert 'filename="voice1_2.2_voice2_2.8.pt"' in response.headers["content-disposition"]
492+
mock_tts_service.get_voices_path.assert_awaited_once_with("voice1(2.2)+voice2(2.8)")
493+
494+
495+
@patch("api.src.routers.openai_compatible.settings")
496+
def test_combine_voices_list_input(mock_settings, mock_tts_service, tmp_path):
497+
"""List input joins into the same combine grammar"""
498+
mock_settings.allow_local_voice_saving = True
499+
pt_path = tmp_path / "voice1+voice2.pt"
500+
pt_path.write_bytes(b"mock tensor")
501+
mock_tts_service.get_voices_path.return_value = ("voice1+voice2", str(pt_path))
502+
503+
response = client.post("/v1/audio/voices/combine", json=["voice1", "voice2"])
504+
assert response.status_code == 200
505+
mock_tts_service.get_voices_path.assert_awaited_once_with("voice1+voice2")
506+
507+
508+
@patch("api.src.routers.openai_compatible.settings")
509+
def test_combine_voices_unknown_voice(mock_settings, mock_tts_service):
510+
"""Unknown voices in a combination 400 with the shared validation message"""
511+
mock_settings.allow_local_voice_saving = True
512+
513+
response = client.post("/v1/audio/voices/combine", json="voice1+nonexistent")
514+
assert response.status_code == 400
515+
error_response = response.json()
516+
assert error_response["detail"]["error"] == "validation_error"
517+
assert "Voice 'nonexistent' not found" in error_response["detail"]["message"]
518+
519+
520+
@patch("api.src.routers.openai_compatible.settings")
521+
def test_combine_voices_disabled(mock_settings, mock_tts_service):
522+
"""Combine endpoint 403s when local voice saving is off"""
523+
mock_settings.allow_local_voice_saving = False
524+
525+
response = client.post("/v1/audio/voices/combine", json="voice1+voice2")
526+
assert response.status_code == 403
527+
assert response.json()["detail"]["error"] == "permission_denied"
473528

474529

475530
def test_server_error(mock_tts_service, test_voice):

‎api/tests/test_tts_service.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ async def test_get_voice_path_single():
7777
mock_get_voice.return_value = voice_manager
7878

7979
service = await TTSService.create()
80-
name, path = await service._get_voices_path("voice1")
80+
name, path = await service.get_voices_path("voice1")
8181
assert name == "voice1"
8282
assert path == "/path/to/voice1.pt"
8383
voice_manager.get_voice_path.assert_called_once_with("voice1")
@@ -100,7 +100,7 @@ async def test_get_voice_path_single_with_weight_normalized():
100100
mock_settings.voice_weight_normalization = True
101101

102102
service = await TTSService.create()
103-
name, path = await service._get_voices_path("voice1(2)")
103+
name, path = await service.get_voices_path("voice1(2)")
104104
assert name == "voice1"
105105
assert path == "/path/to/voice1.pt"
106106
voice_manager.get_voice_path.assert_called_once_with("voice1")
@@ -126,7 +126,7 @@ async def test_get_voice_path_combined():
126126
mock_load.return_value = torch.ones(10)
127127

128128
service = await TTSService.create()
129-
name, path = await service._get_voices_path("voice1+voice2")
129+
name, path = await service.get_voices_path("voice1+voice2")
130130
assert name == "voice1+voice2"
131131
# Verify the path points to a temporary file with expected format
132132
assert Path(path).parent == Path("/tmp")
@@ -169,7 +169,7 @@ async def test_split_multi_voice_resolves_each_speaker_once():
169169
mock_get_voice.return_value = voice_manager
170170

171171
service = await TTSService.create()
172-
service._get_voices_path = AsyncMock(
172+
service.get_voices_path = AsyncMock(
173173
side_effect=lambda voice: (voice, f"/path/to/{voice}.pt")
174174
)
175175

@@ -189,7 +189,7 @@ async def test_split_multi_voice_resolves_each_speaker_once():
189189
speakers.append(voice_name)
190190

191191
assert speakers == ["af_bella", "bm_george", "af_bella"]
192-
assert service._get_voices_path.await_count == 2
192+
assert service.get_voices_path.await_count == 2
193193

194194

195195
@pytest.mark.asyncio
@@ -206,7 +206,7 @@ async def test_split_multi_voice_lang_code_per_speaker():
206206
mock_get_voice.return_value = voice_manager
207207

208208
service = await TTSService.create()
209-
service._get_voices_path = AsyncMock(
209+
service.get_voices_path = AsyncMock(
210210
side_effect=lambda voice: (voice, f"/path/to/{voice}.pt")
211211
)
212212

@@ -237,7 +237,7 @@ async def test_split_multi_voice_explicit_lang_code_wins():
237237
mock_get_voice.return_value = voice_manager
238238

239239
service = await TTSService.create()
240-
service._get_voices_path = AsyncMock(
240+
service.get_voices_path = AsyncMock(
241241
side_effect=lambda voice: (voice, f"/path/to/{voice}.pt")
242242
)
243243

@@ -267,7 +267,7 @@ async def _stubbed_service():
267267
mock_get_voice.return_value = AsyncMock()
268268
service = await TTSService.create()
269269

270-
service._get_voices_path = AsyncMock(
270+
service.get_voices_path = AsyncMock(
271271
side_effect=lambda voice: (voice, f"/path/to/{voice}.pt")
272272
)
273273

0 commit comments

Comments
 (0)