remotion-claude-agent-demo 0.1.0

package/templates/.claude/skills/video-preflight-check/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: video-preflight-check
+version: 1.0.0
+description: 视频预检技能。在渲染前检查音视频同步、字幕覆盖、时长合理性等质量问题。
+triggers:
+  - 视频检查
+  - 预检
+  - 质量检查
+  - preflight
+tools:
+  - Read
+  - Bash
+---
+
+# 视频预检技能 (Video Preflight Check)
+
+在视频渲染前进行全面质量检查，提前发现并修复问题，避免渲染后才发现错误。
+
+## 检查项目清单
+
+| 检查项 | 说明 | 严重程度 |
+|--------|------|---------|
+| 音视频同步 | 场景时长是否匹配音频时长 | 🔴 严重 |
+| 字幕覆盖 | 是否有无字幕的语音片段 | 🟡 警告 |
+| 长静默检测 | 是否有超过2秒的无内容等待 | 🟡 警告 |
+| 文件完整性 | 所有引用的资源文件是否存在 | 🔴 严重 |
+| 时长合理性 | 总时长是否在预期范围内 | 🟢 提示 |
+| 过渡平滑性 | 场景间是否有过渡重叠 | 🟢 提示 |
+
+## 检查脚本
+
+### 1. 音视频同步检查
+
+```typescript
+// scripts/preflight-check.ts
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface CheckResult {
+  passed: boolean;
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+  details?: string;
+}
+
+const FPS = 30;
+const BUFFER_TOLERANCE = 1.5; // 允许的缓冲误差（秒）
+
+// 解析VTT获取音频时长
+function getAudioDuration(vttPath: string): number {
+  const content = fs.readFileSync(vttPath, 'utf-8');
+  let maxEndTime = 0;
+
+  const matches = content.matchAll(/(\d{2}):(\d{2}):(\d{2})[,\.](\d{3})\s*-->\s*(\d{2}):(\d{2}):(\d{2})[,\.](\d{3})/g);
+
+  for (const match of matches) {
+    const endTime =
+      parseInt(match[5]) * 3600 +
+      parseInt(match[6]) * 60 +
+      parseInt(match[7]) +
+      parseInt(match[8]) / 1000;
+    maxEndTime = Math.max(maxEndTime, endTime);
+  }
+
+  return maxEndTime;
+}
+
+// 检查音视频同步
+function checkAudioVideoSync(scenes: Record<string, { duration: number }>, vttDir: string): CheckResult[] {
+  const results: CheckResult[] = [];
+
+  const vttFiles = fs.readdirSync(vttDir).filter(f => f.endsWith('.vtt'));
+
+  for (const vttFile of vttFiles) {
+    const sceneName = vttFile.replace(/^seg_\d+_/, '').replace('.vtt', '');
+    const scene = scenes[sceneName];
+
+    if (!scene) {
+      results.push({
+        passed: false,
+        severity: 'warning',
+        message: `未找到场景配置: ${sceneName}`,
+      });
+      continue;
+    }
+
+    const audioDuration = getAudioDuration(path.join(vttDir, vttFile));
+    const sceneDuration = scene.duration / FPS;
+    const diff = sceneDuration - audioDuration;
+
+    if (diff < 0) {
+      // 场景时长小于音频时长 - 音频会被截断
+      results.push({
+        passed: false,
+        severity: 'error',
+        message: `🔴 [${sceneName}] 音频被截断！`,
+        details: `场景时长: ${sceneDuration.toFixed(2)}s, 音频时长: ${audioDuration.toFixed(2)}s, 差值: ${diff.toFixed(2)}s`,
+      });
+    } else if (diff > BUFFER_TOLERANCE) {
+      // 场景时长比音频长太多 - 会有等待
+      results.push({
+        passed: false,
+        severity: 'warning',
+        message: `🟡 [${sceneName}] 等待时间过长`,
+        details: `场景时长: ${sceneDuration.toFixed(2)}s, 音频时长: ${audioDuration.toFixed(2)}s, 等待: ${diff.toFixed(2)}s`,
+      });
+    } else {
+      results.push({
+        passed: true,
+        severity: 'info',
+        message: `✅ [${sceneName}] 同步正常`,
+        details: `场景: ${sceneDuration.toFixed(2)}s, 音频: ${audioDuration.toFixed(2)}s`,
+      });
+    }
+  }
+
+  return results;
+}
+```
+
+### 2. 字幕覆盖检查
+
+```typescript
+// 检查字幕是否覆盖所有语音
+function checkSubtitleCoverage(
+  subtitles: Record<string, Array<{ start: number; end: number; text: string }>>,
+  scenes: Record<string, { start: number; duration: number }>
+): CheckResult[] {
+  const results: CheckResult[] = [];
+
+  for (const [sceneName, cues] of Object.entries(subtitles)) {
+    const scene = scenes[sceneName];
+    if (!scene) continue;
+
+    // 计算字幕覆盖率
+    let coveredFrames = 0;
+    for (const cue of cues) {
+      coveredFrames += cue.end - cue.start;
+    }
+
+    const coverage = coveredFrames / scene.duration;
+
+    if (coverage < 0.5) {
+      results.push({
+        passed: false,
+        severity: 'warning',
+        message: `🟡 [${sceneName}] 字幕覆盖率低: ${(coverage * 100).toFixed(1)}%`,
+      });
+    } else {
+      results.push({
+        passed: true,
+        severity: 'info',
+        message: `✅ [${sceneName}] 字幕覆盖率: ${(coverage * 100).toFixed(1)}%`,
+      });
+    }
+
+    // 检查字幕间隙
+    const sortedCues = [...cues].sort((a, b) => a.start - b.start);
+    for (let i = 1; i < sortedCues.length; i++) {
+      const gap = sortedCues[i].start - sortedCues[i - 1].end;
+      if (gap > FPS * 2) { // 超过2秒间隙
+        results.push({
+          passed: false,
+          severity: 'warning',
+          message: `🟡 [${sceneName}] 字幕间隙过大: ${(gap / FPS).toFixed(1)}s`,
+          details: `在 "${sortedCues[i - 1].text}" 和 "${sortedCues[i].text}" 之间`,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+```
+
+### 3. 文件完整性检查
+
+```typescript
+// 检查所有引用的文件是否存在
+function checkFileIntegrity(projectDir: string): CheckResult[] {
+  const results: CheckResult[] = [];
+
+  const requiredDirs = [
+    'public/voices',
+    'src/components',
+  ];
+
+  for (const dir of requiredDirs) {
+    const fullPath = path.join(projectDir, dir);
+    if (!fs.existsSync(fullPath)) {
+      results.push({
+        passed: false,
+        severity: 'error',
+        message: `🔴 目录不存在: ${dir}`,
+      });
+    }
+  }
+
+  // 检查音频文件
+  const voicesDir = path.join(projectDir, 'public/voices');
+  if (fs.existsSync(voicesDir)) {
+    const mp3Files = fs.readdirSync(voicesDir).filter(f => f.endsWith('.mp3'));
+    const vttFiles = fs.readdirSync(voicesDir).filter(f => f.endsWith('.vtt'));
+
+    for (const mp3 of mp3Files) {
+      const vtt = mp3.replace('.mp3', '.vtt');
+      if (!vttFiles.includes(vtt)) {
+        results.push({
+          passed: false,
+          severity: 'warning',
+          message: `🟡 缺少字幕文件: ${vtt}`,
+        });
+      }
+    }
+
+    results.push({
+      passed: true,
+      severity: 'info',
+      message: `✅ 音频文件: ${mp3Files.length} 个, 字幕文件: ${vttFiles.length} 个`,
+    });
+  }
+
+  return results;
+}
+```
+
+### 4. 运行完整检查
+
+```typescript
+function runPreflightCheck(projectDir: string, scenes: any, subtitles: any): void {
+  console.log('\n🔍 视频预检开始...\n');
+  console.log('═'.repeat(60));
+
+  let hasErrors = false;
+  let hasWarnings = false;
+
+  // 1. 文件完整性
+  console.log('\n📁 文件完整性检查');
+  console.log('-'.repeat(40));
+  const fileResults = checkFileIntegrity(projectDir);
+  for (const r of fileResults) {
+    console.log(r.message);
+    if (r.details) console.log(`   ${r.details}`);
+    if (r.severity === 'error') hasErrors = true;
+    if (r.severity === 'warning') hasWarnings = true;
+  }
+
+  // 2. 音视频同步
+  console.log('\n🎵 音视频同步检查');
+  console.log('-'.repeat(40));
+  const syncResults = checkAudioVideoSync(scenes, path.join(projectDir, 'public/voices'));
+  for (const r of syncResults) {
+    console.log(r.message);
+    if (r.details) console.log(`   ${r.details}`);
+    if (r.severity === 'error') hasErrors = true;
+    if (r.severity === 'warning') hasWarnings = true;
+  }
+
+  // 3. 字幕覆盖
+  console.log('\n📝 字幕覆盖检查');
+  console.log('-'.repeat(40));
+  const subResults = checkSubtitleCoverage(subtitles, scenes);
+  for (const r of subResults) {
+    console.log(r.message);
+    if (r.details) console.log(`   ${r.details}`);
+    if (r.severity === 'warning') hasWarnings = true;
+  }
+
+  // 结果汇总
+  console.log('\n' + '═'.repeat(60));
+  if (hasErrors) {
+    console.log('❌ 预检失败 - 存在严重问题，请修复后再渲染');
+    process.exit(1);
+  } else if (hasWarnings) {
+    console.log('⚠️  预检通过（有警告） - 建议检查后再渲染');
+  } else {
+    console.log('✅ 预检通过 - 可以开始渲染');
+  }
+  console.log('═'.repeat(60) + '\n');
+}
+```
+
+## 使用方法
+
+### 命令行运行
+
+```bash
+# 在项目目录下运行
+npx ts-node scripts/preflight-check.ts
+
+# 或添加到 package.json
+{
+  "scripts": {
+    "preflight": "ts-node scripts/preflight-check.ts",
+    "render": "npm run preflight && remotion render src/index.ts MyVideo out/video.mp4"
+  }
+}
+```
+
+### 输出示例
+
+```
+🔍 视频预检开始...
+
+════════════════════════════════════════════════════════════
+
+📁 文件完整性检查
+----------------------------------------
+✅ 音频文件: 9 个, 字幕文件: 9 个
+
+🎵 音视频同步检查
+----------------------------------------
+✅ [hook] 同步正常
+   场景: 9.83s, 音频: 8.86s
+✅ [intro] 同步正常
+   场景: 13.37s, 音频: 12.66s
+🟡 [demo] 等待时间过长
+   场景: 25.00s, 音频: 15.33s, 等待: 9.67s
+
+📝 字幕覆盖检查
+----------------------------------------
+✅ [hook] 字幕覆盖率: 85.2%
+🟡 [demo] 字幕覆盖率: 45.3%
+
+════════════════════════════════════════════════════════════
+⚠️  预检通过（有警告） - 建议检查后再渲染
+════════════════════════════════════════════════════════════
+```
+
+## 集成到工作流
+
+在渲染前自动运行预检：
+
+```typescript
+// 在 crafter agent 中
+async function renderVideo() {
+  // 1. 运行预检
+  const preflightResult = await runPreflightCheck(projectDir, SCENES, SUBTITLES);
+
+  if (preflightResult.hasErrors) {
+    throw new Error('预检失败，请先修复问题');
+  }
+
+  if (preflightResult.hasWarnings) {
+    // 询问用户是否继续
+    const shouldContinue = await askUser('存在警告，是否继续渲染？');
+    if (!shouldContinue) return;
+  }
+
+  // 2. 开始渲染
+  await exec('npx remotion render ...');
+}
+```

package/templates/.claude/skills/voice-synthesizer/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: voice-synthesizer
+description: 语音合成技能。使用阿里云 cosyvoice-v3-flash 将文本转为配音音频，支持多语言、多音色、SSML标记。
+---
+
+## 概述
+
+本技能使用阿里云百炼平台的 **cosyvoice-v3-flash** 模型进行语音合成。
+
+**核心特性**:
+- 高质量语音合成（最高 48kHz 采样率）
+- 丰富的预置音色（70+ 种）
+- 支持 SSML 标记语言（精细控制停顿、语速、重音）
+- 支持多语言（中文、英文、粤语、日语、韩语等）
+
+**限流**: 3 RPS（每秒请求数）
+
+## 环境配置
+
+### 1. 环境检查（先确认再操作）
+
+如未安装 Python（`python`/`python3` 命令不存在），需要先安装 Python 3.9+，再继续后续步骤。
+
+如系统仅提供 `python3`，将下方命令中的 `python` 替换为 `python3`。
+
+```bash
+# 检查 Python 版本（建议 3.9+）
+python --version
+
+# 检查 pip 是否可用
+python -m pip --version
+
+# 检查是否已有依赖（已安装则无需重复装）
+python -m pip show dashscope python-dotenv
+```
+
+如未安装 `pip`，先执行：
+```bash
+python -m ensurepip --upgrade
+```
+
+如 `pip` 版本过低，先升级：
+```bash
+python -m pip install --upgrade pip
+```
+
+### 2. 安装依赖（仅在缺失时）
+
+```bash
+pip install dashscope python-dotenv
+```
+
+### 3. 配置 API Key（先检查是否已配置）
+
+**方式 1: 环境变量**
+```bash
+export DASHSCOPE_API_KEY=your-api-key-here
+```
+
+**方式 2: .env 配置文件（推荐）**
+
+先检查 `.env` 是否已存在：
+```bash
+ls -a | grep -E '^\.env$'
+```
+
+如果存在 `.env`，再检查是否已配置 `DASHSCOPE_API_KEY`（无输出表示未配置）：
+```bash
+grep -E '^DASHSCOPE_API_KEY=' .env
+```
+
+如果 `.env` 不存在或未配置 `DASHSCOPE_API_KEY`，需要**手动补充配置**（不要跳过）：
+```env
+DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx
+```
+
+## 基础用法
+
+### 单个文本合成
+
+```python
+import dashscope
+from dashscope.audio.tts_v2 import SpeechSynthesizer
+import os
+
+dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
+
+# 每次调用需重新实例化
+synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash", voice="longanyang")
+audio = synthesizer.call("今天天气怎么样？")
+
+with open('output.mp3', 'wb') as f:
+    f.write(audio)
+```
+
+### 批量合成
+
+```python
+segments = [
+    {"id": "seg_01", "text": "欢迎使用我们的产品"},
+    {"id": "seg_02", "text": "首先，让我们看看主界面"},
+]
+
+for seg in segments:
+    synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash", voice="longanyang")
+    audio = synthesizer.call(seg["text"])
+    with open(f"./voices/{seg['id']}.mp3", 'wb') as f:
+        f.write(audio)
+```
+
+## 推荐音色
+
+### 社交陪伴（标杆音色，支持Instruct）
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙安洋 | longanyang | 阳光大男孩 | 20~30岁 |
+| 龙安欢 | longanhuan | 欢脱元气女 | 20~30岁 |
+
+### 社交陪伴（通用）
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙橙 | longcheng_v3 | 智慧青年男 | 20~25岁 |
+| 龙泽 | longze_v3 | 温暖元气男 | 25~30岁 |
+| 龙哲 | longzhe_v3 | 呆板大暖男 | 25~30岁 |
+| 龙颜 | longyan_v3 | 温暖春风女 | 30~35岁 |
+| 龙星 | longxing_v3 | 温婉邻家女 | 20~25岁 |
+| 龙天 | longtian_v3 | 磁性理智男 | 30~35岁 |
+| 龙婉 | longwan_v3 | 细腻柔声女 | 20~30岁 |
+| 龙嫱 | longqiang_v3 | 浪漫风情女 | 30~35岁 |
+| 龙菲菲 | longfeifei_v3 | 甜美娇气女 | 20~25岁 |
+| 龙浩 | longhao_v3 | 多情忧郁男 | 30~35岁 |
+| 龙安柔 | longanrou_v3 | 温柔闺蜜女 | 20~35岁 |
+| 龙寒 | longhan_v3 | 温暖痴情男 | 30~35岁 |
+| 龙安智 | longanzhi_v3 | 睿智轻熟男 | 25~35岁 |
+| 龙安灵 | longanling_v3 | 思维灵动女 | 20~30岁 |
+| 龙安雅 | longanya_v3 | 高雅气质女 | 25~35岁 |
+| 龙安亲 | longanqin_v3 | 亲和活泼女 | 20~25岁 |
+
+### 语音助手
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙小淳 | longxiaochun_v3 | 知性积极女 | 25~30岁 |
+| 龙小夏 | longxiaoxia_v3 | 沉稳权威女 | 25~30岁 |
+| YUMI | longyumi_v3 | 正经青年女 | 20~25岁 |
+| 龙安昀 | longanyun_v3 | 居家暖男 | 30~35岁 |
+| 龙安温 | longanwen_v3 | 优雅知性女 | 25~35岁 |
+| 龙安莉 | longanli_v3 | 利落从容女 | 25~35岁 |
+| 龙安朗 | longanlang_v3 | 清爽利落男 | 20~25岁 |
+| 龙应沐 | longyingmu_v3 | 优雅知性女 | 25~30岁 |
+
+### 有声书
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙三叔 | longsanshu_v3 | 沉稳质感男 | 25~45岁 |
+| 龙媛 | longyuan_v3 | 温暖治愈女 | 35~40岁 |
+| 龙悦 | longyue_v3 | 温暖磁性女 | 30~35岁 |
+| 龙修 | longxiu_v3 | 博才说书男 | 25~35岁 |
+| 龙楠 | longnan_v3 | 睿智青年男 | 25~30岁 |
+| 龙婉君 | longwanjun_v3 | 细腻柔声女 | 20~30岁 |
+| 龙逸尘 | longyichen_v3 | 洒脱活力男 | 20~30岁 |
+| 龙老伯 | longlaobo_v3 | 沧桑岁月爷 | 60岁以上 |
+| 龙老姨 | longlaoyi_v3 | 烟火从容阿姨 | 60岁以上 |
+
+### 新闻播报
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙书 | longshu_v3 | 沉稳青年男 | 20~25岁 |
+| Bella3.0 | loongbella_v3 | 精准干练女 | 25~30岁 |
+
+### 客服
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙应询 | longyingxun_v3 | 年轻青涩男 | 20~25岁 |
+| 龙应静 | longyingjing_v3 | 低调冷静女（支持时间戳） | 25~35岁 |
+| 龙应聆 | longyingling_v3 | 温和共情女 | 25~30岁 |
+| 龙应桃 | longyingtao_v3 | 温柔淡定女 | 25~30岁 |
+
+### 直播带货
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙应笑 | longyingxiao_v3 | 清甜推销女 | 20~25岁 |
+| 龙安宣 | longanxuan_v3 | 经典直播女 | 30~40岁 |
+
+### 童声
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙呼呼 | longhuhu_v3 | 天真烂漫女童（支持Instruct） | 6~10岁 |
+
+### 短视频配音
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙机器 | longjiqi_v3 | 呆萌机器人 | 20~30岁 |
+| 龙猴哥 | longhouge_v3 | 经典猴哥 | 20~25岁 |
+| 龙黛玉 | longdaiyu_v3 | 娇率才女音 | 15~25岁 |
+
+### 诗词朗诵
+
+| 名称 | voice参数 | 特点 | 年龄 |
+|------|-----------|------|------|
+| 龙飞 | longfei_v3 | 热血磁性男 | 30~35岁 |
+
+### 方言
+
+| 名称 | voice参数 | 特点 | 语言 |
+|------|-----------|------|------|
+| 龙嘉怡 | longjiayi_v3 | 知性粤语女 | 粤语 |
+| 龙安粤 | longanyue_v3 | 欢脱粤语男 | 粤语 |
+| 龙老铁 | longlaotie_v3 | 东北直率男 | 东北话 |
+| 龙陕哥 | longshange_v3 | 原味陕北男 | 陕西话 |
+| 龙安闽 | longanmin_v3 | 清纯萝莉女 | 闽南话 |
+
+### 出海营销
+
+| 名称 | voice参数 | 特点 | 语言 |
+|------|-----------|------|------|
+| loongkyong | loongkyong_v3 | 韩语女 | 韩语 |
+| loongtomoka | loongtomoka_v3 | 日语女 | 日语 |
+
+## 高级参数
+
+### 音频格式
+
+```python
+from dashscope.audio.tts_v2 import AudioFormat
+
+synthesizer = SpeechSynthesizer(
+    model="cosyvoice-v3-flash",
+    voice="longanyang",
+    format=AudioFormat.MP3_22050HZ_MONO_256KBPS  # 默认
+)
+```
+
+可选格式:
+- `MP3_22050HZ_MONO_256KBPS` (默认)
+- `MP3_48000HZ_MONO_256KBPS` (高音质)
+- `WAV_22050HZ_MONO_16BIT`
+- `PCM_22050HZ_MONO_16BIT`
+
+### 语速、音调、音量
+
+```python
+synthesizer = SpeechSynthesizer(
+    model="cosyvoice-v3-flash",
+    voice="longanyang",
+    speech_rate=1.1,    # 语速 [0.5, 2.0]，默认 1.0
+    pitch_rate=1.05,    # 音调 [0.5, 2.0]，默认 1.0
+    volume=60           # 音量 [0, 100]，默认 50
+)
+```
+
+## CLI 工具使用
+
+### 单个文本合成
+
+```bash
+python .claude/skills/voice-synthesizer/scripts/tts_cli.py \
+  --text "今天天气怎么样" \
+  --voice longanyang \
+  --output ./voices/output.mp3
+```
+
+### 批量合成
+
+```bash
+python .claude/skills/voice-synthesizer/scripts/tts_cli.py \
+  --batch segments.json \
+  --output-dir ./voices/
+```
+
+`segments.json` 格式:
+```json
+[
+  {"id": "seg_01", "text": "欢迎使用我们的产品"},
+  {"id": "seg_02", "text": "首先，让我们看看主界面"}
+]
+```
+
+## 注意事项
+
+1. **API Key 安全**: 使用环境变量存储，不提交到代码仓库
+2. **限流控制**: 3 RPS，批量合成时需要控制并发
+3. **长文本处理**: 建议分段合成，每段不超过 500 字
+4. **文本长度限制**: 单次最多 20,000 字符
+
+## 相关文档
+
+- [阿里云 CosyVoice 官方文档](https://help.aliyun.com/zh/model-studio/developer-reference/cosyvoice-large-speech-synthesis)