Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

fix(tts): tell a voice outage from a text problem, accept a UTF-8 BOM

Nikolai Ivakhnenko20977c3153e3
diff --git a/.claude/skills/papermorph/scripts/tts.py b/.claude/skills/papermorph/scripts/tts.py
index a4ce482..0ef4356 100644
--- a/.claude/skills/papermorph/scripts/tts.py
+++ b/.claude/skills/papermorph/scripts/tts.py
@@ -12,12 +12,14 @@ plus one caption cue per sentence. Only beats whose text or voice changed are
regenerated; spoken word times are cached, so caption and mark rules can change
without new audio.
-Narration files are read as UTF-8 on every platform. Keep beat ids and mark names
-ASCII: they become file names and JS keys, and are printed to the console.
+Narration files are read as UTF-8 (a byte order mark is allowed) on every platform.
+Keep beat ids and mark names ASCII: they become file names and JS keys, and are
+printed to the console.
Edge sometimes answers a request with no audio (NoAudioReceived), more often for
some voices; such a beat is requested again up to MAX_ATTEMPTS times with growing
-pauses before the run stops.
+pauses. If it still gets none, a short test phrase in the same voice tells whether
+the voice is unavailable or this beat's text is the problem, and the run stops.
"""
import asyncio
@@ -35,6 +37,7 @@ from edge_tts.exceptions import NoAudioReceived
MARK = re.compile(r"\[\[(\w+)\]\]")
MAX_ATTEMPTS = 5 # requests per beat when Edge returns no audio
FIRST_RETRY_DELAY = 2 # seconds before the second request; doubles after each failure
+PROBE_TEXT = "1, 2, 3." # checks the voice after a beat fails; any voice reads digits in its own language
async def synth(text, voice, rate, mp3_path):
@@ -63,6 +66,25 @@ async def synth_with_retries(beat, text, voice, rate, mp3_path):
await asyncio.sleep(delay)
+async def explain_no_audio(beat, voice, rate, out_dir):
+ """The message for a beat that ran out of attempts: whether the voice or this beat's text failed."""
+ with tempfile.NamedTemporaryFile(dir=out_dir, prefix=".probe-", suffix=".mp3", delete=False) as f:
+ probe_path = Path(f.name)
+ try:
+ await synth(PROBE_TEXT, voice, rate, probe_path)
+ voice_works = True
+ except NoAudioReceived:
+ voice_works = False
+ finally:
+ probe_path.unlink(missing_ok=True)
+ if voice_works:
+ return (f"{beat}: the voice {voice} works, but Edge returned no audio for this beat's text "
+ f"{MAX_ATTEMPTS} times. Look for unusual characters in it, or split the beat.")
+ return (f"{beat}: the voice {voice} returned no audio {MAX_ATTEMPTS} times, and also for a short test phrase, "
+ "so the voice is unavailable at Edge right now; the text is not the cause. Completed beats are saved. "
+ "Rerun later, or choose another voice for the whole book (uv run --with edge-tts edge-tts --list-voices).")
+
+
def split_marks(raw):
"""Return clean text and {mark: char position in clean text}."""
marks, clean, pos = {}, [], 0
@@ -130,11 +152,11 @@ def write_atomic(path, text):
async def main(src, out_dir):
- spec = json.loads(Path(src).read_text(encoding="utf-8"))
+ spec = json.loads(Path(src).read_text(encoding="utf-8-sig"))
out_dir = Path(out_dir)
out_dir.mkdir(parents=True, exist_ok=True)
cache_path = Path(src).with_suffix(".timings.json") # build cache, kept out of the site
- cache = json.loads(cache_path.read_text(encoding="utf-8")) if cache_path.exists() else {}
+ cache = json.loads(cache_path.read_text(encoding="utf-8-sig")) if cache_path.exists() else {}
voice, rate = spec["voice"], spec["rate"]
result = {}
public = lambda v: {k: v[k] for k in ("dur", "marks", "cues")}
@@ -160,7 +182,10 @@ async def main(src, out_dir):
clip = tmp
try:
if not reusable:
- words = await synth_with_retries(beat, clean, voice, rate, clip)
+ try:
+ words = await synth_with_retries(beat, clean, voice, rate, clip)
+ except NoAudioReceived:
+ raise SystemExit(await explain_no_audio(beat, voice, rate, out_dir)) from None
entry = {"key": key, "dur": duration(clip), "words": words,
"marks": mark_times(clean, marks, words), "cues": caption_cues(clean, words)}
if tmp: