video-frames

動画フレームスキル

包括的な品質管理、進捗追跡、安全制限を備えた、実運用に適した動画フレーム抽出です。

使用する場面

✅ 次の場合にこのスキルを使用します：

• 動画から指定したタイムスタンプのフレームを抽出する
• 動画の概要を把握するためのサムネイルグリッド／コンタクトシートを作成する
• 動画の一部からアニメーション GIF を生成する
• 一定間隔（例：N 秒ごと）でフレームを一括抽出する
• 動画のプレビューやストーリーボードを作成する
• インデックスでピクセル単位の精度でフレームにアクセスする必要がある
• 指定した品質レベルでフレームを抽出する

❌ 次の場合はこのスキルを使用しないでください：

• 単純な形式変換 → ffmpeg-tools を使用してください
• 動画編集（エフェクト） → 動画編集ソフトを使用してください
• リアルタイムのフレームキャプチャ → ストリーミングツールを使用してください
• カメラからの動画撮影 → camsnap を使用してください
• 画像生成 → image-gen を使用してください

前提条件

# Install FFmpeg
brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Ubuntu/Debian

# Optional: Install ImageMagick for better grid generation
brew install imagemagick   # macOS
sudo apt install imagemagick   # Ubuntu

# Verify installation
ffmpeg -version
ffprobe -version

コマンド

1. 単一フレームを抽出する

指定した時刻またはフレームインデックスのフレームを 1 枚抽出します。

# Extract frame at timestamp
{baseDir}/video-frames.js frame video.mp4 --time 30 --out frame.jpg
{baseDir}/video-frames.js frame video.mp4 --time 00:02:30 --out frame.jpg
{baseDir}/video-frames.js frame video.mp4 --time 150.5 --out frame.jpg

# Extract by frame index
{baseDir}/video-frames.js frame video.mp4 --index 0 --out first-frame.jpg
{baseDir}/video-frames.js frame video.mp4 --index 1000 --out frame-1000.jpg

# With quality settings
{baseDir}/video-frames.js frame video.mp4 --time 30 --format png --out high-quality.png
{baseDir}/video-frames.js frame video.mp4 --time 30 --quality 1 --out best-quality.jpg
{baseDir}/video-frames.js frame video.mp4 --time 30 --format jpg --quality 2

時刻の形式：

形式	例	説明
秒	30	秒数を指定
MM:SS	2:30	分：秒
HH:MM:SS	00:02:30	完全なタイムコード
小数	90.5	ミリ秒精度

品質設定（JPEG）：

値	品質	ファイルサイズ	用途
1	最高	大	アーカイブ、品質の保持
2-3	高	中	デフォルト、バランスが良好
5	中	小	ウェブ、簡易プレビュー
10+	低	非常に小	下書き、サムネイル

対応形式：

• jpg/jpeg - ウェブに最適化、圧縮
• png - 可逆圧縮、透過、最高品質
• bmp - 非圧縮の生データ
• tiff - プロフェッショナル向け形式
• webp - 次世代のウェブ形式

2. 複数のフレームを抽出する

一定間隔でフレームを一括抽出します。

# Extract 1 frame per second
{baseDir}/video-frames.js frames video.mp4 --fps 1

# Extract specific segment
{baseDir}/video-frames.js frames video.mp4 --fps 1 --start 00:01:00 --duration 60
{baseDir}/video-frames.js frames video.mp4 --fps 5 --start 30 --duration 120

# Higher quality extraction
{baseDir}/video-frames.js frames video.mp4 --fps 1 --quality 1 --prefix keyframe

# Resize during extraction
{baseDir}/video-frames.js frames video.mp4 --fps 1 --width 1920 --quality 1

フレームレートのオプション：

レート	説明	用途
--fps 1	1 フレーム／秒	タイムラインの抽出
--fps 5	5 フレーム／秒	詳細な分析
--fps 0.1	10 秒ごと	概要、ストーリーボード
--fps 0.5	2 秒ごと	中程度の詳細

出力：

/tmp/frames_1234567890/
  ├── frame_00001.jpg
  ├── frame_00002.jpg
  ├── frame_00003.jpg
  └── ...

3. サムネイルグリッド（コンタクトシート）を生成する

動画の概要を確認するためのサムネイルグリッドを作成します。

# Basic grid
{baseDir}/video-frames.js grid video.mp4 --output grid.jpg

# Custom size and layout
{baseDir}/video-frames.js grid video.mp4 --count 16 --columns 4 --width 480 --out grid.jpg

# Compact preview
{baseDir}/video-frames.js grid video.mp4 --count 20 --columns 5 --width 320 --out overview.jpg

# High resolution grid
{baseDir}/video-frames.js grid video.mp4 --count 9 --columns 3 --width 640 --format png --out detailed.png

グリッドレイアウトの例：

枚数	列数	行数	最適な用途
4	2	2	簡易プレビュー
9	3	3	標準的な概要
12	4	3	詳細なタイムライン
16	4	4	包括的なストーリーボード
20	5	4	長い動画

出力形式：

+---+---+---+---+
| 1 | 2 | 3 | 4 |    <- 5 seconds into video
+---+---+---+---+
| 5 | 6 | 7 | 8 |    <- 25 seconds into video
+---+---+---+---+
| 9 |10 |11 |12 |    <- 45 seconds into video
+---+---+---+---+

4. アニメーション GIF を作成する

動画の一部をアニメーション GIF として抽出します。

# Basic GIF (5 seconds from start)
{baseDir}/video-frames.js gif video.mp4 --output clip.gif

# Specific time and duration
{baseDir}/video-frames.js gif video.mp4 --start 00:01:30 --duration 5 --out highlight.gif
{baseDir}/video-frames.js gif video.mp4 --start 30 --duration 10 --out segment.gif

# Quality presets
{baseDir}/video-frames.js gif video.mp4 --start 60 --duration 3 --preset fast --out quick.gif
{baseDir}/video-frames.js gif video.mp4 --start 60 --duration 3 --preset quality --out smooth.gif
{baseDir}/video-frames.js gif video.mp4 --start 60 --duration 3 --preset cinematic --out cinema.gif

# Custom parameters
{baseDir}/video-frames.js gif video.mp4 --start 30 --duration 5 --fps 30 --width 720 --out preview.gif

GIF プリセット：

プリセット	FPS	幅	色数	サイズ	最適な用途
fast	15	480px	128	小	素早い生成
balanced	20	640px	256	中	デフォルト
quality	24	720px	512	大	滑らかな動き
cinematic	30	1080px	1024	非常に大	最高品質

最大長： 300 フレーム（30fps で約 10 秒）

5. 動画情報を取得する

動画の詳細なメタデータを表示します。

{baseDir}/video-frames.js info video.mp4

出力：

{
  "stats": { "size": 1234567890, "mtime": "..." },
  "duration": 3665,
  "width": 1920,
  "height": 1080,
  "fps": 29.97,
  "totalFrames": 109785,
  "info": { ... }  // Full ffprobe output
}

進捗の追跡

処理の進捗がリアルタイムで表示されます：

⏳ Extracting frames: 15/30 (50.0%) | Elapsed: 12.3s
⏳ Generating thumbnails: 8/12 (66.7%) | Elapsed: 5.2s

安全機能

制限

制限	値	説明
動画の最大サイズ	50 GB	入力ファイルサイズの上限
最大長	4 時間	動画の長さの上限
最大フレーム数	1,000	フレーム一括抽出の上限
最大グリッドサイズ	サムネイル 60 枚	コンタクトシートの上限
GIF の最大フレーム数	300	アニメーション GIF の上限
タイムアウト	30 分	処理のデフォルトタイムアウト

動画の検証

処理の前に、このスキルは以下を検証します：

• ファイルが存在し、読み取り可能であること
• ファイルサイズが制限内であること
• 有効な動画形式であること
• 長さが制限内であること
• 動画ストリームが含まれていること
• 破損していないこと

エラー処理

エラーコード

コード	名前	説明
0	SUCCESS	操作が完了しました
1	INVALID_INPUT	パラメーターが不足しているか、無効です
2	FILE_NOT_FOUND	動画が見つかりません
3	INVALID_FORMAT	サポートされていない形式です
4	INVALID_TIME_RANGE	タイムスタンプが無効です
5	FFMPEG_ERROR	FFmpeg の実行に失敗しました
6	OUT_OF_MEMORY	メモリ制限を超過しました
7	TIMEOUT	操作がタイムアウトしました
8	INTERRUPTED	ユーザーによって中断されました
9	PERMISSION_DENIED	読み取り／書き込みができません
10	VALIDATION_FAILED	動画の検証に失敗しました
99	UNKNOWN	予期しないエラーです

よくあるシナリオ

フレームインデックスが範囲外の場合：

{baseDir}/video-frames.js frame video.mp4 --index 999999
# ❌ ERROR: Frame index 999999 out of range (0-109784)

タイムスタンプが動画の長さを超えている場合：

{baseDir}/video-frames.js frame video.mp4 --time 10000
# ❌ ERROR: Timestamp 02:46:40 out of range (0-01:01:05)

フレーム数が多すぎる場合：

{baseDir}/video-frames.js frames video.mp4 --fps 100
# ❌ ERROR: Too many frames requested: 366500 (max: 1000)

大きな GIF をリクエストした場合：

{baseDir}/video-frames.js gif video.mp4 --duration 60 --fps 60
# ❌ ERROR: GIF too long: 3600 frames (max: 300)

技術的な詳細

フレーム抽出方法

1. セグメントシーク（-i の前に -ss を指定）

   • フレームへすばやくアクセスできます
   • --time オプションで使用します
   • 開始位置の精度がわずかに低下します

2. フレーム選択（-vf select）

   • フレームインデックスを正確に抽出します
   • 遅くなりますが、フレーム単位で正確です
   • --index オプションで使用します

3. 一定間隔で抽出（fps フィルター）

   • バッチ抽出を効率的に行えます
   • フレームレートを変換します
   • バッチ操作で使用します

品質設定

JPEG 品質（CRF - Constant Rate Factor）：

-q:v 1  -> 100% quality (best, largest)
-q:v 2  -> ~95% quality (default)
-q:v 5  -> ~85% quality (web)
-q:v 10 -> ~70% quality (low)
-q:v 31 -> ~10% quality (minimum)

PNG 出力：

• 常に可逆圧縮です
• ファイルサイズが大きくなります
• アーカイブに最適です
• 透明な背景をサポートします

スケーリング（Lanczos）：

-vf scale=320:-2:flags=lanczos

• 高品質を実現する Lanczos リサンプリング
• -2 によって、エンコード要件である偶数の寸法を確保します
• アスペクト比を維持します

GIF の最適化

パレットの生成：

1. 動画のセグメントを解析します
2. 最適な 256 色パレットを生成します
3. すべてのフレームにパレットを適用します
4. ディザリングでグラデーションを滑らかにします

ファイルサイズの最適化：

• 固定フレームレート
• 限定されたカラーパレット
• エンコード前のリサイズ
• 最適化されたエンコード設定

例

動画のストーリーボード作成

#!/bin/bash
VIDEO="movie.mp4"
OUTDIR="storyboard"

mkdir -p $OUTDIR

# Create overview grid
echo "Creating overview grid..."
{baseDir}/video-frames.js grid "$VIDEO" --count 20 --columns 5 --width 480 --out "$OUTDIR/overview.jpg"

# Extract key frames every minute
echo "Extracting key frames..."
{baseDir}/video-frames.js frames "$VIDEO" --fps 0.0167 --prefix key --out "$OUTDIR/"

# Create chapter thumbnails
echo "Creating chapter thumbnails..."
for time in 0:00 10:00 20:00 30:00; do
  {baseDir}/video-frames.js frame "$VIDEO" --time $time --quality 1 --out "$OUTDIR/chapter_${time//:/}.png"
done

echo "Storyboard complete in $OUTDIR/"

動画プレビューギャラリー

#!/bin/bash
for video in *.mp4; do
  echo "Processing: $video"
  
  # Create 3x3 grid
  {baseDir}/video-frames.js grid "$video" --count 9 --columns 3 --width 640 --out "${video%.*}-grid.jpg"
  
  # Create 5-second preview GIF
  {baseDir}/video-frames.js gif "$video" --start 30 --duration 5 --preset balanced --out "${video%.*}-preview.gif"
  
done

N 秒ごとにフレームを抽出

# Extract frame at beginning of every minute
for i in {0..60}; do
  {baseDir}/video-frames.js frame video.mp4 --time $((i*60)) --out "frames/minute_${i}.jpg"
done

# Shell script for batch extraction
extract_frames() {
  local video="$1"
  local interval="${2:-10}"  # default 10 seconds
  local duration
  duration=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$video")
  
  for ((t=0; t<duration; t+=interval)); do
    {baseDir}/video-frames.js frame "$video" --time $t --out "frames/frame_${t}.jpg"
  done
}

高品質なサムネイルの生成

# Best quality single frame
{baseDir}/video-frames.js frame video.mp4 \
  --time 10 \
  --format png \
  --width 1920 \
  --out thumbnail.png

# Best quality grid
{baseDir}/video-frames.js grid video.mp4 \
  --count 9 \
  --columns 3 \
  --width 640 \
  --format png \
  --out grid.png

パフォーマンスのヒント

1. 高速化には JPEG を使用する

JPEG エンコードは PNG より高速です：

{baseDir}/video-frames.js frame video.mp4 --format jpg  # Faster
{baseDir}/video-frames.js frame video.mp4 --format png  # Better quality, slower

2. 下書きでは品質を下げる

# Quick preview
{baseDir}/video-frames.js grid video.mp4 --count 9 --width 320  # Small, fast

# Final quality
{baseDir}/video-frames.js grid video.mp4 --count 16 --width 640  # Higher detail

3. 並列処理

# Process multiple videos in parallel
{baseDir}/video-frames.js grid video1.mp4 --out g1.jpg &
{baseDir}/video-frames.js grid video2.mp4 --out g2.jpg &
{baseDir}/video-frames.js grid video3.mp4 --out g3.jpg &
wait

4. 抽出時にリサイズする

フルサイズで抽出してから拡大縮小するより効率的です：

# Good
{baseDir}/video-frames.js frame video.mp4 --width 320 --out thumb.jpg

# Less efficient
{baseDir}/video-frames.js frame video.mp4 --out full.jpg
# Then resize externally

注意事項

• グリッドの生成には、ImageMagick が利用可能な場合は ImageMagick（より高品質）を使用し、それ以外の場合は FFmpeg の tile フィルターを使用します
• フレームインデックス 0 は常に動画の最初のフレームです
• タイムスタンプは、動画の FPS に基づいて最も近いフレームに丸められます
• GIF は品質とサイズのバランスを取るため、256 色パレットで最適化されます
• PNG の透過は維持されます（オーバーレイに便利です）
• すべての操作で一時ファイルが自動的に削除されます
• JSON 出力により、プログラムから連携できます
• グリッドのサムネイルには、動画の時間間隔に沿ったタイムスタンプが含まれます