OpenKatana · Render hdr:
OpenKatana_render_hdr finishes high-dynamic-range video compositions while preserving bright highlights and smooth tonal transitions. It processes images in 32-bit floating-point, linear-light BT.2020 color, which provides a wide color range and allows brightness adjustments and blending to behave more naturally than ordinary display-based mixing. It supports trimmed video clips, resizing, exposure adjustments, opacity changes, linear dissolves, and explicit PNG overlays for elements such as titles or graphics. Its HDR finishing workflow is designed to export a 16-bit FFV1 master, a 10-bit HEVC version, and an SDR preview. This is a separate HDR composition workflow rather than an HDR mode for ordinary canvas effects; those effects remain SDR.
OpenKatana · Render hdr Input Parameters:
project_id
Required STRING identifying the existing OpenKatana project in which the render will run. The project establishes the working directory used to locate source media and store HDR renders. The underlying operation checks the project state before rendering, so you should use the identifier returned when you created or retrieved your project. Source files must be local to that project rather than arbitrary files elsewhere on your computer. No default value, length limit, or list of permitted identifiers is specified in the supplied node interface.
arguments
Required STRING carrying the tool arguments as serialized JSON. The underlying render operation takes a document object describing the HDR composition, so this is where you provide that render document through the tool's argument structure. The document must use schema openkatana.hdr/1 and describes the canvas, output settings, clips, overlays, and any supported audio configuration; audio details are not shown in the supplied implementation. Canvas width and height must each be integers from 16 to 4096 and both must be even; frame rate must be an integer from 1 to 120, and total frame count must be an integer from 1 to 72000. Output transfer must be pq or hlg, and peak_nits must be between 100 and 10000. Clip and overlay timing uses frame numbers: start is zero-based, and each item must fit within the canvas duration. Shared item settings include opacity from 0 to 1, default 1, and integer fade_in and fade_out durations from 0 to the item's frame count, default 0. Clips additionally support trim_seconds from 0 to 86400, default 0, exposure from -10 to 10, default 0, and source_color for source color interpretation. Overlays support integer source_start from 0 to 72000, default 0, and white_nits from 1 to the selected output peak, default 203. These are fields inside the JSON document, not additional node sockets. No default string, string-length limits, or complete source_color options are specified in the supplied node interface.
after
Optional STRING accepted by the node's execution method, with a Python default of None when omitted. In the supplied implementation, this value is not read or forwarded to the HDR rendering operation, so no direct effect on image processing, timing, exposure, or export settings is demonstrated. It may serve a surrounding workflow purpose, but its interpretation outside this method is not established by the provided code. No string default, permitted options, or minimum and maximum lengths are specified.
OpenKatana · Render hdr Output Parameters:
result_json
STRING containing the response produced by the OpenKatana tool call, represented as JSON for use by subsequent nodes or for inspection. The underlying HDR API returns a dictionary, which the node passes through its response formatter; this socket therefore carries response data rather than image frames or a directly playable video stream. Inspect its contents for the information returned by your installed renderer before using any fields in downstream processing. The supplied code does not show the renderer's final return dictionary or the response formatter, so exact property names, artifact paths, statistics, and error-envelope structure cannot be guaranteed from this context. Render files are created under the project's HDR-render output location, but the JSON string itself is not those files.
OpenKatana · Render hdr Usage Tips:
- Prepare an existing project and place all clip files and overlay assets inside its directory before rendering. Use project-local source references; overlay sequence frames are also checked individually so that symbolic links cannot redirect them outside the project.
- Start with a short, lower-resolution test composition, such as an even-sized 1280 × 720 canvas, before attempting a long render. The renderer processes full-resolution floating-point frames, so reducing frame count and resolution is a practical way to test timing, color interpretation, and overlay placement with less processing work.
- Plan duration in frames. For example, a 240-frame canvas at 24 fps lasts 10 seconds, and an item beginning at frame 120 with 120 frames occupies the final five seconds. Every item must end within the canvas frame count.
- Set
trim_secondsto choose where decoding begins in a source clip, then ensure the source has enough remaining material to supply the requested frames at the canvas frame rate. The decoder converts sources to the canvas frame rate before supplying frames. - Use
exposurefor predictable brightness changes: 1 doubles the clip's linear-light values, -1 halves them, and 0 leaves them unchanged. Increase it carefully because values above the selected output peak are clipped rather than automatically compressed into range. - Choose
pqorhlgaccording to your delivery requirements, and setpeak_nitsdeliberately. The renderer clamps the final composition to this brightness ceiling; selecting a lower peak can remove highlight detail if your composition exceeds it. - Prepare overlays as full-canvas sRGB RGBA PNGs, including an alpha channel for transparency. For a sequence, use consecutive five-digit filenames such as
00000.png,00001.png, and00002.png;source_startselects the first numbered file. - Set overlay
white_nitsto control how bright white graphics appear in the HDR composition. Its default is 203 nits, so explicitly choose a lower value ifpeak_nitsis below 203; the default would otherwise exceed the permitted range. - Arrange layers intentionally: active clips are composited in document order, and overlays are applied afterward. Later layers blend over the accumulated picture rather than being automatically arranged as tracks with independent priority settings.
- Match source aspect ratios to the canvas when possible. The shown decoding filter resizes directly to the canvas width and height with bilinear scaling; it does not show automatic letterboxing or cropping, so mismatched proportions can stretch.
OpenKatana · Render hdr Common Errors and Solutions:
Expected schema openkatana.hdr/1
- Explanation: The render document has a missing or incorrect schema identifier. This operation uses a dedicated HDR contract rather than an ordinary timeline document.
- Solution: Set the document's
schemato exactlyopenkatana.hdr/1and check that the rest of the document follows the HDR structure.
HDR export requires even dimensions
- Explanation: The canvas width or height is odd, which the HDR export validation rejects.
- Solution: Choose even dimensions within the supported 16–4096 range, such as 1920 × 1080 or 3840 × 2160.
output.transfer must be pq or hlg
- Explanation: The requested output transfer setting is missing or is not one of the two supported values.
- Solution: Use exactly
pqorhlginoutput.transfer. Do not substitute display labels such as “HDR” or “HDR10.”
Numeric validation failure for canvas or output settings
- Explanation: A required value is missing, has an unsuitable numeric type, or falls outside its supported range. The exact error text from the numeric validator is not included in the supplied code.
- Solution: Supply integer canvas width and height from 16 to 4096, integer fps from 1 to 120, integer frame count from 1 to 72000, and output
peak_nitsfrom 100 to 10000. Also ensure both dimensions are even.
Numeric validation failure for clip or overlay timing
- Explanation: An item starts outside the canvas, extends past its end, or has an invalid frame count or fade duration. The exact numeric-validator wording is not shown.
- Solution: Keep
startbetween 0 and one less than the canvas frame count. Set itemframesto at least 1 and no more than the remaining canvas frames. Use integer fade durations between 0 and that item's frame count.
Numeric validation failure for exposure, opacity, trim_seconds, or white_nits
- Explanation: A brightness, blending, or trim setting exceeds the accepted limits. In particular, the default overlay white level of 203 nits is invalid when the output peak is lower than 203 nits.
- Solution: Keep
exposurebetween -10 and 10,opacitybetween 0 and 1, andtrim_secondsbetween 0 and 86400. Set overlaywhite_nitsbetween 1 and your outputpeak_nits.
HDR source must be a local file within the project
- Explanation: A source does not resolve to an existing acceptable file. Clips require files; only overlays may use a directory containing a PNG sequence.
- Solution: Copy the asset into the project, verify its spelling and location, and reference the correct local path. For overlays, confirm that the referenced directory exists if you intend to use a sequence.
Overlay sequence must contain every requested %05d.png frame
- Explanation: A sequence directory is missing at least one requested five-digit PNG filename. Sequence numbering begins at
source_start, which defaults to 0. - Solution: Check every expected file from the starting number through the requested frame count. For example, a three-frame sequence with
source_startset to 10 requires00010.png,00011.png, and00012.png.
Overlays are explicit full-canvas sRGB RGBA PNGs
- Explanation: A file-based overlay does not have the required PNG extension. The overlay contract also requires full-canvas sRGB imagery with an alpha channel.
- Solution: Export the graphic as an sRGB RGBA PNG matching the canvas dimensions. Convert JPEGs or other formats properly rather than simply renaming their extensions.
Source ended before the requested frame count:
- Explanation: FFmpeg could not provide all requested decoded frames. The message may include additional decoder diagnostics; possible causes include insufficient source duration after trimming or a decoding problem.
- Solution: Reduce the item's frame count, move
trim_secondsearlier, or use a longer source. If the duration is sufficient, inspect the appended FFmpeg message and verify that the source file can be decoded.
Nonfinite pixels in HDR source
- Explanation: A decoded clip contains invalid numerical pixel values, such as infinity or an undefined value. The renderer stops instead of blending these values into the composition.
- Solution: Isolate the affected clip with a short test, check its source color interpretation, and regenerate or transcode the source if necessary.
FileExistsError
- Explanation: The renderer's selected output directory already exists. The implementation explicitly refuses to render into an existing directory.
- Solution: Use the surrounding OpenKatana workflow to obtain a fresh output location. If a failed render left a directory behind, inspect and preserve any needed files before removing it and retrying.
unexpected inputs:
- Explanation: Extra node-level fields were supplied that are not recognized by the generated tool interface.
- Solution: Use only
project_id,arguments, and optionalafteras node inputs. Put HDR document settings inside the JSON arguments instead of adding new node sockets.
Invalid arguments JSON or unsupported document fields
- Explanation: The node parses tool arguments, and the HDR validator checks allowed document fields. Malformed JSON, misspelled keys, or unsupported settings can prevent rendering; the exact parser and field-validation messages are not provided.
- Solution: Validate the JSON syntax, use double-quoted keys and strings, and remove comments or trailing commas. Keep document fields within the supplied HDR contract, and do not assume ordinary canvas effects or timeline settings are accepted by this separate renderer.
