MMnode/utils/subtitles.py
turtle89431 4ea8431cd0
Some checks are pending
Publish to Comfy registry / Publish Custom Node to registry (push) Waiting to run
init
2026-09-26 11:11:23 -07:00

1030 lines
36 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

from __future__ import annotations
from collections.abc import Iterable
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
import re
_START_TIME_KEYS = ("start", "begin", "start_time", "begin_time", "startTime", "beginTime")
_END_TIME_KEYS = ("end", "stop", "end_time", "finish_time", "endTime", "stopTime")
_TEXT_KEYS = ("text", "sentence", "transcript")
_LANGUAGE_KEYS = ("language", "lang")
_SEGMENT_CONTAINER_KEYS = (
"time_stamps",
"timestamps",
"segments",
"chunks",
"sentences",
"words",
"characters",
"tokens",
"items",
"results",
"result",
"data",
"alignments",
)
_SENTENCE_ENDINGS = ("。", "!", "?", ".", "!", "?")
_PUNCTUATION_CHARS = set("。!?.!?,,;;::、")
_NO_SPACE_BEFORE = set("。!?.!?,,;;::、)]})】》”’")
_NO_SPACE_AFTER = set("([{(【《“‘")
_MAX_SUBTITLE_GAP_SECONDS = 0.8
_MAX_SUBTITLE_DURATION_SECONDS = 8.0
_MAX_SUBTITLE_TEXT_LENGTH = 48
_DEFAULT_SUBTITLE_STYLE = {
"font_size": 12,
"color": "#ffffff",
"outline_color": "#000000",
"background_color": "rgba(0, 0, 0, 0)",
"background_opacity": 0.7,
"x": 0.1,
"y": 0.8,
"width": 0.8,
}
_PREVIEW_REFERENCE_HEIGHT = 360.0
_ASS_FONT_SCALE = 1.45
_ASS_FONT_SIZE_OFFSET = 4.0
_ASS_OUTLINE_SCALE = 1.25
_ASS_BOX_PADDING_SCALE = 2.2
@dataclass(frozen=True)
class MultitrackSubtitleSegment:
start: float
end: float
text: str
style: dict[str, object]
_SUBTITLE_TIME_TOKEN = (
r"(?:\d{1,3}:\d{1,2}:\d{2}(?:[,.]\d{1,3})?"
r"|\d{1,3}:\d{2}(?:[,.]\d{1,3})?"
r"|\d+(?:\.\d+)?)"
)
_SUBTITLE_RANGE_RE = re.compile(
rf"^\s*[\[(【(]?\s*"
rf"(?P<start>{_SUBTITLE_TIME_TOKEN})\s*"
rf"(?:-->|->|→|至|~|~|,|\s+-\s+)\s*"
rf"(?P<end>{_SUBTITLE_TIME_TOKEN})\s*"
rf"[\])】)]?\s*(?P<text>.*)$"
)
def _format_srt_timestamp(seconds: float) -> str:
total_ms = max(0, round(seconds * 1000))
hours, remainder = divmod(total_ms, 3_600_000)
minutes, remainder = divmod(remainder, 60_000)
secs, millis = divmod(remainder, 1000)
return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"
def _format_ass_timestamp(seconds: float) -> str:
total_cs = max(0, round(seconds * 100))
hours, remainder = divmod(total_cs, 360_000)
minutes, remainder = divmod(remainder, 6_000)
secs, centis = divmod(remainder, 100)
return f"{hours}:{minutes:02d}:{secs:02d}.{centis:02d}"
def _escape_srt_text(value: str) -> str:
return value.replace("\r\n", "\n").replace("\r", "\n").strip()
def _escape_ass_text(value: str) -> str:
return (
value.replace("\\", r"\\")
.replace("{", r"\{")
.replace("}", r"\}")
.replace("\r\n", r"\N")
.replace("\n", r"\N")
.strip()
)
def _parse_rgb_color(value: object, fallback: tuple[int, int, int]) -> tuple[int, int, int]:
if not isinstance(value, str):
return fallback
text = value.strip()
if not text or text.lower() == "transparent":
return fallback
hex_match = re.fullmatch(r"#?([0-9a-fA-F]{6})", text)
if hex_match:
raw = hex_match.group(1)
return int(raw[0:2], 16), int(raw[2:4], 16), int(raw[4:6], 16)
rgba_match = re.fullmatch(
r"rgba?\(\s*([0-9.]+)\s*,\s*([0-9.]+)\s*,\s*([0-9.]+)(?:\s*,\s*([0-9.]+))?\s*\)",
text,
)
if rgba_match:
return tuple(
max(0, min(255, round(float(rgba_match.group(index)))))
for index in (1, 2, 3)
)
return fallback
def _ass_color(value: object, fallback: tuple[int, int, int]) -> str:
red, green, blue = _parse_rgb_color(value, fallback)
return f"&H00{blue:02X}{green:02X}{red:02X}"
def _ass_override_color(value: object, fallback: tuple[int, int, int]) -> str:
red, green, blue = _parse_rgb_color(value, fallback)
return f"&H{blue:02X}{green:02X}{red:02X}"
def _rgba_opacity(value: object) -> float | None:
if not isinstance(value, str):
return None
match = re.fullmatch(
r"rgba\(\s*[0-9.]+\s*,\s*[0-9.]+\s*,\s*[0-9.]+\s*,\s*([0-9.]+)\s*\)",
value.strip(),
)
if not match:
return None
return max(0.0, min(1.0, float(match.group(1))))
def _is_transparent_background(value: object) -> bool:
if not isinstance(value, str):
return True
if value.strip().lower() == "transparent":
return True
return _rgba_opacity(value) == 0.0
def _ass_alpha(value: object, opacity_override: object | None = None) -> str:
if _is_transparent_background(value):
return "&HFF"
opacity = _clamped_float(opacity_override, -1.0, 0.0, 1.0) if opacity_override is not None else -1.0
if opacity < 0:
parsed_opacity = _rgba_opacity(value)
opacity = 1.0 if parsed_opacity is None else parsed_opacity
alpha = 0 if opacity is None else int((1.0 - opacity) * 255 + 0.5)
return f"&H{alpha:02X}"
def _ass_style_has_background(style: dict[str, object]) -> bool:
return not _is_transparent_background(style.get("background_color"))
def _ass_outline_alpha(value: object) -> str:
if not isinstance(value, str) or value.strip().lower() == "transparent":
return "&HFF"
return "&H00"
def _ass_back_color(value: object) -> str:
if not isinstance(value, str) or value.strip().lower() == "transparent":
return "&HFF000000"
opacity = _rgba_opacity(value)
alpha = 0 if opacity is None else int((1.0 - opacity) * 255 + 0.5)
red, green, blue = _parse_rgb_color(value, (0, 0, 0))
return f"&H{alpha:02X}{blue:02X}{green:02X}{red:02X}"
def _clamped_float(value: object, default: float, minimum: float, maximum: float) -> float:
try:
number = float(value)
except (TypeError, ValueError):
number = default
return max(minimum, min(maximum, number))
def _normalized_subtitle_style(value: object) -> dict[str, object]:
style = dict(_DEFAULT_SUBTITLE_STYLE)
if isinstance(value, dict):
style.update(value)
width = _clamped_float(style.get("width"), 0.8, 0.1, 1.0)
x = _clamped_float(style.get("x"), 0.1, 0.0, 1.0 - width)
style["width"] = width
style["x"] = x
style["y"] = _clamped_float(style.get("y"), 0.8, 0.0, 0.95)
style["font_size"] = _clamped_float(style.get("font_size"), 12, 8, 96)
style["color"] = str(style.get("color") or _DEFAULT_SUBTITLE_STYLE["color"])
style["outline_color"] = str(style.get("outline_color") or _DEFAULT_SUBTITLE_STYLE["outline_color"])
style["background_color"] = str(
style.get("background_color") or _DEFAULT_SUBTITLE_STYLE["background_color"]
)
style["background_opacity"] = _clamped_float(
style.get("background_opacity"),
float(_DEFAULT_SUBTITLE_STYLE["background_opacity"]),
0.0,
1.0,
)
return style
def _preview_to_video_scale(height: int) -> float:
return max(0.1, float(max(1, height)) / _PREVIEW_REFERENCE_HEIGHT)
def collect_multitrack_subtitle_segments(tracks_info: dict) -> list[MultitrackSubtitleSegment]:
"""Extract subtitle track segments from TRACKS_INFO using frame timing."""
frame_rate = _clamped_float(tracks_info.get("frame_rate"), 24.0, 0.001, 10_000.0)
tracks = tracks_info.get("tracks", [])
if not isinstance(tracks, list):
return []
segments: list[MultitrackSubtitleSegment] = []
for track in tracks:
if (
not isinstance(track, dict)
or track.get("type") != "subtitle"
or track.get("muted") is True
or track.get("visible") is False
):
continue
for segment in track.get("segments", []):
if not isinstance(segment, dict):
continue
content = segment.get("content", {})
if not isinstance(content, dict):
content = {}
text = str(content.get("text") or content.get("user_prompt") or "").strip()
if not text:
continue
start_frame = int(segment.get("start_frame", 0) or 0)
end_frame = int(segment.get("end_frame", start_frame) or start_frame)
if end_frame <= start_frame:
continue
segments.append(
MultitrackSubtitleSegment(
start=max(0.0, start_frame / frame_rate),
end=max(0.0, end_frame / frame_rate),
text=text,
style=_normalized_subtitle_style(content.get("subtitle_style")),
)
)
return sorted(segments, key=lambda item: (item.start, item.end))
def _parse_subtitle_timestamp(value: str) -> float:
parts = value.replace(",", ".").split(":")
try:
if len(parts) == 3:
hours, minutes, seconds = int(parts[0]), int(parts[1]), float(parts[2])
elif len(parts) == 2:
hours, minutes, seconds = 0, int(parts[0]), float(parts[1])
else:
hours, minutes, seconds = 0, 0, float(parts[0])
except (TypeError, ValueError) as error:
raise ValueError(f"Invalid subtitle timestamp: {value}") from error
if hours < 0 or minutes < 0 or minutes >= 60 or seconds < 0 or seconds >= 60:
raise ValueError(f"Invalid subtitle timestamp: {value}")
return hours * 3600 + minutes * 60 + seconds
def parse_subtitle_text(
value: str,
style: dict[str, object] | None = None,
) -> list[MultitrackSubtitleSegment]:
"""Parse SRT, inline timestamp, and bracketed subtitle text into segments."""
text = str(value or "").replace("\ufeff", "").replace("\r\n", "\n").replace("\r", "\n")
if not text.strip():
return []
lines = text.split("\n")
segments: list[MultitrackSubtitleSegment] = []
line_index = 0
while line_index < len(lines):
current = lines[line_index].strip()
if not current:
line_index += 1
continue
if current.isdigit() and line_index + 1 < len(lines):
next_line = lines[line_index + 1].strip()
if _SUBTITLE_RANGE_RE.fullmatch(next_line):
line_index += 1
current = next_line
range_match = _SUBTITLE_RANGE_RE.fullmatch(current)
if range_match is None:
raise ValueError(
f"Expected a subtitle timestamp at line {line_index + 1}: {current}"
)
start = _parse_subtitle_timestamp(range_match.group("start"))
end = _parse_subtitle_timestamp(range_match.group("end"))
if end <= start:
raise ValueError(
f"Subtitle end timestamp must be later than its start at line {line_index + 1}."
)
caption_lines: list[str] = []
inline_text = range_match.group("text").lstrip(" \t:-")
if inline_text:
caption_lines.append(inline_text.rstrip())
line_index += 1
while line_index < len(lines):
candidate = lines[line_index]
stripped = candidate.strip()
if not stripped:
line_index += 1
break
if _SUBTITLE_RANGE_RE.fullmatch(stripped):
break
if (
stripped.isdigit()
and line_index + 1 < len(lines)
and _SUBTITLE_RANGE_RE.fullmatch(lines[line_index + 1].strip())
):
break
caption_lines.append(candidate.rstrip())
line_index += 1
caption = "\n".join(caption_lines).strip()
if not caption:
raise ValueError(f"Subtitle text is missing at line {line_index + 1}.")
segments.append(
MultitrackSubtitleSegment(
start=start,
end=end,
text=caption,
style=_normalized_subtitle_style(style),
)
)
return sorted(segments, key=lambda item: (item.start, item.end))
def write_srt_file(segments: list[MultitrackSubtitleSegment], path: Path) -> Path:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(subtitle_segments_to_srt(segments), encoding="utf-8")
return path
def subtitle_segments_to_srt(segments: Iterable[object]) -> str:
"""Format timestamped subtitle segment objects or dictionaries as SRT."""
blocks = []
for index, segment in enumerate(segments, start=1):
if isinstance(segment, dict):
start = segment.get("start")
end = segment.get("end")
text = segment.get("text")
else:
start = getattr(segment, "start", None)
end = getattr(segment, "end", None)
text = getattr(segment, "text", None)
try:
start_seconds = float(start)
end_seconds = float(end)
except (TypeError, ValueError) as error:
raise ValueError(f"Invalid subtitle timestamps at segment {index}.") from error
if end_seconds <= start_seconds:
raise ValueError(f"Subtitle end timestamp must be later than its start at segment {index}.")
subtitle_text = _escape_srt_text(str(text or ""))
if not subtitle_text:
raise ValueError(f"Subtitle text is missing at segment {index}.")
blocks.append(
"\n".join([
str(index),
f"{_format_srt_timestamp(start_seconds)} --> {_format_srt_timestamp(end_seconds)}",
subtitle_text,
])
)
return "\n\n".join(blocks) + ("\n" if blocks else "")
def _format_decimal_seconds(seconds: float) -> str:
return f"{max(0.0, seconds):.3f}".rstrip("0").rstrip(".")
def subtitle_segments_to_timestamp_text(segments: Iterable[object]) -> str:
"""Format subtitle segments as ``(start, end) text`` lines."""
lines: list[str] = []
for index, segment in enumerate(segments, start=1):
if isinstance(segment, dict):
start = segment.get("start")
end = segment.get("end")
text = segment.get("text")
else:
start = getattr(segment, "start", None)
end = getattr(segment, "end", None)
text = getattr(segment, "text", None)
try:
start_seconds = float(start)
end_seconds = float(end)
except (TypeError, ValueError) as error:
raise ValueError(f"Invalid subtitle timestamps at segment {index}.") from error
if end_seconds <= start_seconds:
raise ValueError(f"Subtitle end timestamp must be later than its start at segment {index}.")
subtitle_text = _escape_srt_text(str(text or ""))
if not subtitle_text:
raise ValueError(f"Subtitle text is missing at segment {index}.")
lines.append(
f"({_format_decimal_seconds(start_seconds)}, {_format_decimal_seconds(end_seconds)}) "
f"{subtitle_text}"
)
return "\n".join(lines)
def limit_subtitle_segment_length(segments: Iterable[object], max_length: int) -> list[dict]:
"""Split long subtitle text and distribute its original timing proportionally."""
if max_length < 1:
raise ValueError("max_length must be at least 1")
result: list[dict] = []
for index, segment in enumerate(segments, start=1):
if not isinstance(segment, dict):
raise ValueError(f"Invalid subtitle segment at index {index}.")
text = str(segment.get("text") or "").strip()
try:
start = float(segment.get("start"))
end = float(segment.get("end"))
except (TypeError, ValueError) as error:
raise ValueError(f"Invalid subtitle timestamps at segment {index}.") from error
if not text or end <= start:
continue
if len(text) <= max_length:
result.append({"start": start, "end": end, "text": text})
continue
duration = end - start
text_length = len(text)
for offset in range(0, text_length, max_length):
chunk = text[offset:offset + max_length]
chunk_end_offset = min(text_length, offset + len(chunk))
result.append({
"start": start + duration * offset / text_length,
"end": start + duration * chunk_end_offset / text_length,
"text": chunk,
})
return result
def _split_text_at_natural_boundaries(text: str, max_length: int) -> list[str]:
clauses: list[str] = []
current = ""
for char in text.strip():
current += char
if char in _PUNCTUATION_CHARS:
clauses.append(current.strip())
current = ""
if current.strip():
clauses.append(current.strip())
result: list[str] = []
for clause in clauses:
if len(clause) <= max_length:
result.append(clause)
continue
words = re.findall(r"\S+", clause)
if len(words) <= 1 and _is_cjk_text(clause):
try:
import jieba # type: ignore[import-not-found]
words = [word.strip() for word in jieba.lcut(clause) if word.strip()]
except ImportError:
words = list(clause)
if len(words) <= 1:
result.append(clause)
continue
chunk = ""
for word in words:
joined = _join_subtitle_text(chunk, word)
if chunk and len(joined) > max_length:
result.append(chunk)
chunk = word
else:
chunk = joined
if chunk:
result.append(chunk)
return result
def _expand_timed_subtitle_unit(unit: dict, max_length: int) -> list[dict]:
text = str(unit.get("text") or "").strip()
pieces = _split_text_at_natural_boundaries(text, max_length)
if len(pieces) <= 1:
return [{"start": float(unit["start"]), "end": float(unit["end"]), "text": text}]
start = float(unit["start"])
end = float(unit["end"])
duration = end - start
total_weight = sum(max(1, len(piece)) for piece in pieces)
offset = 0
expanded: list[dict] = []
for piece in pieces:
weight = max(1, len(piece))
piece_start = start + duration * offset / total_weight
offset += weight
piece_end = start + duration * offset / total_weight
expanded.append({"start": piece_start, "end": piece_end, "text": piece})
return expanded
def smart_split_subtitle_segments(segments: Iterable[object], max_length: int) -> list[dict]:
"""Build natural subtitle sentences from timed words or model segments."""
if max_length < 1:
raise ValueError("max_length must be at least 1")
units: list[dict] = []
for index, segment in enumerate(segments, start=1):
if not isinstance(segment, dict):
raise ValueError(f"Invalid subtitle segment at index {index}.")
text = str(segment.get("text") or "").strip()
try:
start = float(segment.get("start"))
end = float(segment.get("end"))
except (TypeError, ValueError) as error:
raise ValueError(f"Invalid subtitle timestamps at segment {index}.") from error
if not text or end <= start:
continue
units.extend(_expand_timed_subtitle_unit(
{"start": start, "end": end, "text": text},
max_length,
))
result: list[dict] = []
current: dict | None = None
def flush() -> None:
nonlocal current
if current is not None:
result.append(current)
current = None
for unit in sorted(units, key=lambda item: (item["start"], item["end"])):
text = str(unit["text"]).strip()
if text and all(_is_punctuation(char) for char in text):
if current is not None:
current["end"] = max(current["end"], unit["end"])
current["text"] = _join_subtitle_text(current["text"], text)
flush()
elif result:
result[-1]["end"] = max(result[-1]["end"], unit["end"])
result[-1]["text"] = _join_subtitle_text(result[-1]["text"], text)
continue
if current is not None:
gap = unit["start"] - current["end"]
joined = _join_subtitle_text(current["text"], text)
if gap > _MAX_SUBTITLE_GAP_SECONDS or len(joined) > max_length:
flush()
if current is None:
current = {"start": unit["start"], "end": unit["end"], "text": text}
else:
current["end"] = max(current["end"], unit["end"])
current["text"] = _join_subtitle_text(current["text"], text)
if current["text"] and _is_punctuation(current["text"][-1]):
flush()
flush()
return result
def write_ass_file(
segments: list[MultitrackSubtitleSegment],
path: Path,
width: int,
height: int,
) -> Path:
path.parent.mkdir(parents=True, exist_ok=True)
header = [
"[Script Info]",
"ScriptType: v4.00+",
f"PlayResX: {max(1, int(width))}",
f"PlayResY: {max(1, int(height))}",
"ScaledBorderAndShadow: yes",
"",
"[V4+ Styles]",
(
"Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, "
"OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, "
"ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, "
"Alignment, MarginL, MarginR, MarginV, Encoding"
),
(
"Style: Default,Arial,12,&H00FFFFFF,&H00FFFFFF,&H00000000,&H99000000,"
"0,0,0,0,100,100,0,0,1,2,0,8,10,10,10,1"
),
(
"Style: Box,Arial,12,&H00FFFFFF,&H00FFFFFF,&H00000000,&H99000000,"
"0,0,0,0,100,100,0,0,3,2,0,8,10,10,10,1"
),
"",
"[Events]",
"Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
]
events: list[str] = []
preview_scale = _preview_to_video_scale(height)
outline_size = max(1.0, round(_ASS_OUTLINE_SCALE * preview_scale, 2))
box_padding_size = max(outline_size, round(_ASS_BOX_PADDING_SCALE * preview_scale, 2))
for segment in segments:
style = segment.style
preview_font_size = _clamped_float(style.get("font_size"), 12, 8, 96)
font_size = round(
preview_font_size * preview_scale * _ASS_FONT_SCALE + _ASS_FONT_SIZE_OFFSET,
2,
)
has_background = _ass_style_has_background(style)
style_name = "Box" if has_background else "Default"
border_size = box_padding_size if has_background else outline_size
color = _ass_override_color(style.get("color"), (255, 255, 255))
outline_color = _ass_override_color(style.get("outline_color"), (0, 0, 0))
outline_alpha = _ass_outline_alpha(style.get("outline_color"))
back_color = _ass_override_color(style.get("background_color"), (0, 0, 0))
back_alpha = _ass_alpha(style.get("background_color"), style.get("background_opacity"))
x = _clamped_float(style.get("x"), 0.1, 0.0, 1.0)
y = _clamped_float(style.get("y"), 0.8, 0.0, 0.95)
box_width = _clamped_float(style.get("width"), 0.8, 0.1, 1.0)
pos_x = round((x + box_width / 2) * width)
pos_y = round(y * height)
override = (
r"{\an8"
rf"\pos({pos_x},{pos_y})"
rf"\fs{font_size:g}"
rf"\bord{border_size:g}"
rf"\c{color}"
rf"\3c{back_color if has_background else outline_color}"
rf"\3a{back_alpha if has_background else outline_alpha}"
r"}"
)
events.append(
"Dialogue: 0,{start},{end},{style},,0,0,0,,{text}".format(
start=_format_ass_timestamp(segment.start),
end=_format_ass_timestamp(segment.end),
style=style_name,
text=override + _escape_ass_text(segment.text),
)
)
path.write_text("\n".join(header + events) + "\n", encoding="utf-8")
return path
def default_subtitle_filename(prefix: str = "easy_multitrack_subtitles") -> str:
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
return f"{prefix}_{timestamp}"
def _value_from(value: object, keys: tuple[str, ...]) -> object | None:
if isinstance(value, dict):
return next((value[key] for key in keys if key in value), None)
return next((getattr(value, key) for key in keys if hasattr(value, key)), None)
def _has_segment_fields(value: object) -> bool:
return (
_value_from(value, _START_TIME_KEYS) is not None
and _value_from(value, _END_TIME_KEYS) is not None
and _value_from(value, _TEXT_KEYS) is not None
)
def _coerce_segment_items(value: object) -> list[object] | None:
if value is None:
return None
if isinstance(value, (str, bytes)):
return None
if isinstance(value, dict):
if _has_segment_fields(value):
return [value]
for key in _SEGMENT_CONTAINER_KEYS:
if key in value:
items = _coerce_segment_items(value[key])
if items is not None:
return items
return None
if isinstance(value, list):
return value
if isinstance(value, tuple):
return list(value)
if _has_segment_fields(value):
return [value]
for key in _SEGMENT_CONTAINER_KEYS:
nested = getattr(value, key, None)
if nested is not None and nested is not value:
items = _coerce_segment_items(nested)
if items is not None:
return items
for method_name in ("model_dump", "dict", "to_dict"):
method = getattr(value, method_name, None)
if callable(method):
try:
dumped = method()
except (TypeError, ValueError, RuntimeError):
continue
items = _coerce_segment_items(dumped)
if items is not None:
return items
if isinstance(value, Iterable):
try:
return list(value)
except TypeError:
return None
length = getattr(value, "__len__", None)
getitem = getattr(value, "__getitem__", None)
if callable(length) and callable(getitem):
try:
return [value[index] for index in range(length())]
except (TypeError, ValueError, RuntimeError, IndexError):
return None
return None
def _detect_language(value: object) -> str | None:
values = value if isinstance(value, list) else [value]
for item in values:
language = _value_from(item, _LANGUAGE_KEYS)
if isinstance(language, str) and language.strip():
return language.strip()
return None
def _detect_text(value: object) -> str | None:
values = value if isinstance(value, list) else [value]
for item in values:
text = _value_from(item, _TEXT_KEYS)
if isinstance(text, str) and text.strip():
return text.strip()
return None
def _summarize_value(value: object, depth: int = 0) -> str:
if depth >= 3:
return type(value).__name__
if isinstance(value, list):
if not value:
return "list(len=0)"
return f"list[{_summarize_value(value[0], depth + 1)}](len={len(value)})"
if isinstance(value, tuple):
if not value:
return "tuple(len=0)"
return f"tuple[{_summarize_value(value[0], depth + 1)}](len={len(value)})"
if isinstance(value, dict):
keys = ", ".join(f"{key}:{_summarize_value(item, depth + 1)}" for key, item in list(value.items())[:8])
return f"dict({keys})"
if isinstance(value, str):
return f"str(len={len(value)})"
if isinstance(value, (int, float, bool)) or value is None:
return repr(value)
attrs: list[str] = []
for key in (*_LANGUAGE_KEYS, *_TEXT_KEYS, "time_stamps", "timestamps", "segments"):
if hasattr(value, key):
attrs.append(f"{key}:{_summarize_value(getattr(value, key), depth + 1)}")
if attrs:
return f"{type(value).__name__}({', '.join(attrs)})"
return type(value).__name__
def _is_cjk_character(value: str) -> bool:
return any("\u4e00" <= char <= "\u9fff" for char in value)
def _join_subtitle_text(current: str, next_text: str) -> str:
current = current.strip()
next_text = next_text.strip()
if not current:
return next_text
if not next_text:
return current
if next_text[0] in _NO_SPACE_BEFORE or current[-1] in _NO_SPACE_AFTER:
return f"{current}{next_text}"
if _is_cjk_character(current[-1]) or _is_cjk_character(next_text[0]):
return f"{current}{next_text}"
return f"{current} {next_text}"
def _is_sentence_end(text: str) -> bool:
stripped = text.rstrip()
return stripped.endswith(_SENTENCE_ENDINGS)
def _is_punctuation(value: str) -> bool:
return value in _PUNCTUATION_CHARS
def _is_cjk_text(value: str) -> bool:
return any("\u4e00" <= char <= "\u9fff" for char in value)
def _normalized_text_with_indices(value: str) -> tuple[str, list[int]]:
chars: list[str] = []
indices: list[int] = []
for index, char in enumerate(value):
if char.isspace() or _is_punctuation(char):
continue
chars.append(char.lower())
indices.append(index)
return "".join(chars), indices
def _punctuation_after_match(transcript: str, normalized_text: str, cursor: int) -> tuple[str, int] | None:
normalized_transcript, original_indices = _normalized_text_with_indices(transcript)
if not normalized_text or not normalized_transcript:
return None
match_index = normalized_transcript.find(normalized_text, cursor)
if match_index < 0:
match_index = normalized_transcript.find(normalized_text)
if match_index < 0:
return None
original_index = original_indices[match_index + len(normalized_text) - 1] + 1
punctuation = ""
while original_index < len(transcript):
char = transcript[original_index]
if char.isspace():
original_index += 1
continue
if _is_punctuation(char):
punctuation += char
original_index += 1
continue
break
return punctuation, match_index + len(normalized_text)
def _default_punctuation(index: int, total: int, is_cjk: bool) -> str:
if index >= total - 1:
return "。" if is_cjk else "."
return "," if is_cjk else ","
def _restore_subtitle_punctuation(
segments: list[dict],
transcript: str | None,
language: str | None = None,
*,
add_fallback: bool = True,
add_final_fallback: bool = False,
) -> list[dict]:
if not segments:
return []
transcript_value = (transcript or "").strip()
segment_text_value = "".join(str(segment.get("text", "")) for segment in segments)
has_ascii_letters = any(char.isascii() and char.isalpha() for char in segment_text_value)
is_cjk = _is_cjk_text(segment_text_value) or (_is_cjk_text(transcript_value) and not has_ascii_letters)
restored: list[dict] = []
cursor = 0
for index, segment in enumerate(segments):
text = str(segment.get("text", "")).strip()
next_segment = {**segment, "text": text}
if text and not _is_punctuation(text[-1]):
normalized_text, _ = _normalized_text_with_indices(text)
matched = _punctuation_after_match(transcript_value, normalized_text, cursor) if transcript_value else None
if matched:
punctuation, cursor = matched
else:
punctuation = ""
fallback = ""
if add_fallback or (add_final_fallback and index == len(segments) - 1):
fallback = _default_punctuation(index, len(segments), is_cjk)
next_segment["text"] = text + (punctuation or fallback)
restored.append(next_segment)
return restored
def _merge_subtitle_segments(segments: list[dict]) -> list[dict]:
if not segments:
return []
ordered_segments = sorted(segments, key=lambda segment: (segment["start"], segment["end"]))
merged: list[dict] = []
current: dict | None = None
for segment in ordered_segments:
text = str(segment.get("text", "")).strip()
if not text:
continue
next_segment = {
"start": float(segment["start"]),
"end": float(segment["end"]),
"text": text,
}
if current is None:
current = next_segment
else:
gap = next_segment["start"] - current["end"]
should_start_new = gap > _MAX_SUBTITLE_GAP_SECONDS or _is_sentence_end(current["text"])
if should_start_new:
merged.append(current)
current = next_segment
else:
current["end"] = max(current["end"], next_segment["end"])
current["text"] = _join_subtitle_text(current["text"], next_segment["text"])
if (
current
and (_is_sentence_end(current["text"])
or current["end"] - current["start"] >= _MAX_SUBTITLE_DURATION_SECONDS
or len(current["text"]) >= _MAX_SUBTITLE_TEXT_LENGTH)
):
merged.append(current)
current = None
if current is not None:
merged.append(current)
return merged
def normalize_subtitle_segments(value: object) -> list[dict]:
raw_segments: object
if isinstance(value, dict):
raw_segments = (
value.get("segments")
or value.get("timestamps")
or value.get("time_stamps")
or value.get("chunks")
or value.get("sentences")
or []
)
else:
raw_segments = getattr(value, "time_stamps", value)
raw_items = _coerce_segment_items(raw_segments)
if raw_items is None:
return []
flattened: list[dict] = []
for item in raw_items:
if isinstance(item, list) or (not _has_segment_fields(item) and _coerce_segment_items(item) is not None):
child_segments = normalize_subtitle_segments(item)
if child_segments:
flattened.extend(child_segments)
continue
nested = _value_from(item, _SEGMENT_CONTAINER_KEYS)
if nested is not None:
flattened.extend(normalize_subtitle_segments(nested))
if flattened:
return _merge_subtitle_segments(flattened)
segments: list[dict] = []
for item in raw_items:
start: object | None = None
end: object | None = None
text: object | None = None
start = _value_from(item, _START_TIME_KEYS)
end = _value_from(item, _END_TIME_KEYS)
text = _value_from(item, _TEXT_KEYS)
if isinstance(item, (list, tuple)) and len(item) >= 3:
start, end, text = item[0], item[1], item[2]
try:
start_number = float(start) # type: ignore[arg-type]
end_number = float(end) # type: ignore[arg-type]
except (TypeError, ValueError):
continue
if end_number <= start_number:
continue
text_value = str(text or "").strip()
if not text_value:
continue
segments.append({"start": start_number, "end": end_number, "text": text_value})
return _merge_subtitle_segments(segments)
def normalize_subtitle_tokens(value: object) -> list[dict]:
"""Extract the finest available timed words, characters, or subtitle segments."""
tokens: list[dict] = []
def collect(item: object) -> None:
if item is None or isinstance(item, (str, bytes)):
return
if isinstance(item, (list, tuple)):
for child in item:
collect(child)
return
words = _value_from(item, ("words", "characters", "tokens"))
word_items = _coerce_segment_items(words)
if word_items:
for child in word_items:
collect(child)
return
start = _value_from(item, _START_TIME_KEYS)
end = _value_from(item, _END_TIME_KEYS)
text = _value_from(item, (*_TEXT_KEYS, "word", "token", "character"))
if start is not None and end is not None and text is not None:
try:
start_number = float(start)
end_number = float(end)
except (TypeError, ValueError):
return
text_value = str(text).strip()
if text_value and end_number > start_number:
tokens.append({"start": start_number, "end": end_number, "text": text_value})
return
for key in _SEGMENT_CONTAINER_KEYS:
nested = _value_from(item, (key,))
nested_items = _coerce_segment_items(nested)
if nested_items is not None:
for child in nested_items:
collect(child)
return
collect(value)
return sorted(tokens, key=lambda item: (item["start"], item["end"]))