remotion-video-reviewer

Remotion 视频审查员

根据动态设计规范，对 Remotion 视频实现进行全面、结构化的审查。识别问题、评估影响，并生成可执行的修改清单。

此技能的功能

执行多层审查分析：

1. 规范合规性 — 验证实现是否符合设计规范
2. 代码质量 — 检查代码模式、性能和最佳实践
3. 时间准确性 — 验证帧数计算和动画时序
4. 视觉保真度 — 确认颜色、排版和布局是否符合规范
5. 素材质量 — 验证素材是否达到生产要求
6. 性能 — 识别渲染瓶颈

输入/输出格式

输入格式：VIDEO_SPEC.md + 代码文件

需要同时提供原始规范和已实现的代码：

VIDEO_SPEC.md（来自 /motion-designer）

# Video Title

## Overview
- Duration: 30 seconds
- Frame Rate: 30 fps

## Color Palette
Primary: #FF6B35
Background: #0A0A0A

## Scene 1: Opening (0s - 5s)
- Logo scales from 0.8 to 1.0
- Spring config: { damping: 200 }

待审查的代码文件：

• src/remotion/compositions/VideoName/index.tsx
• src/remotion/compositions/VideoName/constants.ts
• src/remotion/compositions/VideoName/types.ts
• public/ 中的素材文件

输出格式：REVIEW_REPORT.md

生成包含按优先级排列的问题的全面审查报告：

# Video Review Report: [Video Title]

**Date:** 2026-01-23
**Reviewer:** remotion-video-reviewer
**Spec Version:** VIDEO_SPEC.md v1.0
**Code Location:** `src/remotion/compositions/VideoName/`

---

## Executive Summary

**Overall Status:** ✅ APPROVED WITH MINOR REVISIONS

**Quick Stats:**
- Total Issues: 4 (0 critical, 1 high, 2 medium, 1 low)
- Spec Compliance: 95%
- Code Quality: Excellent
- Production Ready: Yes, after addressing HIGH priority items

**Recommendation:** Address high-priority color mismatch before final render. Medium and low priority items are optional improvements.

---

## Compliance Scores

| Category | Score | Status | Notes |
|----------|-------|--------|-------|
| **Spec Compliance** | 95% | 🟢 Pass | 1 color mismatch in Scene 3 |
| **Code Quality** | 98% | 🟢 Pass | Excellent structure, minor optimization opportunity |
| **Timing Accuracy** | 100% | 🟢 Pass | All frame calculations correct |
| **Visual Fidelity** | 95% | 🟢 Pass | Minor color deviation |
| **Asset Quality** | 90% | 🟡 Good | 1 image could be optimized |
| **Performance** | 95% | 🟢 Pass | Excellent render times |

**Overall Compliance:** 95.5% — Production Ready

---

## Issues Found

### CRITICAL (Must Fix Before Production)
_None_ ✅

### HIGH Priority (Should Fix)

#### 1. Scene 3 Background Color Mismatch
**Category:** Visual Fidelity
**Location:** `src/remotion/compositions/VideoName/scenes/Scene3.tsx:15`
**Impact:** Visual inconsistency with brand colors

**Issue:**
```typescript
// Current implementation
backgroundColor: '#0B0B0B'  // ❌ Wrong

// Spec requirement
Primary: #FF6B35
Background: #0A0A0A  // ✅ Correct

修复方法：

// Update to use COLORS constant
backgroundColor: COLORS.background  // Now: #0A0A0A

验证：

• 如果 COLORS.background 不正确，请更新 constants.ts
• 确认 Scene 3 使用 COLORS.background
• 对照规范中的调色板进行视觉检查

---

中优先级（建议修复）

2. 大型产品图片可以优化

类别： 素材质量 位置： public/images/product.png 影响： 渲染时间更长，输出文件更大

当前情况：

• 格式：PNG
• 分辨率：4000x3000
• 文件大小：8.2MB

建议：

• 格式：JPEG（无需透明背景）
• 分辨率：1920x1440（显示尺寸的 2 倍）
• 质量：90%
• 预期大小：约 400KB（减少 95%）

修复方法：

# Resize and convert
magick public/images/product.png -resize 1920x1440 -quality 90 public/images/product.jpg

# Update code to use .jpg
<Img src={staticFile('images/product.jpg')} />

优点：

• 预览/渲染速度更快
• 最终视频文件更小
• 视觉质量没有损失

---

3. 粒子系统可以使用记忆化

类别： 性能 位置： src/remotion/compositions/VideoName/scenes/Scene2.tsx:45 影响： 有可能小幅提升性能

当前情况：

// Particle positions recalculated (deterministic but not cached)
const particles = Array.from({ length: 70 }, (_, i) => ({
  x: seededRandom(i * 123) * width,
  y: seededRandom(i * 456) * height,
}));

建议：

import { useMemo } from 'react';

const particles = useMemo(
  () => Array.from({ length: 70 }, (_, i) => ({
    x: seededRandom(i * 123) * width,
    y: seededRandom(i * 456) * height,
  })),
  [width, height]
);

预期影响： Scene 2 的渲染速度提升 5-10%

---

低优先级（锦上添花）

4. 为场景组件添加 JSDoc 注释

类别： 代码质量 位置： 所有场景组件 影响： 提高可维护性

建议：

/**
 * Scene 1: Opening animation with logo reveal
 * Duration: 0s - 5s (frames 0-150)
 * Spec reference: VIDEO_SPEC.md Section "Scene 1"
 */
function Scene1Opening() {
  // ...
}

优点：

• 团队成员更容易理解代码
• IDE 自动补全效果更好
• 规范溯源关系更清晰

---

详细分析

规范合规性（95%）

✅ 通过：

• 已实现全部 4 个场景
• 场景时长与规范完全一致（已验证帧数计算）
• 排版符合要求（Inter 字体，字重正确）
• 音频位置正确（背景音乐 + 2 个音效）
• 弹簧配置符合规范描述
• 已按描述实现所有动画

❌ 未通过：

• Scene 3 的背景颜色错误（#0B0B0B，而非 #0A0A0A）

已完成的验证步骤：

• 对比场景数量：4 个场景（符合要求）
• 验证场景时长：均正确
• 检查调色板：发现 1 处不匹配
• 验证弹簧配置：均符合要求
• 测试音频时序：正确

---

代码质量（98%）

✅ 优秀实践：

• 已妥善提取常量（COLORS、SPRING_CONFIGS、SCENE_TIMING）
• 命名规范一致（Scene1Opening、Scene2Content）
• 所有场景均正确使用 AbsoluteFill
• 已提取进度变量（未在行内调用 spring）
• 所有 props 均定义了 TypeScript 类型
• 代码结构清晰易读
• 正确导入 remotion 中的内容

✅ 遵循最佳实践：

• 使用 useVideoConfig 实现响应式定位
• 所有素材均使用 staticFile()
• Sequence 时序使用常量
• 代码中没有魔法数字
• 粒子系统使用确定性随机数

🟡 小幅改进：

• 粒子计算可以添加 useMemo（影响较低）
• 添加 JSDoc 注释可以提高可维护性

时间准确性（100%）

✅ 全部已验证：

Scene 1: 0s - 5s    → frames 0-150    ✓ Correct (5 * 30fps)
Scene 2: 5s - 15s   → frames 150-450  ✓ Correct (10 * 30fps)
Scene 3: 15s - 25s  → frames 450-750  ✓ Correct (10 * 30fps)
Scene 4: 25s - 30s  → frames 750-900  ✓ Correct (5 * 30fps)

Total: 30s = 900 frames ✓ Correct

验证：

• 所有 SCENE_TIMING 常量均符合规范
• 序列组件使用了正确的开始时间和时长
• 没有时间重叠或间隙
• 音频时间与帧计算相符

---

资源质量（90%）

✅ 良好：

• Logo：800x800 PNG，已优化，透明背景 ✓
• 背景音乐：30s MP3，192kbps ✓
• Whoosh 音效：MP3，时长合适 ✓
• Pop 音效：MP3，时长合适 ✓
• 字体：通过 @remotion/google-fonts 正确加载 Inter ✓

🟡 可改进：

• 产品图片：8.2MB PNG → 应为 1920x1440 JPEG（约 400KB）

资源检查清单：

• public/ 中包含所有资源
• 使用了正确的格式（大部分）
• staticFile() 导入正确
• 文件大小已优化（有 1 张大图片）
• 没有缺失资源

---

性能（95%）

渲染性能：

• 平均：85ms/帧 ✅ 优秀（目标：<100ms）
• 场景 1：65ms/帧 ✅
• 场景 2：105ms/帧 🟡（粒子系统，可接受）
• 场景 3：75ms/帧 ✅
• 场景 4：70ms/帧 ✅

没有重大问题：

• ✅ 已提取并重复使用弹簧计算
• ✅ 渲染路径中没有高开销操作
• ✅ 资源加载高效（大 PNG 除外）
• ✅ 未检测到内存泄漏

次要优化机会：

• 对粒子计算使用记忆化（场景 2 可提升 5-10%）
• 优化 product.png（加快资源加载）

---

建议

生产前

1. ✅ 修复高优先级颜色不匹配问题（5 分钟）
2. ⏭️ 考虑优化产品图片（10 分钟）——可选但建议

后续迭代

1. 为场景组件添加 JSDoc 注释
2. 对粒子系统应用记忆化
3. 考虑将 ParticleSystem 提取为可复用组件

---

测试检查清单

已完成验证：

• 对所有场景进行目视检查
• 逐帧验证时间
• 对比调色板
• 音频同步测试
• 资源加载验证
• 渲染性能分析
• 代码模式审查
• 符合最佳实践

---

后续步骤

1. 处理高优先级问题： 修复场景 3 的背景颜色
2. 可选： 优化 product.png 资源
3. 最终渲染： 生成生产视频
4. 性能检查： 如果渲染时间增加，运行 /remotion-performance-optimizer
5. 归档： 将 REVIEW_REPORT.md 与项目文件一同保存

---

批准

状态： ✅ 已批准，需进行少量修改

处理场景 3 的颜色不匹配问题后，此实现即可用于生产。所有关键功能、时间和结构均正确。中低优先级项目属于可选改进，可在后续迭代中处理。

签署人： remotion-video-reviewer 日期： 2026-01-23

**This document provides:**
- Executive summary with quick approval status
- Quantified compliance scores (95%, 98%, etc.)
- Prioritized issues (CRITICAL, HIGH, MEDIUM, LOW)
- Specific code locations and fixes
- Detailed analysis per category
- Testing verification checklist
- Clear next steps
- Official approval status

**Feeds into:**
- Developer: Fix identified issues
- `/remotion-performance-optimizer` if performance issues found
- Final production render after approval

## Review Process

### 1. Spec Comparison

Compare implementation against motion design spec:

**Check:**
- [ ] All scenes from spec are implemented
- [ ] Scene durations match spec timing
- [ ] Color palette matches hex codes exactly
- [ ] Typography (font, size, weight) matches
- [ ] Animation descriptions are accurately translated
- [ ] Audio placement matches timing
- [ ] Spring configurations match spec

### 2. Code Quality Review

Evaluate code structure and patterns:

**Check:**
- [ ] Constants extracted (colors, springs, timing)
- [ ] Scene components follow naming convention
- [ ] AbsoluteFill used for all scenes
- [ ] Progress variables extracted (not inline calculations)
- [ ] useVideoConfig used for responsive positioning
- [ ] TypeScript types defined
- [ ] Proper imports from remotion

### 3. Timing Accuracy

Verify frame calculations:

**Check:**
- [ ] Seconds correctly converted to frames (seconds * fps)
- [ ] Scene timing constants are accurate
- [ ] Delay calculations use frame offsets
- [ ] Transitions account for overlap
- [ ] Total duration matches spec
- [ ] Animation hold times are correct

### 4. Animation Review

Assess animation implementation:

**Check:**
- [ ] Spring configs match spec descriptions
- [ ] Interpolate ranges match spec values
- [ ] Easing functions appropriate for motion type
- [ ] Stagger delays calculated correctly
- [ ] Continuous animations use appropriate patterns
- [ ] Exit animations present where specified

### 5. Visual Fidelity

Confirm visual accuracy:

**Check:**
- [ ] Background colors match spec
- [ ] Element colors use COLORS constants
- [ ] Font sizes match spec exactly
- [ ] Positioning follows spec layout
- [ ] Visual hierarchy maintained
- [ ] Layer organization (background/midground/foreground)

### 6. Asset Quality

Validate asset preparation:

**Check:**
- [ ] All required assets present
- [ ] Assets use staticFile() import
- [ ] Image formats appropriate (PNG for transparency, JPEG for photos)
- [ ] Audio files in supported formats
- [ ] Asset dimensions suitable for composition
- [ ] Fonts loaded correctly

### 7. Performance Check

Identify performance issues:

**Check:**
- [ ] No expensive calculations in render
- [ ] Progress variables reused
- [ ] No unnecessary spring recalculations
- [ ] Memoization used where appropriate
- [ ] Large assets optimized
- [ ] No memory leaks in loops

## Review Output Format

### Summary

```markdown
## Review Summary

**Spec Compliance**: 95% (1 minor deviation)
**Code Quality**: Excellent
**Timing Accuracy**: 100%
**Visual Fidelity**: 98% (color mismatch in Scene 3)
**Asset Quality**: Good (1 optimization needed)
**Performance**: Excellent

**Overall Rating**: READY FOR PRODUCTION (with minor revisions)

问题列表（按优先级排序）

## Issues Found

### CRITICAL (Must Fix)
None

### HIGH (Should Fix)
1. **Scene 3 background color mismatch**
   - Spec: #0A0A0A
   - Code: #0B0B0B
   - Impact: Visual inconsistency
   - Fix: Update COLORS.background

### MEDIUM (Consider Fixing)
1. **Product image could be optimized**
   - Current: 4000x3000 PNG
   - Recommendation: 1920x1440 JPEG
   - Impact: Faster render times
   - Fix: Resize and convert asset

### LOW (Nice to Have)
1. **Add memoization to particle system**
   - Impact: Negligible performance gain
   - Fix: Wrap in useMemo

建议

## Recommendations

### Code Organization
- Extract ParticleSystem to reusable component
- Consider splitting Scene6 (currently 150 lines)

### Performance
- Preload audio files
- Consider lazy loading large assets

### Maintainability
- Add JSDoc comments to scene components
- Consider extracting animation helpers

常见问题检查

时间问题

问题： 帧计算不正确

// Wrong
const duration = 5; // Should be 150 frames, not 5

// Correct
const duration = 5 * fps; // 150 frames

问题： 缺少延迟

// Wrong - all elements appear at once
const progress = spring({ frame, fps, config: SMOOTH_SPRING });

// Correct - staggered with delays
const progress = spring({
  frame: frame - (index * STAGGER_DELAY),
  fps,
  config: SMOOTH_SPRING
});

动画问题

问题： 使用内联弹簧配置，而非常量

// Wrong
const progress = spring({
  frame,
  fps,
  config: { damping: 200 },
});

// Correct
const progress = spring({
  frame,
  fps,
  config: SPRING_CONFIGS.smooth,
});

问题： 重复计算

// Wrong
<div style={{
  opacity: spring({ frame, fps, config: SMOOTH }),
  transform: `scale(${spring({ frame, fps, config: SMOOTH })})`,
}} />

// Correct
const progress = spring({ frame, fps, config: SMOOTH });
<div style={{
  opacity: progress,
  transform: `scale(${progress})`,
}} />

视觉问题

问题： 颜色硬编码

// Wrong
backgroundColor: '#FF6B35'

// Correct
backgroundColor: COLORS.primary

问题： 使用像素值，而非响应式值

// Wrong
left: 960,  // Hardcoded center

// Correct
left: width / 2,  // Responsive center

资源问题

问题： 直接导入，而非使用 staticFile

// Wrong
import logo from './logo.png';

// Correct
import { staticFile } from 'remotion';
const logoSrc = staticFile('logo.png');

性能问题

问题： 渲染过程中执行高开销操作

// Wrong - recalculated every frame
const particles = Array.from({ length: 1000 }, (_, i) => ({
  x: Math.random() * width,
  y: Math.random() * height,
}));

// Correct - calculate once
const particles = useMemo(
  () => Array.from({ length: 1000 }, (_, i) => ({
    x: seededRandom(i * 123) * width,
    y: seededRandom(i * 456) * height,
  })),
  [width, height]
);

审查清单

完整审查清单：

规范符合性

• 已实现所有场景
• 时间符合规范
• 颜色完全匹配
• 排版符合要求
• 动画符合描述
• 音频符合规范

代码质量

• 已正确提取常量
• 遵循命名约定
• 正确使用 AbsoluteFill
• 已定义 TypeScript 类型
• 代码简洁易读

时间

• 帧计算正确
• 延迟计算正确
• 总时长准确
• 转场时间正确

视觉效果

• 颜色使用常量
• 响应式定位
• 视觉层次清晰
• 图层组织合理

资源

• 所有资源齐全
• 使用 staticFile
• 格式适当
• 质量足够

性能

• 没有开销大的渲染计算
• 复用进度变量
• 优化资源
• 在需要时使用记忆化

与其他技能集成

适用于：

• /remotion-spec-translator — 检查翻译后的代码
• /remotion-best-practices — 确保遵循相关模式
• /motion-designer — 与原始规范进行对比
• /remotion-performance-optimizer — 深入分析性能

规则目录

详细审核标准请参阅：

• rules/spec-compliance.md — 验证规范准确性
• rules/timing-review.md — 验证帧时序
• rules/animation-quality.md — 评估动画
• rules/visual-accuracy.md — 检查视觉保真度
• rules/asset-validation.md — 审核资源质量
• rules/performance-audit.md — 检查性能
• rules/code-patterns.md — 代码质量标准

---

此技能可确保 Remotion 实现达到可用于生产环境的标准、符合规范，并在部署前遵循最佳实践。