OpenKatana · Import media batch:
OpenKatana_import_media_batch imports several excerpts from one source media file into an OpenKatana project in a single tracked operation. It is useful when you want to turn a longer recording into smaller assets for editing, review, or further creative work without changing the original file. Excerpts are processed sequentially, and the operation records each imported asset as it finishes, helping you identify what was completed if a later excerpt fails. The batch also calculates a source-file fingerprint and checks that the source remains unchanged during processing, helping keep the imported assets consistent with their recorded origin. Repeating the same successful request with the same request identifier and settings returns its recorded assets, as demonstrated by the supplied test, rather than creating another set. If processing fails, the recorded request is not automatically restarted.
OpenKatana · Import media batch Input Parameters:
project_id
A required STRING identifying the OpenKatana project for the operation. Use the identifier of the project where you want the imported excerpts to belong, and keep it consistent with other OpenKatana operations in your workflow. This selects the project context; it does not identify the source media file. The supplied node interface does not specify a default value, a list of allowed identifiers, length limits, or other minimum and maximum constraints.
arguments
A required STRING carrying the batch-import tool arguments as a JSON object. The underlying operation requires a source file path, an excerpts list, and a request identifier; these are entries inside this string, not separate node inputs. For example, {"source":"/path/to/source.mp4","excerpts":[`{"start":0,"duration":0.25}`,`{"start":0.25,"duration":0.25}`],"request_id":"batch-001","rights":"own"} requests two short excerpts from the same file. Each excerpt supplies settings passed to the media importer: start selects the starting time in seconds, duration sets the excerpt length in seconds, max_width optionally limits video width, and audio_only requests audio rather than a visual excerpt. The underlying importer defaults to start=0, duration=None, max_width=None, and audio_only=False; leaving duration unspecified does not impose a short excerpt length. The batch operation defaults rights to review_pending when omitted. Rights records describe provenance and do not establish legal clearance. The supplied interface defines no default string, size limits, or selectable options for arguments, and the provided implementation excerpt does not establish all validation rules for its contents.
after
An optional STRING accepted by the shared tool interface. The supplied execution code accepts this value but does not explicitly read it or pass it to the batch-import operation, so it should not be treated as a media setting, an excerpt selector, or a request identifier. Its presence can provide a connection point in the workflow, but the supplied code does not document a particular value format or additional execution behavior. No default, allowed options, or minimum and maximum constraints are shown. Leave it unconnected unless your surrounding workflow requires this shared interface connection.
OpenKatana · Import media batch Output Parameters:
result_json
A STRING containing the tool response in JSON form. The underlying batch result records the request signature in request, the source file’s SHA-256 fingerprint in source_sha256, the processing status in state, and the imported asset records in assets. The implementation initially records running and changes the state to succeeded when all excerpts finish. If an exception occurs during the processing loop, it records failed, an error message, and the note Inspect recorded assets; this request is not automatically restarted. Asset records already appended before the failure remain in the result, so a failed batch can still contain successfully imported excerpts. Inspect the state and asset list before continuing with editing or other downstream work; receiving a JSON response alone does not establish that the complete batch succeeded. The exact outer response formatting is handled by shared bridge code that is not included in the supplied context.
OpenKatana · Import media batch Usage Tips:
- Start with a small test batch, such as two excerpts lasting 0.25 seconds each, before importing longer sections. This mirrors the supplied live test and helps you verify the source path and timing with limited processing.
- Specify
durationexplicitly for each excerpt when you only need a short section. The media-import documentation recommends inspecting the source first and avoiding extraction of an entire long video unnecessarily. - Use
max_widthinside excerpt entries when you need smaller video assets for review or lightweight downstream processing. For example,{"start":10,"duration":3,"max_width":320}requests a short, width-limited excerpt. - Use
audio_only:trueinside an excerpt entry when you need only its audio. This node does not expose the IMAGE, VIDEO, AUDIO, or frame-rate sockets of the separate OpenKatanaImportMedia node. - Keep the source file unchanged until the batch finishes. Avoid exporting over it, replacing it, or editing it in place while excerpts are being imported.
- Reuse the same
request_idwith the same settings when retrieving a previously successful batch. For a failed request, inspect the recorded assets before making a new request so you do not unintentionally import completed excerpts again. - Choose a rights label that accurately describes your source. The related media-import interface lists
review_pending,own,licensed, andpublic_domain; the batch signature itself accepts a string and defaults toreview_pending. A label is a provenance record, not permission to use the media. - Treat HDR and rotation-sensitive footage separately when necessary. The supplied import documentation warns that HDR and rotation require explicit conformance; batch import should not be assumed to perform those corrections automatically.
OpenKatana · Import media batch Common Errors and Solutions:
Source changed during batch import
- Explanation: The importer detected a change in the source file’s size or timestamps during processing. This check helps prevent different excerpts in the same batch from being imported from different versions of the file.
- Solution: Wait until recording, downloading, or exporting has finished, then import from a stable copy. Inspect any assets already recorded by the failed batch before submitting a new request.
Inspect recorded assets; this request is not automatically restarted.
- Explanation: This is a failure note rather than the original error message. It means processing stopped and the saved request will not automatically restart; some excerpts may already have been imported.
- Solution: Read the accompanying
errorfield and inspectassets. Correct the underlying problem, then use a new request identifier for a deliberately revised batch containing only the excerpts you still need.
unexpected inputs: ...
- Explanation: The node explicitly raises this error if execution supplies unsupported extra fields. This node exposes only
project_id,arguments, and optionalafter; source and excerpt settings are not additional sockets. - Solution: Remove unsupported top-level inputs and place
source,excerpts,request_id, and any batch rights setting inside the JSON string supplied througharguments.
Invalid JSON in arguments — exact message depends on the shared argument parser
- Explanation: The batch settings must be readable as a JSON object. Missing quotation marks, trailing commas, or Python-style values such as
Truecan prevent parsing before the import starts. The supplied context does not show the parser’s exact error wording. - Solution: Use double-quoted property names and strings, lowercase JSON booleans such as
true, and no trailing commas. Begin with the example in theargumentsdescription and replace its file path and request identifier.
Missing required batch arguments — exact message depends on argument handling
- Explanation: The underlying batch operation requires
source,excerpts, andrequest_idin addition to the project context. Omitting one can prevent the operation from starting; the exact validation message is not supplied. - Solution: Include all three entries in
arguments. Supply a source path accessible to the OpenKatana process, a list of excerpt objects, and a request identifier.
Source file cannot be accessed — exact message depends on the filesystem
- Explanation: The implementation reads file information and calculates a digest from the source. A missing file, an inaccessible location, or insufficient read permission can therefore stop processing. The exact error wording and handling for these early steps are not shown.
- Solution: Verify that the path exists on the machine running OpenKatana, not only on your local workstation. Use a complete path where practical and make sure the running process can read the file.
Excerpt import failed — inspect the error field for the actual message
- Explanation: An exception while importing an individual excerpt changes the batch state to
failedand records the exception text. The supplied code does not enumerate all possible media-processing errors, and earlier excerpts may already be present inassets. - Solution: Read the recorded error, confirm that the source opens correctly, and check the excerpt’s start time and duration against the source length. Test the problematic section with a short duration, and review completed assets before creating another batch.
