remotion-claude-agent-demo 0.1.0

package/templates/.claude/skills/subtitle-processor/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: subtitle-processor
+version: 1.0.0
+description: 字幕处理技能。从VTT文件自动生成Remotion字幕数据，智能分割长句，确保可读性。
+triggers:
+  - 字幕处理
+  - subtitle
+  - VTT解析
+  - 字幕分割
+tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# 字幕处理技能 (Subtitle Processor)
+
+从语音合成生成的 VTT 文件自动提取字幕数据，智能分割过长字幕，生成 Remotion 可用的字幕配置。
+
+## 核心原理
+
+**问题**:
+1. VTT 文件需要手动转换为 Remotion 字幕格式
+2. 语音合成生成的字幕可能一句话很长（30+ 字），显示效果差
+3. 时间戳是秒和毫秒，需要转换为帧数
+
+**解决**:
+1. 自动解析 VTT 提取文本和时间
+2. 智能分割长句（按标点符号自然断句）
+3. 转换时间戳为帧数供 Remotion 使用
+
+## VTT 解析
+
+```typescript
+interface SubtitleCue {
+  start: number;  // 开始帧
+  end: number;    // 结束帧
+  text: string;   // 字幕文本
+}
+
+function parseVTT(vttContent: string, fps: number = 30): SubtitleCue[] {
+  const cues: SubtitleCue[] = [];
+  const lines = vttContent.trim().split('\n');
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i].trim();
+
+    // 匹配时间戳行: 00:00:00.000 --> 00:00:02.500
+    if (line.includes('-->')) {
+      const [startStr, endStr] = line.split('-->').map(s => s.trim());
+      const start = parseVttTime(startStr, fps);
+      const end = parseVttTime(endStr, fps);
+
+      // 获取字幕文本（可能多行）
+      i++;
+      let text = '';
+      while (i < lines.length && lines[i].trim() && !lines[i].match(/^\d+$/)) {
+        text += (text ? ' ' : '') + lines[i].trim();
+        i++;
+      }
+
+      if (text) {
+        cues.push({ start, end, text });
+      }
+    } else {
+      i++;
+    }
+  }
+
+  return cues;
+}
+
+// 时间戳转帧数: 00:00:05.187 → 156 frames (at 30fps)
+function parseVttTime(timeStr: string, fps: number): number {
+  const parts = timeStr.split(':');
+  const seconds =
+    parseFloat(parts[0]) * 3600 +
+    parseFloat(parts[1]) * 60 +
+    parseFloat(parts[2].replace(',', '.'));
+  return Math.round(seconds * fps);
+}
+```
+
+## 智能长句分割
+
+```typescript
+const MAX_CHARS = 25; // 中文最大字符数（英文约50）
+
+function splitLongSubtitle(cue: SubtitleCue): SubtitleCue[] {
+  const { start, end, text } = cue;
+
+  // 长度合理，直接返回
+  if (text.length <= MAX_CHARS) {
+    return [cue];
+  }
+
+  // 优先在标点符号处分割
+  const splitPoints = ['。', '！', '？', '，', '、', '；', ' '];
+
+  const segments: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > MAX_CHARS) {
+    let splitIndex = -1;
+
+    // 在前 MAX_CHARS 字符中找分割点
+    for (const point of splitPoints) {
+      const idx = remaining.lastIndexOf(point, MAX_CHARS);
+      if (idx > 0) {
+        splitIndex = idx + 1;
+        break;
+      }
+    }
+
+    // 没找到分割点，强制在 MAX_CHARS 处分割
+    if (splitIndex === -1) {
+      splitIndex = MAX_CHARS;
+    }
+
+    segments.push(remaining.slice(0, splitIndex).trim());
+    remaining = remaining.slice(splitIndex).trim();
+  }
+
+  if (remaining) {
+    segments.push(remaining);
+  }
+
+  // 按比例分配时间
+  const totalDuration = end - start;
+  const totalChars = segments.reduce((sum, s) => sum + s.length, 0);
+
+  const result: SubtitleCue[] = [];
+  let currentStart = start;
+
+  for (const segment of segments) {
+    const duration = Math.round((segment.length / totalChars) * totalDuration);
+    result.push({
+      start: currentStart,
+      end: currentStart + duration,
+      text: segment,
+    });
+    currentStart += duration;
+  }
+
+  return result;
+}
+```
+
+## 生成 Remotion 字幕数据
+
+```typescript
+function generateSubtitleData(vttFiles: string[], fps: number, outputPath: string): void {
+  const subtitles: Record<string, SubtitleCue[]> = {};
+
+  for (const vttFile of vttFiles) {
+    const sceneName = extractSceneName(vttFile);
+    const vttContent = fs.readFileSync(vttFile, 'utf-8');
+
+    // 解析 VTT
+    const cues = parseVTT(vttContent, fps);
+
+    // 分割长句
+    const processedCues = cues.flatMap(splitLongSubtitle);
+
+    subtitles[sceneName] = processedCues;
+  }
+
+  // 生成 TypeScript 文件
+  const content = `// Auto-generated by subtitle-processor
+// DO NOT EDIT MANUALLY - This file is regenerated on each build
+
+export interface SubtitleCue {
+  start: number;
+  end: number;
+  text: string;
+}
+
+export const SUBTITLES: Record<string, SubtitleCue[]> = ${JSON.stringify(subtitles, null, 2)};
+`;
+
+  fs.writeFileSync(outputPath, content, 'utf-8');
+
+  const totalCues = Object.values(subtitles).reduce((sum, arr) => sum + arr.length, 0);
+  console.log(`✅ Subtitle data generated: ${Object.keys(subtitles).length} scenes, ${totalCues} cues`);
+}
+```
+
+## 使用方法
+
+### 在构建脚本中调用
+
+创建 `scripts/generate-subtitles.ts`:
+```typescript
+import * as fs from 'fs';
+import * as path from 'path';
+
+const VOICES_DIR = path.join(__dirname, '../public/voices');
+const OUTPUT_PATH = path.join(__dirname, '../src/subtitle-data.ts');
+const FPS = 30;
+
+// 读取所有 VTT 文件
+const vttFiles = fs.readdirSync(VOICES_DIR)
+  .filter(f => f.endsWith('.vtt'))
+  .sort()
+  .map(f => path.join(VOICES_DIR, f));
+
+// 生成字幕数据
+generateSubtitleData(vttFiles, FPS, OUTPUT_PATH);
+```
+
+### 在 Remotion 组件中使用
+
+```tsx
+import { SUBTITLES } from './subtitle-data';
+import type { SubtitleCue } from './subtitle-data';
+
+// Subtitles.tsx
+interface SubtitlesProps {
+  cues: SubtitleCue[];
+  // 其他自定义样式属性...
+}
+
+export const Subtitles: React.FC<SubtitlesProps> = ({ cues }) => {
+  const frame = useCurrentFrame();
+
+  const currentCue = cues.find(
+    (cue) => frame >= cue.start && frame <= cue.end
+  );
+
+  if (!currentCue) return null;
+
+  // 自定义动画和样式...
+  return <div>{currentCue.text}</div>;
+};
+
+// MainVideo.tsx
+<TransitionSeries.Sequence durationInFrames={SCENES.hook.duration}>
+  <HookScene />
+  <Audio src={staticFile("voices/seg_01_hook.mp3")} />
+  <Subtitles cues={SUBTITLES.hook} />
+</TransitionSeries.Sequence>
+```
+
+## 字幕分割示例
+
+**原始 VTT**:
+```vtt
+00:00:00.000 --> 00:00:05.187
+传统的AI开发中，你需要手动实现工具调用循环，处理复杂的状态管理。
+```
+
+**分割后**:
+```typescript
+[
+  {
+    start: 0,
+    end: 90,
+    text: "传统的AI开发中"
+  },
+  {
+    start: 90,
+    end: 156,
+    text: "你需要手动实现工具调用循环，处理复杂的状态管理。"
+  }
+]
+```
+
+## 输出示例
+
+```
+✅ Subtitle data generated: 9 scenes, 24 cues
+
+Subtitle statistics:
+  hook      : 2 cues (avg: 19.5 chars)
+  intro     : 4 cues (avg: 21.3 chars)
+  what      : 4 cues (avg: 23.8 chars)
+  demo      : 5 cues (avg: 20.1 chars)
+  tools     : 5 cues (avg: 18.6 chars)
+  features  : 4 cues (avg: 22.4 chars)
+  subagent  : 4 cues (avg: 19.8 chars)
+  install   : 4 cues (avg: 16.2 chars)
+  cta       : 3 cues (avg: 21.7 chars)
+```
+
+## 优势
+
+✅ **自动化**: 不再手动编写字幕数据
+✅ **可读性**: 智能分割长句，避免字幕过长
+✅ **精确对齐**: 基于 VTT 毫秒级时间戳
+✅ **自然断句**: 优先在标点符号处分割
+✅ **类型安全**: 生成 TypeScript 接口
+
+## 配置选项
+
+可在脚本中调整的参数：
+```typescript
+const MAX_CHARS = 25;        // 最大字符数
+const SPLIT_POINTS = [...];  // 分割优先级
+const MIN_DURATION = 45;     // 最短显示时间（帧）
+```
+
+## 注意事项
+
+- 分割后的字幕时长按字符数比例分配
+- 如果字幕仍然过长，会强制在 MAX_CHARS 处截断
+- 对于英文，建议 MAX_CHARS 设为 50
+- 生成的配置文件应添加到 `.gitignore`

package/templates/.claude/skills/timeline-generator/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: timeline-generator
+version: 1.0.0
+description: 自动时间线生成技能。从VTT文件自动计算精确的场景时长和帧数，消除手动硬编码。
+triggers:
+  - 时间线生成
+  - timeline
+  - 音频时长
+  - 场景时间
+tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# 时间线生成技能 (Timeline Generator)
+
+从语音合成生成的 VTT 字幕文件自动计算每个场景的精确时长，生成 TypeScript 配置文件供 Remotion 项目使用。
+
+## 核心原理
+
+**问题**: 手动填写场景时长容易出错，配音重新生成后时长变化导致不同步。
+
+**解决**: 从 VTT 文件解析音频结束时间，自动计算场景时长 = 音频时长 + 缓冲时间。
+
+## VTT 时间戳解析
+
+VTT 文件格式示例：
+```vtt
+WEBVTT
+
+00:00:00.000 --> 00:00:02.500
+第一句话
+
+00:00:02.500 --> 00:00:05.187
+第二句话
+
+00:00:05.187 --> 00:00:08.862
+第三句话
+```
+
+**提取最大结束时间作为音频时长：**
+```typescript
+function getAudioDuration(vttPath: string): number {
+  const content = fs.readFileSync(vttPath, 'utf-8');
+  let maxEndTime = 0;
+
+  // 匹配时间戳: HH:MM:SS.mmm --> HH:MM:SS.mmm
+  const timeRegex = /(\d{2}):(\d{2}):(\d{2})[,\.](\d{3})\s*-->\s*(\d{2}):(\d{2}):(\d{2})[,\.](\d{3})/g;
+
+  let match;
+  while ((match = timeRegex.exec(content)) !== null) {
+    const endTime =
+      parseInt(match[5]) * 3600 +
+      parseInt(match[6]) * 60 +
+      parseInt(match[7]) +
+      parseInt(match[8]) / 1000;
+    maxEndTime = Math.max(maxEndTime, endTime);
+  }
+
+  return maxEndTime;
+}
+```
+
+## 场景时长计算
+
+```typescript
+interface SceneTiming {
+  name: string;
+  audioDuration: number;  // 实际音频时长（秒）
+  start: number;          // 开始帧
+  duration: number;       // 场景总时长（帧）
+}
+
+const FPS = 30;
+const BUFFER = 0.5;      // 音频后缓冲（秒）
+const TRANSITION = 10;   // 转场重叠（帧）
+
+function calculateSceneTimings(vttFiles: string[]): SceneTiming[] {
+  const timings: SceneTiming[] = [];
+  let currentFrame = 0;
+
+  vttFiles.forEach((vttFile, index) => {
+    const sceneName = extractSceneName(vttFile);
+    const audioDuration = getAudioDuration(vttFile);
+
+    // 场景时长 = (音频时长 + 缓冲) × FPS + 转场重叠
+    const sceneDuration = Math.ceil((audioDuration + BUFFER) * FPS) + TRANSITION;
+
+    timings.push({
+      name: sceneName,
+      audioDuration: audioDuration,
+      start: currentFrame,
+      duration: sceneDuration,
+    });
+
+    // 下一场景开始位置（减去转场重叠）
+    const isLast = index === vttFiles.length - 1;
+    currentFrame += Math.ceil((audioDuration + BUFFER) * FPS) - (isLast ? 0 : TRANSITION);
+  });
+
+  return timings;
+}
+```
+
+## 生成 TypeScript 配置
+
+```typescript
+function generateTimelineConfig(timings: SceneTiming[], outputPath: string): void {
+  // 提取音频时长对象
+  const audioDurations = timings.reduce((acc, t) => {
+    acc[t.name] = parseFloat(t.audioDuration.toFixed(2));
+    return acc;
+  }, {} as Record<string, number>);
+
+  // 提取场景配置
+  const scenes = timings.reduce((acc, t) => {
+    acc[t.name] = {
+      start: t.start,
+      duration: t.duration,
+    };
+    return acc;
+  }, {} as Record<string, {start: number; duration: number}>);
+
+  // 计算总时长
+  const totalDuration = Math.max(...timings.map(t => t.start + t.duration));
+
+  // 生成 TypeScript 文件
+  const content = `// Auto-generated by timeline-generator
+// DO NOT EDIT MANUALLY - This file is regenerated on each build
+
+export const AUDIO_DURATIONS = ${JSON.stringify(audioDurations, null, 2)};
+
+export const SCENES = ${JSON.stringify(scenes, null, 2)};
+
+export const TOTAL_DURATION = ${totalDuration};
+
+export const FPS = 30;
+`;
+
+  fs.writeFileSync(outputPath, content, 'utf-8');
+  console.log(`✅ Timeline config generated: ${timings.length} scenes, ${totalDuration} frames (${(totalDuration / 30).toFixed(1)}s)`);
+}
+```
+
+## 使用方法
+
+### 在构建脚本中调用
+
+创建 `scripts/generate-timeline.ts`:
+```typescript
+import * as fs from 'fs';
+import * as path from 'path';
+
+const VOICES_DIR = path.join(__dirname, '../public/voices');
+const OUTPUT_PATH = path.join(__dirname, '../src/timeline-config.ts');
+
+// 读取所有 VTT 文件
+const vttFiles = fs.readdirSync(VOICES_DIR)
+  .filter(f => f.endsWith('.vtt'))
+  .sort()
+  .map(f => path.join(VOICES_DIR, f));
+
+// 计算时间线
+const timings = calculateSceneTimings(vttFiles);
+
+// 生成配置文件
+generateTimelineConfig(timings, OUTPUT_PATH);
+```
+
+### 在 package.json 中配置
+```json
+{
+  "scripts": {
+    "generate:timeline": "tsx scripts/generate-timeline.ts",
+    "prebuild": "npm run generate:timeline",
+    "preview": "npm run generate:timeline && remotion preview",
+    "render": "npm run generate:timeline && remotion render"
+  }
+}
+```
+
+### 在 Remotion 组件中使用
+
+```tsx
+import { SCENES, AUDIO_DURATIONS, TOTAL_DURATION } from './timeline-config';
+
+// MainVideo.tsx
+export const MainVideo: React.FC = () => {
+  return (
+    <TransitionSeries>
+      <TransitionSeries.Sequence durationInFrames={SCENES.hook.duration}>
+        <HookScene />
+        <Audio src={staticFile("voices/seg_01_hook.mp3")} />
+      </TransitionSeries.Sequence>
+
+      <TransitionSeries.Transition ... />
+
+      <TransitionSeries.Sequence durationInFrames={SCENES.intro.duration}>
+        <IntroScene />
+        <Audio src={staticFile("voices/seg_02_intro.mp3")} />
+      </TransitionSeries.Sequence>
+
+      {/* ... 更多场景 */}
+    </TransitionSeries>
+  );
+};
+
+// Root.tsx
+<Composition
+  id="MyVideo"
+  component={MainVideo}
+  durationInFrames={TOTAL_DURATION}
+  fps={30}
+  width={1920}
+  height={1080}
+/>
+```
+
+## 时间线验证输出
+
+生成时输出详细信息：
+```
+✅ Timeline config generated: 9 scenes, 3570 frames (119.0s)
+
+Scene timings:
+  hook      : 8.86s audio → 295 frames (start: 0)
+  intro     : 12.66s audio → 401 frames (start: 275)
+  what      : 14.64s audio → 459 frames (start: 656)
+  demo      : 15.33s audio → 480 frames (start: 1095)
+  tools     : 15.33s audio → 480 frames (start: 1555)
+  features  : 14.53s audio → 451 frames (start: 2015)
+  subagent  : 12.81s audio → 398 frames (start: 2446)
+  install   : 10.62s audio → 338 frames (start: 2824)
+  cta       : 10.14s audio → 318 frames (start: 3142)
+
+Total duration: 3570 frames = 119.0 seconds
+```
+
+## 优势
+
+✅ **消除手动错误**: 不再需要手动填写帧数
+✅ **自动同步**: 重新生成配音后自动更新时间线
+✅ **精确对齐**: 基于 VTT 毫秒级时间戳
+✅ **类型安全**: 生成 TypeScript 配置，编译时检查
+✅ **便于调试**: 可直接查看生成的配置文件
+
+## 注意事项
+
+- 确保 VTT 文件命名规范（如 `seg_01_hook.vtt`）
+- 缓冲时间（BUFFER）可根据视频节奏调整（0.3-1.0秒）
+- 转场重叠（TRANSITION）通常为 10-15 帧（0.33-0.5秒）
+- 生成的配置文件应添加到 `.gitignore`（每次构建重新生成）