free-short-video 5.1.2

package/core/audio/tts.py

@@ -0,0 +1,194 @@
+"""core.audio.tts — TTS 统一接口：EdgeTTSEngine + SilentTTSEngine
+
+基于 edge_tts（免费 Azure Edge TTS）和静音占位两种实现。
+"""
+
+import asyncio
+import logging
+import os
+from abc import ABC, abstractmethod
+from typing import Optional, Tuple
+
+import edge_tts
+
+logger = logging.getLogger(__name__)
+
+
+class TTSEngine(ABC):
+    """TTS 抽象基类。"""
+
+    @abstractmethod
+    async def generate(
+        self, text: str, output_path: str, voice: str = "zh-CN-XiaoxiaoNeural", rate: str = "+0%"
+    ) -> Tuple[str, object]:
+        """生成音频文件，返回 (audio_path, sub_maker_or_cues)。"""
+        ...
+
+
+class EdgeTTSEngine(TTSEngine):
+    """基于 edge_tts 的免费 TTS 引擎。
+
+    generate() 返回 (audio_path, sub_maker)，其中 sub_maker 是 edge_tts.SubMaker 实例，
+    包含逐词时间戳 cues，可用于生成 SRT 字幕。
+    """
+
+    async def generate(
+        self, text: str, output_path: str, voice: str = "zh-CN-XiaoxiaoNeural", rate: str = "+0%"
+    ) -> Tuple[str, "edge_tts.SubMaker"]:
+        """生成 TTS 音频 + SubMaker（含 cues 时间戳）。
+
+        Args:
+            text: 要朗读的文本
+            output_path: 输出音频文件路径（.mp3）
+            voice: edge_tts 语音角色
+            rate: 语速调节（如 "+0%", "+20%", "-10%"）
+
+        Returns:
+            (audio_path, sub_maker) 元组
+
+        Raises:
+            RuntimeError: TTS 生成失败时抛出，调用方应降级到 SilentTTSEngine。
+        """
+        logger.info(f"[TTS] Generating audio: voice={voice}, rate={rate}, text={len(text)} chars...")
+
+        os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
+
+        max_attempts = 2
+        for attempt in range(max_attempts):
+            try:
+                communicate = edge_tts.Communicate(text, voice=voice, rate=rate)
+                sub_maker = edge_tts.SubMaker()
+
+                tmp_path = output_path + ".tmp"
+                with open(tmp_path, "wb") as audio_file:
+                    async for chunk in communicate.stream():
+                        if chunk["type"] == "audio":
+                            audio_file.write(chunk["data"])
+                        elif chunk["type"] in ("WordBoundary", "SentenceBoundary"):
+                            sub_maker.feed(chunk)
+
+                # 原子替换，避免半成品被误用
+                os.replace(tmp_path, output_path)
+                logger.info(f"[TTS] Audio saved: {output_path}")
+                return output_path, sub_maker
+            except Exception as e:
+                # 清理半成品文件
+                for p in (tmp_path, output_path):
+                    if os.path.exists(p):
+                        try:
+                            os.remove(p)
+                        except OSError:
+                            pass
+                if attempt < max_attempts - 1:
+                    logger.warning(f"[TTS] edge_tts attempt {attempt + 1}/{max_attempts} failed: {e}, retrying...")
+                    await asyncio.sleep(3)
+                    continue
+                logger.error(f"[TTS] edge_tts failed after {max_attempts} attempts: {e}")
+                raise RuntimeError(f"EdgeTTS generation failed: {e}") from e
+
+    async def harvest_cues(
+        self, text: str, voice: str = "zh-CN-XiaoxiaoNeural", rate: str = "+0%"
+    ) -> "edge_tts.SubMaker":
+        """仅采集逐词时间戳，不生成/不落盘音频字节（路径 B：音频关、字幕开）。
+
+        edge_tts 的 WordBoundary 与音频数据交织于同一 stream，需消费完整 stream
+        才能收齐全部 cues；本方法只把 WordBoundary/SentenceBoundary 喂给 SubMaker，
+        音频数据直接丢弃。返回含 .cues 的 sub_maker，供 generate_cue_aware_srt 使用。
+
+        字幕只需时间线真值，不需音频字节——这正是「cues 采集」与「音频输出」解耦的核心。
+
+        Args:
+            text: 要朗读的文本
+            voice: edge_tts 语音角色
+            rate: 语速调节
+
+        Returns:
+            含逐词 cues 的 edge_tts.SubMaker 实例
+
+        Raises:
+            RuntimeError: 采集失败时抛出，调用方应降级到 SilentTTSEngine（字幕回退 legacy）。
+        """
+        logger.info(
+            f"[TTS] Harvesting cues only: voice={voice}, rate={rate}, text={len(text)} chars..."
+        )
+
+        max_attempts = 2
+        for attempt in range(max_attempts):
+            try:
+                communicate = edge_tts.Communicate(text, voice=voice, rate=rate)
+                sub_maker = edge_tts.SubMaker()
+                async for chunk in communicate.stream():
+                    if chunk["type"] in ("WordBoundary", "SentenceBoundary"):
+                        sub_maker.feed(chunk)
+                cue_count = len(getattr(sub_maker, "cues", []) or [])
+                logger.info(f"[TTS] Cues harvested: {cue_count} cues")
+                return sub_maker
+            except Exception as e:
+                if attempt < max_attempts - 1:
+                    logger.warning(
+                        f"[TTS] harvest_cues attempt {attempt + 1}/{max_attempts} "
+                        f"failed: {e}, retrying..."
+                    )
+                    await asyncio.sleep(3)
+                    continue
+                logger.error(f"[TTS] harvest_cues failed after {max_attempts} attempts: {e}")
+                raise RuntimeError(f"EdgeTTS cue harvest failed: {e}") from e
+
+
+class SilentTTSEngine(TTSEngine):
+    """静音占位 TTS 引擎。
+
+    生成指定时长的静音音频，返回空 cues。用于用户关闭旁白时仍需要字幕时间轴的场景。
+    """
+
+    async def generate(
+        self,
+        text: str,
+        output_path: str,
+        voice: str = "zh-CN-XiaoxiaoNeural",
+        rate: str = "+0%",
+        duration_sec: Optional[float] = None,
+    ) -> Tuple[str, dict]:
+        """生成静音音频。
+
+        Args:
+            text: 文本（用于估算时长，如果 duration_sec 未提供）
+            output_path: 输出音频文件路径
+            voice: 忽略（静音模式）
+            rate: 忽略（静音模式）
+            duration_sec: 指定静音时长（秒），如果不提供则按文本长度估算
+
+        Returns:
+            (audio_path, empty_cues_dict) 元组
+        """
+        if duration_sec is None:
+            # 估算时长：中文 4 字/秒
+            duration_sec = max(len(text) / 4.0, 1.0)
+
+        logger.info(f"[TTS] Generating silent audio: {duration_sec:.1f}s → {output_path}")
+
+        os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
+
+        # 使用 ffmpeg 生成静音音频
+        proc = await asyncio.create_subprocess_exec(
+            "ffmpeg", "-y",
+            "-f", "lavfi",
+            "-i", f"anullsrc=r=44100:cl=mono",
+            "-t", str(duration_sec),
+            "-c:a", "libmp3lame",
+            "-q:a", "4",
+            output_path,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await proc.communicate()
+
+        # P9: 检查 ffmpeg 返回码，失败时抛出异常而非静默返回
+        if proc.returncode != 0:
+            err_msg = stderr.decode(errors="replace")[:500] if stderr else ""
+            raise RuntimeError(
+                f"[TTS] ffmpeg silent generation failed (code {proc.returncode}): {err_msg}"
+            )
+
+        # 返回空 cues（用 None 而非 {}，让下游正确识别为无 SubMaker 可用）
+        return output_path, None

package/core/audio/voices.py

@@ -0,0 +1,330 @@
+"""core.audio.voices — 音色目录与兼容性
+
+基于 edge_tts.list_voices() 动态加载全部可用音色，按项目 13 种 i18n 语言分组，
+并内置跨语言兼容性矩阵与「文本脚本 → 兼容性」检测，供后端 /api/voices* 接口与
+任务创建时的 voice/text 校验复用。
+
+设计背景见 docs/voice_selector_design.md。核心结论：
+- 同一文字体系内互通，跨体系基本不通（CJK→en 是唯一例外）。
+- edge-tts 跨体系调用直接抛异常，无降级，因此必须前置校验。
+"""
+
+import asyncio
+import logging
+import re
+
+import edge_tts
+
+logger = logging.getLogger(__name__)
+
+# ═══════════════════════════════════════════════════
+# 项目语言定义
+# ═══════════════════════════════════════════════════
+
+# code -> (展示名, 文字体系)
+# 文字体系: cjk / latin / cyrillic
+PROJECT_LANGUAGES = {
+    "zh": {"label": "中文", "script": "cjk"},
+    "en": {"label": "English", "script": "latin"},
+    "ja": {"label": "日本語", "script": "cjk"},
+    "ko": {"label": "한국어", "script": "cjk"},
+    "ru": {"label": "Русский", "script": "cyrillic"},
+    "de": {"label": "Deutsch", "script": "latin"},
+    "fr": {"label": "Français", "script": "latin"},
+    "nl": {"label": "Nederlands", "script": "latin"},
+    "es": {"label": "Español", "script": "latin"},
+    "pt": {"label": "Português", "script": "latin"},
+    "it": {"label": "Italiano", "script": "latin"},
+    "id": {"label": "Bahasa Indonesia", "script": "latin"},
+    "ms": {"label": "Bahasa Melayu", "script": "latin"},
+}
+
+# 拉丁体系包含的全部项目语言（彼此完全互通）
+_LATIN_LANGS = [c for c, v in PROJECT_LANGUAGES.items() if v["script"] == "latin"]
+
+# ═══════════════════════════════════════════════════
+# 预设试听文本（与音色语言严格匹配）
+# ═══════════════════════════════════════════════════
+
+VOICE_PREVIEW_TEXTS = {
+    "zh": "你好，我是{name}，这是一段音色试听。",
+    "en": "Hello, I'm {name}, this is a voice preview sample.",
+    "ja": "こんにちは、{name}です。これはボイスプレビューです。",
+    "ko": "안녕하세요, 저는 {name}입니다. 이것은 음성 미리보기입니다.",
+    "ru": "Здравствуйте, я {name}, это образец голоса.",
+    "de": "Hallo, ich bin {name}, dies ist eine Sprachvorschau.",
+    "fr": "Bonjour, je suis {name}, ceci est un aperçu vocal.",
+    "nl": "Hallo, ik ben {name}, dit is een stemvoorbeeld.",
+    "es": "Hola, soy {name}, esta es una muestra de voz.",
+    "pt": "Olá, eu sou {name}, esta é uma amostra de voz.",
+    "it": "Ciao, sono {name}, questo è un esempio vocale.",
+    "id": "Halo, saya {name}, ini adalah sampel suara.",
+    "ms": "Helo, saya {name}, ini adalah sampel suara.",
+}
+
+# ═══════════════════════════════════════════════════
+# 兼容性矩阵（语言级）
+# ═══════════════════════════════════════════════════
+# 每个语言可读的目标语言集合（实测结论见设计文档 2.2 节）。
+# 拉丁体系 9 种语言完全互通，故共享同一集合。
+
+_LATIN_COMPAT = list(_LATIN_LANGS)  # 自身 + 其他 8 种拉丁语言
+
+LANG_COMPAT = {
+    "zh": ["zh", "en"],
+    "en": list(_LATIN_COMPAT),
+    "ja": ["ja", "zh", "en"],
+    "ko": ["ko", "zh", "en"],
+    "ru": ["ru"],
+    "de": list(_LATIN_COMPAT),
+    "fr": list(_LATIN_COMPAT),
+    "nl": list(_LATIN_COMPAT),
+    "es": list(_LATIN_COMPAT),
+    "pt": list(_LATIN_COMPAT),
+    "it": list(_LATIN_COMPAT),
+    "id": list(_LATIN_COMPAT),
+    "ms": list(_LATIN_COMPAT),
+}
+
+
+# ═══════════════════════════════════════════════════
+# 文本脚本检测（用于任务提交时校验任意文本）
+# ═══════════════════════════════════════════════════
+
+# 各文字体系对应的可读 voice 语言集合
+_SCRIPT_COMPAT_VOICES = {
+    "zh": {"zh", "ja", "ko"},          # 汉字 → 中/日/韩音色
+    "ja": {"ja"},                       # 假名 → 仅日语音色
+    "ko": {"ko"},                       # 谚文 → 仅韩语音色
+    "latin": set(_LATIN_LANGS) | {"zh", "ja", "ko"},  # 拉丁字母 → 全部拉丁 + CJK(均可读英文)
+    "ru": {"ru"},                       # 西里尔 → 仅俄文
+}
+
+
+def detect_text_script(text: str) -> str:
+    """粗略判断文本的 dominant 文字体系。
+
+    Returns: 'zh' | 'ja' | 'ko' | 'latin' | 'ru' | 'unknown'
+    """
+    if not text or not text.strip():
+        return "unknown"
+    # 优先级：谚文 > 假名 > 汉字 > 西里尔 > 拉丁
+    if re.search(r"[가-힣]", text):
+        return "ko"
+    if re.search(r"[぀-ヿ]", text):
+        return "ja"
+    if re.search(r"[一-鿿]", text):
+        return "zh"
+    if re.search(r"[Ѐ-ӿ]", text):
+        return "ru"
+    if re.search(r"[A-Za-z]", text):
+        return "latin"
+    return "unknown"
+
+
+# ═══════════════════════════════════════════════════
+# voice id 解析
+# ═══════════════════════════════════════════════════
+
+def get_voice_lang(voice_id: str):
+    """从 voice id（如 zh-CN-XiaoxiaoNeural）解析项目语言 code。
+
+    返回 PROJECT_LANGUAGES 中的 code，无法识别时返回 None。
+    """
+    if not voice_id:
+        return None
+    lang_part = voice_id.split("-")[0].lower()
+    return lang_part if lang_part in PROJECT_LANGUAGES else None
+
+
+# ═══════════════════════════════════════════════════
+# 兼容性判定
+# ═══════════════════════════════════════════════════
+
+def is_voice_compatible(voice_id: str, target_lang: str) -> bool:
+    """语言级兼容性：voice 能否朗读 target_lang 语言的内容。"""
+    vlang = get_voice_lang(voice_id)
+    if vlang is None or target_lang not in PROJECT_LANGUAGES:
+        # 未知 voice 或未知目标语言：仅当完全相同时视为兼容
+        return vlang == target_lang
+    supported = LANG_COMPAT.get(vlang, [vlang])
+    return target_lang in supported
+
+
+def is_voice_compatible_with_text(voice_id: str, text: str) -> bool:
+    """文本级兼容性：voice 能否朗读给定文本的 dominant 文字体系。
+
+    用于任务提交时校验（稿件正文已知，创意/诗歌等由 LLM 按页面语言生成）。
+    """
+    vlang = get_voice_lang(voice_id)
+    if vlang is None:
+        return True  # 未知音色不阻断
+    script = detect_text_script(text)
+    allowed = _SCRIPT_COMPAT_VOICES.get(script)
+    if allowed is None:
+        return True  # unknown 脚本不阻断
+    return vlang in allowed
+
+
+# ═══════════════════════════════════════════════════
+# 离线 fallback 目录（edge_tts 不可用时使用）
+# ═══════════════════════════════════════════════════
+
+_FALLBACK_VOICES = [
+    {"id": "zh-CN-XiaoxiaoNeural", "name": "Xiaoxiao", "local_name": "晓晓",
+     "region": "普通话", "region_code": "zh-CN", "gender": "female",
+     "style_tags": ["Warm"], "preview_text": "你好，我是晓晓，这是一段音色试听。", "lang": "zh"},
+    {"id": "zh-CN-YunyangNeural", "name": "Yunyang", "local_name": "云扬",
+     "region": "普通话", "region_code": "zh-CN", "gender": "male",
+     "style_tags": ["Professional"], "preview_text": "你好，我是云扬，这是一段音色试听。", "lang": "zh"},
+    {"id": "zh-CN-XiaoyiNeural", "name": "Xiaoyi", "local_name": "小艺",
+     "region": "普通话", "region_code": "zh-CN", "gender": "female",
+     "style_tags": ["Lively"], "preview_text": "你好，我是小艺，这是一段音色试听。", "lang": "zh"},
+    {"id": "zh-CN-YunxiNeural", "name": "Yunxi", "local_name": "云希",
+     "region": "普通话", "region_code": "zh-CN", "gender": "male",
+     "style_tags": ["Sunshine"], "preview_text": "你好，我是云希，这是一段音色试听。", "lang": "zh"},
+]
+
+
+def _build_fallback_catalog() -> dict:
+    return {
+        "languages": [
+            {"code": "zh", "label": "中文", "count": len(_FALLBACK_VOICES), "voices": _FALLBACK_VOICES}
+        ],
+        "compat_hint": LANG_COMPAT,
+        "fallback": True,
+    }
+
+
+# ═══════════════════════════════════════════════════
+# 目录构建
+# ═══════════════════════════════════════════════════
+
+def _region_label(locale: str, lang: str) -> str:
+    """生成 region 展示名。"""
+    if lang == "zh":
+        if locale.startswith("zh-HK"):
+            return "粤语"
+        if locale.startswith("zh-TW"):
+            return "台湾"
+        return "普通话"
+    # 其它语言直接用 locale 代码（如 en-US / es-MX），准确且无歧义
+    return locale
+
+
+def _voice_to_dict(v: dict) -> dict | None:
+    """将 edge_tts 单条 voice 转为目录条目，非项目语言返回 None。"""
+    short = v.get("ShortName", "")
+    if not short:
+        return None
+    lang_part = short.split("-")[0].lower()
+    if lang_part not in PROJECT_LANGUAGES:
+        return None  # 跳过非项目语言（如 ar/fa/hi 等）
+
+    locale = v.get("Locale", "")
+    gender = "female" if str(v.get("Gender", "")).lower() == "female" else "male"
+    name = short.split("-")[-1].replace("Neural", "")
+    region_label = _region_label(locale, lang_part)
+
+    tag = v.get("VoiceTag", {}) or {}
+    personalities = list(tag.get("VoicePersonalities", []) or [])
+    categories = list(tag.get("ContentCategories", []) or [])
+    style_tags = personalities + categories
+
+    preview = VOICE_PREVIEW_TEXTS.get(lang_part, VOICE_PREVIEW_TEXTS["zh"]).format(name=name)
+
+    return {
+        "id": short,
+        "name": name,
+        "local_name": name,
+        "region": region_label,
+        "region_code": locale,
+        "gender": gender,
+        "style_tags": style_tags,
+        "preview_text": preview,
+        "lang": lang_part,
+    }
+
+
+async def load_voice_catalog(force: bool = False) -> dict:
+    """异步加载并构建分组音色目录，结果缓存到模块级变量。"""
+    global _VOICE_CATALOG, _VOICE_INDEX
+    if _VOICE_CATALOG is not None and not force:
+        return _VOICE_CATALOG
+
+    try:
+        raw = await edge_tts.list_voices()
+    except Exception as e:
+        logger.warning(f"[Voices] edge_tts.list_voices failed ({e}); using fallback catalog")
+        _VOICE_CATALOG = _build_fallback_catalog()
+        _VOICE_INDEX = {v["id"]: v for v in _FALLBACK_VOICES}
+        return _VOICE_CATALOG
+
+    if not raw:
+        _VOICE_CATALOG = _build_fallback_catalog()
+        _VOICE_INDEX = {v["id"]: v for v in _FALLBACK_VOICES}
+        return _VOICE_CATALOG
+
+    # 按语言分组
+    groups: dict[str, list] = {code: [] for code in PROJECT_LANGUAGES}
+    index: dict[str, dict] = {}
+    for v in raw:
+        entry = _voice_to_dict(v)
+        if entry is None:
+            continue
+        groups[entry["lang"]].append(entry)
+        index[entry["id"]] = entry
+
+    languages = []
+    for code, voices in groups.items():
+        if not voices:
+            continue
+        # 同语言内按 gender 再按 name 排序，体验更一致
+        voices.sort(key=lambda x: (x["gender"] != "female", x["name"].lower()))
+        languages.append({
+            "code": code,
+            "label": PROJECT_LANGUAGES[code]["label"],
+            "count": len(voices),
+            "voices": voices,
+        })
+
+    # 保持设计文档约定的高频语言顺序
+    _order = ["zh", "en", "ja", "ko", "ru", "es", "fr", "de", "nl", "pt", "it", "id", "ms"]
+    languages.sort(key=lambda g: _order.index(g["code"]) if g["code"] in _order else 99)
+
+    _VOICE_CATALOG = {
+        "languages": languages,
+        "compat_hint": LANG_COMPAT,
+        "fallback": False,
+    }
+    _VOICE_INDEX = index
+    logger.info(f"[Voices] Loaded catalog: {sum(g['count'] for g in languages)} voices across {len(languages)} languages")
+    return _VOICE_CATALOG
+
+
+def get_voice_catalog() -> dict:
+    """同步获取目录（已在服务启动时加载；未加载时返回 fallback 避免崩溃）。"""
+    if _VOICE_CATALOG is None:
+        logger.warning("[Voices] Catalog not loaded yet; returning fallback")
+        return _build_fallback_catalog()
+    return _VOICE_CATALOG
+
+
+def get_voice_by_id(voice_id: str) -> dict | None:
+    """按 id 查询单个音色条目。"""
+    if _VOICE_INDEX is None:
+        get_voice_catalog()
+    return _VOICE_INDEX.get(voice_id)
+
+
+# 模块级缓存
+_VOICE_CATALOG: dict | None = None
+_VOICE_INDEX: dict | None = None
+
+
+def warmup_voice_catalog():
+    """在同步上下文（如程序导入时）预加载目录。失败不抛异常。"""
+    try:
+        asyncio.run(load_voice_catalog())
+    except Exception as e:
+        logger.warning(f"[Voices] warmup failed ({e}); will use fallback")

package/core/compositor/__init__.py

@@ -0,0 +1,6 @@
+"""core.compositor — 视频拼接层"""
+
+from core.compositor.concatenator import VideoConcatenator
+from core.compositor.processor import VideoProcessor
+
+__all__ = ["VideoConcatenator", "VideoProcessor"]