DEV Community

Peiguan
Peiguan

Posted on

Why Does My Own Footage Look a Different Color Next to a Hit the Road Dude Clip? Histogram Matching With a .cube LUT, Measured

A common edit with a Hit the Road Dude remake is to cut it together with something you filmed yourself: a "me reading the sign" intro, a reaction shot, your own dog walking up to the truck. Then the cut lands and the two shots don't look like the same world. Your phone footage is warmer, the blacks are grey, the contrast is flat. Ask an assistant how to fix it and you get "use a color-matching tool in your editor". That works if you have one. If you don't, the same idea fits in about a hundred lines of Python and one ffmpeg filter.

This post builds that tool, tests it on clips where the right answer is known, and is honest about where it breaks.

Context: hittheroaddude.app makes the clip from one photo as a 15-second vertical 9:16 video at 480p or 720p with a new voice (FAQ). I haven't run this on customer clips and I'm not publishing any. The tests below use synthetic clips.

The idea: match the distributions, not the average

Shifting brightness until the averages agree fixes one number and leaves contrast and tint wrong. Histogram matching does more. For each channel (R, G, B) it builds a curve that maps the levels of your footage so their distribution matches the reference's. If 30% of the reference's red values are below 80, then after the mapping 30% of yours are too. That fixes lifted blacks, flat contrast and a colour cast in one pass.

Three practical choices:

  1. Sample, don't decode everything. Colour statistics don't need 720p or every frame. The script pulls 24 evenly spaced frames at 160 px wide.
  2. Write the curves as a .cube 3D LUT. ffmpeg's lut3d filter applies it to every frame, and the same file opens in DaVinci Resolve, Premiere or CapCut desktop if you want to finish there.
  3. Keep the curves monotonic. Matching CDFs can produce tiny reversals where a histogram has gaps. A running maximum removes them, so brighter stays brighter.

Test clips with a known answer

ref.mp4 stands in for the generated clip. mine.mp4 is the same picture pushed warm, with lifted blacks and lower contrast, like phone footage under a kitchen light. Because the content is identical, the matched result can be scored against the reference directly.

#!/usr/bin/env bash
# Two synthetic 9:16 clips: ref.mp4 (stands in for the generated clip) and
# mine.mp4 (the same picture with a warm cast, lifted blacks and lower contrast,
# like phone footage shot under indoor light). Because the content is identical,
# the matched result can be scored against ref.mp4 directly.
set -euo pipefail
ffmpeg -v error -y -f lavfi -i "testsrc2=size=270x480:rate=30:duration=4" \
  -f lavfi -i "sine=frequency=440:duration=4" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 -c:a aac -shortest ref.mp4
ffmpeg -v error -y -i ref.mp4 \
  -vf "colorbalance=rs=0.12:gs=0.02:bs=-0.12:rm=0.10:bm=-0.10,eq=contrast=0.80:brightness=0.06:gamma=1.15" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 -c:a copy mine.mp4
echo "wrote ref.mp4 and mine.mp4"
Enter fullscreen mode Exit fullscreen mode

The matcher

#!/usr/bin/env python3
"""Match the colour of one clip (your footage) to another (the generated clip).

Per-channel histogram matching: sample frames from both clips, build one
256-step curve per R/G/B channel that maps the target's distribution onto the
reference's, write it as a .cube LUT and apply it with ffmpeg lut3d.

usage: color_match.py REF.mp4 TARGET.mp4 [--out matched.mp4] [--cube match.cube]
                      [--strength 0..1] [--frames 24] [--score]
Needs Python 3, numpy, ffmpeg and ffprobe on PATH.
"""
import argparse, json, subprocess, sys
import numpy as np

W = 160  # analysis width; colour statistics don't need full resolution

def probe(path):
    out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0",
                          "-show_entries", "stream=width,height:format=duration",
                          "-of", "json", path], capture_output=True, text=True, check=True).stdout
    j = json.loads(out)
    s = j["streams"][0]
    return s["width"], s["height"], float(j["format"]["duration"])

def frames(path, n):
    """Return n evenly spaced RGB frames, downscaled to width W, as uint8 arrays."""
    w, h, dur = probe(path)
    hh = max(2, round(h * W / w / 2) * 2)
    fps = n / dur
    raw = subprocess.run(["ffmpeg", "-v", "error", "-i", path, "-vf",
                          f"fps={fps:.6f},scale={W}:{hh}:flags=area,format=rgb24",
                          "-f", "rawvideo", "-"], capture_output=True, check=True).stdout
    arr = np.frombuffer(raw, np.uint8)
    return arr.reshape(-1, hh, W, 3)

def cdf(values):
    hist = np.bincount(values.ravel(), minlength=256).astype(np.float64)
    c = np.cumsum(hist)
    return c / c[-1]

def match_curves(ref, tgt):
    """One 256-entry curve per channel: target level -> reference level."""
    curves = []
    for ch in range(3):
        cr, ct = cdf(ref[..., ch]), cdf(tgt[..., ch])
        curve = np.interp(ct, cr, np.arange(256))
        curves.append(np.maximum.accumulate(curve))  # keep it monotonic
    return np.stack(curves)  # shape (3, 256)

def write_cube(curves, path, size=33, strength=1.0):
    x = np.linspace(0, 255, size)
    ident = np.arange(256, dtype=np.float64)
    mapped = [np.interp(x, ident, ident + strength * (curves[c] - ident)) / 255 for c in range(3)]
    with open(path, "w") as f:
        f.write(f'TITLE "histogram match"\nLUT_3D_SIZE {size}\n')
        # .cube order: red changes fastest, then green, then blue
        for b in range(size):
            for g in range(size):
                for r in range(size):
                    f.write(f"{mapped[0][r]:.6f} {mapped[1][g]:.6f} {mapped[2][b]:.6f}\n")

def stats(a, b):
    """Mean per-channel level gap and mean CDF gap (0 = identical distributions)."""
    mean_gap = [float(a[..., c].mean() - b[..., c].mean()) for c in range(3)]
    cdf_gap = float(np.mean([np.abs(cdf(a[..., c]) - cdf(b[..., c])).mean() for c in range(3)]))
    return mean_gap, cdf_gap

def psnr(a, b):
    mse = np.mean((a.astype(np.float64) - b.astype(np.float64)) ** 2)
    return 99.0 if mse == 0 else 10 * np.log10(255 ** 2 / mse)

def report(label, ref, x, score):
    mg, cg = stats(x, ref)
    line = f"{label:8s} mean R/G/B vs ref {mg[0]:+6.1f} {mg[1]:+6.1f} {mg[2]:+6.1f}   CDF gap {cg:.3f}"
    if score and len(x) == len(ref):
        line += f"   PSNR vs ref {psnr(x, ref):.1f} dB"
    print(line)

def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("ref"); ap.add_argument("target")
    ap.add_argument("--out", default="matched.mp4"); ap.add_argument("--cube", default="match.cube")
    ap.add_argument("--strength", type=float, default=1.0)
    ap.add_argument("--frames", type=int, default=24)
    ap.add_argument("--score", action="store_true", help="PSNR vs ref (only meaningful for the same content)")
    a = ap.parse_args()
    ref, tgt = frames(a.ref, a.frames), frames(a.target, a.frames)
    n = min(len(ref), len(tgt)); ref, tgt = ref[:n], tgt[:n]
    curves = match_curves(ref, tgt)
    write_cube(curves, a.cube, strength=a.strength)
    subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", a.target, "-vf",
                    f"lut3d=file={a.cube}:interp=tetrahedral,format=yuv420p",
                    "-c:v", "libx264", "-crf", "18", "-c:a", "copy", a.out], check=True)
    out = frames(a.out, a.frames)[:n]
    report("before", ref, tgt, a.score)
    report("after", ref, out, a.score)
    print(f"wrote {a.cube} and {a.out}")
    return 0

if __name__ == "__main__":
    sys.exit(main())
Enter fullscreen mode Exit fullscreen mode

Results

$ bash make_color_test_clips.sh
$ python3 color_match.py ref.mp4 mine.mp4 --score
before   mean R/G/B vs ref  +19.8  +23.7  +14.9   CDF gap 0.076   PSNR vs ref 19.4 dB
after    mean R/G/B vs ref   +0.4   +0.4   +0.2   CDF gap 0.002   PSNR vs ref 35.8 dB
wrote match.cube and matched.mp4

$ python3 color_match.py ref.mp4 mine.mp4 --score --strength 0.5 --out half.mp4 --cube half.cube
before   mean R/G/B vs ref  +19.8  +23.7  +14.9   CDF gap 0.076   PSNR vs ref 19.4 dB
after    mean R/G/B vs ref   +8.7  +10.8   +6.0   CDF gap 0.034   PSNR vs ref 25.6 dB
Enter fullscreen mode Exit fullscreen mode

The full-strength match brings the channel averages within half a level and lifts PSNR against the ground truth from 19.4 dB to 35.8 dB. The residual is mostly encoder noise from two extra H.264 generations. --strength 0.5 moves halfway, which is often what you want on real footage (see below). The LUT is 33x33x33 (35,937 rows), which is the common size editors expect.

Where it breaks

I also matched a clip with completely different content (SMPTE colour bars) to the same reference. The channel averages came within 3 to 4 levels, but that's not a success. The bars got forced into the gradient's palette. Histogram matching assumes both shots contain roughly the same mix of things. A daylight pond scene and your indoor sofa don't, so a full-strength match will tint your sofa to look like grass and sky.

What works better on real footage:

  • Sample the parts that should match. Crop both clips to a comparable region first (-vf crop=... before running the script), such as skin, a road or a sky, and build the LUT from that.
  • Use --strength 0.4 to 0.7. A partial match takes the cast and the black level most of the way without repainting the scene.
  • Match your footage to the generated clip, not the other way round. The remake is one fixed, consistent look across 15 seconds. Your phone clips are the variable part.
  • Check skin by eye. A per-channel curve can't separate "the wall is too orange" from "the face is too orange". If the face goes grey or green, lower the strength.

It also won't fix a white-balance shift that changes during a shot, or mixed lighting (window plus lamp). Those need masks, which is real grading-tool territory.

Where it fits

Join the clips after matching, then watch the cut at full speed on a phone, since that's where people will see it. The check-before-posting guide covers what else to look at in the remake itself. If you're still choosing a resolution, the 480p or 720p guide explains the difference. And only edit a remake made from a photo of yourself, an adult who agreed, or your own pet, labelled as an AI remake.

For reference, checked on November 15, 2026 at 09:33 (UTC+8): one clip at hittheroaddude.app is $9.99 at 480p (6 credits) or $12.99 at 720p (14 credits). Signed-in accounts can buy packs at $27.99 for 30 credits, $71.99 for 100 or $129.99 for 200 (pricing). You can start from a photo here.

Top comments (0)