remotion-claude-agent-demo 0.1.0

package/templates/.claude/skills/asset-validator/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: asset-validator
+version: 1.0.0
+description: 素材验证技能。在视频渲染前验证所有素材的完整性和有效性，避免渲染到一半才发现问题。
+triggers:
+  - 素材验证
+  - asset validation
+  - 预检查
+  - preflight
+tools:
+  - Read
+  - Bash
+---
+
+# 素材验证技能 (Asset Validator)
+
+在 Remotion 渲染前自动验证所有素材文件是否存在、格式是否正确、时长是否合理，提前发现问题。
+
+## 核心原理
+
+**问题**: 渲染到一半才发现文件缺失或格式错误，浪费时间。
+
+**解决**: 在渲染前执行完整性检查，问题清单化输出。
+
+## 验证检查项
+
+### 1. 文件存在性检查
+
+```typescript
+interface FileCheck {
+  path: string;
+  exists: boolean;
+  size?: number;
+}
+
+function checkFileExists(filePaths: string[]): FileCheck[] {
+  return filePaths.map(path => ({
+    path,
+    exists: fs.existsSync(path),
+    size: fs.existsSync(path) ? fs.statSync(path).size : undefined,
+  }));
+}
+```
+
+### 2. MP3/VTT 配对检查
+
+```typescript
+function checkAudioSubtitlePairs(voicesDir: string): {
+  missing_vtt: string[];
+  missing_mp3: string[];
+  orphaned_files: string[];
+} {
+  const mp3Files = fs.readdirSync(voicesDir).filter(f => f.endsWith('.mp3'));
+  const vttFiles = fs.readdirSync(voicesDir).filter(f => f.endsWith('.vtt'));
+
+  const missing_vtt: string[] = [];
+  const missing_mp3: string[] = [];
+
+  for (const mp3 of mp3Files) {
+    const vtt = mp3.replace('.mp3', '.vtt');
+    if (!vttFiles.includes(vtt)) {
+      missing_vtt.push(vtt);
+    }
+  }
+
+  for (const vtt of vttFiles) {
+    const mp3 = vtt.replace('.vtt', '.mp3');
+    if (!mp3Files.includes(mp3)) {
+      missing_mp3.push(mp3);
+    }
+  }
+
+  return { missing_vtt, missing_mp3, orphaned_files: [] };
+}
+```
+
+### 3. 音频时长验证
+
+```typescript
+async function getAudioDurationFFProbe(filePath: string): Promise<number> {
+  const { stdout } = await exec(
+    `ffprobe -v error -show_entries format=duration -of csv=p=0 "${filePath}"`
+  );
+  return parseFloat(stdout.trim());
+}
+
+async function validateAudioDurations(audioFiles: string[]): Promise<{
+  valid: string[];
+  invalid: Array<{ file: string; duration: number; reason: string }>;
+}> {
+  const valid: string[] = [];
+  const invalid: Array<{ file: string; duration: number; reason: string }> = [];
+
+  for (const file of audioFiles) {
+    const duration = await getAudioDurationFFProbe(file);
+
+    if (duration === 0) {
+      invalid.push({ file, duration, reason: '音频时长为0' });
+    } else if (duration < 1) {
+      invalid.push({ file, duration, reason: '音频时长过短 (<1s)' });
+    } else if (duration > 60) {
+      invalid.push({ file, duration, reason: '音频时长异常长 (>60s)' });
+    } else {
+      valid.push(file);
+    }
+  }
+
+  return { valid, invalid };
+}
+```
+
+### 4. VTT 格式验证
+
+```typescript
+function validateVTTFormat(vttPath: string): {
+  valid: boolean;
+  errors: string[];
+} {
+  const content = fs.readFileSync(vttPath, 'utf-8');
+  const errors: string[] = [];
+
+  // 检查 WEBVTT 头
+  if (!content.startsWith('WEBVTT')) {
+    errors.push('缺少 WEBVTT 文件头');
+  }
+
+  // 检查时间戳格式
+  const timeRegex = /\d{2}:\d{2}:\d{2}[,\.]\d{3}\s*-->\s*\d{2}:\d{2}:\d{2}[,\.]\d{3}/g;
+  const timestamps = content.match(timeRegex);
+
+  if (!timestamps || timestamps.length === 0) {
+    errors.push('未找到有效的时间戳');
+  }
+
+  // 检查是否有字幕文本
+  const lines = content.split('\n').filter(l => l.trim());
+  const textLines = lines.filter(l =>
+    !l.startsWith('WEBVTT') &&
+    !l.match(/^\d+$/) &&
+    !l.match(timeRegex)
+  );
+
+  if (textLines.length === 0) {
+    errors.push('未找到字幕文本');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+```
+
+## 完整验证流程
+
+```typescript
+interface ValidationResult {
+  passed: boolean;
+  errors: Array<{ severity: 'error' | 'warning'; message: string }>;
+  summary: {
+    total_files_checked: number;
+    files_missing: number;
+    audio_files: number;
+    vtt_files: number;
+    invalid_durations: number;
+    format_errors: number;
+  };
+}
+
+async function validateAssets(projectDir: string): Promise<ValidationResult> {
+  const errors: Array<{ severity: 'error' | 'warning'; message: string }> = [];
+  const voicesDir = path.join(projectDir, 'public/voices');
+
+  console.log('\n🔍 Starting asset validation...\n');
+
+  // 1. 检查目录存在
+  if (!fs.existsSync(voicesDir)) {
+    errors.push({
+      severity: 'error',
+      message: `Voices directory not found: ${voicesDir}`,
+    });
+    return {
+      passed: false,
+      errors,
+      summary: { total_files_checked: 0, files_missing: 0, audio_files: 0, vtt_files: 0, invalid_durations: 0, format_errors: 0 },
+    };
+  }
+
+  // 2. 检查 MP3/VTT 配对
+  console.log('📁 Checking audio-subtitle pairs...');
+  const pairCheck = checkAudioSubtitlePairs(voicesDir);
+
+  if (pairCheck.missing_vtt.length > 0) {
+    pairCheck.missing_vtt.forEach(vtt => {
+      errors.push({ severity: 'error', message: `Missing VTT file: ${vtt}` });
+    });
+  }
+
+  if (pairCheck.missing_mp3.length > 0) {
+    pairCheck.missing_mp3.forEach(mp3 => {
+      errors.push({ severity: 'error', message: `Missing MP3 file: ${mp3}` });
+    });
+  }
+
+  // 3. 验证音频时长
+  console.log('🎵 Validating audio durations...');
+  const mp3Files = fs.readdirSync(voicesDir)
+    .filter(f => f.endsWith('.mp3'))
+    .map(f => path.join(voicesDir, f));
+
+  const durationCheck = await validateAudioDurations(mp3Files);
+
+  if (durationCheck.invalid.length > 0) {
+    durationCheck.invalid.forEach(({ file, duration, reason }) => {
+      errors.push({
+        severity: 'error',
+        message: `Invalid audio: ${path.basename(file)} - ${reason} (${duration.toFixed(2)}s)`,
+      });
+    });
+  }
+
+  // 4. 验证 VTT 格式
+  console.log('📝 Validating VTT format...');
+  const vttFiles = fs.readdirSync(voicesDir)
+    .filter(f => f.endsWith('.vtt'))
+    .map(f => path.join(voicesDir, f));
+
+  let formatErrors = 0;
+  for (const vttFile of vttFiles) {
+    const vttCheck = validateVTTFormat(vttFile);
+    if (!vttCheck.valid) {
+      formatErrors++;
+      vttCheck.errors.forEach(err => {
+        errors.push({
+          severity: 'error',
+          message: `VTT format error in ${path.basename(vttFile)}: ${err}`,
+        });
+      });
+    }
+  }
+
+  // 生成摘要
+  const summary = {
+    total_files_checked: mp3Files.length + vttFiles.length,
+    files_missing: pairCheck.missing_vtt.length + pairCheck.missing_mp3.length,
+    audio_files: mp3Files.length,
+    vtt_files: vttFiles.length,
+    invalid_durations: durationCheck.invalid.length,
+    format_errors: formatErrors,
+  };
+
+  const passed = errors.filter(e => e.severity === 'error').length === 0;
+
+  return { passed, errors, summary };
+}
+```
+
+## 使用方法
+
+### 创建验证脚本
+
+`scripts/validate-assets.ts`:
+```typescript
+import { validateAssets } from '../src/utils/asset-validator';
+
+async function main() {
+  const projectDir = path.join(__dirname, '..');
+  const result = await validateAssets(projectDir);
+
+  console.log('\n' + '═'.repeat(60));
+
+  if (result.passed) {
+    console.log('✅ All assets validated successfully!');
+    console.log(`\n📊 Summary:`);
+    console.log(`   Total files: ${result.summary.total_files_checked}`);
+    console.log(`   Audio files: ${result.summary.audio_files}`);
+    console.log(`   VTT files: ${result.summary.vtt_files}`);
+  } else {
+    console.log('❌ Asset validation failed!\n');
+
+    const errorCount = result.errors.filter(e => e.severity === 'error').length;
+    const warningCount = result.errors.filter(e => e.severity === 'warning').length;
+
+    console.log(`Errors: ${errorCount}, Warnings: ${warningCount}\n`);
+
+    result.errors.forEach(({ severity, message }) => {
+      const icon = severity === 'error' ? '🔴' : '🟡';
+      console.log(`${icon} ${message}`);
+    });
+
+    process.exit(1);
+  }
+
+  console.log('═'.repeat(60) + '\n');
+}
+
+main();
+```
+
+### 集成到构建流程
+
+`package.json`:
+```json
+{
+  "scripts": {
+    "validate:assets": "tsx scripts/validate-assets.ts",
+    "prebuild": "npm run validate:assets && npm run generate:timeline && npm run generate:subtitles",
+    "render": "npm run prebuild && remotion render ..."
+  }
+}
+```
+
+## 输出示例
+
+### 成功情况
+```
+🔍 Starting asset validation...
+
+📁 Checking audio-subtitle pairs...
+✅ All audio files have matching VTT files
+
+🎵 Validating audio durations...
+✅ All audio files have valid durations
+
+📝 Validating VTT format...
+✅ All VTT files are properly formatted
+
+═══════════════════════════════════════════════════════
+✅ All assets validated successfully!
+
+📊 Summary:
+   Total files: 18
+   Audio files: 9
+   VTT files: 9
+═══════════════════════════════════════════════════════
+```
+
+### 失败情况
+```
+🔍 Starting asset validation...
+
+📁 Checking audio-subtitle pairs...
+🔴 Missing VTT file: seg_05_tools.vtt
+
+🎵 Validating audio durations...
+🔴 Invalid audio: seg_02_intro.mp3 - 音频时长为0 (0.00s)
+
+📝 Validating VTT format...
+🔴 VTT format error in seg_03_what.vtt: 缺少 WEBVTT 文件头
+
+═══════════════════════════════════════════════════════
+❌ Asset validation failed!
+
+Errors: 3, Warnings: 0
+
+🔴 Missing VTT file: seg_05_tools.vtt
+🔴 Invalid audio: seg_02_intro.mp3 - 音频时长为0 (0.00s)
+🔴 VTT format error in seg_03_what.vtt: 缺少 WEBVTT 文件头
+═══════════════════════════════════════════════════════
+```
+
+## 优势
+
+✅ **早期发现问题**: 渲染前而非渲染中发现问题
+✅ **清晰的错误信息**: 明确指出哪个文件有什么问题
+✅ **自动化**: 集成到构建流程，无需手动检查
+✅ **全面检查**: 文件存在性、配对关系、格式正确性、时长合理性
+
+## 扩展检查项
+
+可根据需要添加更多检查：
+- BGM 文件存在性和格式
+- 录屏素材完整性
+- 图片资源分辨率检查
+- 字体文件可用性
+- 组件代码语法检查

package/templates/.claude/skills/audio-video-sync/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: audio-video-sync
+version: 1.0.0
+description: 音视频同步技能。解析音频时长，自动计算场景时间线，确保画面与语音完美同步。
+triggers:
+  - 音视频同步
+  - 场景时长
+  - 时间线
+  - sync
+tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# 音视频同步技能 (Audio-Video Sync)
+
+确保视频场景时长与音频时长精确匹配，消除"说完话还在等待"的问题。
+
+## 核心原则
+
+1. **音频优先** - 场景时长由音频时长决定，而非硬编码
+2. **合理缓冲** - 音频结束后保留0.5-1秒缓冲，避免突兀切换
+3. **平滑过渡** - 场景间重叠0.3-0.5秒实现交叉淡化
+4. **自动计算** - 从VTT文件自动提取时长，无需手动计算
+
+## 从VTT获取音频时长
+
+VTT文件由 `voice-synthesizer` 技能生成，包含精确的时间戳。
+
+```typescript
+// 解析VTT获取音频结束时间（秒）
+function getAudioDuration(vttPath: string): number {
+  const content = fs.readFileSync(vttPath, 'utf-8');
+  const lines = content.split('\n');
+
+  let maxEndTime = 0;
+
+  for (const line of lines) {
+    // 匹配时间戳行: 00:00:05,187 --> 00:00:08,862
+    const match = line.match(/\d{2}:\d{2}:\d{2}[,\.]\d{3}\s*-->\s*(\d{2}):(\d{2}):(\d{2})[,\.](\d{3})/);
+    if (match) {
+      const endTime =
+        parseInt(match[1]) * 3600 +
+        parseInt(match[2]) * 60 +
+        parseInt(match[3]) +
+        parseInt(match[4]) / 1000;
+      maxEndTime = Math.max(maxEndTime, endTime);
+    }
+  }
+
+  return maxEndTime;
+}
+```
+
+## 场景时间线计算
+
+```typescript
+interface SceneConfig {
+  name: string;
+  audioFile: string;
+  vttFile: string;
+}
+
+interface SceneTiming {
+  start: number;      // 开始帧
+  duration: number;   // 持续帧数
+  audioDuration: number; // 音频时长（秒）
+}
+
+const FPS = 30;
+const BUFFER = 0.5;      // 音频后缓冲（秒）
+const TRANSITION = 10;   // 过渡重叠（帧）
+
+function calculateSceneTimings(scenes: SceneConfig[]): Record<string, SceneTiming> {
+  const timings: Record<string, SceneTiming> = {};
+  let currentFrame = 0;
+
+  scenes.forEach((scene, index) => {
+    // 从VTT获取实际音频时长
+    const audioDuration = getAudioDuration(scene.vttFile);
+
+    // 场景时长 = 音频时长 + 缓冲 + 过渡
+    const sceneDuration = Math.ceil((audioDuration + BUFFER) * FPS) + TRANSITION;
+
+    timings[scene.name] = {
+      start: currentFrame,
+      duration: sceneDuration,
+      audioDuration: audioDuration,
+    };
+
+    // 下一场景开始位置（考虑过渡重叠）
+    const isLast = index === scenes.length - 1;
+    currentFrame += Math.ceil((audioDuration + BUFFER) * FPS) - (isLast ? 0 : TRANSITION);
+  });
+
+  return timings;
+}
+```
+
+## 生成 Remotion 配置
+
+```typescript
+// 场景配置
+const SCENE_CONFIGS: SceneConfig[] = [
+  { name: "hook", audioFile: "seg_01_hook.mp3", vttFile: "public/voices/seg_01_hook.vtt" },
+  { name: "intro", audioFile: "seg_02_intro.mp3", vttFile: "public/voices/seg_02_intro.vtt" },
+  { name: "what", audioFile: "seg_03_what.mp3", vttFile: "public/voices/seg_03_what.vtt" },
+  // ... 更多场景
+];
+
+// 计算时间线
+const SCENES = calculateSceneTimings(SCENE_CONFIGS);
+
+// 计算总时长
+const TOTAL_DURATION = Object.values(SCENES).reduce(
+  (max, scene) => Math.max(max, scene.start + scene.duration),
+  0
+);
+
+// 输出供 MainVideo.tsx 使用
+console.log('Scene Timings:', SCENES);
+console.log('Total Duration:', TOTAL_DURATION, 'frames', '=', TOTAL_DURATION / FPS, 'seconds');
+```
+
+## 在 MainVideo.tsx 中使用
+
+```tsx
+import { AbsoluteFill, Audio, Sequence, staticFile } from "remotion";
+
+// 由 audio-video-sync 计算生成
+const SCENES = {
+  hook: { start: 0, duration: 295, audioDuration: 8.86 },
+  intro: { start: 275, duration: 401, audioDuration: 12.66 },
+  what: { start: 656, duration: 459, audioDuration: 14.64 },
+  // ...
+};
+
+export const TOTAL_DURATION = 3570;
+
+export const MainVideo: React.FC = () => {
+  return (
+    <AbsoluteFill>
+      <Sequence from={SCENES.hook.start} durationInFrames={SCENES.hook.duration}>
+        <HookScene />
+        <Audio src={staticFile("voices/seg_01_hook.mp3")} />
+      </Sequence>
+
+      <Sequence from={SCENES.intro.start} durationInFrames={SCENES.intro.duration}>
+        <IntroScene />
+        <Audio src={staticFile("voices/seg_02_intro.mp3")} />
+      </Sequence>
+
+      {/* ... 更多场景 */}
+    </AbsoluteFill>
+  );
+};
+```
+
+## 时间线可视化
+
+```
+场景      |  音频时长  |  场景时长  |  开始帧  |  结束帧
+----------|-----------|-----------|---------|--------
+hook      |  8.86s    |  295帧    |  0      |  295
+intro     |  12.66s   |  401帧    |  275    |  676
+what      |  14.64s   |  459帧    |  656    |  1115
+demo      |  15.33s   |  480帧    |  1095   |  1575
+...
+
+总时长: 119秒 = 3570帧 @ 30fps
+```
+
+## 常见问题处理
+
+### 问题1: 场景等待太久
+**原因**: 场景时长 > 音频时长
+**解决**: 使用此技能自动计算，确保 场景时长 ≈ 音频时长 + 0.5s
+
+### 问题2: 音频被截断
+**原因**: 场景时长 < 音频时长
+**解决**: 检查VTT解析是否正确，确保读取到最后一条字幕的结束时间
+
+### 问题3: 过渡突兀
+**原因**: 没有场景重叠
+**解决**: 设置 TRANSITION = 10-15 帧（0.3-0.5秒）实现交叉淡化
+
+## 使用流程
+
+1. **确保VTT文件存在**
+```bash
+ls public/voices/*.vtt
+```
+
+2. **运行时间线计算脚本**
+```bash
+npx ts-node scripts/calculate-timings.ts
+```
+
+3. **将输出复制到 MainVideo.tsx**
+
+4. **更新 Root.tsx 中的 durationInFrames**
+```tsx
+<Composition
+  id="MyVideo"
+  component={MainVideo}
+  durationInFrames={TOTAL_DURATION}
+  fps={30}
+  width={1920}
+  height={1080}
+/>
+```
+
+## 质量检查
+
+- [ ] 每个场景的 duration >= audioDuration * FPS
+- [ ] 场景间过渡平滑（有重叠）
+- [ ] 总时长合理（无多余空白）
+- [ ] 音频不被截断