R RenderComp
remotion visual-regression testing render-still lambda

Remotionの画像差分テストでしきい値を決める方法

執筆: RenderComp チーム 編集方針

Remotion では、動画はフレーム番号を入力にとる React コンポーネントの計算結果です。同じ props と同じフレーム番号を渡せば同じ絵が出るので、特定のフレームを静止画として書き出し、前回の画像と画素単位で比べるテストが組めます。レイアウト崩れやフォントの差し替わりは、目で動画を見返すより先にこの比較で見つかります。

実際に組むと、詰まるのはしきい値です。差分ゼロを合格条件にすると、出力形式や拡大率の設定次第で毎回落ちるテストになります。逆に緩めすぎると、ボタンが 1 つ消えても通ってしまいます。この記事では、しきい値を出力設定とセットで決める手順を、コードと一緒に追います。


テスト対象のフレームを決める

比較するフレームは、アニメーションの途中より、動きが止まった直後や Sequence の切り替わり直後を選ぶと意図が読みやすくなります。次のコンポジションは 30fps で、タイトルが 0〜20 フレームでフェードインし、45 フレーム目からサブタイトルの Sequence が始まります。

import {AbsoluteFill, Sequence, interpolate, useCurrentFrame, useVideoConfig} from 'remotion';

export const TitleCard: React.FC<{title: string; subtitle: string}> = ({title, subtitle}) => {
  const frame = useCurrentFrame();
  const {width} = useVideoConfig();

  // 0〜20フレームで不透明度を0→1に。20フレーム以降は1で固定される
  const opacity = interpolate(frame, [0, 20], [0, 1], {
    extrapolateLeft: 'clamp',
    extrapolateRight: 'clamp',
  });

  return (
    <AbsoluteFill style={{backgroundColor: '#0b0b10', justifyContent: 'center', alignItems: 'center'}}>
      <h1 style={{opacity, color: 'white', fontSize: width * 0.06}}>{title}</h1>
      {/* 45フレーム目から表示。差分テストではこの境界の直後を撮る */}
      <Sequence from={45} layout="none">
        <p style={{color: '#9aa0b4', fontSize: width * 0.025}}>{subtitle}</p>
      </Sequence>
    </AbsoluteFill>
  );
};

このコンポジションなら、フェードが終わった 20 フレーム目と、サブタイトルが出た 45 フレーム目の 2 枚を撮れば足ります。フェードの途中を撮ると、interpolate の範囲を少し変えただけで不透明度が変わり、意図した修正でもテストが落ちます。


基準画像は PNG で書き出す

renderStill の imageFormat には png、jpeg、pdf、webp を指定でき、既定値は png です。差分テストでは既定のまま PNG を使います。JPEG を選ぶと jpegQuality に 0〜100 の整数を渡すことになり、既定値は 80 です。非可逆圧縮のノイズが画素差分に混ざるので、そのぶんしきい値を緩める必要が出てきます。

jpegQuality は PNG で書き出すときには効きません。設定ファイルに jpegQuality を残したまま形式だけ PNG に切り替えても、出力は変わりません。品質値を変えたのに差分が出ないときは、この組み合わせを疑います。

import {bundle} from '@remotion/bundler';
import {renderStill, selectComposition} from '@remotion/renderer';
import path from 'node:path';

// 撮影するフレーム。Sequenceの境界直後とフェード終了直後
const FRAMES = [20, 45];

export const captureFrames = async (outDir: string) => {
  const serveUrl = await bundle({entryPoint: path.resolve('src/index.ts')});
  const inputProps = {title: 'RenderComp', subtitle: 'Visual regression'};

  const composition = await selectComposition({serveUrl, id: 'TitleCard', inputProps});

  for (const frame of FRAMES) {
    await renderStill({
      composition,
      serveUrl,
      inputProps,
      frame,
      output: path.join(outDir, `title-card-${frame}.png`),
      imageFormat: 'png', // 既定値と同じだが、テストの前提として明示しておく
      scale: 1, // 基準画像と比較画像で必ず同じ値にそろえる
    });
  }
};

imageFormat を明示しているのは、後から誰かが既定値に頼らず jpeg に変えたとき、差分テストの前提が崩れたことをコード上で追えるようにするためです。


しきい値は画素数ではなく比率で持つ

scale は 0 より大きく 16 以下の値をとり、既定値は 1 です。16 にすると縦横がそれぞれ 16 倍になり、画素数は 256 倍になります。1 未満も指定でき、0.5 なら縦横が半分になって画素数は 4 分の 1 です。

このため「差分が 500 画素まで」のように画素数でしきい値を書くと、scale を変えた瞬間に意味が変わります。1 から 2 に上げると同じ崩れでも差分の画素数は 4 倍に増えるので、比較的小さな修正でもテストが落ちます。しきい値は画像全体に対する比率で持ち、1 画素ごとの色の許容差とは分けて考えます。

type DiffOptions = {
  // 1画素のRGBAの各チャンネルで、この値を超える差があれば「違う画素」と数える
  channelTolerance: number;
  // 違う画素が全体のこの割合を超えたら失敗にする
  maxDiffRatio: number;
};

// rgbaA / rgbaB は同じ幅・高さでデコード済みのRGBA配列
export const comparePixels = (
  rgbaA: Uint8Array,
  rgbaB: Uint8Array,
  width: number,
  height: number,
  {channelTolerance, maxDiffRatio}: DiffOptions,
) => {
  const total = width * height;
  if (rgbaA.length !== total * 4 || rgbaB.length !== total * 4) {
    // サイズ違いは差分以前の問題。scaleの食い違いがよくある原因
    throw new Error(`Size mismatch: expected ${total * 4} bytes`);
  }

  let diffPixels = 0;
  for (let i = 0; i < rgbaA.length; i += 4) {
    const delta = Math.max(
      Math.abs(rgbaA[i] - rgbaB[i]),
      Math.abs(rgbaA[i + 1] - rgbaB[i + 1]),
      Math.abs(rgbaA[i + 2] - rgbaB[i + 2]),
      Math.abs(rgbaA[i + 3] - rgbaB[i + 3]),
    );
    if (delta > channelTolerance) diffPixels++;
  }

  const ratio = diffPixels / total;
  return {diffPixels, ratio, passed: ratio <= maxDiffRatio};
};

PNG で書き出す前提なら channelTolerance は小さく始め、落ちたフレームの差分画素を目で確かめてから広げます。JPEG に切り替える場合は、jpegQuality を固定したうえで channelTolerance を別に設定します。2 つの形式で同じ値を使い回すと、どちらかが緩すぎるか厳しすぎるかのどちらかになります。

サイズが一致しないときに例外を投げているのは、scale の食い違いを差分率の数字に紛れ込ませないためです。基準画像が scale: 1、比較画像が scale: 2 なら、差分率を計算する前に止めるのが正しい挙動です。


Lambda で回すときの容量

CI から Lambda で基準画像を撮る場合、scale の値はメモリと一時領域の見積もりに直結します。Lambda のメモリは 128 MB から 10,240 MB まで 1 MB 刻みで、/tmp の容量は 512 MB から 10,240 MB まで 1 MB 刻みで設定できます。

scale を 2 にすると 1 枚あたりの画素数は 4 倍になり、撮るフレーム数を増やすほど /tmp に溜まる画像も増えます。先に scale: 1 で全フレームを通し、その出力サイズを見てから拡大率と /tmp の設定を決めると、容量不足で途中終了する事態を避けられます。次にやるのは、上の FRAMES に自分のコンポジションの Sequence 境界を並べ、scale: 1 の PNG で最初の基準画像を書き出すことです。

販売中

1,000以上のRemotionテンプレートを一括入手

買い切り(一括払い)・サブスクなし・生涯アップデート無料。TypeScript製。

料金プランを見る →

無料50本

テンプレート50本を ZIP で受け取る

メールアドレスを入れると、50本の ZIP のリンクをすぐにお送りします。

50本の ZIP をメールで受け取ります。あわせて RenderComp テンプレートの更新と、有料ライブラリを含む製品のご案内を受け取ることに同意します(メールは数通・ワンクリック解除)。 プライバシーポリシー(英語)

メールを使わずに受け取ることもできます。GitHub のリポジトリは公開のままで、登録も不要です。 リポジトリを開く