ass_karaoke_generate
Generate karaoke timing tags for ASS subtitle lines by distributing durations across syllables using character, word, or marker modes.
Instructions
Generate \k tags across a line's syllables.
Arguments
selection / index
Which lines to rewrite. index names one line; otherwise
selection goes through :func:base.resolve_indices (None uses
the session selection, and an error is raised when nothing is selected).
start_ms / end_ms
Span the durations are distributed over. When omitted the line's own
Start/End are used. The line's own times are never modified
by this tool (use :func:ass_karaoke_retime for that).
mode marker / char / word / regex (pattern for regex).
kind karaoke tag kind: k, kf, ko or kt.
link how tags attach to the syllables:
"none" one tag per syllable, placed before the syllable's own
override tags;
"syl" the same count but each tag is placed after the
syllable's leading override tags;
"char" one tag per visible character (combining marks stay
with their base character) — the line span is split per character.
weights "char" (visible length), "char_class" (CJK/Latin/space
weighting, see karaoke.syllable_weights_by_char_class) or
"even".
replace_existing
True (default) rewrites existing karaoke tags. False leaves any
line that already carries karaoke tags untouched and reports it in
skipped.
min_cs minimum duration per syllable; a span too short to honour it
raises :class:ToolError instead of silently producing zeros.
snap_to_line
Clamp an explicitly requested span to the line's own span when it would
overshoot (reported in snapped).
Returns
{"text_source": "line", "doc_id", "mode", "kind", "link", "weights", "min_cs", "exact_sum_guaranteed": True, "sum_within_one_cs": True, "lines": [{"index", "start_ms", "end_ms", "span_ms", "span_cs", "snapped", "skipped", "reason", "durations_cs", "duration_sum_cs", "line_duration_cs", "discrepancy_cs", "matches_line_duration", "message", "syllables", "text", "old_text"}], "lines_changed": n}
The centisecond durations always sum to exactly span_cs (and therefore
to the line duration when the span came from the line) — better than the
one-centisecond tolerance required, so exact_sum_guaranteed is always
True when a line is written.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | k | |
| link | No | none | |
| mode | No | marker | |
| index | No | ||
| doc_id | No | ||
| end_ms | No | ||
| marker | No | | | |
| min_cs | No | ||
| pattern | No | ||
| weights | No | char | |
| start_ms | No | ||
| selection | No | ||
| snap_to_line | No | ||
| replace_existing | No |