aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/video_workflow/google_models.py

@@ -0,0 +1,278 @@
+"""Google Cloud (Vertex AI) models used by the video workflow.
+
+Every model call in the workflow goes through here, so the pipeline has one
+place that knows endpoints, credentials and response shapes:
+
+- Gemini (native :generateContent) — reads images and scripts, writes the
+  edit plan with a JSON response schema.
+- Gemini TTS (gemini-2.5-flash-tts) — narration. Returns bare 24 kHz / 16-bit
+  mono PCM, wrapped here in a WAV header. The same request shape is already in
+  production in Arthera's voice routes.
+- Veo — generated shots. Paid per second, so it is only reachable through
+  `generate_shot(..., confirmed=True)`; see pipeline.render_video.
+
+Credentials: Application Default Credentials plus VERTEX_PROJECT (or
+GOOGLE_CLOUD_PROJECT). No API keys are read here.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import shutil
+import struct
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+DEFAULT_PLANNER_MODEL = "gemini-3.8-flash"
+DEFAULT_TTS_MODEL = "gemini-2.5-flash-tts"
+DEFAULT_TTS_VOICE = "Aoede"
+# Listed in the Vertex publisher catalog (checked 2026-09-14). Generation itself
+# has not been exercised from this workflow yet: it costs money per second.
+# veo-3.0-* is not reachable from our production project (404, checked 2026-09-15); Veo 3.1 is.
+DEFAULT_VEO_MODEL = "veo-3.1-fast-generate-001"
+
+MAX_INLINE_IMAGE_BYTES = 4 * 1024 * 1024
+IMAGE_SUFFIX_MIME = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp"}
+
+
+class GoogleModelError(RuntimeError):
+    """A Google Cloud model call failed; the message says which and why."""
+
+
+def _adc_config_project() -> str:
+    """The project named on disk by `gcloud auth application-default login`.
+
+    `google.auth.default()` finds the project for a user credential by running
+    `gcloud`, so it returns nothing whenever gcloud is not on PATH — which is
+    every run launched from a desktop app rather than a shell. Both files it
+    would consult are plain text, so they are read directly instead.
+    """
+    config = Path(os.getenv("CLOUDSDK_CONFIG") or Path.home() / ".config" / "gcloud")
+    try:
+        adc = json.loads((config / "application_default_credentials.json").read_text())
+        if adc.get("quota_project_id"):
+            return str(adc["quota_project_id"])
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        for line in (config / "configurations" / "config_default").read_text().splitlines():
+            name, _, value = line.partition("=")
+            if name.strip() == "project" and value.strip():
+                return value.strip()
+    except Exception:  # noqa: BLE001
+        pass
+    return ""
+
+
+def vertex_project() -> str:
+    """The Google Cloud project: VERTEX_PROJECT, GOOGLE_CLOUD_PROJECT, then what ADC names.
+
+    A desktop app launches this workflow without the shell's environment, so
+    the project configured with `gcloud` is the useful last resort.
+    """
+    configured = os.getenv("VERTEX_PROJECT") or os.getenv("GOOGLE_CLOUD_PROJECT", "")
+    if configured:
+        return configured
+    try:
+        import google.auth
+
+        _, project = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
+        if project:
+            return str(project)
+    except Exception:  # noqa: BLE001
+        pass
+    return _adc_config_project()
+
+
+def _access_token() -> str:
+    try:
+        import google.auth
+        from google.auth.transport.requests import Request as GoogleAuthRequest
+
+        creds, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
+        creds.refresh(GoogleAuthRequest())
+    except Exception as exc:  # noqa: BLE001
+        raise GoogleModelError(f"Google Cloud credentials unavailable (run `gcloud auth application-default login`): {exc}") from exc
+    if not creds.token:
+        raise GoogleModelError("Google Cloud credentials returned no access token")
+    return creds.token
+
+
+# Vertex's shared endpoints shed load: 429 and 503 mean "busy now", not
+# "wrong request", and a plan that took a minute to set up should not be
+# thrown away because of one of them.
+_BUSY_STATUSES = frozenset({429, 503})
+_BUSY_ATTEMPTS = 4
+_BUSY_BACKOFF = (2.0, 6.0, 15.0)
+
+
+def _explain(status: int, model: str, body: str) -> str:
+    """Say what a refusal means, when Vertex says it in its own vocabulary.
+
+    A project whose billing is suspended is refused with "Lightning dunning
+    decision is deny for project: projects/<number>" — internal wording that
+    reads like a fault in the request, and sends you looking through code and
+    credentials for something that is not there. It is the billing account.
+    """
+    if status == 403 and "dunning" in body.lower():
+        return (
+            "Google Cloud is refusing this project because of its billing account "
+            "(check for an unpaid balance or a suspended billing account in the "
+            "Cloud console). Nothing is wrong with the request or the credentials."
+        )
+    if status == 403:
+        return f"Google Cloud refused the call to {model}: {body[:300]}"
+    if status == 404:
+        return f"{model} is not available to this project (HTTP 404)"
+    return f"HTTP {status} from {model}: {body[:300]}"
+
+
+def _post(url: str, body: Dict[str, Any], timeout: float) -> Dict[str, Any]:
+    import requests
+
+    project = vertex_project()
+    if not project:
+        raise GoogleModelError(
+            "No Google Cloud project: run `gcloud auth application-default login` "
+            "or set VERTEX_PROJECT"
+        )
+    model = url.rsplit("/", 1)[-1]
+    for attempt in range(_BUSY_ATTEMPTS):
+        response = requests.post(
+            url,
+            headers={"Authorization": f"Bearer {_access_token()}", "Content-Type": "application/json", "x-goog-user-project": project},
+            json=body,
+            timeout=timeout,
+        )
+        if response.status_code == 200:
+            return response.json()
+        if response.status_code in _BUSY_STATUSES and attempt < _BUSY_ATTEMPTS - 1:
+            time.sleep(_BUSY_BACKOFF[attempt])
+            continue
+        if response.status_code in _BUSY_STATUSES:
+            raise GoogleModelError(f"{model} is busy right now (HTTP {response.status_code}); try again in a minute")
+        raise GoogleModelError(_explain(response.status_code, model, response.text))
+    raise GoogleModelError(f"{model} is busy right now; try again in a minute")
+
+
+def _generate_content_url(model: str) -> str:
+    return (
+        f"https://aiplatform.googleapis.com/v1/projects/{vertex_project()}"
+        f"/locations/global/publishers/google/models/{model}:generateContent"
+    )
+
+
+def image_part(path: str) -> Dict[str, Any]:
+    """An inline image part. Large images are downscaled with ffmpeg first."""
+    source = Path(path)
+    mime = IMAGE_SUFFIX_MIME.get(source.suffix.lower())
+    data = source.read_bytes()
+    if mime is None or len(data) > MAX_INLINE_IMAGE_BYTES:
+        if shutil.which("ffmpeg") is None:
+            raise GoogleModelError(f"{source.name}: unsupported or too large, and ffmpeg is not available to convert it")
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "image.jpg"
+            result = subprocess.run(
+                ["ffmpeg", "-y", "-loglevel", "error", "-i", str(source), "-vf", "scale='min(1600,iw)':-2", "-q:v", "3", str(out)],
+                capture_output=True, text=True, timeout=60,
+            )
+            if result.returncode != 0 or not out.exists():
+                raise GoogleModelError(f"{source.name}: could not convert image: {result.stderr[-200:]}")
+            data, mime = out.read_bytes(), "image/jpeg"
+    return {"inlineData": {"mimeType": mime, "data": base64.b64encode(data).decode("ascii")}}
+
+
+def generate_json(
+    parts: List[Dict[str, Any]],
+    response_schema: Dict[str, Any],
+    *,
+    system: str = "",
+    model: Optional[str] = None,
+    timeout: float = 120.0,
+) -> Dict[str, Any]:
+    """Ask Gemini for a JSON object matching `response_schema` (OpenAPI subset)."""
+    body: Dict[str, Any] = {
+        "contents": [{"role": "user", "parts": parts}],
+        "generationConfig": {
+            "responseMimeType": "application/json",
+            "responseSchema": response_schema,
+            "temperature": 0.4,
+        },
+    }
+    if system:
+        body["systemInstruction"] = {"parts": [{"text": system}]}
+    model_id = model or os.getenv("ARIA_VIDEO_PLANNER_MODEL", DEFAULT_PLANNER_MODEL)
+    payload = _post(_generate_content_url(model_id), body, timeout)
+    try:
+        text = "".join(part.get("text", "") for part in payload["candidates"][0]["content"]["parts"])
+        return json.loads(text)
+    except (KeyError, IndexError, json.JSONDecodeError) as exc:
+        raise GoogleModelError(f"{model_id} returned no usable JSON: {str(payload)[:300]}") from exc
+
+
+def _wav_from_pcm(pcm: bytes, sample_rate: int = 24000, channels: int = 1, bits: int = 16) -> bytes:
+    byte_rate = sample_rate * channels * bits // 8
+    block_align = channels * bits // 8
+    header = (
+        b"RIFF" + struct.pack("<I", 36 + len(pcm)) + b"WAVE"
+        + b"fmt " + struct.pack("<IHHIIHH", 16, 1, channels, sample_rate, byte_rate, block_align, bits)
+        + b"data" + struct.pack("<I", len(pcm))
+    )
+    return header + pcm
+
+
+def synthesize_speech(text: str, output_path: str, *, voice: Optional[str] = None, model: Optional[str] = None) -> str:
+    """Narrate `text` with Gemini TTS into a WAV file; returns the path."""
+    text = (text or "").strip()
+    if not text:
+        raise GoogleModelError("Nothing to narrate")
+    model_id = model or os.getenv("ARIA_VIDEO_TTS_MODEL", DEFAULT_TTS_MODEL)
+    body = {
+        "contents": [{"role": "user", "parts": [{"text": text}]}],
+        "generationConfig": {
+            "responseModalities": ["AUDIO"],
+            "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": voice or DEFAULT_TTS_VOICE}}},
+        },
+    }
+    payload = _post(_generate_content_url(model_id), body, timeout=90.0)
+    try:
+        inline = payload["candidates"][0]["content"]["parts"][0]["inlineData"]
+        pcm = base64.b64decode(inline["data"])
+    except (KeyError, IndexError) as exc:
+        raise GoogleModelError(f"{model_id} returned no audio: {str(payload)[:300]}") from exc
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_bytes(_wav_from_pcm(pcm))
+    return str(out)
+
+
+def generate_shot(
+    prompt: str,
+    output_path: str,
+    *,
+    duration_seconds: int,
+    aspect_ratio: str,
+    image_path: Optional[str] = None,
+    model: Optional[str] = None,
+    confirmed: bool = False,
+) -> str:
+    """Generate one shot with Veo. Refuses unless `confirmed` — it is billed per second."""
+    if not confirmed:
+        raise GoogleModelError("Veo generation is paid per second; it needs explicit confirmation")
+    from aria_code.providers.google_video_provider import generate_video_google
+
+    model_id = model or os.getenv("ARIA_VIDEO_VEO_MODEL", DEFAULT_VEO_MODEL)
+    result = generate_video_google(
+        prompt, image_path=image_path, model=model_id, aspect_ratio=aspect_ratio, duration_seconds=duration_seconds,
+        max_wait_seconds=600.0,
+    )
+    if not result.get("success") or not result.get("path"):
+        raise GoogleModelError(f"Veo ({model_id}) failed: {result.get('error') or result}")
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(result["path"], out)
+    return str(out)

aria_code/video_workflow/music/__init__.py

@@ -0,0 +1,5 @@
+"""music package — 视频音乐与音频资产管理服务。"""
+
+from .service import MusicLibraryService, MusicTrackMetadata
+
+__all__ = ["MusicLibraryService", "MusicTrackMetadata"]

aria_code/video_workflow/music/foley_service.py

@@ -0,0 +1,132 @@
+"""foley_service.py — 影视级拟音声效 (Foley SFX) 与转场音效服务。
+
+为视频自动识别并在精确毫秒时间码插入音效：
+- whoosh: 镜头快速推拉或转场切换时的空气扫风声；
+- glint: 金属墨镜反光、高光扫掠或极光破晓时的清脆晶莹音效；
+- impact: 标题出字或产品霸气定格时的低音共振冲击 (Sub-bass impact)；
+- click: 极简机械按键或聚光灯开启声。
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import struct
+import wave
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class FoleyCue:
+    sound_type: str  # "whoosh" | "glint" | "impact" | "click"
+    timestamp_seconds: float
+    volume: float = 0.5
+    duration: float = 0.8
+    description: str = ""
+
+
+class FoleySoundService:
+    """拟音声效编排与程序化生成服务。"""
+
+    @classmethod
+    def generate_cues_for_storyboard(cls, shots: List[Dict[str, Any]]) -> List[FoleyCue]:
+        """依据分镜时序与动作特征自动打点生成音效提示清单。"""
+        cues: List[FoleyCue] = []
+        cursor = 0.0
+
+        for idx, shot in enumerate(shots):
+            dur = float(shot.get("duration", 4.0))
+            prompt = str(shot.get("prompt", "")).lower()
+
+            # 镜头转场处（除首镜头外）插入转场扫风
+            if idx > 0:
+                cues.append(FoleyCue(
+                    sound_type="whoosh",
+                    timestamp_seconds=round(max(0.0, cursor - 0.15), 2),
+                    volume=0.35,
+                    description="Shot transition whoosh",
+                ))
+
+            # 包含光线反光或高光的镜头插入 Glint
+            if any(k in prompt for k in ["sunglasses", "reflection", "flare", "shimmer", "glint", "反光", "高光"]):
+                cues.append(FoleyCue(
+                    sound_type="glint",
+                    timestamp_seconds=round(cursor + dur * 0.4, 2),
+                    volume=0.4,
+                    description="Specular highlight glint shimmer",
+                ))
+
+            # 压轴定格或 Hook 开头插入 Sub-impact
+            if idx == 0 or idx == len(shots) - 1:
+                cues.append(FoleyCue(
+                    sound_type="impact",
+                    timestamp_seconds=round(cursor + 0.2, 2),
+                    volume=0.45,
+                    description="Cinematic low-end keynote presence",
+                ))
+
+            cursor += dur
+
+        return cues
+
+    @classmethod
+    def synthesize_cue_track(
+        cls,
+        cues: List[FoleyCue],
+        total_duration: float,
+        output_path: str,
+        sample_rate: int = 44100,
+    ) -> str:
+        """程序化合成包含所有 Foley 打点音效的独立音轨。"""
+        out_path = Path(output_path)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        total_samples = int(total_duration * sample_rate)
+        samples = [0.0] * total_samples
+
+        for cue in cues:
+            start_sample = int(cue.timestamp_seconds * sample_rate)
+            if start_sample >= total_samples:
+                continue
+
+            cue_samples = int(cue.duration * sample_rate)
+            for s in range(cue_samples):
+                idx = start_sample + s
+                if idx >= total_samples:
+                    break
+
+                t = s / sample_rate
+                # 根据不同音效类型生成对应的正弦频移波形
+                if cue.sound_type == "whoosh":
+                    # 扫频白噪过滤带通效果
+                    freq = 200.0 + 600.0 * math.sin(math.pi * (t / cue.duration))
+                    val = 0.5 * math.sin(2 * math.pi * freq * t) * math.sin(math.pi * (t / cue.duration))
+                elif cue.sound_type == "glint":
+                    # 高频清脆钟音 2400Hz 快速衰减
+                    val = math.sin(2 * math.pi * 2400 * t) * math.exp(-6.0 * t)
+                elif cue.sound_type == "impact":
+                    # 低频 60Hz -> 30Hz 重低音下潜
+                    freq = 65.0 * math.exp(-2.5 * t)
+                    val = math.sin(2 * math.pi * freq * t) * math.exp(-3.0 * t)
+                else:
+                    val = 0.0
+
+                samples[idx] += val * cue.volume
+
+        # 封包为 16-bit 双声道 PCM WAV
+        frames = bytearray()
+        for sample in samples:
+            clamped = int(max(-32767, min(32767, sample * 16000)))
+            frames.extend(struct.pack("<hh", clamped, clamped))
+
+        with wave.open(str(out_path), "wb") as wf:
+            wf.setnchannels(2)
+            wf.setsampwidth(2)
+            wf.setframerate(sample_rate)
+            wf.writeframes(frames)
+
+        return str(out_path)

aria_code/video_workflow/music/service.py

@@ -0,0 +1,212 @@
+"""service.py — 视频背景音乐 (BGM) 与音效智能管理服务。
+
+核心功能：
+1. 情绪与风格智能选曲：根据剧本文案与视觉风格（Keynote发布会、科技极简、萌宠轻快、史诗电影等）
+   自动分析匹配最契合的背景音乐风格。
+2. 免版税与本地音乐库索引：统一管理本地存储 (~/.aria-code/music 或 assets/music) 的免版税音频资产。
+3. 程序化高保真氛围音轨合成 (Procedural Ambient Synth)：零依赖、零外链，可在本地瞬时合成指定时长的
+   苹果发布会质感 44.1kHz 立体声环境背景音轨。
+4. AI 生成式配乐 (MusicGen / Suno) 提示词编排：为后续接入云端生成式音乐大模型提供专业的 Prompt 生成器。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import os
+import struct
+import wave
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MusicTrackMetadata:
+    id: str
+    title: str
+    genre: str  # ambient, electronic, acoustic, orchestral, lofi
+    mood: str   # professional, futuristic, cute, epic, chill
+    bpm: int = 90
+    duration_seconds: float = 30.0
+    file_path: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+    license: str = "Royalty-Free / CC0"
+
+
+class MusicLibraryService:
+    """背景音乐与音频资产管理服务单例。"""
+
+    _instance: Optional[MusicLibraryService] = None
+
+    STYLE_MOOD_MAP = {
+        "apple_keynote": {"genre": "ambient", "mood": "professional", "bpm": 80, "desc": "Apple keynote ambient synthesizer, C major 7th chords, minimalist, spacious, inspiring"},
+        "tech": {"genre": "electronic", "mood": "futuristic", "bpm": 110, "desc": "Modern tech, crisp digital synth plucks, clean bassline, innovation narrative"},
+        "cute": {"genre": "acoustic", "mood": "cute", "bpm": 105, "desc": "Playful acoustic, wooden marimba, ukulele, cheerful, warm, bouncy pet style"},
+        "cinematic": {"genre": "orchestral", "mood": "epic", "bpm": 75, "desc": "Cinematic orchestral swelling, deep cello, expansive cinematic atmosphere"},
+        "chill": {"genre": "lofi", "mood": "chill", "bpm": 85, "desc": "Warm lo-fi chill hip-hop, vinyl crackle, gentle Rhodes piano, relaxing vibe"},
+    }
+
+    def __init__(self, custom_library_dir: Optional[str] = None):
+        self.library_dir = Path(custom_library_dir or os.path.expanduser("~/.aria-code/music"))
+        self.library_dir.mkdir(parents=True, exist_ok=True)
+        self._tracks: Dict[str, MusicTrackMetadata] = {}
+        self._load_local_library()
+
+    @classmethod
+    def get_instance(cls) -> MusicLibraryService:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    def _load_local_library(self) -> None:
+        """扫描本地音乐库目录下的音频文件与元数据。"""
+        meta_file = self.library_dir / "catalog.json"
+        if meta_file.exists():
+            try:
+                data = json.loads(meta_file.read_text(encoding="utf-8"))
+                for item in data.get("tracks", []):
+                    self._tracks[item["id"]] = MusicTrackMetadata(**item)
+            except Exception as exc:
+                logger.warning(f"[MusicLibraryService] Failed to parse {meta_file}: {exc}")
+
+        # 扫描目录下的 mp3 / wav 文件
+        for ext in ("*.mp3", "*.wav", "*.m4a"):
+            for audio_file in self.library_dir.glob(ext):
+                tid = audio_file.stem
+                if tid not in self._tracks:
+                    self._tracks[tid] = MusicTrackMetadata(
+                        id=tid,
+                        title=tid.replace("_", " ").title(),
+                        genre="general",
+                        mood="ambient",
+                        file_path=str(audio_file),
+                    )
+
+    def analyze_script_mood(self, script: str, style: str = "apple_keynote") -> Dict[str, Any]:
+        """根据脚本词汇与视频风格推断配乐情绪与匹配标准。"""
+        script_lower = script.lower()
+        matched_style = style.lower()
+
+        # 关键字启发式推导
+        if any(w in script_lower for w in ["发布会", "keynote", "apple", "旗舰", "pro", "极简", "优雅"]):
+            matched_style = "apple_keynote"
+        elif any(w in script_lower for w in ["猫", "狗", "萌", "可爱", "taco", "cute", "pet", "bunny", "兔"]):
+            matched_style = "cute"
+        elif any(w in script_lower for w in ["芯片", "算法", "ai", "算力", "科技", "智能", "未来"]):
+            matched_style = "tech"
+        elif any(w in script_lower for w in ["震撼", "史诗", "宇宙", "宏大", "征程", "突破"]):
+            matched_style = "cinematic"
+
+        spec = self.STYLE_MOOD_MAP.get(matched_style, self.STYLE_MOOD_MAP["apple_keynote"])
+        return {
+            "style": matched_style,
+            "genre": spec["genre"],
+            "mood": spec["mood"],
+            "target_bpm": spec["bpm"],
+            "ai_prompt": spec["desc"],
+        }
+
+    def match_or_synthesize_bgm(
+        self,
+        script: str,
+        style: str = "apple_keynote",
+        duration_seconds: float = 20.0,
+        output_dir: Optional[str] = None,
+    ) -> str:
+        """获取或合成与脚本最匹配的背景音乐，返回音频文件绝对路径。"""
+        mood_spec = self.analyze_script_mood(script, style)
+        matched_genre = mood_spec["genre"]
+
+        # 1. 如果本地库有匹配的音频文件，优先使用
+        for track in self._tracks.values():
+            if track.genre == matched_genre and track.file_path and os.path.exists(track.file_path):
+                logger.info(f"[MusicLibraryService] Using matched local library track: {track.title}")
+                return track.file_path
+
+        # 2. 如果没有本地预录文件，运行程序化高保真合成 (零依赖快速产出)
+        target_dir = Path(output_dir) if output_dir else self.library_dir
+        target_dir.mkdir(parents=True, exist_ok=True)
+        filename = f"bgm_{mood_spec['style']}_{int(duration_seconds)}s.wav"
+        out_path = target_dir / filename
+
+        if not out_path.exists():
+            logger.info(f"[MusicLibraryService] Synthesizing procedural ambient keynote track ({duration_seconds}s)...")
+            self.synthesize_ambient_synth_bgm(str(out_path), duration_seconds=duration_seconds)
+
+        return str(out_path)
+
+    @classmethod
+    def synthesize_ambient_synth_bgm(
+        cls,
+        output_path: str,
+        duration_seconds: float = 25.0,
+        sample_rate: int = 44100,
+    ) -> str:
+        """纯 Python 程序化合成 44.1kHz 立体声苹果发布会风格环境氛围音轨 (Cmaj7 -> Am9)。"""
+        out_path = Path(output_path)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        total_samples = int(duration_seconds * sample_rate)
+        # 苹果发布会经典和弦走带: Cmaj7 (C, E, G, B) -> Am9 (A, C, E, G, B) -> Fmaj7 -> Gsus4
+        chords = [
+            [261.63, 329.63, 392.00, 493.88],  # Cmaj7
+            [220.00, 261.63, 329.63, 392.00],  # Am7/Am9
+            [174.61, 220.00, 261.63, 329.63],  # Fmaj7
+            [196.00, 261.63, 293.66, 392.00],  # Gsus4
+        ]
+
+        chord_dur = 6.0  # 每个和弦 6 秒展开
+        frames = bytearray()
+
+        for i in range(total_samples):
+            t = i / sample_rate
+            chord_idx = int((t / chord_dur) % len(chords))
+            chord = chords[chord_idx]
+
+            # 和弦内插淡入淡出包络
+            t_in_chord = t % chord_dur
+            env = math.sin(math.pi * min(1.0, t_in_chord / chord_dur)) ** 0.6
+
+            # 整体首尾淡入淡出
+            fade_in = min(1.0, t / 1.5)
+            fade_out = min(1.0, (duration_seconds - t) / 2.0)
+            master_vol = 0.28 * fade_in * fade_out * env
+
+            left_sample = 0.0
+            right_sample = 0.0
+
+            # 4个声音分音合唱 (Chorus & Stereo Detune)
+            for idx, freq in enumerate(chord):
+                # 微音分失谐 (Detuning) 营造空灵大空间感
+                freq_l = freq * (1.0 + 0.0012 * (idx - 1.5))
+                freq_r = freq * (1.0 - 0.0012 * (idx - 1.5))
+
+                phase_l = 2.0 * math.pi * freq_l * t
+                phase_r = 2.0 * math.pi * freq_r * t
+
+                # 正弦基波 + 微弱次泛音 (Warm Ambient)
+                tone_l = 0.7 * math.sin(phase_l) + 0.2 * math.sin(phase_l * 2) + 0.1 * math.sin(phase_l * 0.5)
+                tone_r = 0.7 * math.sin(phase_r) + 0.2 * math.sin(phase_r * 2) + 0.1 * math.sin(phase_r * 0.5)
+
+                # 立体声微向展开
+                pan_bias = (idx / 3.0) - 0.5  # -0.5 ~ +0.5
+                left_sample += tone_l * (0.6 - pan_bias * 0.3)
+                right_sample += tone_r * (0.6 + pan_bias * 0.3)
+
+            # 压限防止削波
+            left_val = int(max(-32767, min(32767, left_sample * master_vol * 12000)))
+            right_val = int(max(-32767, min(32767, right_sample * master_vol * 12000)))
+
+            frames.extend(struct.pack("<hh", left_val, right_val))
+
+        with wave.open(str(out_path), "wb") as wf:
+            wf.setnchannels(2)
+            wf.setsampwidth(2)
+            wf.setframerate(sample_rate)
+            wf.writeframes(frames)
+
+        return str(out_path)