agentleFS
KewtonKewton/CommandMate/.agents/skills/video-to-gif/SKILL.md

video-to-gif

Skill44 starsChanged 3 days agoMITView on GitHub

録画済みの mp4 / webm / mov を、GitHub の markdown ビューアが実際に再生できる GIF に変換する。バイト予算を指定すると解像度・fps・パレットを段階的に落として収まるまで再試行し、収まらなければ書かずに落ちる。「GIF を作って」「GIF 化」「mp4 を GIF に」「README に貼れる動画」等の指示で使う。

  • Installs packages

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

video-to-gif

録画済みの動画を GIF にする。to-gif.sh 一発で、バイト予算に収まる GIF が出る。

.claude/skills/video-to-gif/scripts/to-gif.sh demo.mp4                 # demo.gif を隣に出す
.claude/skills/video-to-gif/scripts/to-gif.sh *.mp4 --out docs/images/features
.claude/skills/video-to-gif/scripts/to-gif.sh clip.mp4 --max-bytes 500k
.claude/skills/video-to-gif/scripts/to-gif.sh --ladder                 # 再試行の段取りだけ表示(ffmpeg 不要)
.claude/skills/video-to-gif/scripts/to-gif.sh --report docs/images/features/*.gif
.claude/skills/video-to-gif/scripts/to-gif.sh --check                  # 依存確認のみ

なぜ GIF なのか

GitHub の markdown ビューアは <video> を描画しない。HTML 許可リストに含まれておらず、 動画添付が再生されるのは issue / PR / discussion のコメントだけである。リポジトリ内の .md に貼って動く動画は GIF しかない。

例外は GitHub Pages(website/)で、そちらは素の HTML がそのまま配信されるので <video> が使える。LP に置くなら GIF ではなく mp4 の方が軽い(実測 GIF 1.02MB に対し mp4 0.56MB)。GIF が要るのは docs 配下の markdown だけ。

なぜ demo-video の compose.sh --gif と別なのか

compose.sh --gif は合成パイプラインの途中でしか発火せず、720px / 12fps / sierra2_4a を ハードコードしている。docs に載せるときに要るのは「完成済みの mp4 から、リポジトリが 背負えるサイズの GIF を作る」ことで、しかも収まったかどうかは測って判断する必要がある。 この 2 点は合成の関心事ではないので別スキルにした。

設計判断: dither は既定で切る

同一素材(20 秒 / 1280x800 の UI キャプチャ)を、無劣化リファレンスに対する SSIM で実測した。

設定バイト数SSIM (All)
colors=256 dither=none ← 既定1,073,7250.99653
colors=128 dither=none883,9120.99439
colors=128 dither=sierra2_4a1,271,6710.99160
colors=128 dither=bayer998,3390.99149
colors=64 dither=none736,1630.99202

ディザは 2 軸とも悪化させる。 空間ノイズを撒くので GIF が圧縮に使う LZW の run が壊れ、 かつ画面録画の大半を占める平坦な UI パネルには均すべきグラデーションが無い。 colors=64 + sierra2_4a は 1,472,301 バイトで colors=128 の同ディザより大きい — パレットが粗いほど誤差拡散が遠くまで広がるためである。

グラデーションが実在する素材(写真・動画コンテンツ)では --dither sierra2_4a を 意識して渡すこと。既定で有効にはしない。

--stats-mode diff も測ったが誤差の範囲で、むしろ僅かに大きくなった(full のまま)。

バイト予算とラダー

--max-bytes(既定 1.5M)に収まるまで、3 軸をラウンドロビンで一段ずつ落として再試行する。 fps を底まで落としてから解像度に手を付ける、という順序にはしない。4fps 等倍も 360px 30fps も 中間の妥協より見た目が悪く、画面の文字が読めることが UI デモの目的だからである。

$ to-gif.sh --ladder
to-gif: budget 1.50MB per file; floors 360px / 6fps / 32 colors
rung    width    fps   colors
1         600     10      256
2         600      8      256
3         480      8      256
4         480      8      128
5         480      6      128
6         384      6      128
7         384      6       64
8         360      6       64
9         360      6       32

--ladder は ffmpeg を 1 度も呼ばない。段取りの算術だけを検証できるようにしてあり、 tests/unit/skills/video-to-gif/ladder.test.ts がここを固定している。

底まで行っても収まらなければ exit 1 で、ファイルを書かない。到達した最小サイズと その設定を stderr に出す。知った上で書きたいときだけ --allow-oversize(それでも exit 1)。

主なオプション

オプション既定説明
--out PATH入力の隣.gif で終われば出力ファイル、それ以外はディレクトリ(自動作成)
--width PX600開始幅。高さはアスペクト比に従う
--fps N10開始フレームレート
--colors N256パレット数 2..256
--dither MODEnonesierra2_4a 等を明示指定可
--max-bytes SIZE1.5M1500000 / 1500k / 1.5M / none
--no-fit—ラダーを歩かず 1 回だけ試す
--start SEC / --duration SEC—トリミング
--loop N00 = 無限ループ、-1 = 1 回だけ再生
--min-width / --min-fps / --min-colors360 / 6 / 32ラダーの下限

落とし穴(実際に踏んだもの)

  • サイズは wc -c で測る。du は使わない。 APFS では du -h が 1,536,216 バイトの ファイルを 2.3M と報告した。ブロック割り当てであって中身ではない。git が保存するのは wc -c の方で、この差で総量を 38MB と 25.8MB に読み違えかけた。
  • -t は -i の前に置く。 引数列の末尾に足すとパレット入力(2 本目の -i)の 入力オプションとして解釈され、トリムが黙って効かなくなる。--duration 6 が 16 秒の GIF を吐いた。
  • 動画は git の delta 圧縮が効かない。 作り直すたび全部を再コミットしないこと。 出力の最後に「コミットすれば何バイト増えるか」を出しているのはこのため。
  • scale=W:-1 は奇数の高さを作りうる(600 幅 → 375)。GIF は問題ないが、同じ式で h264 に渡すと height not divisible by 2 で落ちる。比較用のリファレンスを作るときは -2 か可逆コーデックを使う。
  • 引数の検証は ffmpeg の存在確認より先に行っている。逆順だと、ffmpeg の無い環境 (= 全 CI ランナー)で引数の誤りがすべて required command not found: ffmpeg になり、 開発機では踏めず CI でだけ落ちる(compose.sh で実際に起きた。PR #1562)。

構成

video-to-gif/
├── SKILL.md
└── scripts/
    └── to-gif.sh      # 変換・ラダー・計測・依存確認をモードで持つ単一スクリプト

テストは tests/unit/skills/video-to-gif/ にあり npm run test:unit に含まれる (.claude/skills/** に置くと CI では 1 度も実行されない。root tsconfig が .claude/** を 除外しているためです。npm run lint は Issue #2719 以降 src と tests を見ますが、 .claude/** は対象外のままです)。

スキルは .claude/skills/ と .agents/skills/ の両方に byte-identical で置く。 公式の install 先は .agents/skills のみ(Codex / Antigravity が読む)で、Claude は .claude/skills しか読まない。片方だけに置くと何のエラーも出ないままもう一方の エージェントから不可視になる。mirror.test.ts が差分を落とす。

制約

  • bash 3.2 互換(declare -A / mapfile を使わない)。macOS が同梱しているのは 3.2 である。
  • ffmpeg / ffprobe が要る。無ければ --check が brew install ffmpeg を提示して exit 1。
  • 出力先が .gif で終わらないファイル名(hero.png 等)はディレクトリとして扱わず拒否する。 タイプミスで hero.png/ というフォルダを作る方が黙って困る。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.