ComfyUI ALICE Lab Audio Tools is a collection of custom nodes for selecting media ranges, editing and comparing audio, visualizing waveforms and spectrograms, and replacing audio in video workflows.

Status: This is an alpha release. Node interfaces and UI behavior may still change.

<a href="docs/images/workflow-overview.png"> <img src="docs/images/workflow-overview.png" alt="ComfyUI ALICE Lab Audio Tools workflow overview" width="100%"> </a> Example workflow using ALICE Lab Audio Tools. Click the image to view it at full size.

Features

| Category | Node | Purpose | | --- | --- | --- | | Media | Load Media Range (Upload) | Load media from your local device, select an A-B range while viewing its waveform, and output the selected range as AUDIO and VIDEO. | | Media | Load Media Range (Path) | Open media directly from an absolute path, select an A-B range while viewing its waveform, and output the selected range as AUDIO and VIDEO. | | Media | Media Range (Input) | Preview upstream AUDIO or VIDEO, select an A-B range from its waveform, and pass the selected range downstream. | | Audio | Audio Mixer | Arrange and mix up to eight tracks with waveform previews, clip resizing, and per-clip copy, paste, cut, delete, and duplicate operations across tracks. | | Audio | Compare Audio | Compare two waveforms, automatically correct their time difference, and output aligned audio, difference audio, similarity, and delay. | | Audio | Audio Spectrogram | Inspect the frequency content of audio as a dBFS spectrogram and output the graph as an IMAGE. | | Audio | Audio to Irodori Ref Config | Convert AUDIO to the IRODORI_REF_CONFIG used by comfy-Irodori-TTS reference audio input. | | Audio | Output Waveform | Play AUDIO, inspect its waveform and basic audio information, and pass it downstream unchanged. | | Utils | Output Float | Display a connected FLOAT result with a label and selected precision, then pass it downstream unchanged. | | Video | Replace Video Audio | Keep the video image and replace its soundtrack with processed AUDIO. | | Video | Preview Video | Preview VIDEO in the node, download it with a selected filename, and pass it downstream unchanged. |

Nodes appear under these Add Node categories:

ALICE_Lab
├── Audio
├── Media
├── Video
└── Utils

Requirements

ComfyUI with the current AUDIO type and comfy_api.latest video APIs.
PyTorch, normally supplied by ComfyUI.
ffmpeg and ffprobe, both executable by the ComfyUI process.
A modern browser supported by the ComfyUI frontend.

ffmpeg and ffprobe are searched in the process PATH. On macOS, the nodes also check the common Homebrew locations /opt/homebrew/bin and /usr/local/bin because GUI-launched applications may not inherit the shell PATH.

No model, inference engine, CUDA runtime, FFmpeg binary, media sample, or desktop application is bundled with this project.

Installation

Clone or extract this repository directly under ComfyUI/custom_nodes.
Keep the repository entry point at the custom-node root; do not add another nested package directory.
Make sure ffmpeg and ffprobe are visible to the same process that starts ComfyUI.
Restart ComfyUI.
Confirm that the ALICE_Lab categories appear in the Add Node menu.

Expected layout:

ComfyUI/
└── custom_nodes/
    └── ComfyUI-ALICE-Lab-Audio-Tools/
        ├── __init__.py
        ├── src/
        │   ├── nodes.py
        │   ├── audio_compare.py
        │   └── audio_spectrogram.py
        └── web/

There are currently no additional pip dependencies beyond the libraries supplied by ComfyUI. FFmpeg is an external system dependency.

Quick Start

Example workflow JSON files are available in docs/examples/.

Select and process part of a video

Load Media Range
  ├── audio ──> audio processing or Audio Mixer ──> Replace Video Audio.audio
  └── video ──────────────────────────────────────> Replace Video Audio.video

Replace Video Audio.video ──> Preview Video

Compare two audio results

audio result 1 ──> Compare Audio.audio_1
audio result 2 ──> Compare Audio.audio_2

Compare Audio.similarity              ──> Output Float
Compare Audio.audio_2_delay_seconds   ──> Output Float
Compare Audio.1−2 difference          ──> Output Waveform

Create a spectrogram image

AUDIO ──> Audio Spectrogram ──> IMAGE

Use a selected range as Irodori-TTS reference audio

Media Range (Input).audio
  ──> Audio to Irodori Ref Config.audio
  ──> IrodoriTTS Sampler.ref_config

This integration requires comfy-Irodori-TTS for the receiving sampler. ALICE Lab Audio Tools still loads normally when it is not installed.

Node Reference

Load Media Range (Upload)

Loads media from your local device. You can select an A-B range while viewing the waveform, then output the selected range downstream as AUDIO and VIDEO.

Uploaded media must be 100 MB or smaller under ComfyUI's default upload limit. If ComfyUI is started with a different upload-size setting, that configured limit is used instead. Uploaded files are stored under ComfyUI/input.

Inputs:

media: an uploaded media file.
start_seconds: range start, in seconds.
end_seconds: range end, in seconds.

Outputs, in order:

audio: selected 44.1 kHz stereo AUDIO.
start_seconds: actual selected start.
end_seconds: actual selected end.
duration_seconds: selected duration.
video: trimmed VIDEO when the source contains video; otherwise no video value.

Use the Path variant when the media exceeds the upload limit or when you do not want to copy it into ComfyUI/input.

Load Media Range (Path)

Opens media directly from an absolute path without uploading or copying it. You can select an A-B range while viewing the waveform, then output the selected range as AUDIO and VIDEO.

media_path must be an absolute path to a supported file. The range controls and outputs are the same as the Upload variant.

The source is not copied into ComfyUI/input. The ComfyUI server process must have permission to read it.

Use this node only on a trusted ComfyUI server. Do not expose unrestricted server-side paths to untrusted users.

Media Range (Input)

Loads exactly one upstream AUDIO or VIDEO value. You can preview it, select an A-B range from its waveform, and output that selection downstream.

This node can also be used to preview upstream output.

Accepts exactly one upstream input:

audio: preserves the input sample rate and channels while trimming samples directly.
video: trims the video and, when present, extracts its audio as 44.1 kHz stereo.

Run the node once to load its preview and duration. The initial end_seconds = 0 selects the complete input. Edit A-B, then run again to produce the selected range.

For an audio-only input, the video output is unavailable. For a video without an audio stream, the audio output is unavailable.

Media Range controls

Drag A or B to adjust a boundary.
Click the waveform to move the playback position.
Use A−, A+, B−, and B+ for 10 ms adjustments.
Play or loop the selected range.
Left-drag inside the A-B selection to move the complete selection horizontally.
Zoom to A-B, show the complete source, zoom around the pointer with the mouse wheel, and pan with right-drag.
Change Wave height to adjust only the visual waveform scale.
Read adaptive time ticks along the horizontal axis; their interval changes with zoom.

When zoomed, the node requests a more detailed signed min/max waveform for the visible range.

Audio to Irodori Ref Config

Accepts standard ComfyUI AUDIO plus the same normalize_ref_audio and max_ref_seconds options as IrodoriTTS Reference Audio. It outputs IRODORI_REF_CONFIG for direct connection to IrodoriTTS Sampler.

The first audio batch is averaged to mono and written at its original sample rate as PCM16 WAV under ComfyUI/temp/alice_lab_audio_tools/irodori_ref/. The filename is a content hash, so rerunning identical audio reuses the same file. Currently, this can be used with the IrodoriTTS Sampler from comfy-Irodori-TTS.

Audio Mixer

Displays up to eight audio tracks on a shared timeline. You can arrange them while viewing their waveforms, adjust each track, and output both the completed mix and the processed individual tracks.

Accepts up to eight optional inputs, audio_1 through audio_8.

Controls:

Per-track name and waveform color.
Per-clip gain from -100 dB to +24 dB, position, fade in, and fade out.
Mute and solo; one track cannot be both muted and soloed.
Master gain from -100 dB to +24 dB.
Optional peak-based clipping protection.
reset_before_run clears clip edits and copied/pasted clips, then resets gain, position, and fades.
Shared timeline with adaptive time ticks, mouse-wheel zoom, right-drag panning, and Show All to fit every positioned waveform, including waveforms moved outside the previous view.

Click a clip to select it and drag it to change its timeline position. Drag either edge to shorten or extend the clip; trimmed audio can be restored, and areas beyond the available source audio are added as silence. Drag the top handles to edit linear fades. Double-click the dB, Pos, Fade In, or Fade Out label to reset that value to zero. The waveform and mixed output follow the edited clip length.

Right-click a clip for Copy, Cut, Duplicate, or Delete. After copying or cutting, right-click the destination time on the same or another track and choose Paste. Duplicate places a new editable clip directly after the source clip.

A positive position delays a clip. A negative position removes samples that fall before the shared timeline starts.

Outputs:

mixed_audio.
track_1 through track_8, with track gain, position, and fades applied.

Muted, inactive-solo, missing-track outputs are blocked instead of emitting silent audio. Clipping protection applies uniform peak normalization; it is not a limiter, compressor, or LUFS normalizer.

Compare Audio

Displays two waveforms for comparison. It can automatically correct their time difference and output aligned audio, difference audio, an overlay, similarity, and the detected delay.

Inputs:

audio_1 and audio_2.
auto_align: enables time alignment.
max_shift_seconds: search limit from 0 to 30 seconds; default 2 seconds.

Outputs:

Audio 1 only.
Audio 2 only.
1−2 difference.
similarity, from 0.0 to 1.0.
audio_2_delay_seconds; a negative value means Audio 2 was advanced.
1+2 overlay, mixed at equal gain.

The node displays aligned or pre-alignment waveforms, adaptive time ticks, selection controls, playback for each output, alignment and waveform metrics, delay, zoom, pan, loop, and fixed-display controls. With Fixed display enabled, All (stacked) shows Audio 1, Audio 2, and the 1−2 difference vertically on the same time axis.

With auto-alignment enabled, similarity is 0.65 × alignment score + 0.35 × absolute waveform correlation. With it disabled, similarity is the absolute waveform correlation. Similarity, Alignment, Waveform, and Delay show the complete Run result and remain fixed while zooming. Visible Waveform shows the waveform correlation for the visible time range and changes with zoom or pan. This is a signal comparison metric, not speech recognition, speaker identification, perceptual quality assessment, or proof that two recordings are identical.

Similarity metrics are displayed as percentages with six decimal places. Delay is displayed in seconds with four decimal places.

Interactive playback is limited to 600 seconds per request. Detailed comparison data is stored in a bounded in-memory session; run the node again if that session expires.

Audio Spectrogram

Displays the frequency content of AUDIO as a dBFS spectrogram and outputs the displayed graph as an IMAGE for downstream use.

Inputs:

audio.
spectrum_min_db: -144 to 0 dBFS; default -100.
spectrum_max_db: -144 to +12 dBFS; default 0.
start_seconds and end_seconds; an end of 0 analyzes the complete input.

The node displays an interactive dBFS spectrogram. Hover to inspect dBFS, time, and frequency. Drag a range to update the time widgets, then run again to analyze that selection.

Its IMAGE output is a 900 × 520 RGB chart with a title, time axis, frequency axis, and dBFS color bar.

Output Waveform

Plays an AUDIO value so you can confirm its sound and waveform. The waveform includes adaptive time ticks. The node also displays duration, sample rate, channel count, and peak dBFS, then returns the unchanged audio output.

waveform_color = auto uses color metadata already attached to the input AUDIO, including metadata produced by Audio Mixer. A color may also be specified manually.

Output Float

Displays a connected FLOAT result with a custom label and 0 to 12 decimal places, making values such as similarity and delay easy to check. It then returns the same value.

Replace Video Audio

Keeps the image from the connected VIDEO and replaces its soundtrack with the connected AUDIO. The result is output as a new VIDEO for preview or further processing.

The first audio batch is converted to PCM16 for FFmpeg input.
Video is stream-copied when possible.
Audio is encoded as AAC at 192 kbps.
Short audio is padded with silence; long audio is trimmed to the video duration.
If video stream copy fails, the node retries with H.264 (libx264, CRF 18, yuv420p).
If no video is connected, downstream video execution is blocked safely.

Preview Video

Displays a connected VIDEO directly in the node for playback and confirmation. It can be downloaded with the name entered in filename, and the unchanged video is also passed downstream.

The Save button downloads the temporary preview through the browser. It does not write directly to an arbitrary server-side output directory.

Supported Media Extensions

aac  aiff  avi  flac  m2ts  m4a  m4v  mkv  mov
mp3  mp4   mpg  mpeg  ogg   opus ts   wav  webm  wma

Extension support does not guarantee codec support. The installed FFmpeg build must be able to decode the file.

Platform Notes

Windows

Make both ffmpeg.exe and ffprobe.exe visible to the ComfyUI process. Verify drive-letter paths, long paths, and non-ASCII filenames in your environment.

macOS

Apple Silicon media loading has been exercised with Homebrew FFmpeg/ffprobe 8.1.1. The code includes /opt/homebrew/bin and /usr/local/bin fallbacks for GUI-launched ComfyUI processes. Other ComfyUI, frontend, browser, and FFmpeg combinations still require verification.

Ubuntu / Linux

On Ubuntu and other Linux distributions, install FFmpeg through the system package manager or another trusted source, and make both commands visible in the environment used to launch ComfyUI.

A complete release compatibility matrix has not yet been finalized. Compatibility depends on the ComfyUI video API, frontend version, browser, FFmpeg build, codecs, and display scaling.

Troubleshooting

Nodes do not appear

Confirm that __init__.py is at the custom-node repository root.
Check the ComfyUI terminal for import errors.
Confirm that your ComfyUI build provides comfy_api.latest and the current video APIs.
Restart ComfyUI after installation.

The UI width or scaling looks wrong

After a ComfyUI or frontend update, perform a hard refresh so old and new frontend assets are not mixed. On Windows and Linux browsers, use Ctrl+Shift+R. On macOS browsers, use the browser's equivalent cache-bypassing reload.

FFmpeg or ffprobe is not found

Run both commands from the environment used to start ComfyUI.
If ComfyUI is launched from a GUI, verify the process environment rather than only the interactive shell.
On macOS, check /opt/homebrew/bin and /usr/local/bin.
Restart ComfyUI after changing PATH.

A large upload is rejected

Use Load Media Range (Path) or change ComfyUI's upload-size configuration. The Path variant does not upload or copy the source file.

Comparison data expired

Run Compare Audio again. Interactive analysis sessions are intentionally bounded to limit memory use.

Known Limitations

Media support is filtered by extension and then limited by the installed FFmpeg codecs.
File-based Media Range output audio is always 44.1 kHz stereo. Direct AUDIO input to Media Range (Input) preserves its original format.
Audio to Irodori Ref Config uses the first audio batch and averages all of its channels to mono.
Compare Audio uses only the first audio batch and at most two channels.
Automatic alignment uses amplitude-envelope correlation and may select an unintended offset for silence, unrelated sources, repetitive content, or delays outside the search range.
Audio Mixer supports at most eight inputs.
Replace Video Audio produces MP4 and requires libx264 only when stream-copy fallback is needed.
Preview Video downloads a temporary browser preview; it is not a server-side save node.

Disclaimer

This project is provided as-is, without warranty of any kind.

Use of this software is at your own risk. The authors and contributors are not responsible for any data loss, damage, legal issues, or other consequences resulting from its use.

Users are responsible for ensuring that any audio, video, or other media processed with this software is used in accordance with applicable laws, licenses, copyrights, and terms of service.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for the full license terms and the NOTICE file for copyright and attribution information.

Author

ALICE Lab

Articles and Workflows

Development notes, experiments, usage examples, and practical workflows for ALICE Lab Audio Tools are published on note.

ALICE Lab Audio Tools Development Log on note

Support

If you find these tools useful and would like to support ongoing development, testing, and maintenance, you can support ALICE Lab here:

Buy Me a Coffee