OpenKatana · Import media:
OpenKatanaImportMedia, displayed as “OpenKatana · Import media” in the OpenKatana/Media category, brings generated image frames or video into a shared OpenKatana project so you can use them in later editing and rendering steps. It acts as a bridge between media available in your ComfyUI workflow and the project’s stored media assets, saving and transferring the material for import rather than building an edit itself. It supports turning an image sequence into time-based media, preserving available video audio, and including separately connected audio. This makes it useful for combining AI-generated visuals, existing footage, and sound in a common project while recording the selected rights status for the imported material. That rights information documents provenance; it does not verify ownership or provide legal clearance.
OpenKatana · Import media Input Parameters:
project_id
A required STRING identifying the OpenKatana project that receives the imported media. The default is my-film; no minimum or maximum string length is specified in this node. Use the same project identifier across related import, editing, and rendering steps so the assets belong to the project you intend to work with. Changing this value changes the target project passed to the import service; it does not change the visual content or frame rate of your media. The node does not expose project creation or project-access settings.
fps
A required FLOAT setting the playback frame rate for an IMAGE batch, measured in frames per second. The default is 24, the minimum is 1, and the maximum is 120. For a fixed number of image frames, a higher value produces a shorter, faster-playing sequence, while a lower value produces a longer, slower-playing sequence; for example, 48 frames represent approximately two seconds at 24 fps or four seconds at 12 fps. Choose the rate that matches how your frames were generated or how quickly you want the sequence to play. This setting applies only to IMAGE batches and does not override the frame rate of a connected VIDEO.
rights
A required COMBO selection that records the rights status supplied with the import. The available options are review_pending, own, licensed, and public_domain. The source declares no separate default value; review_pending is the first listed option. These choices let you distinguish material awaiting review from material you identify as your own, licensed, or in the public domain. The value is passed to the import service as provenance information, not as proof that you have permission to use the material. Choose the status that accurately reflects your records; selecting an option does not obtain a license or perform legal clearance.
images
An optional IMAGE connection for image content, including batches of frames produced by image or animation workflows. When connected, the node saves the image data for transfer and imports it using the selected fps. This is the visual-source path to use when your material is represented as ComfyUI images rather than a VIDEO object. No default value or numeric range is specified. Although the connection is marked optional, you must provide either images or video for an import to take place, and you must not connect both. If neither is available, the node skips the import.
video
An optional VIDEO connection for video content available in your workflow. The node saves the connected video as an MP4 using H.264 before transferring it for import, so this path involves video serialization rather than simply passing an existing filename to the project. Available video audio can be preserved through the import process. The fps field does not control this video’s frame rate. No default value or numeric range is specified. Connect this instead of images when your visual material is a VIDEO object; connecting both visual-source inputs raises an error.
audio
An optional AUDIO connection for sound to accompany the imported visual media. When supplied, the node saves it as a WAV file in the same transfer as the images or video, making it available to the import process as a separate audio asset. No default value or numeric range is specified. This connection is useful when you have separately generated music, speech, or another soundtrack to bring into the project alongside your visuals. It does not make this node an audio-only importer: if neither images nor video is provided, execution skips before saving the audio. The supplied node code does not establish mixing or replacement rules when a video already has sound and separate audio is also connected.
OpenKatana · Import media Output Parameters:
media_id
A STRING containing the identifier of the imported visual media asset returned by OpenKatana. This is a project asset reference, not the image frames, video data, or a local file path. Its main purpose is to let later OpenKatana operations, such as building an edit, refer to the media that was just imported. Keep those downstream operations associated with the same project. When the import is skipped because no visual source is available, this output is an empty string rather than a usable media identifier.
music_asset_id
A STRING containing the identifier of the audio asset associated with the import, when one is available. Despite the name, it refers to an audio asset and is not limited to music; the import process can handle audio accompanying video or separately supplied audio. You can use the identifier in later operations that accept an audio asset reference. The provided import helper returns an empty string when no audio asset exists, so an empty value does not by itself mean that the visual import failed. This output is also empty when the node skips an import because no visual source is connected.
result_json
A STRING containing the full import-service result serialized as JSON after a successful import. It provides more context than the two asset identifiers alone and is useful for inspecting what the service imported or for passing structured result information to another workflow step. The supplied import helper shows result information including the project identifier, visual asset identifier and record, and audio identifier and record when available. Treat this output as text containing structured data, not as playable media or a file path. If execution is skipped, do not expect a normal successful-import result; the node returns a skip response instead, and the supplied class does not show its exact JSON structure.
OpenKatana · Import media Usage Tips:
- Connect exactly one visual source: use
imagesfor generated image frames orvideofor a VIDEO object. Optional upstream file selections can remain empty, but this node will then skip if neither visual source is supplied. - Match
fpsto the intended timing of your image sequence. For example, use24for 24 generated frames intended to play over approximately one second; increasing the value does not create additional frames or improve their detail. - Do not adjust
fpsto retime a connected video. Prepare the video’s timing upstream if you need a different playback rate, because this node applies that setting only to image batches. - Use a consistent
project_idthroughout the workflow, and passmedia_idto subsequent editing steps that need the imported visual asset. Check that it is nonempty before relying on it. - Connect
audiowhen you need to include a separately prepared soundtrack, but always provide an image or video source as well. If the video already contains audio, inspect the returned audio information rather than assuming separate audio will be mixed with it. - For an initial test, import a short video or a small image batch before transferring a large sequence. This can help you check timing, audio availability, and project selection before committing to a larger import.
- Choose
review_pendingwhile rights are unresolved, and update your rights records based on actual ownership or permission. Selectinglicensedorpublic_domainis a record of your assessment, not an automated verification. - Prepare trimming, resizing, or color and orientation corrections upstream when needed. This node does not expose those controls, and the supplied API documentation notes that HDR and rotation require explicit conformance.
OpenKatana · Import media Common Errors and Solutions:
Connect exactly one IMAGE or VIDEO source
- Explanation: This is the exact ValueError raised when both
imagesandvideoare connected and supply content. The node accepts only one visual-source type per import. - Solution: Disconnect one of the two visual sources. To import both pieces of media, use separate OpenKatanaImportMedia nodes with the same
project_id.
No video or photo chosen; nothing imported.
- Explanation: This is the exact skip message returned when neither
imagesnorvideosupplies content. It is an intentional skip, not a failed media conversion. Connecting onlyaudioalso leads to this result. - Solution: Supply an IMAGE or VIDEO source and check that any upstream file selector has a file chosen. If the empty slot is intentional, no correction is needed; make sure downstream steps can handle empty asset identifiers.
Video cannot be saved or encoded as MP4/H.264
- Explanation: This is a descriptive failure category, not a fixed error message from the class. Before importing a VIDEO, the node calls its save operation with MP4 and H.264 settings. An unreadable video, incompatible object, or unavailable encoding support can prevent that step from completing.
- Solution: Confirm that the upstream node produces a valid VIDEO and that the source can be opened. Try a short, known-working video, then check the detailed ComfyUI error for the failing video component or encoder. Fix that dependency or prepare a compatible video upstream.
Image or audio data cannot be saved
- Explanation: This is a descriptive failure category; the exact message depends on the media-saving helper. Connected images and audio must be saved before the import request is sent, so invalid media data or an unwritable transfer location can stop execution.
- Solution: Check that
imagescomes from an IMAGE output andaudiofrom an AUDIO output. Test a small, known-working sample and confirm that the ComfyUI process has available disk space and permission to write temporary transfer files.
Import service or transfer failure
- Explanation: This is a descriptive failure category, not a literal message defined by the node. After preparing the media, the node sends an
import_framesrequest through the OpenKatana bridge. A failure in that service or its access to the transferred files can prevent asset identifiers from being returned. - Solution: Check the detailed error and OpenKatana service logs, confirm that the bridge and service are running and configured, and verify the intended
project_id. Retry with a small sample to distinguish a general connection problem from a media-specific failure.
music_asset_id is empty
- Explanation: An empty audio identifier is an output condition rather than necessarily an error. The import helper explicitly returns an empty string when no audio asset is available, even if the visual media imported successfully.
- Solution: Check whether your video actually contains an audio track or whether the separate
audioconnection supplies valid sound. If you need audio, provide a valid AUDIO source alongside the visual source and inspectresult_jsonafter importing again.
