Back to Details

colorize

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Colorize

Colorize（上色）

Workflow

工作流程

  1. Collect the user's inputs: images, videos, or Live Photos. Use absolute paths.
  2. Resolve the skill directory and install dependencies once (see Requirements).
  3. Run 
    scripts/colorize.py
    with the inputs and an output path.
  4. Wait for 
    VALIDATION=PASS
    and 
    OUTPUT_VIDEO=<absolute path>
    .
  5. Optionally extract a few frames with 
    ffmpeg
    to check the look before replying.
  6. Return the output path and the settings used.
  1. 收集用户输入的图像、视频或 Live Photos。使用绝对路径。
  2. 确定 skill 目录并一次性安装依赖（参见“要求”）。
  3. 使用输入内容和输出路径运行 
    scripts/colorize.py
    。
  4. 等待 
    VALIDATION=PASS
    和 
    OUTPUT_VIDEO=<absolute path>
    。
  5. 可选地使用 
    ffmpeg
    提取几帧，以在回复前检查效果。
  6. 返回输出路径和所使用的设置。

Quick Start

快速开始

bash
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"
If the agent already knows the directory containing this 
SKILL.md
, use that as 
skill_dir
.
bash
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
。

Inputs

输入

InputWhat happens
Image (
png jpg jpeg webp heic heif avif bmp tif
)		Static plate; the reveal lasts 
--duration
seconds, then 
--hold
seconds of the settled frame.
Video (
mp4 mov m4v webm mkv avi gif
)		Each source frame keeps moving; the reveal runs over the first 
--duration
seconds and the rest of the clip keeps the settled look. Audio is kept.
iPhone Live PhotoPass the still (
IMG_0001.HEIC
or 
.JPG
). A same-name 
.MOV
beside it is used automatically, with its audio. Pass the 
.MOV
directly for the same result.
Android motion photoPass the 
.jpg
; the embedded MP4 (Google 
MP.jpg
/ 
MVIMG
, Samsung) is extracted automatically.
Several inputsRendered in order and joined into one MP4. Each input gets its own reveal.
Use 
--still
to ignore Live Photo or motion photo video and animate only the still.
输入处理方式
图像（
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 motion photo传入 
.jpg
；嵌入的 MP4（Google 
MP.jpg
/ 
MVIMG
、Samsung）会被自动提取。
多个输入按顺序渲染并拼接为一个 MP4。每个输入都会获得独立的揭示效果。
使用 
--still
可忽略 Live Photo 或 motion photo 中的视频，仅为静态图像添加动画。

Common Commands

常用命令

bash
undefined
bash
undefined

One photo, 2 s reveal + 0.5 s hold

One photo, 2 s reveal + 0.5 s hold

python3 "$skill_dir/scripts/colorize.py" photo.jpg --hold 0.5 -o out/photo.mp4
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)

Live Photo (IMG_0001.MOV next to it is picked up)

python3 "$skill_dir/scripts/colorize.py" IMG_0001.HEIC -o out/live.mp4
python3 "$skill_dir/scripts/colorize.py" IMG_0001.HEIC -o out/live.mp4

Video: slower 3 s reveal, keep the first 6 s

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
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

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
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

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
undefined
python3 "$skill_dir/scripts/colorize.py" photo.jpg --set angle=0.09 --set bloom=0.7 -o out/strong.mp4
undefined

Options

选项

OptionDefaultMeaning
-o, --output
<first input>_colorize.mp4
Output MP4 path.
--duration
2
Reveal length in seconds.
--hold
0
Images only: seconds to hold the settled frame.
--fps
30
Output frame rate.
--size WxH
first input's aspect, long edge ≤ 
--max-edge
Force output size; other inputs are center-cropped to it.
--max-edge
1920
Long-edge cap when 
--size
is not set. Never upscales.
--max-length
full clipVideos: keep at most this many seconds.
--still
offIgnore Live Photo / motion photo video.
--mute
offDrop audio.
--set KEY=VALUE
—Override one effect parameter (repeatable).
--params file.json
—Override several effect parameters.
--crf
17
x264 quality; lower is larger and sharper.
选项默认值含义
-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 或 motion photo 中的视频。
--mute
关闭移除音频。
--set KEY=VALUE
—覆盖单个效果参数，可重复使用。
--params file.json
—覆盖多个效果参数。
--crf
17
x264 质量；数值越低，文件越大且越清晰。

Effect Parameters

效果参数

The defaults were fitted to the Jianying effect stack on static photos. Useful knobs for 
--set
:
KeyDefaultEffect
angle
0.0503
Spin-blur arc in radians; larger is stronger, the sign sets direction. Decays to zero.
focus_scale
0.9
Final width of the sharp center disc; larger settles the edges sooner.
motion
0.70
Horizontal motion-blur strength; decays to zero.
blur_power
1.0
Blur decay curve; larger fades faster.
front_speed
0.63
Speed of the color sweep.
edge
0.24
Softness of the color/mono boundary.
bloom
/ 
rays
0.54
/ 
0.29
Soft glow and radial light-ray strength.
softness
2.3
Residual softening; 
0
is sharpest.
saturation
0.98
Final saturation.
center_x
, 
center_y
0.5
Spin center in UV (y up).
默认值已针对静态照片适配剪映（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 轴向上）。

Behavior

行为

  • Renders on the GPU with OpenGL 3.3 through 
    moderngl
    (falls back to EGL on headless Linux) and encodes H.264 
    yuv420p
    BT.709 MP4 with 
    ffmpeg
    .
  • Output follows the first input's aspect ratio and orientation, including rotation metadata on phone videos.
  • HDR (HLG/PQ) videos are tone-mapped to SDR when 
    ffmpeg
    has 
    zscale
    .
  • HEIC/AVIF stills need 
    pillow-heif
    , macOS 
    sips
    , or an 
    ffmpeg
    with HEIF support.
  • When any input has audio, every segment carries an AAC track (silence for images) so joined clips stay in sync.
  • Videos shorter than 
    --duration
    get a compressed reveal that still ends fully settled.
  • Prints 
    VALIDATION=PASS
    after checking the output's size, duration, and audio with 
    ffprobe
    .
  • 通过 
    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
    。

Requirements

要求

  • Python 3.9+ with 
    numpy
    , 
    moderngl
    , 
    Pillow
    (
    scripts/requirements.txt
    ); optional 
    pillow-heif
  • ffmpeg
    and 
    ffprobe
    on 
    PATH
  • A GPU or driver with OpenGL 3.3 (macOS, Windows, desktop Linux, or Linux with EGL)
On macOS, if 
moderngl
has to build from source: 
CXXFLAGS='-std=c++11' python3 -m pip install moderngl
.
  • Python 3.9+，并安装 
    numpy
    、
    moderngl
    、
    Pillow
    （
    scripts/requirements.txt
    ）；可选安装 
    pillow-heif
  • ffmpeg
    和 
    ffprobe
    已添加到 
    PATH
  • 支持 OpenGL 3.3 的 GPU 或驱动程序（macOS、Windows、桌面 Linux，或带 EGL 的 Linux）
在 macOS 上，如果 
moderngl
必须从源代码构建：
bash
CXXFLAGS='-std=c++11' python3 -m pip install moderngl