video-colorizer
Colorize black-and-white films and shows, frame by frame, with the open-source DDColor model. Then steady the color so it doesn't flicker.
Source on GitHub
Troubleshooting
Directed by Michael Fluharty. Written by Claude. Claude, Anthropic's AI, wrote every script and document, ran the tests and measured the results. Michael set the goal and made the calls. The colorization model itself is DDColor, by its own authors (credits below).
What it does · Getting started · How fast · Common problems · Credits · Need help?
What it does
- Colorize each frame. The picture's brightness and detail stay exactly as they were. The model only adds the color.
- Smooth the color. Color is averaged over 7 frames while brightness comes from the original, so the color doesn't flicker and the picture stays sharp.
- Batch it. Point it at a list of videos. Each result lands beside its original as "name (Colorized).mp4". Originals are never changed, and a stopped batch picks up where it left off.
Getting started
| You need | Notes |
|---|
| A Mac with Apple silicon, or a PC with an NVIDIA graphics card | It also runs on any computer's processor alone, but far more slowly. |
| Python | 3.14 works for the standard path. The faster Mac-only Core ML path needs Python 3.9 to 3.13 (the Mac's built-in Python works). |
| FFmpeg | For reading and writing video. On a Mac: brew install ffmpeg. |
| About 1 GB free, plus room for one extra copy of your largest video | The model's weights are about 0.9 GB and download on first use. |
Step-by-step setup, every command, and the options are in the README on GitHub.
How fast
Measured on an Apple M1 Mac mini with an 8-core GPU, on the same 100 frames:
| Engine | Speed | Picture |
|---|
| PyTorch on the Mac's GPU | 1.86 frames a second | reference |
| Core ML on the Mac's GPU (recommended) | 2.72 frames a second, 1.5× faster | looks the same |
| Core ML on the Neural Engine | 4.58 frames a second, 2.5× faster | colors come out washed out |
At the recommended setting, a 25-minute episode takes about 3 hours 50 minutes, and a 90-minute film about 13 hours, on an M1.
Common problems
- "No matching distribution found for coremltools": your Python is too new for the Core ML path. Use Python 3.9 to 3.13.
- Colors look gray or washed out: you ran Core ML with the Neural Engine (
ALL). Use CPU_AND_GPU.
- "ffmpeg: command not found" only in a background job: background jobs don't load your shell's settings. Add
export PATH=/opt/homebrew/bin:$PATH at the top of the job.
- Very slow, under 1 frame a second: it's using the processor, not the graphics chip. The README shows how to check.
- Squeezed or stretched picture: the video's shape is copied from the original; widescreen sources without that information need the fallback changed.
The full troubleshooting table is in the README.
Check that you have the right to colorize and share a film or show. Many older works are in the public domain, but not all, and some have newer restorations that aren't.
Credits
video-colorizer's scripts are MIT-licensed. Michael Fluharty's copyright claims none of the following work; each belongs to its authors:
- DDColor, the colorization model and its weights, by Xiaoyang Kang, Tao Yang, Wenqi Ouyang, Peiran Ren, Lingzhi Li and Xuansong Xie (ICCV 2023), first released by Alibaba DAMO Academy on ModelScope. Apache License 2.0.
- PyTorch and torchvision (BSD), coremltools by Apple (BSD), timm by Ross Wightman (Apache 2.0), huggingface_hub and safetensors by Hugging Face (Apache 2.0), OpenCV (Apache 2.0), NumPy (BSD), and FFmpeg with x264 (LGPL/GPL), which you install separately.
Need help?
Open an issue on GitHub, or email michael@fluharty.com with what happened, your computer and its operating system version, and the command you ran.