per block: each enters as its own words are spoken and stays on screen, so the sentence assembles itself, and every block clears at the same instant. Set granularity='word' for the older one-title-per-word rhythm. A sentence too tall for the band splits into successive compositions. These are TITLES, not captions: no subtitles role, so they render over the video without enabling caption display. Uses each media file's local Whisper word-level transcript (_transcript.json, auto-transcribes if missing). Style fields below (band_height through inactive_color) fall back to the style saved from the app's 'Legendas Dinâmicas' screen (~/.fcp-mcp-server/config.json via save_dynamic_subtitle_config) when omitted — pass a value here only to override that for one call. Non-destructive: writes a _dynamic_subtitles copy.", inputSchema={ "type": "object", "properties": { "filepath": {"type": "string", "description": "Path to FCPXML file"}, "clip_name": {"type": "string", "description": "Only caption the clip with this name (default: all spine clips with matched source media)"}, "model": {"type": "string", "default": "base", "description": "Whisper model size if transcription is needed"}, "language": {"type": "string", "description": "ISO language code hint (e.g. 'en'); auto-detected if omitted"}, "band_height": {"type": "number", "description": "Fraction of frame height the sentence block may fill before splitting into another block. Falls back to the saved style (default 0.22 — about three lines)"}, "block_center_y": {"type": "number", "description": "Vertical centre of the block in canvas points; negative sits below frame centre. Falls back to the saved style (default -167, just under centre)"}, "line_gap": {"type": "number", "description": "Air between stacked lines in canvas points. Lines are stacked on their real ink, so this is the whole distance beyond the glyphs themselves; negative values deliberately tuck each line into the one above. Falls back to the saved style (default 8)"}, "granularity": {"type": "string", "enum": ["phrase", "word"], "default": "phrase", "description": "'phrase': one title per LINE of the composition, key word set large (the reference look). 'word': one title per word."}, "emphasis_font": {"type": "string", "description": "Family for the key word (phrase mode). Must be installed on the editing Mac; unmeasured families fall back to estimated widths. Falls back to the saved style (default 'Playfair Display')"}, "emphasis_face": {"type": "string", "description": "Face for the key word, e.g. 'Medium Italic' or a script/calligraphic face. Falls back to the saved style (default 'Medium Italic')"}, "emphasis_size": {"type": "integer", "description": "Key-word size in canvas points, at the 2160x3840 reference frame. Falls back to the saved style (default 265)"}, "emphasis_color": {"type": "string", "description": "RGBA (0-1, space-separated) for the key word (phrase mode). Defaults to active_color, so the block reads in a single colour unless the key word is deliberately set apart"}, "text_scale": {"type": "number", "description": "Ratio between the title template's fontSize space and the canvas-point space it positions in. The \"Text\" template sizes type in frame pixels, so sizes are doubled on the way out. Falls back to the saved style (default 2.0). Lower it only if a template renders type larger than the chosen point size"}, "font": {"type": "string", "description": "Title font family (supporting lines in phrase mode). Falls back to the saved style (default 'Helvetica Neue')"}, "font_size": {"type": "integer", "description": "Supporting-line font size in canvas points, at the 2160x3840 reference frame. Falls back to the saved style (default 104)"}, "active_color": {"type": "string", "description": "RGBA (0-1, space-separated) for even-indexed lines. Falls back to the saved style (default '1 1 1 1')"}, "inactive_color": {"type": "string", "default": "0.7 0.7 0.7 1", "description": "RGBA (0-1, space-separated) for odd-indexed lines — alternates with active_color for visual variety between stacked lines"}, "output_path": {"type": "string", "description": "Output path (default: adds _dynamic_subtitles suffix)"}, }, "required": ["filepath"] } ), Tool( name="generate_plain_subtitles", description="Generate simple editable FCPXML text-title subtitles, synchronized to transcript words but without visual build-in/build-out effects. Words are grouped into short blocks, placed at a configurable vertical position, and written as static Text titles rather than SRT captions.", inputSchema={ "type": "object", "properties": { "filepath": {"type": "string", "description": "Path to FCPXML file"}, "clip_name": {"type": "string", "description": "Only caption the clip with this name (default: all spine clips with matched source media)"}, "model": {"type": "string", "default": "base", "description": "Whisper model size if transcription is needed"}, "language": {"type": "string", "description": "ISO language code hint (e.g. 'pt'); auto-detected if omitted"}, "font": {"type": "string", "description": "Text font family. Falls back to saved plain-subtitle config."}, "font_size": {"type": "integer", "description": "Font size in canvas points. Falls back to saved plain-subtitle config."}, "font_color": {"type": "string", "description": "RGBA (0-1, space-separated). Falls back to saved plain-subtitle config."}, "max_words": {"type": "integer", "description": "Maximum words per subtitle block. Falls back to saved plain-subtitle config."}, "position_y": {"type": "number", "description": "Vertical title position in canvas points; negative sits lower in frame."}, "uppercase": {"type": "boolean", "description": "Render text in uppercase."}, "keep_punctuation": {"type": "boolean", "description": "Keep punctuation such as comma and period."}, "text_scale": {"type": "number", "description": "Template font-size scale. Falls back to saved plain-subtitle config."}, "output_path": {"type": "string", "description": "Output path (default: adds _plain_subtitles suffix)"}, }, "required": ["filepath"] } ), Tool( name="generate_subtitles_by_emphasis", description="Generate BOTH subtitle styles in one pass, split by word so they never coexist on the same range: dynamic progressive-composition titles (see generate_dynamic_subtitles) cover whichever whole phrases were marked as emphasis in the phrase-review step (etapa 5, zoom applied, level >= 1); plain static titles (see generate_plain_subtitles) cover every OTHER word in the clip. A plain block is simply not created where a dynamic phrase already covers — not created-then-disabled — because a disabled title still shows as its own struck-through clip in Final Cut's timeline even though it never renders, and a heavily emphasized edit ended up with dozens of dead clips cluttering the track. Trade-off: if emphasis is turned off by hand later, the plain line under it has to be regenerated, not just re-enabled. Reads emphasis spans from the media's cached '<media>_phrase_actions.json' (written by save_phrase_review after the app's etapa 5 review) — run the voice-editing wizard through that step first, or nothing is treated as emphasis and every word gets a plain title. Style knobs are the saved 'Legendas Dinâmicas'/plain-subtitle configs (~/.fcp-mcp-server/config.json); this tool does not expose per-call style overrides, only the split logic — use generate_dynamic_subtitles/generate_plain_subtitles directly if you need one-off styling.", inputSchema={ "type": "object", "properties": { "filepath": {"type": "string", "description": "Path to FCPXML file"}, "clip_name": {"type": "string", "description": "Only caption the clip with this name (default: all spine clips with matched source media)"}, "model": {"type": "string", "default": "base", "description": "Whisper model size if transcription is needed"}, "language": {"type": "string", "description": "ISO language code hint (e.g. 'pt'); auto-detected if omitted"}, "granularity": {"type": "string", "enum": ["phrase", "word"], "default": "phrase", "description": "Passed through to the dynamic half, same meaning as in generate_dynamic_subtitles"}, "max_words": {"type": "integer", "description": "Max words per block for the plain half. Falls back to saved plain-subtitle config."}, "uppercase": {"type": "boolean", "description": "Uppercase the plain half. Falls back to saved plain-subtitle config."}, "keep_punctuation": {"type": "boolean", "description": "Keep punctuation in the plain half. Falls back to saved plain-subtitle config."}, "output_path": {"type": "string", "description": "Output path (default: adds _emphasis_subtitles suffix)"}, }, "required": ["filepath"] } ), ] _PUNCT_RE = re.compile(r"[^\w\sÀ-ÖØ-öø-ÿ]", re.UNICODE) def _words_overlapping_clip(words: Sequence[dict], start: float, end: float) -> list[dict]: """Return transcript words that overlap a source window, rebased to it.""" clip_words: list[dict] = [] for w in words: word_start = float(w.get("start", 0.0)) word_end = float(w.get("end", word_start)) if word_end <= start or word_start >= end: continue clip_words.append( { "word": w.get("word", ""), "start": max(0.0, word_start - start), "end": max(0.0, min(word_end, end) - start), } ) return clip_words def _plain_word_text(word: str, *, uppercase: bool, keep_punctuation: bool) -> str: text = str(word or "").strip() if not keep_punctuation: text = _PUNCT_RE.sub("", text) text = re.sub(r"\s+", " ", text).strip() return text.upper() if uppercase else text def _plain_subtitle_blocks(words: Sequence[dict], max_words: int) -> list[list[dict]]: blocks: list[list[dict]] = [] pending: list[dict] = [] for word in words: if not str(word.get("word", "")).strip(): continue pending.append(word) if len(pending) >= max(1, max_words): blocks.append(pending) pending = [] if pending: blocks.append(pending) return blocks def _phrase_actions_path(media_path: str) -> Path: """Where `save_phrase_review` writes emphasis decisions for this media. Mirrors `phrase_review.review_paths()`'s naming (stem + "_phrase_actions.json"), without importing that module just for a path — the voice_timeline this would normally derive from is itself named `<media stem>_voice_timeline.json`, so stripping straight from the media stem lands on the same file. """ stem = Path(media_path).stem return Path(media_path).with_name(f"{stem}_phrase_actions.json") def _load_emphasis_spans(media_path: str) -> list[dict]: """Load emphasis spans (source-media time) saved by the etapa-5 phrase review. Returns [] if the review was never run for this media — callers should treat that as "nothing is emphasis yet", not as an error, since the wizard's later steps are optional. """ path = _phrase_actions_path(media_path) if not path.is_file(): return [] try: data = json.loads(path.read_text(encoding="utf-8")) except (OSError, json.JSONDecodeError): return [] spans = data.get("emphasis_spans", []) return [s for s in spans if isinstance(s, dict) and "start" in s and "end" in s] def _word_in_spans(word_start: float, word_end: float, spans: Sequence[dict]) -> bool: """A word belongs to an emphasis span if its midpoint falls inside it. Midpoint, not start, so a word straddling a span boundary (which can happen since spans come from phrase trims, not word timestamps) lands on whichever side it mostly belongs to instead of always defaulting to one edge. """ mid = (word_start + word_end) / 2.0 return any(float(s["start"]) <= mid < float(s["end"]) for s in spans) def _words_in_spans(words: Sequence[dict], spans: Sequence[dict]) -> list[dict]: """The subset of source-time transcript words that fall inside a span. Feeds only the DYNAMIC half — the plain half always gets every word, full clip, unfiltered; this is not a partition of the word list into two disjoint sets, it is "which words also get the dynamic treatment on top". """ if not spans: return [] return [ w for w in words if _word_in_spans(float(w.get("start", 0.0)), float(w.get("end", w.get("start", 0.0))), spans) ] def _segments_in_spans(segments: Sequence[dict], spans: Sequence[dict]) -> list[dict]: """Keep only the sentences that fall inside an emphasis span (by midpoint). Feeds the dynamic half's sentence-block builder; segments outside every span would only produce blocks with no words left in them after the word filter. """ if not spans: return [] kept = [] for seg in segments: start = float(seg.get("start", 0.0)) end = float(seg.get("end", start)) mid = (start + end) / 2.0 if any(float(s["start"]) <= mid < float(s["end"]) for s in spans): kept.append(seg) return kept def _overlaps_any_span(start: float, end: float, spans: Sequence[tuple[float, float]]) -> bool: """Half-open interval overlap: a plain title under this window is skipped.""" return any(start < span_end and end > span_start for span_start, span_end in spans) async def handle_validate_subtitle_layout(arguments: dict) -> Sequence[TextContent]: """Validate title/subtitle layout for spatial collisions and safe-area containment (collision.validate_titles over every <title> in the file).""" filepath = _validate_filepath(arguments["filepath"], (".fcpxml", ".fcpxmld")) modifier = FCPXMLModifier(filepath) report = modifier.validate_subtitle_layout( safe_margin_x=float(arguments.get("safe_margin_x", 0.05)), safe_margin_y=float(arguments.get("safe_margin_y", 0.05)), min_font_size=( float(arguments["min_font_size"]) if arguments.get("min_font_size") is not None else None ), min_distance=( float(arguments["min_distance"]) if arguments.get("min_distance") is not None else None ), max_distance=( float(arguments["max_distance"]) if arguments.get("max_distance") is not None else None ), ) if arguments.get("output_format") == "json": return _text_result(json.dumps(report, indent=2)) summary = report["summary"] lines = [ "# Subtitle Layout Validation", "", f"## Summary (severity: {report['severity']})", f"- **Titles**: {summary['title_count']}", f"- **Issues**: {summary['issue_count']}", f"- **Collisions**: {summary['spatial_collision']}", f"- **Outside frame**: {summary['outside_frame']}", f"- **Outside safe area**: {summary['outside_safe_area']}", f"- **Font fallback**: {summary['font_missing']}", f"- **Font too small**: {summary['font_too_small']}", "", ] issues = report["issues"] if issues: lines.append(f"## Issues ({len(issues)})") for issue in issues: sev = issue["severity"].upper() if issue["type"] == "spatial_collision": corr = issue["suggested_correction"] lines.append( f"- [{sev}] collision: \"{issue['first_title']}\" x " f"\"{issue['second_title']}\" " f"(overlap {issue['overlap_width']:.0f}x" f"{issue['overlap_height']:.0f} = " f"{issue['overlap_area']:.0f}px, ratio " f"{issue['overlap_ratio']:.2f}, move " f"{corr['axis']} {corr['minimum_movement']:.0f}px)" ) else: detail = issue.get("title", "") or issue.get("font", "") lines.append(f"- [{sev}] {issue['type']}: {detail}".rstrip()) else: lines.append("_No issues found — no simultaneous titles overlap._") return _text_result("\n".join(lines)) async def handle_generate_dynamic_subtitles(arguments: dict) -> Sequence[TextContent]: """Generate per-word subtitle titles laid out as a block per sentence. Whisper's segments become sentences; each word becomes its own positioned <title> connected clip, appearing as it is spoken and accumulating on screen until the whole block clears at once. No compound clip. Reuses the same SOURCE-media -> TIMELINE mapping as ``transcript_markers`` (``modifier.source_file_start`` per spine clip) so word timestamps land at the correct position even across trimmed/multiple clips. """ model = arguments.get("model", "base") language = arguments.get("language") output_dir = arguments.get("output_dir") clip_filter = arguments.get("clip_name") # Anything the caller didn't explicitly pass falls back to the style # persisted from the "Legendas Dinâmicas" screen (~/.fcp-mcp-server/ # config.json), not a hardcoded default — so the UI is the single place # that configures the look, and every caller (app, MCP, this session) # renders the same thing without threading 11 fields through every call. saved = load_dynamic_subtitle_config() body_color = arguments.get("active_color") or saved["active_color"] config = DynamicSubtitleConfig( style=WordStyle( font=arguments.get("font") or saved["font"], font_size=int(arguments.get("font_size", saved["font_size"])), active_color=body_color, inactive_color=arguments.get("inactive_color", "0.7 0.7 0.7 1"), emphasis_look=WordLook( int(arguments.get("emphasis_size", saved["emphasis_size"])), arguments.get("emphasis_color") or saved["emphasis_color"] or body_color, font=arguments.get("emphasis_font") or saved["emphasis_font"], face=arguments.get("emphasis_face") or saved["emphasis_face"], kerning=0.0, ), body_look=WordLook( int(arguments.get("font_size", saved["font_size"])), body_color, font=arguments.get("font") or saved["font"], face="Bold", kerning=1.2, ), ), band_height=float(arguments.get("band_height", saved["band_height"])), block_center_y=float(arguments.get("block_center_y", saved["block_center_y"])), granularity=arguments.get("granularity", "phrase"), text_scale=float(arguments.get("text_scale", saved["text_scale"])), line_gap=float(arguments.get("line_gap", saved["line_gap"])), ) filepath, output_path, modifier = _setup_modifier(arguments, "_dynamic_subtitles") added: list[tuple[str, int, int]] = [] skipped: list[tuple[str, str]] = [] spine_clips = [el for _, el in modifier._iter_spine_clips()] for el in spine_clips: name = el.get("name", "") if clip_filter and name != clip_filter: continue src = modifier.resources.get(el.get("ref", ""), {}).get("src", "") media_path = media_src_to_path(src) if not media_path or not Path(media_path).is_file(): skipped.append((name, "media file missing")) continue data, reason = _load_or_transcribe(media_path, model, language, output_dir) if data is None: skipped.append((name, reason)) continue clip_source_start = modifier.source_file_start(el).to_seconds() clip_duration = modifier._parse_time(el.get("duration", "0s")).to_seconds() window_end = clip_source_start + clip_duration clip_words = _words_overlapping_clip(data.get("words", []), clip_source_start, window_end) if not clip_words: skipped.append((name, "no words in clip's source range")) continue # Sentence boundaries, rebased the same way, so each sentence becomes # its own block of titles that builds up and then clears together. # Overlap rather than containment: a segment straddling the clip's # in-point still governs the words that made the cut. clip_segments = [ { "start": float(s.get("start", 0.0)) - clip_source_start, "end": float(s.get("end", 0.0)) - clip_source_start, } for s in data.get("segments", []) if float(s.get("end", 0.0)) > clip_source_start and float(s.get("start", 0.0)) < window_end ] # Pass the element itself, not `name` — after ripple-cut/silence # removal every fragment of an originally-named clip keeps the same # `name`, so a name lookup here would resolve every clip in this # loop to whichever one `self.clips` last indexed, stacking every # clip's captions onto a single wrong spine element instead of each # clip's own. See Engine/docs/05_EXPERIENCIAS.md, entry 2026-08-17. lines = modifier.generate_dynamic_subtitles( el, clip_words, config, segments=clip_segments ) added.append((name, len(lines), len(clip_words))) if not added: text = "# Dynamic Subtitles\n\nNo captions generated — file unchanged (nothing saved)." if skipped: text += "\n\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) return _text_result(text) modifier.save(output_path) total_lines = sum(lines for _, lines, _ in added) total_words = sum(words for _, _, words in added) result = "# Dynamic Subtitles Generated (local Whisper)\n\n## Summary\n" result += ( f"- **Clips Captioned**: {len(added)}\n" f"- **Caption Lines (Title Clips)**: {total_lines}\n" f"- **Total Words**: {total_words}\n\n" ) result += _markdown_table( ["Clip", "Caption Lines", "Words"], [[n, str(lines), str(words)] for n, lines, words in added], ) if skipped: result += "\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) result += f"\n\nSaved to: `{output_path}`\n\n*Transcripts are cached as _transcript.json.*" return _text_result(result) async def handle_generate_plain_subtitles(arguments: dict) -> Sequence[TextContent]: """Generate static, editable title subtitles from word-level transcripts.""" model = arguments.get("model", "base") language = arguments.get("language") output_dir = arguments.get("output_dir") clip_filter = arguments.get("clip_name") saved = load_plain_subtitle_config() font = arguments.get("font") or saved["font"] font_size = int(arguments.get("font_size", saved["font_size"])) font_color = arguments.get("font_color") or saved["font_color"] max_words = max(1, int(arguments.get("max_words", saved["max_words"]))) position_y = float(arguments.get("position_y", saved["position_y"])) uppercase = bool(arguments.get("uppercase", saved["uppercase"])) keep_punctuation = bool(arguments.get("keep_punctuation", saved["keep_punctuation"])) filepath, output_path, modifier = _setup_modifier(arguments, "_plain_subtitles") added: list[tuple[str, int, int]] = [] skipped: list[tuple[str, str]] = [] spine_clips = [el for _, el in modifier._iter_spine_clips()] for el in spine_clips: name = el.get("name", "") if clip_filter and name != clip_filter: continue src = modifier.resources.get(el.get("ref", ""), {}).get("src", "") media_path = media_src_to_path(src) if not media_path or not Path(media_path).is_file(): skipped.append((name, "media file missing")) continue data, reason = _load_or_transcribe(media_path, model, language, output_dir) if data is None: skipped.append((name, reason)) continue clip_source_start = modifier.source_file_start(el).to_seconds() clip_duration = modifier._parse_time(el.get("duration", "0s")).to_seconds() clip_words = _words_overlapping_clip( data.get("words", []), clip_source_start, clip_source_start + clip_duration ) if not clip_words: skipped.append((name, "no words in clip's source range")) continue blocks = _plain_subtitle_blocks(clip_words, max_words) created = 0 for block in blocks: parts = [ _plain_word_text(w.get("word", ""), uppercase=uppercase, keep_punctuation=keep_punctuation) for w in block ] text = " ".join(p for p in parts if p).strip() if not text: continue start = max(0.0, min(float(w.get("start", 0.0)) for w in block)) end = max(float(w.get("end", start)) for w in block) duration = max(end - start, modifier.frame_duration_fraction()) modifier.add_text_title( el, text, offset=f"{start:.6f}s", duration=f"{duration:.6f}s", lane=20, position=f"0 {position_y:g}", font=font, font_size=font_size, font_color=font_color, bold=True, face=None, font_scale=1.0, size_param=font_size, ) created += 1 if created: added.append((name, created, len(clip_words))) if not added: text = "# Plain Subtitles\n\nNo subtitles generated — file unchanged (nothing saved)." if skipped: text += "\n\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) return _text_result(text) modifier.save(output_path) total_titles = sum(lines for _, lines, _ in added) total_words = sum(words for _, _, words in added) result = "# Plain Subtitles Generated\n\n## Summary\n" result += ( f"- **Clips Captioned**: {len(added)}\n" f"- **Title Clips**: {total_titles}\n" f"- **Total Words**: {total_words}\n\n" ) result += _markdown_table( ["Clip", "Title Clips", "Words"], [[n, str(lines), str(words)] for n, lines, words in added], ) if skipped: result += "\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) result += f"\n\nSaved to: `{output_path}`\n\n*Transcripts are cached as _transcript.json.*" return _text_result(result) async def handle_generate_subtitles_by_emphasis(arguments: dict) -> Sequence[TextContent]: """Generate dynamic titles for the emphasis phrases, and plain titles for every OTHER word — a plain block is simply not created where a dynamic phrase already covers, rather than created and disabled. A disabled ("enabled=0") title still shows as its own struck-through clip in Final Cut's timeline even though it never renders — a heavily emphasized edit ended up with dozens of dead clips cluttering the track. Not generating them there trades that clutter for a smaller gap: if the emphasis is turned off by hand later, the plain line has to be regenerated rather than just re-enabled. """ model = arguments.get("model", "base") language = arguments.get("language") output_dir = arguments.get("output_dir") clip_filter = arguments.get("clip_name") granularity = arguments.get("granularity", "phrase") saved_dynamic = load_dynamic_subtitle_config() body_color = saved_dynamic["active_color"] dynamic_config = DynamicSubtitleConfig( style=WordStyle( font=saved_dynamic["font"], font_size=int(saved_dynamic["font_size"]), active_color=body_color, inactive_color="0.7 0.7 0.7 1", emphasis_look=WordLook( int(saved_dynamic["emphasis_size"]), saved_dynamic["emphasis_color"] or body_color, font=saved_dynamic["emphasis_font"], face=saved_dynamic["emphasis_face"], kerning=0.0, ), body_look=WordLook( int(saved_dynamic["font_size"]), body_color, font=saved_dynamic["font"], face="Bold", kerning=1.2, ), ), band_height=float(saved_dynamic["band_height"]), block_center_y=float(saved_dynamic["block_center_y"]), granularity=granularity, text_scale=float(saved_dynamic["text_scale"]), line_gap=float(saved_dynamic["line_gap"]), ) saved_plain = load_plain_subtitle_config() plain_font = saved_plain["font"] plain_font_size = int(saved_plain["font_size"]) plain_font_color = saved_plain["font_color"] max_words = max(1, int(arguments.get("max_words", saved_plain["max_words"]))) position_y = float(saved_plain["position_y"]) uppercase = bool(arguments.get("uppercase", saved_plain["uppercase"])) keep_punctuation = bool(arguments.get("keep_punctuation", saved_plain["keep_punctuation"])) filepath, output_path, modifier = _setup_modifier(arguments, "_emphasis_subtitles") added: list[tuple[str, int, int, int, int]] = [] skipped: list[tuple[str, str]] = [] no_review: list[str] = [] spine_clips = [el for _, el in modifier._iter_spine_clips()] for el in spine_clips: name = el.get("name", "") if clip_filter and name != clip_filter: continue src = modifier.resources.get(el.get("ref", ""), {}).get("src", "") media_path = media_src_to_path(src) if not media_path or not Path(media_path).is_file(): skipped.append((name, "media file missing")) continue data, reason = _load_or_transcribe(media_path, model, language, output_dir) if data is None: skipped.append((name, reason)) continue spans = _load_emphasis_spans(media_path) if not spans: no_review.append(name) clip_source_start = modifier.source_file_start(el).to_seconds() clip_duration = modifier._parse_time(el.get("duration", "0s")).to_seconds() window_end = clip_source_start + clip_duration # Clip-relative windows, for deciding which plain titles to hide — # same coordinate space add_text_title's offsets end up in. clip_spans = [ (max(0.0, float(s["start"]) - clip_source_start), min(clip_duration, float(s["end"]) - clip_source_start)) for s in spans if float(s["end"]) > clip_source_start and float(s["start"]) < window_end ] all_words = data.get("words", []) dynamic_lines = 0 dynamic_word_count = 0 emphasis_words = _words_in_spans(all_words, spans) clip_emphasis_words = _words_overlapping_clip(emphasis_words, clip_source_start, window_end) if clip_emphasis_words: all_segments = data.get("segments", []) emphasis_segments = _segments_in_spans(all_segments, spans) clip_segments = [ { "start": float(s.get("start", 0.0)) - clip_source_start, "end": float(s.get("end", 0.0)) - clip_source_start, } for s in emphasis_segments if float(s.get("end", 0.0)) > clip_source_start and float(s.get("start", 0.0)) < window_end ] # Pass the element itself, not `name` — see the same note in # handle_generate_dynamic_subtitles (Engine/docs/05_EXPERIENCIAS.md, # entry 2026-08-17). dynamic_lines = len( modifier.generate_dynamic_subtitles( el, clip_emphasis_words, dynamic_config, segments=clip_segments ) ) dynamic_word_count = len(clip_emphasis_words) # Plain covers every word OUTSIDE an emphasis span. A block landing # under a dynamic phrase is simply not created there — generating it # disabled was tried first, but every disabled title still shows up # as its own clip in Final Cut's timeline (just struck through), so # a heavily-emphasized edit ended up with dozens of dead clips # cluttering the track for no visible benefit. The trade-off: if the # emphasis is later turned off by hand, the plain line under it has # to be regenerated rather than just re-enabled. plain_created = 0 plain_hidden = 0 clip_all_words = _words_overlapping_clip(all_words, clip_source_start, window_end) blocks = _plain_subtitle_blocks(clip_all_words, max_words) for block in blocks: parts = [ _plain_word_text(w.get("word", ""), uppercase=uppercase, keep_punctuation=keep_punctuation) for w in block ] text = " ".join(p for p in parts if p).strip() if not text: continue start = max(0.0, min(float(w.get("start", 0.0)) for w in block)) end = max(float(w.get("end", start)) for w in block) if _overlaps_any_span(start, end, clip_spans): plain_hidden += 1 continue duration = max(end - start, modifier.frame_duration_fraction()) modifier.add_text_title( el, text, offset=f"{start:.6f}s", duration=f"{duration:.6f}s", lane=20, position=f"0 {position_y:g}", font=plain_font, font_size=plain_font_size, font_color=plain_font_color, bold=True, face=None, font_scale=1.0, size_param=plain_font_size, ) plain_created += 1 if dynamic_lines or plain_created: added.append( (name, dynamic_lines, plain_created, plain_hidden, dynamic_word_count + len(clip_all_words)) ) else: skipped.append((name, "no words in clip's source range")) if not added: text = "# Subtitles by Emphasis\n\nNo captions generated — file unchanged (nothing saved)." if skipped: text += "\n\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) return _text_result(text) modifier.save(output_path) total_dynamic = sum(d for _, d, _, _, _ in added) total_plain = sum(p for _, _, p, _, _ in added) total_hidden = sum(h for _, _, _, h, _ in added) total_words = sum(w for _, _, _, _, w in added) result = "# Subtitles by Emphasis Generated\n\n## Summary\n" result += ( f"- **Clips Captioned**: {len(added)}\n" f"- **Dynamic Title Lines (emphasis)**: {total_dynamic}\n" f"- **Plain Title Blocks**: {total_plain}\n" f"- **Plain Blocks Skipped Under Emphasis (not created there)**: {total_hidden}\n" f"- **Total Words**: {total_words}\n\n" ) result += _markdown_table( ["Clip", "Dynamic Lines", "Plain Blocks", "Skipped", "Words"], [[n, str(d), str(p), str(h), str(w)] for n, d, p, h, w in added], ) if no_review: result += ( "\n## Sem revisão de ênfase\n" "Nenhum `_phrase_actions.json` encontrado para: " + ", ".join(no_review) + " — todas as frases desses clipes saíram como legenda comum. " "Rode a etapa 5 do Assistente (revisão de frases) antes, se quiser destaque dinâmico.\n" ) if skipped: result += "\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) result += f"\n\nSaved to: `{output_path}`\n\n*Transcripts are cached as _transcript.json; emphasis spans from _phrase_actions.json.*" return _text_result(result) HANDLERS = { "validate_subtitle_layout": handle_validate_subtitle_layout, "generate_dynamic_subtitles": handle_generate_dynamic_subtitles, "generate_plain_subtitles": handle_generate_plain_subtitles, "generate_subtitles_by_emphasis": handle_generate_subtitles_by

"""Legendas dinâmicas (geração → validação) — tool schemas and handlers. Extracted from server.py; see Engine/docs/03_SERVER_TOOLS.md for the tool catalog. """ from __future__ import annotations import json import re from pathlib import Path from typing import Sequence from mcp.types import TextContent, Tool from fcpxml.media_intel import media_src_to_path from fcpxml.model_manager import load_dynamic_subtitle_config, load_plain_subtitle_config from fcpxml.models import DynamicSubtitleConfig, WordLook, WordStyle from fcpxml.writer import FCPXMLModifier from server_tools._shared import ( _load_or_transcribe, _markdown_table, _setup_modifier, _text_result, _validate_filepath, ) TOOLS = [ Tool( name="validate_subtitle_layout", description="Re-measure every title/subtitle in an FCPXML and report spatial collisions, frame and safe-area violations, and font fallbacks. Detects overlapping boxes only for titles on screen at the same time (half-open time intervals, so a title ending exactly as the next begins is never flagged). Returns a severity (none/render_tolerance/warning/probable/severe), the list of issues with suggested corrections, and summary counts.", inputSchema={ "type": "object", "properties": { "filepath": {"type": "string", "description": "Path to FCPXML file"}, "safe_margin_x": {"type": "number", "default": 0.05, "description": "Fraction of frame width to inset from each side (0.05 = 5%)"}, "safe_margin_y": {"type": "number", "default": 0.05, "description": "Fraction of frame height to inset from top/bottom"}, "min_font_size": {"type": "number", "description": "Flag titles whose emitted fontSize is below this readable minimum"}, "min_distance": {"type": "number", "description": "Flag same-block titles closer than this many pixels (insufficient_spacing)"}, "max_distance": {"type": "number", "description": "Flag same-block titles farther than this many pixels (excessive_spacing)"}, "output_format": {"type": "string", "enum": ["markdown", "json"], "default": "markdown", "description": "Report format"} }, "required": ["filepath"] } ), Tool( name="generate_dynamic_subtitles", description="Generate progressive-composition subtitles as real, editable FCPXML title clips (the 'Text'/Basic Text template). Whisper's segments become sentences; each sentence is diagrammed as stacked blocks — supporting words grouped small in a grotesque, the sentence's key word alone and large in a display italic, body lines staggered to opposite edges. One per block: each enters as its own words are spoken and stays on screen, so the sentence assembles itself, and every block clears at the same instant. Set granularity='word' for the older one-title-per-word rhythm. A sentence too tall for the band splits into successive compositions. These are TITLES, not captions: no subtitles role, so they render over the video without enabling caption display. Uses each media file's local Whisper word-level transcript (_transcript.json, auto-transcribes if missing). Style fields below (band_height through inactive_color) fall back to the style saved from the app's 'Legendas Dinâmicas' screen (~/.fcp-mcp-server/config.json via save_dynamic_subtitle_config) when omitted — pass a value here only to override that for one call. Non-destructive: writes a _dynamic_subtitles copy.", inputSchema={ "type": "object", "properties": { "filepath": {"type": "string", "description": "Path to FCPXML file"}, "clip_name": {"type": "string", "description": "Only caption the clip with this name (default: all spine clips with matched source media)"}, "model": {"type": "string", "default": "base", "description": "Whisper model size if transcription is needed"}, "language": {"type": "string", "description": "ISO language code hint (e.g. 'en'); auto-detected if omitted"}, "band_height": {"type": "number", "description": "Fraction of frame height the sentence block may fill before splitting into another block. Falls back to the saved style (default 0.22 — about three lines)"}, "block_center_y": {"type": "number", "description": "Vertical centre of the block in canvas points; negative sits below frame centre. Falls back to the saved style (default -167, just under centre)"}, "line_gap": {"type": "number", "description": "Air between stacked lines in canvas points. Lines are stacked on their real ink, so this is the whole distance beyond the glyphs themselves; negative values deliberately tuck each line into the one above. Falls back to the saved style (default 8)"}, "granularity": {"type": "string", "enum": ["phrase", "word"], "default": "phrase", "description": "'phrase': one title per LINE of the composition, key word set large (the reference look). 'word': one title per word."}, "emphasis_font": {"type": "string", "description": "Family for the key word (phrase mode). Must be installed on the editing Mac; unmeasured families fall back to estimated widths. Falls back to the saved style (default 'Playfair Display')"}, "emphasis_face": {"type": "string", "description": "Face for the key word, e.g. 'Medium Italic' or a script/calligraphic face. Falls back to the saved style (default 'Medium Italic')"}, "emphasis_size": {"type": "integer", "description": "Key-word size in canvas points, at the 2160x3840 reference frame. Falls back to the saved style (default 265)"}, "emphasis_color": {"type": "string", "description": "RGBA (0-1, space-separated) for the key word (phrase mode). Defaults to active_color, so the block reads in a single colour unless the key word is deliberately set apart"}, "text_scale": {"type": "number", "description": "Ratio between the title template's fontSize space and the canvas-point space it positions in. The \"Text\" template sizes type in frame pixels, so sizes are doubled on the way out. Falls back to the saved style (default 2.0). Lower it only if a template renders type larger than the chosen point size"}, "font": {"type": "string", "description": "Title font family (supporting lines in phrase mode). Falls back to the saved style (default 'Helvetica Neue')"}, "font_size": {"type": "integer", "description": "Supporting-line font size in canvas points, at the 2160x3840 reference frame. Falls back to the saved style (default 104)"}, "active_color": {"type": "string", "description": "RGBA (0-1, space-separated) for even-indexed lines. Falls back to the saved style (default '1 1 1 1')"}, "inactive_color": {"type": "string", "default": "0.7 0.7 0.7 1", "description": "RGBA (0-1, space-separated) for odd-indexed lines — alternates with active_color for visual variety between stacked lines"}, "output_path": {"type": "string", "description": "Output path (default: adds _dynamic_subtitles suffix)"}, }, "required": ["filepath"] } ), Tool( name="generate_plain_subtitles", description="Generate simple editable FCPXML text-title subtitles, synchronized to transcript words but without visual build-in/build-out effects. Words are grouped into short blocks, placed at a configurable vertical position, and written as static Text titles rather than SRT captions.", inputSchema={ "type": "object", "properties": { "filepath": {"type": "string", "description": "Path to FCPXML file"}, "clip_name": {"type": "string", "description": "Only caption the clip with this name (default: all spine clips with matched source media)"}, "model": {"type": "string", "default": "base", "description": "Whisper model size if transcription is needed"}, "language": {"type": "string", "description": "ISO language code hint (e.g. 'pt'); auto-detected if omitted"}, "font": {"type": "string", "description": "Text font family. Falls back to saved plain-subtitle config."}, "font_size": {"type": "integer", "description": "Font size in canvas points. Falls back to saved plain-subtitle config."}, "font_color": {"type": "string", "description": "RGBA (0-1, space-separated). Falls back to saved plain-subtitle config."}, "max_words": {"type": "integer", "description": "Maximum words per subtitle block. Falls back to saved plain-subtitle config."}, "position_y": {"type": "number", "description": "Vertical title position in canvas points; negative sits lower in frame."}, "uppercase": {"type": "boolean", "description": "Render text in uppercase."}, "keep_punctuation": {"type": "boolean", "description": "Keep punctuation such as comma and period."}, "text_scale": {"type": "number", "description": "Template font-size scale. Falls back to saved plain-subtitle config."}, "output_path": {"type": "string", "description": "Output path (default: adds _plain_subtitles suffix)"}, }, "required": ["filepath"] } ), Tool( name="generate_subtitles_by_emphasis", description="Generate BOTH subtitle styles in one pass, split by word so they never coexist on the same range: dynamic progressive-composition titles (see generate_dynamic_subtitles) cover whichever whole phrases were marked as emphasis in the phrase-review step (etapa 5, zoom applied, level >= 1); plain static titles (see generate_plain_subtitles) cover every OTHER word in the clip. A plain block is simply not created where a dynamic phrase already covers — not created-then-disabled — because a disabled title still shows as its own struck-through clip in Final Cut's timeline even though it never renders, and a heavily emphasized edit ended up with dozens of dead clips cluttering the track. Trade-off: if emphasis is turned off by hand later, the plain line under it has to be regenerated, not just re-enabled. Reads emphasis spans from the media's cached '<media>_phrase_actions.json' (written by save_phrase_review after the app's etapa 5 review) — run the voice-editing wizard through that step first, or nothing is treated as emphasis and every word gets a plain title. Style knobs are the saved 'Legendas Dinâmicas'/plain-subtitle configs (~/.fcp-mcp-server/config.json); this tool does not expose per-call style overrides, only the split logic — use generate_dynamic_subtitles/generate_plain_subtitles directly if you need one-off styling.", inputSchema={ "type": "object", "properties": { "filepath": {"type": "string", "description": "Path to FCPXML file"}, "clip_name": {"type": "string", "description": "Only caption the clip with this name (default: all spine clips with matched source media)"}, "model": {"type": "string", "default": "base", "description": "Whisper model size if transcription is needed"}, "language": {"type": "string", "description": "ISO language code hint (e.g. 'pt'); auto-detected if omitted"}, "granularity": {"type": "string", "enum": ["phrase", "word"], "default": "phrase", "description": "Passed through to the dynamic half, same meaning as in generate_dynamic_subtitles"}, "max_words": {"type": "integer", "description": "Max words per block for the plain half. Falls back to saved plain-subtitle config."}, "uppercase": {"type": "boolean", "description": "Uppercase the plain half. Falls back to saved plain-subtitle config."}, "keep_punctuation": {"type": "boolean", "description": "Keep punctuation in the plain half. Falls back to saved plain-subtitle config."}, "output_path": {"type": "string", "description": "Output path (default: adds _emphasis_subtitles suffix)"}, }, "required": ["filepath"] } ), ] _PUNCT_RE = re.compile(r"[^\w\sÀ-ÖØ-öø-ÿ]", re.UNICODE) def _words_overlapping_clip(words: Sequence[dict], start: float, end: float) -> list[dict]: """Return transcript words that overlap a source window, rebased to it.""" clip_words: list[dict] = [] for w in words: word_start = float(w.get("start", 0.0)) word_end = float(w.get("end", word_start)) if word_end <= start or word_start >= end: continue clip_words.append( { "word": w.get("word", ""), "start": max(0.0, word_start - start), "end": max(0.0, min(word_end, end) - start), } ) return clip_words def _plain_word_text(word: str, *, uppercase: bool, keep_punctuation: bool) -> str: text = str(word or "").strip() if not keep_punctuation: text = _PUNCT_RE.sub("", text) text = re.sub(r"\s+", " ", text).strip() return text.upper() if uppercase else text def _plain_subtitle_blocks(words: Sequence[dict], max_words: int) -> list[list[dict]]: blocks: list[list[dict]] = [] pending: list[dict] = [] for word in words: if not str(word.get("word", "")).strip(): continue pending.append(word) if len(pending) >= max(1, max_words): blocks.append(pending) pending = [] if pending: blocks.append(pending) return blocks def _phrase_actions_path(media_path: str) -> Path: """Where `save_phrase_review` writes emphasis decisions for this media. Mirrors `phrase_review.review_paths()`'s naming (stem + "_phrase_actions.json"), without importing that module just for a path — the voice_timeline this would normally derive from is itself named `<media stem>_voice_timeline.json`, so stripping straight from the media stem lands on the same file. """ stem = Path(media_path).stem return Path(media_path).with_name(f"{stem}_phrase_actions.json") def _load_emphasis_spans(media_path: str) -> list[dict]: """Load emphasis spans (source-media time) saved by the etapa-5 phrase review. Returns [] if the review was never run for this media — callers should treat that as "nothing is emphasis yet", not as an error, since the wizard's later steps are optional. """ path = _phrase_actions_path(media_path) if not path.is_file(): return [] try: data = json.loads(path.read_text(encoding="utf-8")) except (OSError, json.JSONDecodeError): return [] spans = data.get("emphasis_spans", []) return [s for s in spans if isinstance(s, dict) and "start" in s and "end" in s] def _word_in_spans(word_start: float, word_end: float, spans: Sequence[dict]) -> bool: """A word belongs to an emphasis span if its midpoint falls inside it. Midpoint, not start, so a word straddling a span boundary (which can happen since spans come from phrase trims, not word timestamps) lands on whichever side it mostly belongs to instead of always defaulting to one edge. """ mid = (word_start + word_end) / 2.0 return any(float(s["start"]) <= mid < float(s["end"]) for s in spans) def _words_in_spans(words: Sequence[dict], spans: Sequence[dict]) -> list[dict]: """The subset of source-time transcript words that fall inside a span. Feeds only the DYNAMIC half — the plain half always gets every word, full clip, unfiltered; this is not a partition of the word list into two disjoint sets, it is "which words also get the dynamic treatment on top". """ if not spans: return [] return [ w for w in words if _word_in_spans(float(w.get("start", 0.0)), float(w.get("end", w.get("start", 0.0))), spans) ] def _segments_in_spans(segments: Sequence[dict], spans: Sequence[dict]) -> list[dict]: """Keep only the sentences that fall inside an emphasis span (by midpoint). Feeds the dynamic half's sentence-block builder; segments outside every span would only produce blocks with no words left in them after the word filter. """ if not spans: return [] kept = [] for seg in segments: start = float(seg.get("start", 0.0)) end = float(seg.get("end", start)) mid = (start + end) / 2.0 if any(float(s["start"]) <= mid < float(s["end"]) for s in spans): kept.append(seg) return kept def _overlaps_any_span(start: float, end: float, spans: Sequence[tuple[float, float]]) -> bool: """Half-open interval overlap: a plain title under this window is skipped.""" return any(start < span_end and end > span_start for span_start, span_end in spans) async def handle_validate_subtitle_layout(arguments: dict) -> Sequence[TextContent]: """Validate title/subtitle layout for spatial collisions and safe-area containment (collision.validate_titles over every <title> in the file).""" filepath = _validate_filepath(arguments["filepath"], (".fcpxml", ".fcpxmld")) modifier = FCPXMLModifier(filepath) report = modifier.validate_subtitle_layout( safe_margin_x=float(arguments.get("safe_margin_x", 0.05)), safe_margin_y=float(arguments.get("safe_margin_y", 0.05)), min_font_size=( float(arguments["min_font_size"]) if arguments.get("min_font_size") is not None else None ), min_distance=( float(arguments["min_distance"]) if arguments.get("min_distance") is not None else None ), max_distance=( float(arguments["max_distance"]) if arguments.get("max_distance") is not None else None ), ) if arguments.get("output_format") == "json": return _text_result(json.dumps(report, indent=2)) summary = report["summary"] lines = [ "# Subtitle Layout Validation", "", f"## Summary (severity: {report['severity']})", f"- **Titles**: {summary['title_count']}", f"- **Issues**: {summary['issue_count']}", f"- **Collisions**: {summary['spatial_collision']}", f"- **Outside frame**: {summary['outside_frame']}", f"- **Outside safe area**: {summary['outside_safe_area']}", f"- **Font fallback**: {summary['font_missing']}", f"- **Font too small**: {summary['font_too_small']}", "", ] issues = report["issues"] if issues: lines.append(f"## Issues ({len(issues)})") for issue in issues: sev = issue["severity"].upper() if issue["type"] == "spatial_collision": corr = issue["suggested_correction"] lines.append( f"- [{sev}] collision: \"{issue['first_title']}\" x " f"\"{issue['second_title']}\" " f"(overlap {issue['overlap_width']:.0f}x" f"{issue['overlap_height']:.0f} = " f"{issue['overlap_area']:.0f}px, ratio " f"{issue['overlap_ratio']:.2f}, move " f"{corr['axis']} {corr['minimum_movement']:.0f}px)" ) else: detail = issue.get("title", "") or issue.get("font", "") lines.append(f"- [{sev}] {issue['type']}: {detail}".rstrip()) else: lines.append("_No issues found — no simultaneous titles overlap._") return _text_result("\n".join(lines)) async def handle_generate_dynamic_subtitles(arguments: dict) -> Sequence[TextContent]: """Generate per-word subtitle titles laid out as a block per sentence. Whisper's segments become sentences; each word becomes its own positioned <title> connected clip, appearing as it is spoken and accumulating on screen until the whole block clears at once. No compound clip. Reuses the same SOURCE-media -> TIMELINE mapping as ``transcript_markers`` (``modifier.source_file_start`` per spine clip) so word timestamps land at the correct position even across trimmed/multiple clips. """ model = arguments.get("model", "base") language = arguments.get("language") output_dir = arguments.get("output_dir") clip_filter = arguments.get("clip_name") # Anything the caller didn't explicitly pass falls back to the style # persisted from the "Legendas Dinâmicas" screen (~/.fcp-mcp-server/ # config.json), not a hardcoded default — so the UI is the single place # that configures the look, and every caller (app, MCP, this session) # renders the same thing without threading 11 fields through every call. saved = load_dynamic_subtitle_config() body_color = arguments.get("active_color") or saved["active_color"] config = DynamicSubtitleConfig( style=WordStyle( font=arguments.get("font") or saved["font"], font_size=int(arguments.get("font_size", saved["font_size"])), active_color=body_color, inactive_color=arguments.get("inactive_color", "0.7 0.7 0.7 1"), emphasis_look=WordLook( int(arguments.get("emphasis_size", saved["emphasis_size"])), arguments.get("emphasis_color") or saved["emphasis_color"] or body_color, font=arguments.get("emphasis_font") or saved["emphasis_font"], face=arguments.get("emphasis_face") or saved["emphasis_face"], kerning=0.0, ), body_look=WordLook( int(arguments.get("font_size", saved["font_size"])), body_color, font=arguments.get("font") or saved["font"], face="Bold", kerning=1.2, ), ), band_height=float(arguments.get("band_height", saved["band_height"])), block_center_y=float(arguments.get("block_center_y", saved["block_center_y"])), granularity=arguments.get("granularity", "phrase"), text_scale=float(arguments.get("text_scale", saved["text_scale"])), line_gap=float(arguments.get("line_gap", saved["line_gap"])), ) filepath, output_path, modifier = _setup_modifier(arguments, "_dynamic_subtitles") added: list[tuple[str, int, int]] = [] skipped: list[tuple[str, str]] = [] spine_clips = [el for _, el in modifier._iter_spine_clips()] for el in spine_clips: name = el.get("name", "") if clip_filter and name != clip_filter: continue src = modifier.resources.get(el.get("ref", ""), {}).get("src", "") media_path = media_src_to_path(src) if not media_path or not Path(media_path).is_file(): skipped.append((name, "media file missing")) continue data, reason = _load_or_transcribe(media_path, model, language, output_dir) if data is None: skipped.append((name, reason)) continue clip_source_start = modifier.source_file_start(el).to_seconds() clip_duration = modifier._parse_time(el.get("duration", "0s")).to_seconds() window_end = clip_source_start + clip_duration clip_words = _words_overlapping_clip(data.get("words", []), clip_source_start, window_end) if not clip_words: skipped.append((name, "no words in clip's source range")) continue # Sentence boundaries, rebased the same way, so each sentence becomes # its own block of titles that builds up and then clears together. # Overlap rather than containment: a segment straddling the clip's # in-point still governs the words that made the cut. clip_segments = [ { "start": float(s.get("start", 0.0)) - clip_source_start, "end": float(s.get("end", 0.0)) - clip_source_start, } for s in data.get("segments", []) if float(s.get("end", 0.0)) > clip_source_start and float(s.get("start", 0.0)) < window_end ] # Pass the element itself, not `name` — after ripple-cut/silence # removal every fragment of an originally-named clip keeps the same # `name`, so a name lookup here would resolve every clip in this # loop to whichever one `self.clips` last indexed, stacking every # clip's captions onto a single wrong spine element instead of each # clip's own. See Engine/docs/05_EXPERIENCIAS.md, entry 2026-08-17. lines = modifier.generate_dynamic_subtitles( el, clip_words, config, segments=clip_segments ) added.append((name, len(lines), len(clip_words))) if not added: text = "# Dynamic Subtitles\n\nNo captions generated — file unchanged (nothing saved)." if skipped: text += "\n\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) return _text_result(text) modifier.save(output_path) total_lines = sum(lines for _, lines, _ in added) total_words = sum(words for _, _, words in added) result = "# Dynamic Subtitles Generated (local Whisper)\n\n## Summary\n" result += ( f"- **Clips Captioned**: {len(added)}\n" f"- **Caption Lines (Title Clips)**: {total_lines}\n" f"- **Total Words**: {total_words}\n\n" ) result += _markdown_table( ["Clip", "Caption Lines", "Words"], [[n, str(lines), str(words)] for n, lines, words in added], ) if skipped: result += "\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) result += f"\n\nSaved to: `{output_path}`\n\n*Transcripts are cached as _transcript.json.*" return _text_result(result) async def handle_generate_plain_subtitles(arguments: dict) -> Sequence[TextContent]: """Generate static, editable title subtitles from word-level transcripts.""" model = arguments.get("model", "base") language = arguments.get("language") output_dir = arguments.get("output_dir") clip_filter = arguments.get("clip_name") saved = load_plain_subtitle_config() font = arguments.get("font") or saved["font"] font_size = int(arguments.get("font_size", saved["font_size"])) font_color = arguments.get("font_color") or saved["font_color"] max_words = max(1, int(arguments.get("max_words", saved["max_words"]))) position_y = float(arguments.get("position_y", saved["position_y"])) uppercase = bool(arguments.get("uppercase", saved["uppercase"])) keep_punctuation = bool(arguments.get("keep_punctuation", saved["keep_punctuation"])) filepath, output_path, modifier = _setup_modifier(arguments, "_plain_subtitles") added: list[tuple[str, int, int]] = [] skipped: list[tuple[str, str]] = [] spine_clips = [el for _, el in modifier._iter_spine_clips()] for el in spine_clips: name = el.get("name", "") if clip_filter and name != clip_filter: continue src = modifier.resources.get(el.get("ref", ""), {}).get("src", "") media_path = media_src_to_path(src) if not media_path or not Path(media_path).is_file(): skipped.append((name, "media file missing")) continue data, reason = _load_or_transcribe(media_path, model, language, output_dir) if data is None: skipped.append((name, reason)) continue clip_source_start = modifier.source_file_start(el).to_seconds() clip_duration = modifier._parse_time(el.get("duration", "0s")).to_seconds() clip_words = _words_overlapping_clip( data.get("words", []), clip_source_start, clip_source_start + clip_duration ) if not clip_words: skipped.append((name, "no words in clip's source range")) continue blocks = _plain_subtitle_blocks(clip_words, max_words) created = 0 for block in blocks: parts = [ _plain_word_text(w.get("word", ""), uppercase=uppercase, keep_punctuation=keep_punctuation) for w in block ] text = " ".join(p for p in parts if p).strip() if not text: continue start = max(0.0, min(float(w.get("start", 0.0)) for w in block)) end = max(float(w.get("end", start)) for w in block) duration = max(end - start, modifier.frame_duration_fraction()) modifier.add_text_title( el, text, offset=f"{start:.6f}s", duration=f"{duration:.6f}s", lane=20, position=f"0 {position_y:g}", font=font, font_size=font_size, font_color=font_color, bold=True, face=None, font_scale=1.0, size_param=font_size, ) created += 1 if created: added.append((name, created, len(clip_words))) if not added: text = "# Plain Subtitles\n\nNo subtitles generated — file unchanged (nothing saved)." if skipped: text += "\n\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) return _text_result(text) modifier.save(output_path) total_titles = sum(lines for _, lines, _ in added) total_words = sum(words for _, _, words in added) result = "# Plain Subtitles Generated\n\n## Summary\n" result += ( f"- **Clips Captioned**: {len(added)}\n" f"- **Title Clips**: {total_titles}\n" f"- **Total Words**: {total_words}\n\n" ) result += _markdown_table( ["Clip", "Title Clips", "Words"], [[n, str(lines), str(words)] for n, lines, words in added], ) if skipped: result += "\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) result += f"\n\nSaved to: `{output_path}`\n\n*Transcripts are cached as _transcript.json.*" return _text_result(result) async def handle_generate_subtitles_by_emphasis(arguments: dict) -> Sequence[TextContent]: """Generate dynamic titles for the emphasis phrases, and plain titles for every OTHER word — a plain block is simply not created where a dynamic phrase already covers, rather than created and disabled. A disabled ("enabled=0") title still shows as its own struck-through clip in Final Cut's timeline even though it never renders — a heavily emphasized edit ended up with dozens of dead clips cluttering the track. Not generating them there trades that clutter for a smaller gap: if the emphasis is turned off by hand later, the plain line has to be regenerated rather than just re-enabled. """ model = arguments.get("model", "base") language = arguments.get("language") output_dir = arguments.get("output_dir") clip_filter = arguments.get("clip_name") granularity = arguments.get("granularity", "phrase") saved_dynamic = load_dynamic_subtitle_config() body_color = saved_dynamic["active_color"] dynamic_config = DynamicSubtitleConfig( style=WordStyle( font=saved_dynamic["font"], font_size=int(saved_dynamic["font_size"]), active_color=body_color, inactive_color="0.7 0.7 0.7 1", emphasis_look=WordLook( int(saved_dynamic["emphasis_size"]), saved_dynamic["emphasis_color"] or body_color, font=saved_dynamic["emphasis_font"], face=saved_dynamic["emphasis_face"], kerning=0.0, ), body_look=WordLook( int(saved_dynamic["font_size"]), body_color, font=saved_dynamic["font"], face="Bold", kerning=1.2, ), ), band_height=float(saved_dynamic["band_height"]), block_center_y=float(saved_dynamic["block_center_y"]), granularity=granularity, text_scale=float(saved_dynamic["text_scale"]), line_gap=float(saved_dynamic["line_gap"]), ) saved_plain = load_plain_subtitle_config() plain_font = saved_plain["font"] plain_font_size = int(saved_plain["font_size"]) plain_font_color = saved_plain["font_color"] max_words = max(1, int(arguments.get("max_words", saved_plain["max_words"]))) position_y = float(saved_plain["position_y"]) uppercase = bool(arguments.get("uppercase", saved_plain["uppercase"])) keep_punctuation = bool(arguments.get("keep_punctuation", saved_plain["keep_punctuation"])) filepath, output_path, modifier = _setup_modifier(arguments, "_emphasis_subtitles") added: list[tuple[str, int, int, int, int]] = [] skipped: list[tuple[str, str]] = [] no_review: list[str] = [] spine_clips = [el for _, el in modifier._iter_spine_clips()] for el in spine_clips: name = el.get("name", "") if clip_filter and name != clip_filter: continue src = modifier.resources.get(el.get("ref", ""), {}).get("src", "") media_path = media_src_to_path(src) if not media_path or not Path(media_path).is_file(): skipped.append((name, "media file missing")) continue data, reason = _load_or_transcribe(media_path, model, language, output_dir) if data is None: skipped.append((name, reason)) continue spans = _load_emphasis_spans(media_path) if not spans: no_review.append(name) clip_source_start = modifier.source_file_start(el).to_seconds() clip_duration = modifier._parse_time(el.get("duration", "0s")).to_seconds() window_end = clip_source_start + clip_duration # Clip-relative windows, for deciding which plain titles to hide — # same coordinate space add_text_title's offsets end up in. clip_spans = [ (max(0.0, float(s["start"]) - clip_source_start), min(clip_duration, float(s["end"]) - clip_source_start)) for s in spans if float(s["end"]) > clip_source_start and float(s["start"]) < window_end ] all_words = data.get("words", []) dynamic_lines = 0 dynamic_word_count = 0 emphasis_words = _words_in_spans(all_words, spans) clip_emphasis_words = _words_overlapping_clip(emphasis_words, clip_source_start, window_end) if clip_emphasis_words: all_segments = data.get("segments", []) emphasis_segments = _segments_in_spans(all_segments, spans) clip_segments = [ { "start": float(s.get("start", 0.0)) - clip_source_start, "end": float(s.get("end", 0.0)) - clip_source_start, } for s in emphasis_segments if float(s.get("end", 0.0)) > clip_source_start and float(s.get("start", 0.0)) < window_end ] # Pass the element itself, not `name` — see the same note in # handle_generate_dynamic_subtitles (Engine/docs/05_EXPERIENCIAS.md, # entry 2026-08-17). dynamic_lines = len( modifier.generate_dynamic_subtitles( el, clip_emphasis_words, dynamic_config, segments=clip_segments ) ) dynamic_word_count = len(clip_emphasis_words) # Plain covers every word OUTSIDE an emphasis span. A block landing # under a dynamic phrase is simply not created there — generating it # disabled was tried first, but every disabled title still shows up # as its own clip in Final Cut's timeline (just struck through), so # a heavily-emphasized edit ended up with dozens of dead clips # cluttering the track for no visible benefit. The trade-off: if the # emphasis is later turned off by hand, the plain line under it has # to be regenerated rather than just re-enabled. plain_created = 0 plain_hidden = 0 clip_all_words = _words_overlapping_clip(all_words, clip_source_start, window_end) blocks = _plain_subtitle_blocks(clip_all_words, max_words) for block in blocks: parts = [ _plain_word_text(w.get("word", ""), uppercase=uppercase, keep_punctuation=keep_punctuation) for w in block ] text = " ".join(p for p in parts if p).strip() if not text: continue start = max(0.0, min(float(w.get("start", 0.0)) for w in block)) end = max(float(w.get("end", start)) for w in block) if _overlaps_any_span(start, end, clip_spans): plain_hidden += 1 continue duration = max(end - start, modifier.frame_duration_fraction()) modifier.add_text_title( el, text, offset=f"{start:.6f}s", duration=f"{duration:.6f}s", lane=20, position=f"0 {position_y:g}", font=plain_font, font_size=plain_font_size, font_color=plain_font_color, bold=True, face=None, font_scale=1.0, size_param=plain_font_size, ) plain_created += 1 if dynamic_lines or plain_created: added.append( (name, dynamic_lines, plain_created, plain_hidden, dynamic_word_count + len(clip_all_words)) ) else: skipped.append((name, "no words in clip's source range")) if not added: text = "# Subtitles by Emphasis\n\nNo captions generated — file unchanged (nothing saved)." if skipped: text += "\n\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) return _text_result(text) modifier.save(output_path) total_dynamic = sum(d for _, d, _, _, _ in added) total_plain = sum(p for _, _, p, _, _ in added) total_hidden = sum(h for _, _, _, h, _ in added) total_words = sum(w for _, _, _, _, w in added) result = "# Subtitles by Emphasis Generated\n\n## Summary\n" result += ( f"- **Clips Captioned**: {len(added)}\n" f"- **Dynamic Title Lines (emphasis)**: {total_dynamic}\n" f"- **Plain Title Blocks**: {total_plain}\n" f"- **Plain Blocks Skipped Under Emphasis (not created there)**: {total_hidden}\n" f"- **Total Words**: {total_words}\n\n" ) result += _markdown_table( ["Clip", "Dynamic Lines", "Plain Blocks", "Skipped", "Words"], [[n, str(d), str(p), str(h), str(w)] for n, d, p, h, w in added], ) if no_review: result += ( "\n## Sem revisão de ênfase\n" "Nenhum `_phrase_actions.json` encontrado para: " + ", ".join(no_review) + " — todas as frases desses clipes saíram como legenda comum. " "Rode a etapa 5 do Assistente (revisão de frases) antes, se quiser destaque dinâmico.\n" ) if skipped: result += "\n## Skipped Clips\n" + _markdown_table( ["Clip", "Reason"], [[n, r] for n, r in skipped] ) result += f"\n\nSaved to: `{output_path}`\n\n*Transcripts are cached as _transcript.json; emphasis spans from _phrase_actions.json.*" return _text_result(result) HANDLERS = { "validate_subtitle_layout": handle_validate_subtitle_layout, "generate_dynamic_subtitles": handle_generate_dynamic_subtitles, "generate_plain_subtitles": handle_generate_plain_subtitles, "generate_subtitles_by_emphasis": handle_generate_subtitles_by_emphasis, }