OpenKatana · Compare reference:
OpenKatana_compare_reference helps you review a rendered video against a reference so you can judge how closely your work follows the intended visual direction. The available comparison tools include paired still frames at selected moments, a side-by-side video preview, and numerical look-difference measurements. Paired frames make it easier to inspect composition, timing, and visible details without switching between separate videos, while look measurements provide an additional quantitative check. The frame-comparison method preserves each image’s proportions inside a common viewing area and can account for a timing offset between the two videos. These tools support your own visual judgment rather than automatically proving that effects, typography, or artistic style are equivalent.
OpenKatana · Compare reference Input Parameters:
project_id
A required STRING identifying the OpenKatana project for the comparison request. The node passes this value into the tool-argument preparation step, providing project context for the operation. Use the identifier of the project you have already created; the supplied test creates a project before requesting a comparison. This is a project identifier, not a video filename. The provided node interface does not specify a default value, allowed identifier format, length limits, or a list of available options.
arguments
A required STRING containing the arguments for the comparison tool, supplied as JSON text. This is where you describe the comparison request rather than adding extra input sockets to the node. The supplied tests establish that the comparison needs at least one of the comparison choices named times, side_by_side, or look; a request without any of these is rejected, while enabling look produces a result containing a look entry. For explicit frame comparisons, the supplied implementation accepts between 1 and 12 comparison times and extracts corresponding frames from the reference and render, with an offset applied to the render’s sampling times. The complete comparison API signature and media-path argument names are not included in the context, so use the tool’s documented schema when constructing the full JSON request rather than guessing those keys. No default string value or overall string-length limits are specified by the provided node interface.
after
An optional STRING accepted by the node’s execution method. In the supplied implementation, this value is not included in the prepared comparison arguments or explicitly passed to the tool invocation, so there is no demonstrated effect on frame selection, look measurements, or comparison content. A connected value can provide an input dependency in your workflow, but the supplied code does not establish any additional sequencing or status-checking behavior. The execution method defaults to None when this input is omitted; no string default, length limits, or selectable options are shown.
OpenKatana · Compare reference Output Parameters:
result_json
A STRING containing the tool response in JSON form, suitable for inspecting the comparison results or passing to another node that reads JSON. The contents depend on the comparison options you request rather than following one fully documented response structure in the supplied context. For explicit frame comparisons, the underlying implementation returns preview_images containing paths to generated comparison sheets, times containing the requested reference timestamps, render_offset recording the render timing offset, and a note explaining the method’s limitations. Each sheet places reference frames on the left and render frames on the right, labels them with their sampling times, and contains up to three frame pairs; the sheets are 960 pixels wide, with 390 pixels of height per pair. Look comparison is confirmed to produce a look entry at the API level, and the underlying measurement helper includes render_minus_reference values; comparing a video with itself produces values effectively equal to zero in the supplied test. The output is text describing results and generated assets, not a direct ComfyUI image or video output, and the exact outer response structure is not shown.
OpenKatana · Compare reference Usage Tips:
- Choose a comparison mode explicitly in
arguments. Usetimesfor inspecting particular moments,side_by_sidefor a paired video review, orlookfor numerical look differences, following the comparison tool’s full argument schema. - For frame comparisons, select 1–12 useful timestamps rather than sampling randomly. Moments near a cut, a major composition change, or a distinctive visual effect are good candidates for checking whether the render follows the reference.
- Start with three comparison times for a compact review. The frame-comparison helper places up to three pairs on each sheet, so three samples produce one sheet, while twelve produce four sheets.
- Keep timestamps within the playable portions of both videos. If your comparison configuration applies a render offset, check the adjusted render timestamps too: the implementation samples the render at the reference time plus the offset.
- Use the timestamp labels when diagnosing timing differences. A positive offset samples a later moment in the render, while a negative offset samples an earlier moment; confirm the API’s offset argument name before adding it to your JSON.
- Inspect aspect ratio and framing separately from the comparison layout. Each frame is fitted into a 480-by-360 viewing area with padding, so empty borders in the sheet may come from the review layout rather than from your original footage.
- Use look measurements alongside visual inspection, not as an automatic artistic approval score. The supplied code explicitly avoids claiming automatic equivalence for aesthetics, effects, or fonts.
- When checking whether your setup works, compare a video with itself using look comparison. The supplied test verifies that the underlying numerical differences are effectively zero for this case.
OpenKatana · Compare reference Common Errors and Solutions:
times, side_by_side or look
- Explanation: This exact text is the error fragment checked by the supplied test when a comparison request does not select any comparison mode. Providing the project and video sources alone is not sufficient.
- Solution: Add at least one supported comparison choice to your JSON arguments, such as enabling
lookor supplying comparisontimes, using the tool’s documented argument schema.
Supply 1..12 comparison times
- Explanation: The frame-comparison implementation raises this exact error when the number of requested timestamps is outside the supported range. An empty list or a list containing more than twelve times cannot be processed by this method.
- Solution: Supply between one and twelve timestamps. If you need more samples, divide them into separate comparison requests.
unexpected inputs: …
- Explanation: The node raises this error if its execution receives additional field names that are not declared in its typed inputs. The supplied interface exposes only
project_id,arguments, and optionalafter. - Solution: Keep those input names unchanged and place tool-specific comparison settings inside
arguments. If an older workflow contains additional sockets, recreate the node using the currently loaded version.
Invalid JSON in arguments
- Explanation: This is a troubleshooting category rather than an exact error string shown in the supplied code. Since
argumentssupplies JSON text, malformed text can prevent the request from being prepared correctly; the parser’s exact error message is not provided. - Solution: Validate your JSON before running the node. Use double quotes around property names and text values, use lowercase
trueandfalsefor JSON booleans, and remove trailing commas.
Media cannot be opened or a requested frame cannot be extracted
- Explanation: The exact error wording is not shown in the supplied context. The comparison tools need readable media, and frame comparison needs valid sampling times in both sources; missing files, inaccessible paths, or timestamps outside the media duration can prevent a useful comparison.
- Solution: Verify that both videos are accessible from the machine running OpenKatana, confirm that they play correctly, and begin with a timestamp safely inside both videos. If using a render offset, check that the adjusted timestamp remains valid.
FileExistsError when creating the comparison output directory
- Explanation: The frame-comparison helper creates its output directory with
exist_ok=False, so it can fail if that directory already exists. The exact directory path and full exception wording depend on the request, and the supplied node code does not show how the API chooses that directory. - Solution: Check the output location reported in the error. Preserve any results you need before removing or renaming a conflicting directory, and use a fresh output location if the tool’s documented arguments allow you to choose one.
