Skip to content

利用 AI 大模型和自动化工作流,根据主题或关键词一键生成高清短视频。Generate HD short videos from a topic or keyword with an automated AI workflow.

fix: timeout hanging edge tts streams

Harryd5e0701e4505
diff --git a/app/services/voice.py b/app/services/voice.py
index 8f61df85..4920e079 100644
--- a/app/services/voice.py
+++ b/app/services/voice.py
@@ -2,7 +2,10 @@ import asyncio
import inspect
import math
import os
+import queue
import re
+import threading
+import time
from datetime import datetime
from typing import Union
from xml.sax.saxutils import unescape
@@ -17,6 +20,8 @@ from moviepy.audio.io.AudioFileClip import AudioFileClip
from app.config import config
from app.utils import utils
+_DEFAULT_EDGE_TTS_TIMEOUT_SECONDS = 30.0
+
def mktimestamp(time_unit: float) -> str:
"""
@@ -1306,7 +1311,95 @@ def create_edge_tts_communicate(
return edge_tts.Communicate(text, voice_name, **communicate_kwargs)
-def stream_edge_tts_chunks(communicate, on_chunk) -> None:
+def get_edge_tts_timeout_seconds() -> Union[float, None]:
+ """
+ 获取 Azure TTS V1 单次流式请求的超时时间。
+
+ 背景:
+ Edge consumer TTS 在网络不通、服务端限流、voice 与文本语言不匹配等场景下,
+ 可能长时间卡在 `stream_sync()` 内部,日志只停留在 `start`。这里提供一个
+ 默认超时,避免 WebUI 任务长期无反馈。
+
+ 使用方式:
+ - 默认 30 秒,覆盖常见短视频脚本的首包等待时间;
+ - 如用户处于慢网络或代理环境,可在 `config.toml` 里设置
+ `edge_tts_timeout = 60`;
+ - 设置为 0 或负数表示显式禁用超时,保留完全向后兼容。
+ """
+ raw_timeout = config.app.get(
+ "edge_tts_timeout", _DEFAULT_EDGE_TTS_TIMEOUT_SECONDS
+ )
+ try:
+ timeout_seconds = float(raw_timeout)
+ except (TypeError, ValueError):
+ logger.warning(
+ "invalid edge_tts_timeout: "
+ f"{raw_timeout}, fallback to {_DEFAULT_EDGE_TTS_TIMEOUT_SECONDS}s"
+ )
+ timeout_seconds = _DEFAULT_EDGE_TTS_TIMEOUT_SECONDS
+
+ if timeout_seconds <= 0:
+ return None
+
+ return timeout_seconds
+
+
+def _stream_edge_tts_sync_with_timeout(
+ communicate, on_chunk, timeout_seconds: float
+) -> None:
+ """
+ 带总超时地消费 edge_tts 7.x 的同步流。
+
+ 实现原因:
+ `stream_sync()` 本身是阻塞迭代器,网络层卡住时主线程无法及时恢复。
+ 这里把阻塞迭代放到 daemon 线程中,主线程通过 Queue 获取 chunk,
+ 到达超时时间后直接抛出 TimeoutError,让外层重试和错误日志继续工作。
+
+ 注意:
+ daemon 线程只作为兜底保护使用,最多随 Azure TTS V1 的 3 次重试产生
+ 少量残留线程;进程退出时会自动回收。相比 WebUI 任务永久卡住,这是
+ 更可控的失败模式。
+ """
+ stream_queue = queue.Queue()
+ done_marker = object()
+
+ def _produce_chunks():
+ try:
+ for chunk in communicate.stream_sync():
+ stream_queue.put(("chunk", chunk))
+ stream_queue.put(("done", done_marker))
+ except Exception as e:
+ stream_queue.put(("error", e))
+
+ thread = threading.Thread(target=_produce_chunks, daemon=True)
+ thread.start()
+
+ deadline = time.monotonic() + timeout_seconds
+ while True:
+ remaining_seconds = deadline - time.monotonic()
+ if remaining_seconds <= 0:
+ raise TimeoutError(
+ f"edge_tts stream timed out after {timeout_seconds:g}s"
+ )
+
+ try:
+ item_type, payload = stream_queue.get(
+ timeout=min(0.5, remaining_seconds)
+ )
+ except queue.Empty:
+ continue
+
+ if item_type == "chunk":
+ on_chunk(payload)
+ elif item_type == "error":
+ raise payload
+ elif item_type == "done":
+ return
+
+
+def stream_edge_tts_chunks(
+ communicate, on_chunk, timeout_seconds: Union[float, None] = None
+) -> None:
"""
统一消费 edge_tts 的同步流和旧版异步流。
@@ -1317,8 +1410,15 @@ def stream_edge_tts_chunks(communicate, on_chunk) -> None:
Args:
communicate: edge_tts.Communicate 实例
on_chunk: 每拿到一个事件块时执行的回调
+ timeout_seconds: 单次流式请求总超时;为 None 时不启用超时。
"""
if hasattr(communicate, "stream_sync"):
+ if timeout_seconds:
+ _stream_edge_tts_sync_with_timeout(
+ communicate, on_chunk, timeout_seconds
+ )
+ return
+
for chunk in communicate.stream_sync():
on_chunk(chunk)
return
@@ -1334,7 +1434,12 @@ def stream_edge_tts_chunks(communicate, on_chunk) -> None:
# 在同步调用栈里遇到“当前线程没有事件循环”或跨线程复用循环的问题。
loop = asyncio.new_event_loop()
try:
- loop.run_until_complete(_consume_async_stream())
+ if timeout_seconds:
+ loop.run_until_complete(
+ asyncio.wait_for(_consume_async_stream(), timeout=timeout_seconds)
+ )
+ else:
+ loop.run_until_complete(_consume_async_stream())
finally:
loop.close()
@@ -1355,6 +1460,7 @@ def azure_tts_v1(
ensure_file_path_exists(voice_file)
communicate = create_edge_tts_communicate(text, voice_name, rate_str)
sub_maker = edge_tts.SubMaker()
+ timeout_seconds = get_edge_tts_timeout_seconds()
with open(voice_file, "wb") as file:
def _handle_chunk(chunk):
@@ -1367,7 +1473,9 @@ def azure_tts_v1(
# 仍然走项目现有逻辑。
sub_maker.feed(chunk)
- stream_edge_tts_chunks(communicate, _handle_chunk)
+ stream_edge_tts_chunks(
+ communicate, _handle_chunk, timeout_seconds=timeout_seconds
+ )
if not sub_maker.get_srt():
logger.warning("failed, sub_maker.get_srt() is empty")
@@ -1377,6 +1485,17 @@ def azure_tts_v1(
return sub_maker
except Exception as e:
logger.error(f"failed, error: {str(e)}")
+ # TTS 流式写入如果在首包前超时或网络异常,会留下 0 字节音频文件。
+ # 这种文件既不可播放,也可能误导后续排查,因此失败后只清理空文件;
+ # 如果已经写入了部分数据,则保留现场文件,便于分析服务端返回内容。
+ if os.path.exists(voice_file) and os.path.getsize(voice_file) == 0:
+ try:
+ os.remove(voice_file)
+ except Exception as remove_error:
+ logger.warning(
+ "failed to remove empty tts file: "
+ f"{voice_file}, error: {str(remove_error)}"
+ )
return None
diff --git a/config.example.toml b/config.example.toml
index 07104418..39f8ed20 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -4,6 +4,12 @@ video_source = "pexels" # "pexels" or "pixabay"
# 是否隐藏配置面板
hide_config = false
+# Azure TTS V1(edge_tts) 单次流式请求超时时间,单位秒。
+# 网络异常、服务端限流或 voice 与文本语言不匹配时,edge_tts 可能长期卡住。
+# 默认 30 秒可避免 WebUI 任务无反馈;慢网络或代理环境可适当调大。
+# 设置为 0 表示禁用超时。
+edge_tts_timeout = 30
+
# 是否校验外部 API 和素材下载的 TLS 证书。
# 默认必须开启,避免 Pexels/Pixabay API key 和下载素材被中间人攻击篡改。
# 只有在企业代理或自签证书环境明确需要时,才临时改为 false。
diff --git a/test/services/test_voice.py b/test/services/test_voice.py
index e02ee7e4..e051cbc4 100644
--- a/test/services/test_voice.py
+++ b/test/services/test_voice.py
@@ -3,6 +3,7 @@ import unittest
import os
import sys
import tempfile
+import time
from pathlib import Path
from unittest.mock import patch
@@ -139,6 +140,55 @@ class TestVoiceService(unittest.TestCase):
self.assertEqual(len(sub_maker.events), 1)
self.assertEqual(sub_maker.events[0]["type"], "WordBoundary")
+ def test_azure_tts_v1_times_out_hanging_stream_sync(self):
+ """
+ 验证 Azure TTS V1 在 edge_tts 同步流卡住时能够快速失败。
+
+ 真实现场里,网络异常、服务端限流、voice 语言与文本不匹配时,
+ `stream_sync()` 可能长时间不返回,导致 WebUI 任务只停在
+ `start, voice name...`。这里用阻塞的 fake stream 复现该场景,
+ 确认超时保护会让函数结束并返回 None。
+ """
+
+ class _HangingCommunicate:
+ def __init__(self, text, voice, rate="+0%", boundary=None):
+ self.text = text
+ self.voice = voice
+ self.rate = rate
+ self.boundary = boundary
+
+ def stream_sync(self):
+ time.sleep(10)
+ yield {"type": "audio", "data": b"unreachable"}
+
+ class _FakeSubMaker:
+ def feed(self, chunk):
+ return None
+
+ def get_srt(self):
+ return ""
+
+ with tempfile.TemporaryDirectory() as tmp_dir, patch.object(
+ vs.edge_tts, "Communicate", _HangingCommunicate
+ ), patch.object(vs.edge_tts, "SubMaker", _FakeSubMaker), patch.object(
+ vs.config,
+ "app",
+ dict(vs.config.app, edge_tts_timeout=0.05),
+ ):
+ voice_file = Path(tmp_dir) / "hanging-edge-tts.mp3"
+ started_at = time.monotonic()
+ sub_maker = vs.azure_tts_v1(
+ text="帮我生成一个花开花落的视频",
+ voice_name="en-AU-NatashaNeural-Female",
+ voice_file=str(voice_file),
+ voice_rate=1.0,
+ )
+ elapsed = time.monotonic() - started_at
+ self.assertFalse(voice_file.exists())
+
+ self.assertIsNone(sub_maker)
+ self.assertLess(elapsed, 2)
+
def test_azure_tts_v2(self):
voice_name = "zh-CN-XiaoxiaoMultilingualNeural-V2-Female"
voice_name = vs.parse_voice_name(voice_name)