colorize

上色

工作流

1. 收集用户输入：图像、视频或 Live Photos。使用绝对路径。
2. 确定技能目录并安装依赖项一次（请参阅“要求”）。
3. 使用输入和输出路径运行 scripts/colorize.py。
4. 等待 VALIDATION=PASS 和 OUTPUT_VIDEO=<absolute path>。
5. 可选：使用 ffmpeg 提取几帧，在回复前检查效果。
6. 返回输出路径和使用的设置。

快速开始

skill_dir=""
for base in "${AGENTS_HOME:-$HOME/.agents}" "${CLAUDE_HOME:-$HOME/.claude}" "${CODEX_HOME:-$HOME/.codex}"; do
  if [ -d "$base/skills/colorize" ]; then
    skill_dir="$base/skills/colorize"
    break
  fi
done
[ -n "$skill_dir" ] || { echo "colorize skill not found under ~/.agents, ~/.claude, or ~/.codex"; exit 1; }

python3 -m pip install -r "$skill_dir/scripts/requirements.txt"
python3 "$skill_dir/scripts/colorize.py" "/abs/path/photo.jpg" -o "$(pwd)/out/photo_colorize.mp4"

如果 Agent 已知此 SKILL.md 所在目录，请将其用作 skill_dir。

输入

输入	处理方式
图像（png jpg jpeg webp heic heif avif bmp tif）	静态画面；色彩显现持续 --duration 秒，然后定格 --hold 秒。
视频（mp4 mov m4v webm mkv avi gif）	每个源帧都会保持动态；色彩显现会在前 --duration 秒内进行，片段剩余部分保持最终效果。保留音频。
iPhone Live Photo	传入静态图像（IMG_0001.HEIC 或 .JPG）。旁边同名的 .MOV 会自动使用，并保留其音频。也可直接传入 .MOV，效果相同。
Android 动态照片	传入 .jpg；系统会自动提取其中嵌入的 MP4（Google MP.jpg / MVIMG、Samsung）。
多个输入	按顺序渲染并合并为一个 MP4。每个输入都会单独进行色彩显现。

使用 --still 忽略 Live Photo 或动态照片的视频，仅为静态图像添加动画。

常用命令

# One photo, 2 s reveal + 0.5 s hold
python3 "$skill_dir/scripts/colorize.py" photo.jpg --hold 0.5 -o out/photo.mp4

# Live Photo (IMG_0001.MOV next to it is picked up)
python3 "$skill_dir/scripts/colorize.py" IMG_0001.HEIC -o out/live.mp4

# Video: slower 3 s reveal, keep the first 6 s
python3 "$skill_dir/scripts/colorize.py" clip.mov --duration 3 --max-length 6 -o out/clip.mp4

# Several images and videos as one vertical reel
python3 "$skill_dir/scripts/colorize.py" a.jpg b.heic c.mov --size 1080x1920 -o out/reel.mp4

# Stronger spin and a little more glow
python3 "$skill_dir/scripts/colorize.py" photo.jpg --set angle=0.09 --set bloom=0.7 -o out/strong.mp4

选项

选项	默认值	含义
-o, --output	<first input>_colorize.mp4	输出 MP4 路径。
--duration	2	色彩显现时长，单位为秒。
--hold	0	仅适用于图像：定格最终画面的时长，单位为秒。
--fps	30	输出帧率。
--size WxH	首个输入的宽高比，长边 ≤ --max-edge	强制指定输出尺寸；其他输入会居中裁剪至此尺寸。
--max-edge	1920	未设置 --size 时的长边上限。绝不放大。
--max-length	完整片段	视频：最多保留此时长，单位为秒。
--still	关闭	忽略 Live Photo / 动态照片视频。
--mute	关闭	移除音频。
--set KEY=VALUE	—	覆盖一个效果参数（可重复使用）。
--params file.json	—	覆盖多个效果参数。
--crf	17	x264 质量；数值越低，文件越大、画面越清晰。

效果参数

这些默认值是根据静态照片上的 Jianying 效果堆栈拟合而来。以下参数适用于 --set：

键	默认值	效果
angle	0.0503	旋转模糊弧度；数值越大，效果越强；正负号决定方向。会逐渐衰减至零。
focus_scale	0.9	清晰中心圆盘的最终宽度；数值越大，边缘越快稳定。
motion	0.70	水平运动模糊强度；会逐渐衰减至零。
blur_power	1.0	模糊衰减曲线；数值越大，淡出越快。
front_speed	0.63	色彩扫过的速度。
edge	0.24	色彩与黑白边界的柔和度。
bloom / rays	0.54 / 0.29	柔和辉光和径向光线强度。
softness	2.3	残余柔化程度；0 最清晰。
saturation	0.98	最终饱和度。
center_x, center_y	0.5	旋转中心，使用 UV 坐标（y 轴向上）。

行为

• 使用 moderngl 通过 OpenGL 3.3 在 GPU 上渲染（无头 Linux 上回退至 EGL），并通过 ffmpeg 编码为 H.264 yuv420p BT.709 MP4。
• 输出遵循首个输入的宽高比和方向，包括手机视频中的旋转元数据。
• 当 ffmpeg 支持 zscale 时，会将 HDR（HLG/PQ）视频映射为 SDR。
• HEIC/AVIF 静态图像需要 pillow-heif、macOS sips，或支持 HEIF 的 ffmpeg。
• 如果任一输入带有音频，则每个片段都会包含 AAC 音轨（图像片段使用静音），以确保合并后的片段保持同步。
• 短于 --duration 的视频会使用压缩后的色彩显现效果，但最终仍会完全稳定。
• 使用 ffprobe 检查输出尺寸、时长和音频后，会打印 VALIDATION=PASS。

要求

• Python 3.9+，以及 numpy、moderngl、Pillow（scripts/requirements.txt）；可选的 pillow-heif
• PATH 中需有 ffmpeg 和 ffprobe
• 配备支持 OpenGL 3.3 的 GPU 或驱动（macOS、Windows、桌面 Linux，或带 EGL 的 Linux）

在 macOS 上，如果 moderngl 必须从源代码构建：CXXFLAGS='-std=c++11' python3 -m pip install moderngl。