Skip to content

Commit c3cb020

Browse files
committed
feat(normalizer): opt-in remove_emoji, 400 before streaming on unspeakable input (remsky#353)
1 parent 4f826d6 commit c3cb020

7 files changed

Lines changed: 146 additions & 15 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ Notable changes to this project will be documented in this file.
55
Per-PR attribution and contributor credits are published automatically on the corresponding GitHub release page; this file is the curated, human-readable summary.
66

77
## [Unreleased]
8+
### Added
9+
- `normalization_options.remove_emoji` drops emoji before synthesis instead of reading them by name, any language (#353). Off by default.
10+
811
### Changed
912
- Text normalization refactored towards multi-language support: `Normalizer` base class w/ neutral passes, `EnglishNormalizer` implements the rest, registry keyed by lang code. Adding a language is a subclass + table test, see CONTRIBUTING.md.
1013

@@ -17,6 +20,7 @@ Per-PR attribution and contributor credits are published automatically on the co
1720
- `.5` reads as zero point five, `1980S` as nineteen eighty S.
1821
- Long digit runs no longer stall or 500 the request.
1922
- Times with seconds keep their am/pm (`12:30:15 pm`).
23+
- Blank input, or emoji-only input with `remove_emoji`, is a 400 on the streaming path too, not an empty 200.
2024
- `--` and `---` read as a dash. Previously the words on either side fused and word timestamps stopped for the rest of the chunk (#249).
2125

2226
## [v0.8.2] - 2026-09-05

‎api/src/routers/development.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@
1515
from ..services.streaming_audio_writer import StreamingAudioWriter
1616
from ..services.temp_manager import TempFileWriter
1717
from ..services.text_processing import smart_split
18-
from ..services.text_processing.text_processor import check_pause_budget
18+
from ..services.text_processing.text_processor import (
19+
check_pause_budget,
20+
check_speakable,
21+
)
1922
from ..services.tts_service import TTSService
2023
from ..structures import (
2124
CaptionedSpeechRequest,
@@ -241,6 +244,11 @@ async def create_captioned_speech(
241244
apply_alias_rate(request)
242245
# checked post-SSML and pre-stream, so an over-budget request 400s before headers
243246
check_pause_budget(request.input)
247+
check_speakable(
248+
request.input,
249+
request.allow_voice_tags,
250+
request.normalization_options,
251+
)
244252

245253
# Set content type based on format
246254
content_type = {

‎api/src/routers/openai_compatible.py‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
from ..services.text_processing.text_processor import (
1717
VOICE_TAG_PATTERN,
1818
check_pause_budget,
19+
check_speakable,
1920
)
2021
from ..services.tts_service import TTSService
2122
from ..structures import OpenAISpeechRequest
@@ -331,6 +332,11 @@ async def create_speech(
331332
apply_alias_rate(request)
332333
# checked post-SSML and pre-stream, so an over-budget request 400s before headers
333334
check_pause_budget(request.input)
335+
check_speakable(
336+
request.input,
337+
request.allow_voice_tags,
338+
request.normalization_options,
339+
)
334340

335341
# Set content type based on format
336342
content_type = {
@@ -733,9 +739,7 @@ async def list_voices(legacy: bool = False):
733739
if legacy:
734740
return {"voices": voices}
735741
return {
736-
"voices": [
737-
{"id": v, "name": v, **_voice_grades.get(v, {})} for v in voices
738-
]
742+
"voices": [{"id": v, "name": v, **_voice_grades.get(v, {})} for v in voices]
739743
}
740744
except Exception as e:
741745
logger.error(f"Error listing voices: {str(e)}")

‎api/src/services/text_processing/text_processor.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import time
66
from typing import AsyncGenerator, Iterator, List, Optional, Tuple
77

8+
import regex
89
from loguru import logger
910
from unicode_segmentation_rs import unicode_sentences
1011

@@ -20,6 +21,10 @@
2021
CUSTOM_PHONEMES = re.compile(r"(\[[^\[\]]*?\]\(\/[^\/\(\)]*?\/\))")
2122
# Pattern to find pause tags like [pause:0.5s]
2223
PAUSE_TAG_PATTERN = re.compile(r"\[pause:(\d+(?:\.\d+)?)s\]", re.IGNORECASE)
24+
EMOJI_PATTERN = regex.compile(
25+
r" ?(?:[0-9#*]\uFE0F?\u20E3|[\p{Extended_Pictographic}\p{Regional_Indicator}"
26+
r"\p{Emoji_Modifier}\u200D\uFE0F\u20E3]+) ?"
27+
)
2328
PARAGRAPH_PATTERN = re.compile(r"(?:\r?\n[^\S\r\n]*){2,}")
2429
LINE_PATTERN = re.compile(r"\r?\n[^\S\r\n]*")
2530
# Pattern to find voice tags like [voice:af_bella] or [voice:af_bella(2)+af_sky]
@@ -136,6 +141,24 @@ def split_by_voice(text: str, default_voice: str) -> List[Tuple[str, float, str]
136141
return [(voice, rate, text.strip()) for voice, rate, text in segments]
137142

138143

144+
def strip_emoji(text: str) -> str:
145+
return EMOJI_PATTERN.sub(" ", text)
146+
147+
148+
def check_speakable(
149+
text: str,
150+
allow_voice_tags: bool = False,
151+
normalization_options: Optional[NormalizationOptions] = None,
152+
) -> None:
153+
"""Raise before a stream opens when nothing would be spoken (issue #353)."""
154+
if allow_voice_tags:
155+
text = CONTROL_TAG_PATTERN.sub(" ", text)
156+
if normalization_options is not None and normalization_options.remove_emoji:
157+
text = strip_emoji(text)
158+
if not text.strip():
159+
raise ValueError("Input contains no speakable text")
160+
161+
139162
def check_pause_budget(text: str) -> None:
140163
"""Cap aggregate silence across the whole request, before any segmentation."""
141164
total_pause_s = math.fsum(
@@ -213,6 +236,8 @@ async def smart_split(
213236
if (
214237
text_part_raw and text_part_raw.strip()
215238
): # Only process if the part is not empty string
239+
if normalization_options.remove_emoji:
240+
text_part_raw = strip_emoji(text_part_raw)
216241
processed_text = join_lines(text_part_raw)
217242

218243
# Normalize text (original logic)

‎api/src/structures/schemas.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,10 @@ class NormalizationOptions(BaseModel):
127127
default=True,
128128
description="Replaces the remaining symbols after normalization with their words",
129129
)
130+
remove_emoji: bool = Field(
131+
default=False,
132+
description="Removes emoji instead of letting the phonemizer read them by name",
133+
)
130134

131135

132136
# shared with text_processor's VOICE_TAG_PATTERN so a rendered [voice:...] round-trips as one tag

‎api/tests/test_openai_endpoints.py‎

Lines changed: 44 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -275,9 +275,7 @@ def test_openai_speech_endpoint(mock_tts_service, test_voice, mock_audio_bytes):
275275
assert response.content == mock_audio_bytes
276276

277277
mock_tts_service.generate_audio.assert_called_once()
278-
assert (
279-
mock_tts_service.generate_audio.call_args.kwargs["output_format"] == "mp3"
280-
)
278+
assert mock_tts_service.generate_audio.call_args.kwargs["output_format"] == "mp3"
281279

282280

283281
def test_openai_speech_streaming(mock_tts_service, test_voice, mock_audio_bytes):
@@ -319,6 +317,43 @@ def test_openai_speech_streaming_over_pause_budget_is_400(mock_tts_service, test
319317
assert response.json()["detail"]["error"] == "validation_error"
320318

321319

320+
def test_openai_speech_streaming_nothing_speakable_is_400(mock_tts_service, test_voice):
321+
"""Blank input, or emoji-only with remove_emoji, 400s before the stream opens instead of an empty 200 (issue #353)."""
322+
for body in [
323+
{"input": " "},
324+
{"input": "😊", "normalization_options": {"remove_emoji": True}},
325+
]:
326+
response = client.post(
327+
"/v1/audio/speech",
328+
json={
329+
"model": "kokoro",
330+
"voice": test_voice,
331+
"response_format": "mp3",
332+
"stream": True,
333+
**body,
334+
},
335+
)
336+
assert response.status_code == 400
337+
assert response.json()["detail"]["error"] == "validation_error"
338+
339+
340+
def test_openai_speech_streaming_null_normalization_options(
341+
mock_tts_service, test_voice
342+
):
343+
response = client.post(
344+
"/v1/audio/speech",
345+
json={
346+
"model": "kokoro",
347+
"input": "Hello world",
348+
"voice": test_voice,
349+
"response_format": "mp3",
350+
"stream": True,
351+
"normalization_options": None,
352+
},
353+
)
354+
assert response.status_code == 200
355+
356+
322357
def test_captioned_streaming_over_pause_budget_is_400(mock_tts_service):
323358
"""The captioned handler carries the same pre-stream budget check."""
324359
with patch(
@@ -401,12 +436,7 @@ def test_openai_speech_invalid_voice(mock_tts_service):
401436

402437

403438
def test_openai_speech_empty_text(mock_tts_service, test_voice):
404-
"""Test error handling for empty text"""
405-
406-
async def mock_error_stream(*args, **kwargs):
407-
raise ValueError("Text is empty after preprocessing")
408-
409-
mock_tts_service.generate_audio = mock_error_stream
439+
"""Empty input is rejected before the service is called."""
410440
mock_tts_service.list_voices.return_value = ["test_voice"]
411441

412442
response = client.post(
@@ -422,7 +452,8 @@ async def mock_error_stream(*args, **kwargs):
422452
assert response.status_code == 400
423453
error_response = response.json()
424454
assert error_response["detail"]["error"] == "validation_error"
425-
assert "Text is empty after preprocessing" in error_response["detail"]["message"]
455+
assert "no speakable text" in error_response["detail"]["message"]
456+
mock_tts_service.generate_audio.assert_not_called()
426457
assert error_response["detail"]["type"] == "invalid_request_error"
427458

428459

@@ -504,7 +535,9 @@ def test_combine_voices_weighted(mock_settings, mock_tts_service, tmp_path):
504535

505536
response = client.post("/v1/audio/voices/combine", json="voice1(2.2)+voice2(2.8)")
506537
assert response.status_code == 200
507-
assert 'filename="voice1_2.2_voice2_2.8.pt"' in response.headers["content-disposition"]
538+
assert (
539+
'filename="voice1_2.2_voice2_2.8.pt"' in response.headers["content-disposition"]
540+
)
508541
mock_tts_service.get_voices_path.assert_awaited_once_with("voice1(2.2)+voice2(2.8)")
509542

510543

‎api/tests/test_text_processor.py‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
1+
import time
2+
13
import pytest
24

35
from api.src.services.text_processing import text_processor
46
from api.src.services.text_processing.normalization import Normalizer
57
from api.src.services.text_processing.text_processor import (
8+
check_speakable,
69
get_sentence_info,
710
join_lines,
811
process_text_chunk,
912
smart_split,
1013
split_by_voice,
14+
strip_emoji,
1115
)
1216
from api.src.structures.schemas import NormalizationOptions
1317

@@ -68,6 +72,55 @@ async def test_smart_split_keeps_custom_phonemes_out_of_the_normalizer(
6872
break
6973

7074

75+
# issue #353
76+
REMOVE_EMOJI = NormalizationOptions(remove_emoji=True)
77+
78+
79+
@pytest.mark.asyncio
80+
async def test_smart_split_keeps_emoji_by_default():
81+
async for chunk_text, _, _ in smart_split("hello 😊 world", lang_code="a"):
82+
assert "😊" in chunk_text
83+
84+
85+
@pytest.mark.asyncio
86+
@pytest.mark.parametrize("lang_code", ["a", "z"])
87+
async def test_smart_split_remove_emoji_option(lang_code):
88+
async for chunk_text, _, _ in smart_split(
89+
"hello 😊 world", lang_code=lang_code, normalization_options=REMOVE_EMOJI
90+
):
91+
assert chunk_text == "hello world"
92+
assert [
93+
chunk
94+
async for chunk in smart_split(
95+
"😊", lang_code=lang_code, normalization_options=REMOVE_EMOJI
96+
)
97+
] == []
98+
99+
100+
def test_check_speakable():
101+
check_speakable("hi")
102+
check_speakable("[pause:1s]")
103+
check_speakable("[voice:af_bella]")
104+
check_speakable("😊")
105+
for text in ["😊", "⏰ 1️⃣", " ", "[voice:af_bella] [voice:bm_george]"]:
106+
with pytest.raises(ValueError, match="no speakable text"):
107+
check_speakable(
108+
text, allow_voice_tags=True, normalization_options=REMOVE_EMOJI
109+
)
110+
111+
112+
def test_strip_emoji_sequences():
113+
for emoji in ["😊", "⏰", "1️⃣", "👨‍👩‍👧", "🇺🇸", "👍🏽"]:
114+
assert strip_emoji(f"a {emoji} b") == "a b"
115+
assert strip_emoji("call 1 or # now") == "call 1 or # now"
116+
117+
118+
def test_strip_emoji_flood_is_fast():
119+
start = time.monotonic()
120+
strip_emoji("1\ufe0f" * 20_000 + "😊" * 20_000)
121+
assert time.monotonic() - start < 2.0
122+
123+
71124
def test_process_text_chunk_basic():
72125
"""Test basic text chunk processing."""
73126
text = "Hello world"

0 commit comments

Comments
 (0)