media-composition

メディア合成スキル

複数のメディアアセット（GIF、動画、画像）を組み合わせて、詳細なチュートリアルやドキュメント向けの合成出力を作成します。

使用する場面

• 複数のメディア出力を組み合わせて合成する場合
• ターミナルとブラウザーの録画から合成デモを作成する場合

使用しない場面

• 合成が不要な単一形式の出力
• シンプルなターミナル録画の場合 — scry:vhs-recording を直接使用してください

概要

このスキルは、個別に生成されたメディアアセットを統合した出力に組み合わせます。コンポーネントと合成ルールを定義するマニフェストファイルを読み込み、すべての入力が存在することを検証し、FFmpeg コマンドを実行して最終的な合成メディアを生成します。

前提条件

このスキルを使用する前に、以下のツールを PATH 上で利用できる必要があります。

• ffmpeg：メディアの合成とエンコード
• yq：YAML マニフェストの解析

ffmpeg -version と yq --version を実行して、利用可能であることを確認してください。

必須の進捗項目

- Parse composition manifest file
- Validate all component outputs exist
- Determine composition layout and parameters
- Execute FFmpeg composition command
- Verify combined output file created
- Report composition metrics (file size, dimensions)

マニフェスト形式

マニフェストでは、組み合わせるコンポーネントとその配置方法を定義します。

# Example manifest: tutorials/mcp.manifest.yaml
name: mcp
title: "MCP Server Integration"
components:
  - type: tape
    source: mcp.tape
    output: assets/gifs/mcp-terminal.gif
  - type: playwright
    source: browser/mcp-browser.spec.ts
    output: assets/gifs/mcp-browser.gif
    requires:
      - "skrills serve"
combine:
  output: assets/gifs/mcp-combined.gif
  layout: vertical
  options:
    padding: 10
    background: "#1a1a2e"

マニフェストのスキーマ

フィールド	型	必須	説明
name	string	はい	合成を識別する名前
title	string	いいえ	人が読めるタイトル
components	array	はい	組み合わせるメディアコンポーネントのリスト
components[].type	string	はい	ソースの種類：tape、playwright、static
components[].source	string	はい	ソースファイルへのパス
components[].output	string	はい	生成される出力へのパス
components[].requires	array	いいえ	生成前に実行するコマンド
combine.output	string	はい	合成出力のパス
combine.layout	string	はい	レイアウトモード（下表を参照）
combine.options	object	いいえ	レイアウト固有のオプション

手順

1. マニフェストファイルを解析する

# Read and validate manifest structure
yq eval '.' manifest.yaml

# Extract component outputs
yq eval '.components[].output' manifest.yaml

2. コンポーネントの出力を検証する

# Check all required files exist
for output in $(yq eval '.components[].output' manifest.yaml); do
  if [[ ! -f "$output" ]]; then
    echo "ERROR: Missing component: $output"
    exit 1
  fi
done

3. FFmpeg で合成を実行する

マニフェストで指定されたレイアウトに応じて、適切な FFmpeg コマンドを実行します。

4. 合成出力を検証する

# Verify output exists and has content
if [[ -f "$output" && -s "$output" ]]; then
  echo "Composition successful: $output"
  ls -lh "$output"
else
  echo "ERROR: Composition failed"
  exit 1
fi

FFmpeg の合成コマンド

垂直方向への配置

GIF／動画を上から下へ並べます。

ffmpeg -i top.gif -i bottom.gif \
  -filter_complex "[0:v][1:v]vstack=inputs=2" \
  -y output.gif

間に余白を設ける場合：

ffmpeg -i top.gif -i bottom.gif \
  -filter_complex "[0:v]pad=iw:ih+10:0:0:color=black[top];[top][1:v]vstack=inputs=2" \
  -y output.gif

水平方向への配置

GIF／動画を横に並べます。

ffmpeg -i left.gif -i right.gif \
  -filter_complex "[0:v][1:v]hstack=inputs=2" \
  -y output.gif

順番に連結

GIF／動画を順番に再生します。

# Create concat list file
cat > concat_list.txt << EOF
file 'first.gif'
file 'second.gif'
file 'third.gif'
EOF

# Concatenate
ffmpeg -f concat -safe 0 -i concat_list.txt \
  -y output.gif

グリッドレイアウト（2x2）

ffmpeg -i tl.gif -i tr.gif -i bl.gif -i br.gif \
  -filter_complex "[0:v][1:v]hstack=inputs=2[top];[2:v][3:v]hstack=inputs=2[bottom];[top][bottom]vstack=inputs=2" \
  -y output.gif

背景色を指定する場合

ffmpeg -i top.gif -i bottom.gif \
  -filter_complex "color=c=#1a1a2e:s=800x600[bg];[bg][0:v]overlay=0:0[tmp];[tmp][1:v]overlay=0:300" \
  -y output.gif

レイアウトオプション

レイアウト	説明	オプション
vertical	上から下へ並べる	padding、background、align
horizontal	左から右へ並べる	padding、background、align
sequential	順番に再生する	transition、duration
grid	N x M のグリッドに配置する	rows、cols、padding
overlay	互いに重ねる	position、opacity
pip	ピクチャー・イン・ピクチャー	corner、scale、margin

レイアウトオプションの詳細

オプション	型	デフォルト	説明
padding	int	0	コンポーネント間のピクセル数
background	string	"black"	背景色（16進数または色名）
align	string	"center"	配置：left、center、right
transition	string	"none"	トランジションの種類：fade、wipe、none
scale	float	0.25	PiP の拡大縮小率
corner	string	"br"	PiP の角：tl、tr、bl、br

合成例

ターミナルとブラウザーのチュートリアル

name: plugin-demo
components:
  - type: tape
    source: demo.tape
    output: terminal.gif
  - type: playwright
    source: browser.spec.ts
    output: browser.gif
combine:
  output: demo-combined.gif
  layout: vertical
  options:
    padding: 5
    background: "#0d1117"

横並びの比較

name: before-after
components:
  - type: static
    source: before.gif
    output: before.gif
  - type: static
    source: after.gif
    output: after.gif
combine:
  output: comparison.gif
  layout: horizontal
  options:
    padding: 10

ピクチャー・イン・ピクチャー

name: pip-demo
components:
  - type: tape
    source: main.tape
    output: main.gif
  - type: playwright
    source: overlay.spec.ts
    output: overlay.gif
combine:
  output: pip-demo.gif
  layout: pip
  options:
    corner: br
    scale: 0.3
    margin: 20

完了条件

• マニフェストファイルの解析に成功している
• すべてのコンポーネント出力の存在が確認されている
• FFmpeg の合成コマンドがエラーなく実行されている
• 合成出力ファイルが存在し、サイズが 0 より大きい
• 出力の寸法と再生時間が記録されている
• 一時ファイルが削除されている