Chatterbox SRT / Subtitles 📝

Every TTS tool will read your text. Almost none of them will read your timings, and that's the whole point of a subtitles node. You paste an SRT, the model speaks each cue as its own clip, and - here's the interesting part - the node then tells you the truth about what it made: a new SRT whose timestamps match the audio you actually got, plus a report on what it had to bend to get there.

Why this exists

SRT-driven TTS in ComfyUI has a lineage. The big multi-engine TTS Audio Suite everyone uses was originally a Chatterbox SRT tool before it grew into a hub wrapping F5, VibeVoice, Qwen3-TTS and friends. The pitch is the same here: an SRT is already a shot list for narration. If you have a video cut to length and a subtitle file to match, the file is your script - you don't want to re-time your edit because the voice took nine seconds where you wrote seven.

And that's the actual problem this node solves, because a cue synthesised on its own is however long the model said it was. Written slot: three seconds. Real output: five. Two cues like that and your narration has drifted half a minute behind the picture.

The four timing modes

timing_mode is the setting you're really choosing, and the other timings widgets are just its limits.

• smart_natural (default) - keeps the audio natural, shifts later cues when one runs long, and applies a bounded time-stretch only when drift exceeds timing_tolerance. It never knowingly emits overlapping cues; if honouring the original timings would force an overlap, the track gets re-laid out and the fallback is recorded in timing_report.
• stretch_to_fit - obeys the file exactly and time-stretches audio to each written slot. Distorts the voice. Sometimes that's the trade you want.
• pad_with_silence - natural audio at the SRT start times, gaps filled with silence. Can overlap, and the tooltip says so.
• concatenate - ignores the written timings completely, speaks cues back to back, and writes a fresh SRT from the real timings. The right mode when the SRT was only ever a script and never a schedule.

The stretch limits are worth understanding because the defaults are opinionated. max_stretch_ratio defaults to 1.0, meaning no expansion at all: out of the box only compression is enabled, on the reasoning that slowing speech down is the adjustment a listener always notices. min_stretch_ratio of 0.5 is twice as fast - about as far as synthesis stays intelligible. timing_tolerance at 2.0 lets a line run to three times its written length untouched. And fade_for_StretchToFit (0.01) applies a head/tail fade to stretched clips, because a resampled join is a step discontinuity and a step is a click.

Inputs and outputs

Required: model_pack_name, srt_content (standard SRT, HH:MM:SS,mmm), timing_mode, and then the synthesis knobs - max_new_tokens (25 tokens is roughly one second of audio, so a long cue needs more than the default 1000), flow_cfg_scale, exaggeration, temperature, seed, use_watermark, plus timing_tolerance, max_stretch_ratio, min_stretch_ratio, fade_for_StretchToFit, the runtime device / dtype / attention_mode trio, and crash_protection_template for cues under 21 characters. Subtitle cues are short by nature - "Yes." is a cue - and that's the shape of input upstream Chatterbox fails on.

Optional audio_prompt is the narrator's reference clip; unconnected, you get the checkpoint's built-in voice.

Four outputs, and all four are useful:

• audio - the spoken track, already laid out to timing_mode.
• Adjusted_SRT - the corrected subtitle file. This strings into a text-save node or your own .srt write, and it's the file you ship next to the video.
• timing_report - what the reconciliation actually did, including any fallback re-layouts.
• generation_info - per-cue generation stats.

Keep temperature low here. It's not just taste: a cue whose length changes run to run changes the subtitle file too, so the same prompt gives you a different SRT on every queue.

Install

Manager → Install Custom Nodes → search ComfyUI-Chatterbox → Install → restart. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/wildminder/ComfyUI-Chatterbox.git
pip install -r ComfyUI-Chatterbox/requirements.txt

One added dependency, s3tokenizer; the pack vendored Chatterbox's DSP in pure numpy/torch and dropped librosa, scipy, omegaconf and conformer. ComfyUI >=0.37.0 - it's a V3-API pack, so no NODE_CLASS_MAPPINGS inside, and that's expected. Python >=3.10. Model packs download on first run into ComfyUI/models/tts/chatterbox/, ~2.5 GB each.

Where people get burned

Truncated cues. A cue that reads long hits the token budget and gets cut off. max_new_tokens is per cue, so raise it rather than editing your script.

Fighting the defaults. If you want cues stretched to the file, that's stretch_to_fit, and you should expect the voice to sound stretched. smart_natural is the default because it's the mode that keeps speech sounding like speech while still refusing overlaps.

Install troubles on old interpreters. s3tokenizer is the one dependency that has caused real install failures - reported on Python 3.10 setups (Stability Matrix uses 3.10) while 3.12 is fine. If pip fails, that's the first suspect, not the pack.

Upgrading from 1.x. Version 2.0.0 moved the model packs from models/chatterbox_tts/ to models/tts/chatterbox/ with no compatibility shim. Move the folders or delete the old directory by hand.