OpenKatana · Transcribe audio:
OpenKatana_transcribe_audio converts spoken audio into readable text with timing information for individual words and longer speech segments, helping you prepare captions and review dialogue for creative projects. It uses faster-whisper to run Whisper speech recognition locally with a model already present in the local cache; the transcription process does not download models. Before recognition, it uses FFmpeg to convert the selected audio into a consistent mono, 16 kHz format suitable for speech processing. It can detect the spoken language automatically or recognize speech using a specified language, and it can process an entire recording or a selected section. The underlying transcription routine attempts GPU processing first and falls back to CPU processing if the GPU attempt fails. Word-level confidence estimates help you identify parts that may need closer attention. The transcript is machine-generated, so you should check words, names, and timings against the recording before using it for final captions.
OpenKatana · Transcribe audio Input Parameters:
project_id
A required STRING identifying the OpenKatana project associated with this transcription task. The transcription API resolves the project and accesses its state before processing the recording, and the transcript is written within the project's transcript output location. Use the identifier for the project you intend to work in, rather than an audio filename or the recognized text. The supplied node class does not show a default value, allowed identifier list, or minimum and maximum string lengths, so these cannot be specified from the available information.
arguments
A required STRING containing the tool arguments as a JSON object. This is where you describe the recording and any transcription settings, rather than adding extra node sockets. The underlying transcription API accepts source for the recording to process, model for an optional locally cached model, language for an optional language hint, start for the beginning of the selected section in seconds, and duration for its length in seconds. For example, {"source": "/path/to/recording.wav", "language": "en", "start": 10, "duration": 30} requests a 30-second section beginning 10 seconds into the recording, provided that the source is accepted by OpenKatana's source resolver. The underlying API defaults are model=None, language=None, start=0, and duration=None; an unspecified language allows automatic detection, and an unspecified duration leaves the extraction length unrestricted by a duration setting. The start value must be at least 0, and a supplied duration must be between 0.2 and 7200 seconds. A supplied language must match two or three lowercase letters; en is an example accepted by the validation. The provided code does not identify the default model or enumerate supported model choices, so check OpenKatana's transcription capabilities before selecting one. These are settings inside the JSON text, not additional node inputs. The node class does not show a default value or length limits for the arguments STRING itself.
after
An optional STRING accepted by the node's execution method, with a Python default of None when omitted. In the supplied execution code, this value is not explicitly read, merged into the transcription arguments, or passed to the transcription API. It therefore does not select an audio range, change recognition settings, or specify a transcript destination. Any broader workflow behavior associated with this socket is not documented in the supplied implementation, so do not rely on it to change transcription behavior. No allowed values or minimum and maximum string lengths are shown.
OpenKatana · Transcribe audio Output Parameters:
result_json
A STRING containing the JSON-formatted response returned through OpenKatana's tool-response wrapper. On success, the underlying transcription result includes words_file, the path to the generated words.json file; text, the recognized segment text joined together; words and segments, which are counts rather than lists in this summary; and language, model, and device, which identify the detected language, model used, and actual processing device. It also includes low_confidence, containing up to 40 words whose confidence probabilities are below 0.5, and may include fallback with details of failed device attempts before a successful attempt. The next field recommends checking the text before using the words file with make_captions. The referenced words.json file contains the complete word and segment lists, including start and end times, individual word probabilities, language-detection probability, source information, a SHA-256 source fingerprint, and the requested processing range. Its timestamps are measured in seconds from the beginning of the original source file, not from the beginning of the extracted section; for example, a word recognized two seconds into a section starting at 10 seconds is recorded at approximately 12 seconds. The output socket is a JSON string, not a direct audio object, subtitle file, or word-list socket. The exact outer response structure is not shown in the supplied wrapper code.
OpenKatana · Transcribe audio Usage Tips:
- Check OpenKatana's transcription capabilities before running a large job. The code points to
get_capabilitiesfor transcription availability and cached-model information, and this transcription routine does not download a missing model. - Make sure FFmpeg is installed and available to the process running ComfyUI. The recording must be decoded successfully before speech recognition can begin, even if faster-whisper and a suitable model are already available.
- For a recording in a known language, include a language hint such as
"language": "en"insidearguments. Omit the setting or use JSONnullwhen you want automatic language detection; the supplied API accepts a single language hint, not a list. - Test a short section before processing a long recording. For example,
"start": 20, "duration": 15lets you check recognition quality on a 15-second passage without transcribing the entire file. Keep an explicitly supplied duration within 0.2–7200 seconds. - Do not add a
devicesetting based on the underlying transcription function alone. Although that function supports device selection, the exposedtranscribe_audioAPI shown here does not accept it; its default behavior attempts CUDA with float16 computation, then CPU with int8 computation. - Inspect the returned
deviceand anyfallbackinformation when a run is unexpectedly slow. A successful CPU fallback means transcription completed, but the earlier GPU attempt encountered a problem that may be worth addressing before larger jobs. - Review
low_confidenceentries first, then listen through the remaining transcript. This list is capped at 40 entries and includes only words with probabilities below 0.5, so an empty list does not guarantee that every word is correct. - Preserve the original-source timing when preparing captions. The transcript already includes the selected section's start offset; follow the captioning tool's offset requirements when placing that source on a timeline rather than adding the extraction start a second time.
- Use
words_filefor the subsequent captioning step after reviewing the transcript. The combinedtextfield is convenient for reading, but the saved file contains the word timings needed for time-aligned captions.
OpenKatana · Transcribe audio Common Errors and Solutions:
<filename>: no decodable audio in the requested range (...)
- Explanation: FFmpeg failed to produce usable audio for the requested section. The code raises this error if decoding fails, the temporary audio file is missing, or the file contains no usable audio data. Possible causes include a recording without a decodable audio track, an inaccessible or damaged source, or a start position beyond the available audio. The parentheses contain a shortened FFmpeg diagnostic when available.
- Solution: Confirm that the source opens and contains audio, check that the selected start and duration overlap the recording, and try a short section near the beginning. Read the diagnostic text for format or file-access problems, and replace or re-export a damaged recording if necessary.
Transcription failed: cuda: ...; cpu: ...
- Explanation: All attempted recognition devices failed. In the default automatic mode, the routine tries CUDA first and then CPU, collecting the exception type and a shortened explanation from each failed attempt. A failed GPU attempt alone does not stop the task if CPU transcription succeeds.
- Solution: Read both device-specific messages. Check that the selected model is already cached and loadable, verify the faster-whisper installation, and address any reported memory or runtime problems. If both attempts report a missing model, resolve the model cache issue rather than changing GPU settings.
language: an ISO 639-1 code such as en, or null to detect
- Explanation: The language setting failed validation. The supplied code requires two or three lowercase letters when a language is provided, so values such as
English,EN, oren-USdo not pass this check. - Solution: Use a supported lowercase language code such as
"language": "en", omit the setting, or set it to JSONnullfor automatic detection. Matching the validation pattern alone does not establish that every possible code is supported by the recognition engine.
Invalid start or duration value
- Explanation: The API validates the selected time range before transcription.
startmust be numeric and at least 0, while a supplieddurationmust be numeric and between 0.2 and 7200 seconds. The exact validation error text is not included in the supplied code. - Solution: Enter times as JSON numbers in seconds, such as
"start": 0and"duration": 30, rather than time strings such as"00:30". Omitdurationor usenullif you do not want to set an extraction length, and make sure the selected section actually exists in the source.
Missing or unavailable faster_whisper
- Explanation: The availability check returns false when importing
faster_whisperraisesImportError. This means the local speech-recognition dependency is not available to the Python environment running OpenKatana. The supplied snippets do not show the exact message displayed by the node for this condition. - Solution: Install or repair faster-whisper in the same Python environment used by ComfyUI, restart ComfyUI, and check transcription capabilities again. Installing it in a different Python environment will not make it available to this node.
FFmpeg executable not found
- Explanation: The audio preparation step launches the
ffmpegcommand directly. If the executable is missing or cannot be found by ComfyUI's process, transcription cannot reach the recognition stage. The exact operating-system error wording varies. - Solution: Install FFmpeg and ensure its executable is available on the PATH used to launch ComfyUI. Restart ComfyUI after changing the environment, especially when it runs through a launcher, service, or container.
Missing or unloadable locally cached model
- Explanation: The model is loaded with
local_files_only=True, so the transcription routine cannot fetch missing model files. Missing, incomplete, or incompatible cached files can appear as model-loading errors inside the device failure report. - Solution: Check the available transcription models through OpenKatana's capabilities information and select an installed model. If its cache is incomplete, restore or provision the model separately before retrying; this node does not perform that download for you.
Invalid JSON in arguments
- Explanation: The node sends the
argumentsstring through an argument-processing helper. Malformed JSON, such as unquoted property names, single-quoted strings, or trailing commas, can prevent the request from being interpreted. The helper's exact error wording is not supplied. - Solution: Use a valid JSON object such as
{"source": "/path/to/recording.wav", "language": "en"}. Use double quotes for property names and strings, and write JSONnullrather than PythonNone.
unexpected inputs: ...
- Explanation: The node explicitly raises this error when execution receives extra fields that are not declared as supported typed inputs. The authoritative interface here exposes only
project_id,arguments, and optionalafter. - Solution: Remove additional node-level fields. Put supported transcription settings such as
source,language,start, anddurationinside theargumentsJSON object rather than supplying them as separate sockets or execution fields.
