remotion-video-reviewer

Remotion Video Reviewer

モーションデザイン仕様に照らして、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 フォント、正しいウェイト）
• 音声の配置は正しいです（BGM＋2つの効果音）
• スプリング設定は仕様の説明と一致しています
• すべてのアニメーションが説明どおりに実装されています

❌ 不合格：

• Scene 3 の背景色が異なります（#0A0A0A ではなく #0B0B0B）

完了した検証手順：

• シーン数を比較：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%）

✅ 良好：

• ロゴ：800x800 PNG、最適化済み、透過 ✓
• BGM：30s MP3、192kbps ✓
• Whoosh 効果音：MP3、適切な長さ ✓
• Pop 効果音：MP3、適切な長さ ✓
• フォント：Inter を @remotion/google-fonts 経由で正しく読み込み ✓

🟡 改善の余地あり：

• 製品画像：8.2MB PNG → 1920x1440 JPEG（約400KB）にするべきです

アセットチェックリスト：

• すべてのアセットが public/ に存在
• 適切な形式を使用（ほとんど）
• staticFile() のインポートが正しい
• ファイルサイズが最適化されている（大きな画像が1つ）
• アセットの欠落なし

---

パフォーマンス（95%）

レンダリングパフォーマンス：

• 平均：85ms/フレーム ✅ 優秀（目標：<100ms）
• シーン 1：65ms/フレーム ✅
• シーン 2：105ms/フレーム 🟡（パーティクルシステム、許容範囲）
• シーン 3：75ms/フレーム ✅
• シーン 4：70ms/フレーム ✅

重大な問題なし：

• ✅ Spring の計算を抽出して再利用
• ✅ レンダリング処理に高コストの操作なし
• ✅ アセットを効率よく読み込み（大きな PNG を除く）
• ✅ メモリーリークは検出されず

軽微な最適化の機会：

• パーティクルの計算をメモ化（シーン 2 で5～10%の改善）
• product.png を最適化（アセットの読み込みを高速化）

---

推奨事項

本番環境への移行前

1. ✅ 優先度 HIGH の色の不一致を修正（5分）
2. ⏭️ 製品画像の最適化を検討（10分）－任意ですが推奨

今後のイテレーションで

1. シーンコンポーネントに JSDoc コメントを追加
2. パーティクルシステムにメモ化を適用
3. ParticleSystem を再利用可能なコンポーネントとして抽出することを検討

---

テストチェックリスト

検証完了：

• すべてのシーンを目視で確認
• フレームごとのタイミングを検証
• カラーパレットを比較
• 音声同期テスト
• アセット読み込みを検証
• レンダリングパフォーマンスをプロファイリング
• コードパターンをレビュー
• ベストプラクティスへの準拠を確認

---

次のステップ

1. 優先度 HIGH の問題に対処： シーン 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
});

アニメーションの問題

問題： 定数ではなく 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 の実装が本番環境に対応し、仕様に準拠し、デプロイ前にベストプラクティスに従っていることを確認できます。