"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
fix(cli): improve video creation harness workflows
yuhao8120c9f231ab
diff --git a/gimp/agent-harness/cli_anything/gimp/core/export.py b/gimp/agent-harness/cli_anything/gimp/core/export.pyindex 0e2dd7a13..616531daf 100644--- a/gimp/agent-harness/cli_anything/gimp/core/export.py+++ b/gimp/agent-harness/cli_anything/gimp/core/export.py@@ -67,7 +67,7 @@ def render(# --- GIMP-native rendering (preferred) ---try:from cli_anything.gimp.utils.gimp_backend import is_available, render_project- if is_available():+ if is_available() and not _project_has_draw_ops(project):return render_project(project, output_path,preset=preset, overwrite=overwrite,@@ -142,6 +142,7 @@ def _render_via_pillow(continuelayer_img = _apply_filters(layer_img, layer.get("filters", []))+ layer_img = _apply_draw_ops(layer_img, layer.get("draw_ops", []))if "_scale_x" in layer:new_w = max(1, round(layer_img.width * layer["_scale_x"]))@@ -252,6 +253,66 @@ def _render_text_layer(layer, canvas_w, canvas_h):return img+def _apply_draw_ops(img, draw_ops):+ """Apply stored draw operations onto a layer image."""+ if not draw_ops:+ return img++ from PIL import ImageDraw, ImageFont++ canvas = img.convert("RGBA")+ draw = ImageDraw.Draw(canvas)++ for op in draw_ops:+ op_type = op.get("type")+ if op_type == "rect":+ fill = op.get("fill")+ outline = op.get("outline")+ line_width = max(1, int(op.get("width", 1)))+ draw.rectangle(+ [op.get("x1", 0), op.get("y1", 0), op.get("x2", 0), op.get("y2", 0)],+ fill=fill,+ outline=outline,+ width=line_width,+ )+ elif op_type == "text":+ font_size = int(op.get("size", 24))+ font_name = op.get("font", "Arial")+ font = _load_font(font_name, font_size)+ draw.text(+ (op.get("x", 0), op.get("y", 0)),+ op.get("text", ""),+ fill=op.get("color", "#000000"),+ font=font,+ )++ return canvas+++def _load_font(font_name, font_size):+ """Best-effort font loading for Pillow rendering."""+ from PIL import ImageFont++ candidate_paths = [+ "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",+ "/usr/share/fonts/truetype/liberation2/LiberationSans-Regular.ttf",+ "/usr/share/fonts/truetype/msttcorefonts/Arial.ttf",+ "arial.ttf",+ font_name,+ ]+ for candidate in candidate_paths:+ try:+ return ImageFont.truetype(candidate, font_size)+ except (OSError, IOError):+ continue+ return ImageFont.load_default()+++def _project_has_draw_ops(project):+ """Check whether any layer includes deferred draw operations."""+ return any(layer.get("draw_ops") for layer in project.get("layers", []))++def _apply_filters(img, filters):"""Apply a chain of filters to an image (Pillow fallback path)."""for f in filters:diff --git a/gimp/agent-harness/cli_anything/gimp/gimp_cli.py b/gimp/agent-harness/cli_anything/gimp/gimp_cli.pyindex 58031951b..ae039a3d1 100644--- a/gimp/agent-harness/cli_anything/gimp/gimp_cli.py+++ b/gimp/agent-harness/cli_anything/gimp/gimp_cli.py@@ -324,13 +324,20 @@ def layer_move(index, to):output({"moved": index, "to": to}, f"Moved layer {index} to position {to}")[email protected]("set")[email protected]("set", context_settings={"ignore_unknown_options": True, "allow_extra_args": True})[email protected]_context@click.argument("index", type=int)@click.argument("prop")[email protected]("value")[email protected]("value", required=False)@handle_error-def layer_set(index, prop, value):+def layer_set(ctx, index, prop, value):"""Set a layer property (name, opacity, visible, mode, offset_x, offset_y)."""+ if value is None:+ if not ctx.args:+ raise ValueError("Missing layer property value")+ value = ctx.args[0]+ elif ctx.args:+ value = " ".join([value] + ctx.args)sess = get_session()sess.snapshot(f"Set layer {index} {prop}={value}")layer_mod.set_layer_property(sess.get_project(), index, prop, value)@@ -674,7 +681,7 @@ def draw():@click.option("--color", default="#000000", help="Text color (hex)")@handle_errordef draw_text(layer_index, text, x, y, font, size, color):- """Draw text on a layer (by converting it to a text layer)."""+ """Draw text on a layer as a persisted draw operation."""sess = get_session()sess.snapshot(f"Draw text on layer {layer_index}")proj = sess.get_project()@@ -682,14 +689,16 @@ def draw_text(layer_index, text, x, y, font, size, color):if layer_index < 0 or layer_index >= len(layers):raise IndexError(f"Layer index {layer_index} out of range")layer = layers[layer_index]- layer["type"] = "text"- layer["text"] = text- layer["font"] = font- layer["font_size"] = size- layer["color"] = color- layer["offset_x"] = x- layer["offset_y"] = y- output({"layer": layer_index, "text": text}, f"Set text on layer {layer_index}")+ layer.setdefault("draw_ops", []).append({+ "type": "text",+ "text": text,+ "x": x,+ "y": y,+ "font": font,+ "size": size,+ "color": color,+ })+ output({"layer": layer_index, "text": text}, f"Drew text on layer {layer_index}")@draw.command("rect")diff --git a/gimp/agent-harness/cli_anything/gimp/tests/test_core.py b/gimp/agent-harness/cli_anything/gimp/tests/test_core.pyindex 86dd0643a..c318bfc33 100644--- a/gimp/agent-harness/cli_anything/gimp/tests/test_core.py+++ b/gimp/agent-harness/cli_anything/gimp/tests/test_core.py@@ -8,6 +8,7 @@ import osimport sysimport tempfileimport pytest+from click.testing import CliRunnersys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))@@ -24,6 +25,7 @@ from cli_anything.gimp.core.canvas import (resize_canvas, scale_canvas, crop_canvas, set_mode, set_dpi, get_canvas_info,)from cli_anything.gimp.core.session import Session+from cli_anything.gimp import gimp_cli# ── Project Tests ────────────────────────────────────────────────@@ -207,6 +209,32 @@ class TestLayers:assert "text" in layerassert "font_size" in layer+ def test_layer_can_store_draw_ops(self):+ proj = self._make_project()+ layer = add_layer(proj, name="Overlay", layer_type="image")+ layer.setdefault("draw_ops", []).append({"type": "text", "text": "Hello"})+ assert layer["type"] == "image"+ assert layer["draw_ops"][0]["type"] == "text"+++class TestCliLayerSet:+ def test_layer_set_accepts_negative_offsets(self, tmp_path):+ proj = create_project()+ add_layer(proj, name="Overlay")+ project_path = tmp_path / "negative-offsets.gimp-cli.json"+ save_project(proj, str(project_path))++ gimp_cli._session = None+ runner = CliRunner()+ result = runner.invoke(+ gimp_cli.cli,+ ["--project", str(project_path), "layer", "set", "0", "offset_x", "-48"],+ )+ assert result.exit_code == 0, result.output++ updated = open_project(str(project_path))+ assert updated["layers"][0]["offset_x"] == -48+# ── Filter Tests ─────────────────────────────────────────────────diff --git a/gimp/agent-harness/cli_anything/gimp/tests/test_full_e2e.py b/gimp/agent-harness/cli_anything/gimp/tests/test_full_e2e.pyindex 97034524d..b21f4ce30 100644--- a/gimp/agent-harness/cli_anything/gimp/tests/test_full_e2e.py+++ b/gimp/agent-harness/cli_anything/gimp/tests/test_full_e2e.py@@ -501,6 +501,35 @@ class TestRealWorldWorkflows:render(proj, out, preset="png", overwrite=True)assert os.path.exists(out)+ def test_draw_ops_overlay_workflow(self, tmp_dir, sample_image):+ """Render non-destructive draw operations on top of an image layer."""+ proj = create_project(width=300, height=200)+ add_from_file(proj, sample_image, name="Background")+ overlay = add_layer(proj, name="Overlay", layer_type="image")+ overlay.setdefault("draw_ops", []).append({+ "type": "rect",+ "x1": 10,+ "y1": 10,+ "x2": 290,+ "y2": 60,+ "fill": "#111111cc",+ "outline": "#ffffff",+ "width": 2,+ })+ overlay["draw_ops"].append({+ "type": "text",+ "x": 20,+ "y": 20,+ "text": "Overlay Title",+ "font": "Arial",+ "size": 24,+ "color": "#ffffff",+ })++ out = os.path.join(tmp_dir, "draw_ops_overlay.png")+ render(proj, out, preset="png", overwrite=True)+ assert os.path.exists(out)+def test_batch_filter_workflow(self, tmp_dir, sample_image):"""Apply multiple artistic filters in sequence."""proj = create_project(width=300, height=200)diff --git a/inkscape/agent-harness/cli_anything/inkscape/core/document.py b/inkscape/agent-harness/cli_anything/inkscape/core/document.pyindex ee3cfbe2a..f570a0c72 100644--- a/inkscape/agent-harness/cli_anything/inkscape/core/document.py+++ b/inkscape/agent-harness/cli_anything/inkscape/core/document.py@@ -322,6 +322,7 @@ def _add_gradient_to_defs(defs, grad: Dict[str, Any]) -> None:def _object_to_svg_element(obj: Dict[str, Any]):"""Convert a JSON object dict to an SVG element."""import xml.etree.ElementTree as ET+ from cli_anything.inkscape.core.text import layout_text_lines, text_anchor_xobj_type = obj.get("type", "")obj_id = obj.get("id", "")@@ -377,11 +378,26 @@ def _object_to_svg_element(obj: Dict[str, Any]):elif obj_type == "text":tag = f"{{{SVG_NS}}}text"- for attr in ("x", "y"):- if attr in obj:- attribs[attr] = str(obj[attr])+ anchor_x = text_anchor_x(obj)+ attribs["x"] = str(anchor_x)+ if "y" in obj:+ attribs["y"] = str(obj["y"])elem = ET.Element(tag, attribs)- elem.text = obj.get("text", "")+ lines = layout_text_lines(obj)+ if len(lines) == 1:+ elem.text = lines[0]+ return elem+ font_size = float(obj.get("font_size", 24) or 24)+ line_height = float(obj.get("line_height", 1.2) or 1.2)+ y = float(obj.get("y", 0))+ for idx, line in enumerate(lines):+ tspan_attribs = {"x": str(anchor_x)}+ if idx == 0:+ tspan_attribs["y"] = str(y)+ else:+ tspan_attribs["dy"] = str(font_size * line_height)+ tspan = ET.SubElement(elem, f"{{{SVG_NS}}}tspan", tspan_attribs)+ tspan.text = linereturn elemelif obj_type == "image":diff --git a/inkscape/agent-harness/cli_anything/inkscape/core/export.py b/inkscape/agent-harness/cli_anything/inkscape/core/export.pyindex d524bf901..be9b78421 100644--- a/inkscape/agent-harness/cli_anything/inkscape/core/export.py+++ b/inkscape/agent-harness/cli_anything/inkscape/core/export.py@@ -10,6 +10,7 @@ import shutilfrom typing import Dict, Any, List, Optionalfrom cli_anything.inkscape.core.document import project_to_svg, save_svg+from cli_anything.inkscape.core.text import layout_text_lines, text_anchor_xfrom cli_anything.inkscape.utils.svg_utils import serialize_svg# Export presets@@ -264,18 +265,21 @@ def _render_object(draw, obj: Dict[str, Any], sx: float, sy: float) -> None:draw.polygon(points, fill=fill, outline=stroke, width=stroke_w)elif obj_type == "text":- x = float(obj.get("x", 0)) * sx+ anchor_x = text_anchor_x(obj) * sxy = float(obj.get("y", 50)) * sy- text = obj.get("text", "")text_fill = fill or "#000000"font_size = int(float(obj.get("font_size", 24)) * sy)+ line_height = float(obj.get("line_height", 1.2) or 1.2)try:from PIL import ImageFontfont = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",font_size)except (ImportError, OSError):font = None- draw.text((x, y), text, fill=text_fill, font=font)+ for idx, line in enumerate(layout_text_lines(obj)):+ x = _resolve_text_line_x(draw, line, anchor_x, obj, font, sx)+ line_y = y + (idx * font_size * line_height)+ draw.text((x, line_y), line, fill=text_fill, font=font)elif obj_type == "star" and "d" in obj:# Render star as polygon from path data@@ -326,3 +330,22 @@ def _render_path_as_polygon(draw, d: str, fill, stroke, stroke_w: int,elif len(points) == 2:line_color = stroke or fill or "#000000"draw.line([points[0], points[1]], fill=line_color, width=stroke_w)+++def _resolve_text_line_x(draw, line: str, anchor_x: float, obj: Dict[str, Any], font, sx: float) -> float:+ """Resolve actual line x-position for Pillow drawing."""+ anchor = obj.get("text_anchor", "start")+ if anchor == "start":+ return anchor_x++ try:+ bbox = draw.textbbox((0, 0), line, font=font)+ width = bbox[2] - bbox[0]+ except Exception:+ width = len(line) * max(1.0, float(obj.get("font_size", 24)) * 0.58 * sx)++ if anchor == "middle":+ return anchor_x - (width / 2.0)+ if anchor == "end":+ return anchor_x - width+ return anchor_xdiff --git a/inkscape/agent-harness/cli_anything/inkscape/core/text.py b/inkscape/agent-harness/cli_anything/inkscape/core/text.pyindex e21a0b911..cc99f7e09 100644--- a/inkscape/agent-harness/cli_anything/inkscape/core/text.py+++ b/inkscape/agent-harness/cli_anything/inkscape/core/text.py@@ -20,6 +20,8 @@ TEXT_PROPERTIES = {"letter-spacing": {"type": "float", "description": "Letter spacing"},"word-spacing": {"type": "float", "description": "Word spacing"},"line-height": {"type": "float", "description": "Line height multiplier"},+ "box-width": {"type": "float", "description": "Optional text box width for wrapping"},+ "box-height": {"type": "float", "description": "Optional text box height for wrapping"},"fill": {"type": "str", "description": "Text fill color"},"stroke": {"type": "str", "description": "Text stroke color"},"opacity": {"type": "float", "description": "Text opacity (0.0-1.0)"},@@ -45,6 +47,9 @@ def add_text(font_style: str = "normal",fill: str = "#000000",text_anchor: str = "start",+ box_width: Optional[float] = None,+ box_height: Optional[float] = None,+ line_height: float = 1.2,name: Optional[str] = None,layer: Optional[str] = None,) -> Dict[str, Any]:@@ -53,6 +58,12 @@ def add_text(raise ValueError("Text content cannot be empty")if font_size <= 0:raise ValueError(f"Font size must be positive: {font_size}")+ if box_width is not None and box_width <= 0:+ raise ValueError(f"Text box width must be positive: {box_width}")+ if box_height is not None and box_height <= 0:+ raise ValueError(f"Text box height must be positive: {box_height}")+ if line_height <= 0:+ raise ValueError(f"Line height must be positive: {line_height}")# Build style stringstyle_parts = {@@ -79,10 +90,15 @@ def add_text("font_style": font_style,"fill": fill,"text_anchor": text_anchor,+ "line_height": line_height,"style": style,"transform": "","layer": _default_layer_id(project),}+ if box_width is not None:+ obj["box_width"] = box_width+ if box_height is not None:+ obj["box_height"] = box_heightif layer:obj["layer"] = layer@@ -130,6 +146,14 @@ def set_text_property(value = float(value)if value <= 0:raise ValueError(f"Font size must be positive: {value}")+ if prop in {"box-width", "box-height"}:+ value = float(value)+ if value <= 0:+ raise ValueError(f"{prop} must be positive: {value}")+ if prop == "line-height":+ value = float(value)+ if value <= 0:+ raise ValueError(f"Line height must be positive: {value}")if prop == "opacity":value = float(value)if value < 0 or value > 1:@@ -147,6 +171,8 @@ def set_text_property("letter-spacing": "letter_spacing","word-spacing": "word_spacing","line-height": "line_height",+ "box-width": "box_width",+ "box-height": "box_height",}internal_name = field_map.get(prop, prop)@@ -173,10 +199,43 @@ def list_text_objects(project: Dict[str, Any]) -> List[Dict[str, Any]]:"fill": obj.get("fill", "#000000"),"x": obj.get("x", 0),"y": obj.get("y", 0),+ "box_width": obj.get("box_width"),+ "box_height": obj.get("box_height"),})return result+def layout_text_lines(obj: Dict[str, Any]) -> List[str]:+ """Lay out wrapped text lines for a text object."""+ text = str(obj.get("text", ""))+ if not text:+ return [""]++ box_width = obj.get("box_width")+ line_height = float(obj.get("line_height", 1.2) or 1.2)+ font_size = float(obj.get("font_size", 24) or 24)++ if not box_width:+ return text.splitlines() or [text]++ avg_char_width = max(1.0, font_size * 0.58)+ max_chars = max(1, int(float(box_width) / avg_char_width))++ lines: List[str] = []+ for paragraph in text.splitlines() or [text]:+ wrapped = _wrap_paragraph(paragraph, max_chars)+ lines.extend(wrapped or [""])++ box_height = obj.get("box_height")+ if box_height:+ max_lines = max(1, int(float(box_height) / max(1.0, font_size * line_height)))+ if len(lines) > max_lines:+ lines = lines[:max_lines]+ lines[-1] = _truncate_with_ellipsis(lines[-1], max_chars)++ return lines++# ── Internal Helpers ────────────────────────────────────────────def _rebuild_text_style(obj: Dict[str, Any]) -> None:@@ -210,6 +269,20 @@ def _rebuild_text_style(obj: Dict[str, Any]) -> None:obj["style"] = serialize_style(style_parts)+def text_anchor_x(obj: Dict[str, Any]) -> float:+ """Compute the anchor x-position, taking text boxes into account."""+ x = float(obj.get("x", 0))+ box_width = obj.get("box_width")+ anchor = obj.get("text_anchor", "start")+ if not box_width:+ return x+ if anchor == "middle":+ return x + float(box_width) / 2.0+ if anchor == "end":+ return x + float(box_width)+ return x++def _default_layer_id(project: Dict[str, Any]) -> str:"""Get the ID of the first layer."""layers = project.get("layers", [])@@ -228,3 +301,43 @@ def _add_object(project: Dict[str, Any], obj: Dict[str, Any]) -> None:if layer.get("id") == layer_id:layer.setdefault("objects", []).append(obj["id"])break+++def _wrap_paragraph(paragraph: str, max_chars: int) -> List[str]:+ """Wrap a paragraph to an approximate character count."""+ words = paragraph.split()+ if not words:+ return [""]++ lines: List[str] = []+ current = ""+ for word in words:+ if len(word) > max_chars:+ if current:+ lines.append(current)+ current = ""+ while len(word) > max_chars:+ lines.append(word[:max_chars])+ word = word[max_chars:]+ current = word+ continue++ candidate = word if not current else f"{current} {word}"+ if len(candidate) <= max_chars:+ current = candidate+ else:+ lines.append(current)+ current = word++ if current:+ lines.append(current)+ return lines+++def _truncate_with_ellipsis(text: str, max_chars: int) -> str:+ """Trim text to fit and add an ellipsis when needed."""+ if len(text) <= max_chars:+ return text+ if max_chars <= 1:+ return text[:max_chars]+ return text[: max_chars - 1].rstrip() + "…"diff --git a/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.py b/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.pyindex 95a2e3ff1..f2f0cb0ad 100644--- a/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.py+++ b/inkscape/agent-harness/cli_anything/inkscape/inkscape_cli.py@@ -50,6 +50,24 @@ def get_session() -> Session:return _session+def _load_or_seed_project(project_path: str) -> None:+ """Open an existing project path or seed a new in-memory document for it."""+ sess = get_session()+ if sess.has_project():+ return+ if os.path.exists(project_path):+ proj = doc_mod.open_document(project_path)+ else:+ default_name = os.path.basename(project_path)+ if default_name.endswith(".inkscape-cli.json"):+ default_name = default_name[: -len(".inkscape-cli.json")]+ else:+ default_name = os.path.splitext(default_name)[0]+ default_name = default_name or "untitled"+ proj = doc_mod.create_document(name=default_name)+ sess.set_project(proj, project_path)++def output(data, message: str = ""):if _json_output:click.echo(json.dumps(data, indent=2, default=str))@@ -141,10 +159,7 @@ def cli(ctx, use_json, project_path, auto_save, dry_run):_dry_run = dry_runif project_path:- sess = get_session()- if not sess.has_project():- proj = doc_mod.open_document(project_path)- sess.set_project(proj, project_path)+ _load_or_seed_project(project_path)# Register auto-save callback to run after each commandctx.call_on_close(_auto_save_callback)@@ -444,16 +459,22 @@ def text():@click.option("--font-weight", default="normal", help="Font weight")@click.option("--fill", default="#000000", help="Text color")@click.option("--text-anchor", default="start", help="Alignment: start, middle, end")[email protected]("--box-width", type=float, default=None, help="Optional text box width for wrapping")[email protected]("--box-height", type=float, default=None, help="Optional text box height for wrapping")[email protected]("--line-height", type=float, default=1.2, help="Line height multiplier")@click.option("--name", "-n", default=None)@handle_error-def text_add(text, x, y, font_family, font_size, font_weight, fill, text_anchor, name):+def text_add(text, x, y, font_family, font_size, font_weight, fill, text_anchor,+ box_width, box_height, line_height, name):"""Add a text element."""sess = get_session()sess.snapshot("Add text")obj = text_mod.add_text(sess.get_project(), text=text, x=x, y=y,font_family=font_family, font_size=font_size,font_weight=font_weight, fill=fill,- text_anchor=text_anchor, name=name)+ text_anchor=text_anchor, box_width=box_width,+ box_height=box_height, line_height=line_height,+ name=name)output(obj, f"Added text: {obj['name']}")@@ -1005,9 +1026,7 @@ def repl(project_path):skin = ReplSkin("inkscape", version="1.0.0")if project_path:- sess = get_session()- proj = doc_mod.open_document(project_path)- sess.set_project(proj, project_path)+ _load_or_seed_project(project_path)skin.print_banner()diff --git a/inkscape/agent-harness/cli_anything/inkscape/tests/test_core.py b/inkscape/agent-harness/cli_anything/inkscape/tests/test_core.pyindex a8f6d3db3..b8d0a4df1 100644--- a/inkscape/agent-harness/cli_anything/inkscape/tests/test_core.py+++ b/inkscape/agent-harness/cli_anything/inkscape/tests/test_core.py@@ -8,6 +8,7 @@ import osimport sysimport tempfileimport pytest+from click.testing import CliRunnersys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))@@ -28,7 +29,7 @@ from cli_anything.inkscape.core.shapes import (list_objects, get_object, SHAPE_TYPES,)from cli_anything.inkscape.core.text import (- add_text, set_text_property, list_text_objects, TEXT_PROPERTIES,+ add_text, set_text_property, list_text_objects, layout_text_lines, TEXT_PROPERTIES,)from cli_anything.inkscape.core.styles import (set_fill, set_stroke, set_opacity, set_style,@@ -53,6 +54,7 @@ from cli_anything.inkscape.core.gradients import ()from cli_anything.inkscape.core.export import EXPORT_PRESETS, list_presetsfrom cli_anything.inkscape.core.session import Session+from cli_anything.inkscape import inkscape_cli@pytest.fixture(autouse=True)@@ -237,6 +239,36 @@ class TestDocument:assert svg.tag == f"{{{SVG_NS}}}svg"assert "800" in svg.get("width", "")+ def test_project_to_svg_wrapped_text_uses_tspans(self):+ proj = create_document(name="svg_text_wrap", width=800, height=600)+ add_text(+ proj,+ text="Real capture plus Veo cold open plus Gemini score",+ x=20,+ y=40,+ box_width=140,+ font_size=20,+ )+ svg = project_to_svg(proj)+ text_nodes = list(svg.iter(f"{{{SVG_NS}}}text"))+ assert len(text_nodes) == 1+ tspans = list(text_nodes[0].iter(f"{{{SVG_NS}}}tspan"))+ assert len(tspans) > 1+++class TestCliBootstrap:+ def test_nonexistent_project_path_bootstraps_new_document(self, tmp_path):+ project_path = tmp_path / "fresh.inkscape-cli.json"+ inkscape_cli._session = None+ runner = CliRunner()+ result = runner.invoke(+ inkscape_cli.cli,+ ["--project", str(project_path), "document", "save"],+ )+ assert result.exit_code == 0, result.output+ loaded = open_document(str(project_path))+ assert loaded["name"] == "fresh"+# ── Shape Tests ─────────────────────────────────────────────────@@ -406,6 +438,12 @@ class TestText:assert obj["text"] == "Hello World"assert obj["x"] == 100+ def test_add_text_with_box(self):+ proj = self._make_doc()+ obj = add_text(proj, text="Wrapped text", x=10, y=20, box_width=200, box_height=80)+ assert obj["box_width"] == 200+ assert obj["box_height"] == 80+def test_add_text_empty(self):proj = self._make_doc()with pytest.raises(ValueError, match="cannot be empty"):@@ -434,6 +472,12 @@ class TestText:set_text_property(proj, 0, "font-size", "48")assert proj["objects"][0]["font_size"] == 48.0+ def test_set_box_width(self):+ proj = self._make_doc()+ add_text(proj, text="Hi")+ set_text_property(proj, 0, "box-width", "220")+ assert proj["objects"][0]["box_width"] == 220.0+def test_set_invalid_font_weight(self):proj = self._make_doc()add_text(proj, text="Hi")@@ -468,6 +512,18 @@ class TestText:assert "48" in style and "px" in styleassert "#ff0000" in style+ def test_layout_text_lines_wraps(self):+ proj = self._make_doc()+ obj = add_text(+ proj,+ text="Real capture plus Veo cold open plus Gemini score",+ box_width=120,+ box_height=90,+ font_size=20,+ )+ lines = layout_text_lines(obj)+ assert len(lines) > 1+# ── Style Tests ─────────────────────────────────────────────────diff --git a/shotcut/agent-harness/cli_anything/shotcut/core/export.py b/shotcut/agent-harness/cli_anything/shotcut/core/export.pyindex 610fe861a..e2e2b7cb8 100644--- a/shotcut/agent-harness/cli_anything/shotcut/core/export.py+++ b/shotcut/agent-harness/cli_anything/shotcut/core/export.py@@ -184,7 +184,7 @@ def _build_volume(props: dict) -> Optional[str]:"""Convert MLT volume filter to ffmpeg volume/afade."""level = props.get("level", props.get("gain", "1.0"))if "=" in level and ";" in level:- return _build_audio_fade(level)+ return _build_volume_expression(level)# Check if gain in dBgain = props.get("gain")if gain:@@ -192,20 +192,33 @@ def _build_volume(props: dict) -> Optional[str]:return f"volume={level}"-def _build_audio_fade(keyframes: str) -> Optional[str]:- """Convert keyframed volume to ffmpeg afade."""- parts = keyframes.split(";")- if len(parts) < 2:+def _build_volume_expression(keyframes: str) -> Optional[str]:+ """Convert keyframed volume to an ffmpeg volume expression."""+ parts = [part for part in keyframes.split(";") if part]+ if not parts:return Nonetry:- first_val = float(parts[0].split("=")[1])- last_val = float(parts[-1].split("=")[1])- last_tc = parts[-1].split("=")[0]- duration = _tc_to_seconds(last_tc)- if first_val < last_val:- return f"afade=t=in:st=0:d={duration:.3f}"- else:- return f"afade=t=out:st=0:d={duration:.3f}"+ points = []+ for part in parts:+ timecode, value = part.split("=", 1)+ points.append((_tc_to_seconds(timecode), float(value)))+ if len(points) == 1:+ return f"volume={points[0][1]}"++ def _segment(index: int) -> str:+ current_t, current_val = points[index]+ next_t, next_val = points[index + 1]+ if next_t <= current_t:+ return _segment(index + 1)+ linear = (+ f"({current_val:.6f}+({next_val:.6f}-{current_val:.6f})"+ f"*(t-{current_t:.6f})/{(next_t - current_t):.6f})"+ )+ if index + 1 == len(points) - 1:+ return linear+ return f"if(lt(t,{next_t:.6f}),{linear},{_segment(index + 1)})"++ return f"volume='if(lt(t,{points[0][0]:.6f}),{points[0][1]:.6f},{_segment(0)})'"except (ValueError, IndexError):return Nonediff --git a/shotcut/agent-harness/cli_anything/shotcut/core/filters.py b/shotcut/agent-harness/cli_anything/shotcut/core/filters.pyindex b3a1c151a..9703eab73 100644--- a/shotcut/agent-harness/cli_anything/shotcut/core/filters.py+++ b/shotcut/agent-harness/cli_anything/shotcut/core/filters.py@@ -4,6 +4,7 @@ from typing import Optionalfrom lxml import etreefrom ..utils import mlt_xml+from ..utils.time import parse_time_input, frames_to_timecodefrom .session import Session@@ -790,6 +791,14 @@ def _resolve_target(session: Session, track_index: Optional[int] = None,return producer+def _find_filter_index(target: etree._Element, service: str) -> tuple[int | None, etree._Element | None]:+ """Find the first filter on a target by MLT service name."""+ for index, filt in enumerate(target.findall("filter")):+ if mlt_xml.get_property(filt, "mlt_service", "") == service:+ return index, filt+ return None, None++def add_filter(session: Session, filter_name: str,track_index: Optional[int] = None,clip_index: Optional[int] = None,@@ -838,8 +847,6 @@ def add_filter(session: Session, filter_name: str,"target": target_desc,"params": props,}--def remove_filter(session: Session, filter_index: int,track_index: Optional[int] = None,clip_index: Optional[int] = None) -> dict:@@ -933,3 +940,104 @@ def list_filters(session: Session,})return result+++def set_volume_envelope(+ session: Session,+ points: list[tuple[str, str]],+ *,+ track_index: Optional[int] = None,+ clip_index: Optional[int] = None,+) -> dict:+ """Create or update a keyframed volume envelope."""+ if not points:+ raise ValueError("At least one time=level point is required")++ session.checkpoint()+ profile = session.get_profile()+ fps_num = int(profile.get("frame_rate_num", 30000))+ fps_den = int(profile.get("frame_rate_den", 1001))++ normalized: dict[int, str] = {}+ for timecode, level in points:+ float(level)+ normalized[parse_time_input(timecode, fps_num, fps_den)] = str(level)++ envelope = ";".join(+ f"{frames_to_timecode(frame, fps_num, fps_den)}={level}"+ for frame, level in sorted(normalized.items())+ )++ target = _resolve_target(session, track_index, clip_index)+ filter_index, filt = _find_filter_index(target, "volume")+ if filt is None:+ filt = mlt_xml.add_filter_to_element(target, "volume", {"level": envelope})+ filter_index = len(target.findall("filter")) - 1+ old_value = None+ else:+ old_value = mlt_xml.get_property(filt, "level")+ mlt_xml.set_property(filt, "level", envelope)++ return {+ "action": "set_volume_envelope",+ "filter_index": filter_index,+ "service": "volume",+ "old_value": old_value,+ "level": envelope,+ }+++def duck_volume(+ session: Session,+ windows: list[tuple[str, str]],+ *,+ track_index: Optional[int] = None,+ clip_index: Optional[int] = None,+ normal_level: float = 1.0,+ duck_level: float = 0.25,+ attack: str = "00:00:00.150",+ release: str = "00:00:00.250",+) -> dict:+ """Apply a simple ducking envelope over one or more absolute timeline windows."""+ if not windows:+ raise ValueError("At least one ducking window is required")++ profile = session.get_profile()+ fps_num = int(profile.get("frame_rate_num", 30000))+ fps_den = int(profile.get("frame_rate_den", 1001))+ attack_frames = parse_time_input(attack, fps_num, fps_den)+ release_frames = parse_time_input(release, fps_num, fps_den)++ frame_points: dict[int, str] = {0: str(normal_level)}+ sorted_windows = sorted(windows, key=lambda item: parse_time_input(item[0], fps_num, fps_den))+ for start_tc, end_tc in sorted_windows:+ start_frame = parse_time_input(start_tc, fps_num, fps_den)+ end_frame = parse_time_input(end_tc, fps_num, fps_den)+ if end_frame < start_frame:+ raise ValueError(f"Invalid ducking window: {start_tc}:{end_tc}")++ frame_points[max(0, start_frame - attack_frames)] = str(normal_level)+ frame_points[start_frame] = str(duck_level)+ frame_points[end_frame] = str(duck_level)+ frame_points[end_frame + release_frames] = str(normal_level)++ result = set_volume_envelope(+ session,+ [+ (frames_to_timecode(frame, fps_num, fps_den), level)+ for frame, level in sorted(frame_points.items())+ ],+ track_index=track_index,+ clip_index=clip_index,+ )+ result.update(+ {+ "action": "duck_volume",+ "windows": sorted_windows,+ "normal_level": normal_level,+ "duck_level": duck_level,+ "attack": attack,+ "release": release,+ }+ )+ return resultdiff --git a/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py b/shotcut/agent-harness/cli_anything/shotcut/core/timeline.pyindex d0fd4d5fe..13e453367 100644--- a/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py+++ b/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py@@ -30,6 +30,56 @@ def _get_fps(session: Session) -> tuple[int, int]:return fps_num, fps_den+def _entry_duration_frames(session: Session, entry: dict) -> int:+ """Return duration in frames for a playlist entry or blank."""+ fps_num, fps_den = _get_fps(session)+ if entry["type"] == "blank":+ return parse_time_input(entry["length"], fps_num, fps_den)++ in_point = entry.get("in") or "00:00:00.000"+ out_point = entry.get("out")+ if not out_point:+ raise RuntimeError("Absolute timeline placement requires clips with finite out points")+ return parse_time_input(out_point, fps_num, fps_den) - parse_time_input(in_point, fps_num, fps_den)+++def _absolute_insertion_point(+ session: Session, playlist: etree._Element, at_time: str+) -> tuple[int, int, int]:+ """Resolve where a new clip can start on a track timeline.++ Returns:+ (insert_child_index, leading_blank_frames, trailing_blank_frames)+ """+ fps_num, fps_den = _get_fps(session)+ target = parse_time_input(at_time, fps_num, fps_den)+ if target < 0:+ raise ValueError(f"Timeline position must be non-negative, got {at_time!r}")++ children = list(playlist)+ entries = mlt_xml.get_playlist_entries(playlist)+ timeline_cursor = 0++ for idx, entry in enumerate(entries):+ duration = _entry_duration_frames(session, entry)+ start = timeline_cursor+ end = start + duration+ if target == start:+ return idx + len([c for c in children[: idx] if c.tag == "property"]), 0, 0+ if entry["type"] == "blank" and start < target < end:+ leading = target - start+ trailing = end - target+ return idx + len([c for c in children[: idx] if c.tag == "property"]), leading, trailing+ if entry["type"] == "entry" and start < target < end:+ raise RuntimeError(+ f"Timeline position {at_time} overlaps an existing clip on track; "+ "split or move clips before placing another clip there"+ )+ timeline_cursor = end++ return len(children), max(0, target - timeline_cursor), 0++def add_track(session: Session, track_type: str = "video",name: str = "") -> dict:"""Add a new track to the timeline.@@ -149,6 +199,7 @@ def add_clip(session: Session, resource: str, track_index: int,in_point: Optional[str] = None,out_point: Optional[str] = None,position: Optional[int] = None,+ at_time: Optional[str] = None,caption: Optional[str] = None) -> dict:"""Add a media clip to a track.@@ -159,11 +210,14 @@ def add_clip(session: Session, resource: str, track_index: int,in_point: Trim in point (timecode or frames)out_point: Trim out point (timecode or frames)position: Insert position (clip index on track), None = append+ at_time: Absolute timeline start time for the clipcaption: Display name for the clip"""resource = os.path.abspath(resource)if not os.path.isfile(resource):raise FileNotFoundError(f"Media file not found: {resource}")+ if position is not None and at_time is not None:+ raise ValueError("Use either position or at_time, not both")session.checkpoint()@@ -177,12 +231,36 @@ def add_clip(session: Session, resource: str, track_index: int,# Add entry to the track's playlistplaylist = _get_track_playlist(session, track_index)- entry = mlt_xml.add_entry_to_playlist(- playlist, producer.get("id"),- in_point=in_point,- out_point=out_point,- position=position,- )+ if at_time is not None:+ insert_child_index, leading_blank_frames, trailing_blank_frames = _absolute_insertion_point(+ session, playlist, at_time+ )+ fps_num, fps_den = _get_fps(session)+ if leading_blank_frames:+ blank = etree.Element("blank")+ blank.set("length", frames_to_timecode(leading_blank_frames, fps_num, fps_den))+ playlist.insert(insert_child_index, blank)+ insert_child_index += 1++ entry = etree.Element("entry")+ entry.set("producer", producer.get("id"))+ if in_point:+ entry.set("in", in_point)+ if out_point:+ entry.set("out", out_point)+ playlist.insert(insert_child_index, entry)++ if trailing_blank_frames:+ blank = etree.Element("blank")+ blank.set("length", frames_to_timecode(trailing_blank_frames, fps_num, fps_den))+ playlist.insert(insert_child_index + 1, blank)+ else:+ entry = mlt_xml.add_entry_to_playlist(+ playlist, producer.get("id"),+ in_point=in_point,+ out_point=out_point,+ position=position,+ )return {"action": "add_clip",@@ -192,6 +270,7 @@ def add_clip(session: Session, resource: str, track_index: int,"in": in_point,"out": out_point,"position": position,+ "at_time": at_time,"caption": caption or os.path.basename(resource),}diff --git a/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.py b/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.pyindex 39d06e7d4..643d684ed 100755--- a/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.py+++ b/shotcut/agent-harness/cli_anything/shotcut/shotcut_cli.py@@ -354,13 +354,14 @@ def timeline_remove_track(track_index):@click.option("--in", "in_point", default=None, help="In point (timecode)")@click.option("--out", "out_point", default=None, help="Out point (timecode)")@click.option("--position", default=None, type=int, help="Insert position (clip index)")[email protected]("--at", "at_time", default=None, help="Absolute timeline start time")@click.option("--caption", default=None, help="Display name")@handle_error-def timeline_add_clip(resource, track_index, in_point, out_point, position, caption):+def timeline_add_clip(resource, track_index, in_point, out_point, position, at_time, caption):"""Add a media clip to a track."""session = get_session()result = tl_mod.add_clip(session, resource, track_index,- in_point, out_point, position, caption)+ in_point, out_point, position, at_time, caption)output(result, f"Added clip to track {track_index}")@@ -522,7 +523,6 @@ def filter_add(filter_name, track_index, clip_index, params):param_dict if param_dict else None)output(result, f"Added filter '{filter_name}'")-@filter_group.command("remove")@click.argument("filter_index", type=int)@click.option("--track", "track_index", default=None, type=int,@@ -570,6 +570,70 @@ def filter_list(track_index, clip_index):output(result, f"Filters on {target}:")+@filter_group.command("volume-envelope")[email protected]("--track", "track_index", default=None, type=int,+ help="Track index (omit for global)")[email protected]("--clip", "clip_index", default=None, type=int,+ help="Clip index on track (omit for track-level)")[email protected]("--point", "points", multiple=True, required=True,+ help="Envelope point as TIME=LEVEL (repeatable)")+@handle_error+def filter_volume_envelope(track_index, clip_index, points):+ """Create or update a keyframed volume envelope."""+ session = get_session()+ parsed = []+ for point in points:+ if "=" not in point:+ raise ValueError(f"Invalid point format: {point!r}. Use TIME=LEVEL")+ timecode, level = point.split("=", 1)+ parsed.append((timecode, level))+ result = filt_mod.set_volume_envelope(+ session,+ parsed,+ track_index=track_index,+ clip_index=clip_index,+ )+ output(result, "Updated volume envelope")+++@filter_group.command("duck")[email protected]("--track", "track_index", default=None, type=int,+ help="Track index (omit for global)")[email protected]("--clip", "clip_index", default=None, type=int,+ help="Clip index on track (omit for track-level)")[email protected]("--window", "windows", multiple=True, required=True,+ help="Ducking window as START:END (repeatable)")[email protected]("--normal", "normal_level", default=1.0, show_default=True, type=float,+ help="Volume outside ducking windows")[email protected]("--duck", "duck_level", default=0.25, show_default=True, type=float,+ help="Volume inside ducking windows")[email protected]("--attack", default="00:00:00.150", show_default=True,+ help="Fade-down duration before each window")[email protected]("--release", default="00:00:00.250", show_default=True,+ help="Fade-up duration after each window")+@handle_error+def filter_duck(track_index, clip_index, windows, normal_level, duck_level, attack, release):+ """Apply a simple ducking envelope over one or more windows."""+ session = get_session()+ parsed = []+ for window in windows:+ if ":" not in window:+ raise ValueError(f"Invalid window format: {window!r}. Use START:END")+ start, end = window.rsplit(":", 1)+ parsed.append((start, end))+ result = filt_mod.duck_volume(+ session,+ parsed,+ track_index=track_index,+ clip_index=clip_index,+ normal_level=normal_level,+ duck_level=duck_level,+ attack=attack,+ release=release,+ )+ output(result, "Applied ducking envelope")++# ============================================================================# Media commands# ============================================================================@@ -925,7 +989,7 @@ def _run_repl(s: Session, skin):"tracks": "List timeline tracks","show": "Show timeline overview","add-track <video|audio> [name]": "Add a track",- "add-clip <file> <track> [in] [out]": "Add clip to track",+ "add-clip <file> <track> [in] [out] [--at tc]": "Add clip to track","clips <track>": "List clips on a track","remove-clip <track> <clip>": "Remove a clip","trim <track> <clip> [--in tc] [--out tc]": "Trim a clip",@@ -934,6 +998,8 @@ def _run_repl(s: Session, skin):"filters [--track n] [--clip n]": "List filters on target","remove-filter <idx> [--track n] [--clip n]": "Remove a filter","set-filter <idx> <param> <value> [--track n] [--clip n]": "Set filter param",+ "volume-envelope [--track n] [--clip n] TIME=LEVEL ...": "Set a keyframed volume envelope",+ "duck [--track n] [--clip n] START:END ...": "Apply ducking across timeline windows","filter-info <name>": "Show filter details","list-filters [video|audio]": "List available filters","media": "List media in project",@@ -1025,14 +1091,22 @@ def _run_repl(s: Session, skin):output(result, f"Added {ttype} track")elif cmd == "add-clip":+ at_time = None+ if "--at" in args:+ at_index = args.index("--at")+ if at_index + 1 >= len(args):+ click.echo("Usage: add-clip <file> <track> [in] [out] [--at tc]")+ continue+ at_time = args[at_index + 1]+ args = args[:at_index] + args[at_index + 2:]if len(args) < 2:- click.echo("Usage: add-clip <file> <track> [in] [out]")+ click.echo("Usage: add-clip <file> <track> [in] [out] [--at tc]")continueresource = args[0]track = int(args[1])in_pt = args[2] if len(args) > 2 else Noneout_pt = args[3] if len(args) > 3 else None- result = tl_mod.add_clip(s, resource, track, in_pt, out_pt)+ result = tl_mod.add_clip(s, resource, track, in_pt, out_pt, at_time=at_time)output(result, f"Added clip to track {track}")elif cmd == "clips":@@ -1162,6 +1236,79 @@ def _run_repl(s: Session, skin):track_idx, clip_idx)output(result)+ elif cmd == "volume-envelope":+ track_idx = None+ clip_idx = None+ points = []+ i = 0+ while i < len(args):+ if args[i] == "--track" and i + 1 < len(args):+ track_idx = int(args[i + 1])+ i += 2+ elif args[i] == "--clip" and i + 1 < len(args):+ clip_idx = int(args[i + 1])+ i += 2+ else:+ if "=" not in args[i]:+ click.echo("Usage: volume-envelope [--track n] [--clip n] TIME=LEVEL ...")+ break+ timecode, level = args[i].split("=", 1)+ points.append((timecode, level))+ i += 1+ else:+ result = filt_mod.set_volume_envelope(+ s, points, track_index=track_idx, clip_index=clip_idx+ )+ output(result)++ elif cmd == "duck":+ track_idx = None+ clip_idx = None+ windows = []+ normal_level = 1.0+ duck_level = 0.25+ attack = "00:00:00.150"+ release = "00:00:00.250"+ i = 0+ while i < len(args):+ if args[i] == "--track" and i + 1 < len(args):+ track_idx = int(args[i + 1])+ i += 2+ elif args[i] == "--clip" and i + 1 < len(args):+ clip_idx = int(args[i + 1])+ i += 2+ elif args[i] == "--normal" and i + 1 < len(args):+ normal_level = float(args[i + 1])+ i += 2+ elif args[i] == "--duck" and i + 1 < len(args):+ duck_level = float(args[i + 1])+ i += 2+ elif args[i] == "--attack" and i + 1 < len(args):+ attack = args[i + 1]+ i += 2+ elif args[i] == "--release" and i + 1 < len(args):+ release = args[i + 1]+ i += 2+ else:+ if ":" not in args[i]:+ click.echo("Usage: duck [--track n] [--clip n] START:END ...")+ break+ start, end = args[i].rsplit(":", 1)+ windows.append((start, end))+ i += 1+ else:+ result = filt_mod.duck_volume(+ s,+ windows,+ track_index=track_idx,+ clip_index=clip_idx,+ normal_level=normal_level,+ duck_level=duck_level,+ attack=attack,+ release=release,+ )+ output(result)+elif cmd == "filter-info":if not args:click.echo("Usage: filter-info <name>")diff --git a/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py b/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.pyindex 14ff6c180..0123972f5 100644--- a/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py+++ b/shotcut/agent-harness/cli_anything/shotcut/tests/test_core.py@@ -17,6 +17,7 @@ from cli_anything.shotcut.core import media as media_modfrom cli_anything.shotcut.core import export as export_modfrom cli_anything.shotcut.core import transitions as trans_modfrom cli_anything.shotcut.core import compositing as comp_mod+from cli_anything.shotcut.core.export import _build_volume_expressionfrom cli_anything.shotcut.utils.time import (timecode_to_frames, frames_to_timecode, parse_time_input,frames_to_seconds, seconds_to_frames,@@ -365,6 +366,62 @@ class TestTimeline:finally:os.unlink(tmpfile)+ def test_add_clip_at_absolute_time(self):+ s = self._make_session()+ tl_mod.add_track(s, "video")++ with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:+ f.write(b"dummy")+ tmpfile = f.name++ try:+ result = tl_mod.add_clip(+ s,+ tmpfile,+ 1,+ in_point="00:00:00.000",+ out_point="00:00:02.000",+ at_time="00:00:05.000",+ )+ assert result["at_time"] == "00:00:05.000"++ clips = tl_mod.list_clips(s, 1)+ assert clips[0]["type"] == "blank"+ assert abs(+ parse_time_input(clips[0]["length"]) - parse_time_input("00:00:05.000")+ ) <= 1+ assert clips[1]["clip_index"] == 0+ finally:+ os.unlink(tmpfile)++ def test_add_clip_at_absolute_time_rejects_overlap(self):+ s = self._make_session()+ tl_mod.add_track(s, "video")++ with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:+ f.write(b"dummy")+ tmpfile = f.name++ try:+ tl_mod.add_clip(+ s,+ tmpfile,+ 1,+ in_point="00:00:00.000",+ out_point="00:00:05.000",+ )+ with pytest.raises(RuntimeError, match="overlaps an existing clip"):+ tl_mod.add_clip(+ s,+ tmpfile,+ 1,+ in_point="00:00:00.000",+ out_point="00:00:02.000",+ at_time="00:00:03.000",+ )+ finally:+ os.unlink(tmpfile)+def test_remove_clip(self):s = self._make_session()tl_mod.add_track(s, "video")@@ -483,6 +540,54 @@ class TestTimeline:result = tl_mod.add_blank(s, 1, "00:00:02.000")assert result["action"] == "add_blank"+ def test_add_clip_at_time_inserts_gap(self):+ s = self._make_session()+ tl_mod.add_track(s, "video")+ with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:+ f.write(b"dummy")+ tmpfile = f.name+ try:+ result = tl_mod.add_clip(+ s,+ tmpfile,+ 1,+ in_point="00:00:00.000",+ out_point="00:00:02.000",+ at_time="00:00:08.000",+ )+ assert result["at_time"] == "00:00:08.000"+ clips = tl_mod.list_clips(s, 1)+ assert clips[0]["type"] == "blank"+ assert clips[1]["clip_index"] == 0+ finally:+ os.unlink(tmpfile)++ def test_add_clip_at_time_rejects_overlap(self):+ s = self._make_session()+ tl_mod.add_track(s, "video")+ with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:+ f.write(b"dummy")+ tmpfile = f.name+ try:+ tl_mod.add_clip(+ s,+ tmpfile,+ 1,+ in_point="00:00:00.000",+ out_point="00:00:05.000",+ )+ with pytest.raises(RuntimeError, match="overlaps an existing clip"):+ tl_mod.add_clip(+ s,+ tmpfile,+ 1,+ in_point="00:00:00.000",+ out_point="00:00:01.000",+ at_time="00:00:02.000",+ )+ finally:+ os.unlink(tmpfile)+def test_undo_add_track(self):s = self._make_session()initial = len(tl_mod.list_tracks(s))@@ -598,6 +703,37 @@ class TestFilters:finally:os.unlink(tmpfile)+ def test_set_volume_envelope(self):+ s, tmpfile = self._make_session_with_clip()+ try:+ result = filt_mod.set_volume_envelope(+ s,+ [("00:00:00.000", "1.0"), ("00:00:03.000", "0.25"), ("00:00:04.000", "1.0")],+ track_index=1,+ )+ assert result["action"] == "set_volume_envelope"+ filters = filt_mod.list_filters(s, track_index=1)+ assert filters[0]["service"] == "volume"+ assert filters[0]["params"]["level"].count("=") == 3+ finally:+ os.unlink(tmpfile)++ def test_duck_volume(self):+ s, tmpfile = self._make_session_with_clip()+ try:+ result = filt_mod.duck_volume(+ s,+ [("00:00:01.000", "00:00:02.000")],+ track_index=1,+ normal_level=1.0,+ duck_level=0.3,+ )+ assert result["action"] == "duck_volume"+ filters = filt_mod.list_filters(s, track_index=1)+ assert "0.3" in filters[0]["params"]["level"]+ finally:+ os.unlink(tmpfile)+# ============================================================================# Media module@@ -658,6 +794,15 @@ class TestExport:def test_list_presets(self):result = export_mod.list_presets()assert len(result) > 0++ def test_build_volume_expression_from_keyframes(self):+ expr = _build_volume_expression("00:00:00.000=1;00:00:02.000=0.3;00:00:03.000=1")+ assert expr is not None+ assert expr.startswith("volume='if(")+ assert "0.300000" in expr++ def test_list_presets_contains_defaults(self):+ result = export_mod.list_presets()names = [p["name"] for p in result]assert "default" in namesassert "h264-high" in namesdiff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/README.md b/videocaptioner/agent-harness/cli_anything/videocaptioner/README.mdindex 0a18e9be5..2a969d559 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/README.md+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/README.md@@ -1,6 +1,7 @@# VideoCaptioner CLI-AI-powered video captioning tool with beautiful customizable subtitle styles.+AI-powered video captioning tool that mirrors the stable `videocaptioner`+backend surface.## Architecture@@ -13,15 +14,18 @@ AI-powered video captioning tool with beautiful customizable subtitle styles.```Audio/Video → ASR Transcription → Subtitle Splitting → LLM Optimization → Translation → Video Synthesis- (bijian/whisper) (semantic) (fix errors) (38 languages) (styled subtitles)+ (bijian/whisper) (semantic) (fix errors) (38 languages) (video synthesis)```## Install```bash-pip install videocaptioner click prompt-toolkit+python3.12 -m pip install videocaptioner click prompt-toolkit```+VideoCaptioner `1.4.1` currently declares `Requires-Python: >=3.10,<3.13`.+Use Python `3.10`-`3.12`; Python `3.13+` is not a safe default for this stack.+## Run```bash@@ -34,12 +38,19 @@ cli-anything-videocaptioner transcribe video.mp4 --asr bijian -o output.srt# Translate existing subtitlescli-anything-videocaptioner subtitle input.srt --translator google --target-language ja-# Burn subtitles with anime style-cli-anything-videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard --style anime+# Burn subtitles into a video+cli-anything-videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard++# Block a hard-burn if the subtitle file drifted too far from the approved script+cli-anything-videocaptioner synthesize video.mp4 -s sub.srt \+ --subtitle-mode hard \+ --review-script approved_script.txt-# Custom style (red outline, large font)-cli-anything-videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard \- --style-override '{"outline_color": "#ff0000", "font_size": 48}'+# Review a subtitle file and render a single preview frame before final export+cli-anything-videocaptioner review sub.srt \+ --script approved_script.txt \+ --preview-video video.mp4 \+ --preview-output review_5s.png# JSON output mode (for agent consumption)cli-anything-videocaptioner --json transcribe video.mp4 --asr bijian@@ -48,17 +59,15 @@ cli-anything-videocaptioner --json transcribe video.mp4 --asr bijiancli-anything-videocaptioner```-## Subtitle Styles--Two rendering modes for beautiful subtitles:--**ASS mode** — traditional outline/shadow:-- Presets: `default` (white+black), `anime` (warm+orange), `vertical` (portrait videos)+## Backend compatibility-**Rounded mode** — modern rounded background boxes:-- Preset: `rounded` (dark text on semi-transparent background)+The harness intentionally tracks the stable `videocaptioner` backend interface.+As of backend `1.4.x`, `synthesize` exposes subtitle mode, quality, and output+path controls, while styling is driven by the subtitle asset itself rather than+runtime style flags.-Fully customizable via `--style-override` with inline JSON.+Use the `review` command, or `synthesize --review-script`, to catch subtitle+drift before hard-burning a permanent delivery.## Coverage@@ -66,6 +75,6 @@ Fully customizable via `--style-override` with inline JSON.|---------|----------|| Transcription | 4 ASR engines, auto language detection, word timestamps || Subtitle Processing | Split + optimize + translate, 3 translators, 38 languages |-| Video Synthesis | Soft/hard subtitles, 4 quality levels, 5 style presets |-| Styles | ASS outline + rounded background, inline JSON customization |+| Video Synthesis | Soft/hard subtitles, 4 quality levels |+| Styles | Backend-version dependent; the harness reports availability || Utilities | Config management, style listing, video download |diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/core/pipeline.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/core/pipeline.pyindex c1b802820..341bde9bf 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/core/pipeline.py+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/core/pipeline.py@@ -64,12 +64,6 @@ def process(args += ["--target-language", target_language]if layout:args += ["--layout", layout]- if style:- args += ["--style", style]- if style_override:- args += ["--style-override", style_override]- if render_mode:- args += ["--render-mode", render_mode]if no_optimize:args.append("--no-optimize")if no_translate:diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/core/synthesize.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/core/synthesize.pyindex 330459b60..982cc436a 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/core/synthesize.py+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/core/synthesize.py@@ -1,6 +1,7 @@"""Video synthesis — burn subtitles into video with customizable styles."""from cli_anything.videocaptioner.utils.vc_backend import run_quiet+from cli_anything.videocaptioner.core.review import ensure_subtitle_consistencydef synthesize(@@ -14,6 +15,8 @@ def synthesize(style: str | None = None,style_override: str | None = None,font_file: str | None = None,+ review_script: str | None = None,+ max_script_diff_ratio: float = 0.12,) -> str:"""Burn subtitles into a video file.@@ -23,27 +26,31 @@ def synthesize(output_path: Output video file path.subtitle_mode: 'soft' (embedded track) or 'hard' (burned in).quality: Video quality (ultra, high, medium, low).- layout: Bilingual layout.- render_mode: 'ass' (outline/shadow) or 'rounded' (background boxes).- style: Style preset name (default, anime, vertical, rounded).- style_override: Inline JSON to override style fields.- font_file: Custom font file path (.ttf/.otf).+ layout: Deprecated compatibility arg; ignored because backend 1.4.x+ does not support synthesize-time layout control.+ render_mode: Deprecated compatibility arg; ignored because backend 1.4.x+ does not support synthesize-time style selection.+ style: Deprecated compatibility arg; ignored because backend 1.4.x does+ not support synthesize-time style presets.+ style_override: Deprecated compatibility arg; ignored because backend+ 1.4.x does not support synthesize-time style overrides.+ font_file: Deprecated compatibility arg; ignored because backend 1.4.x+ does not support synthesize-time custom fonts.+ review_script: Optional reference script/transcript. When supplied, the+ harness checks subtitle/script drift before final synthesize.+ max_script_diff_ratio: Maximum allowed normalized subtitle/script drift.Returns:Output video file path."""+ if review_script:+ ensure_subtitle_consistency(+ subtitle_path,+ review_script,+ max_diff_ratio=max_script_diff_ratio,+ )args = ["synthesize", video_path, "-s", subtitle_path,"--subtitle-mode", subtitle_mode, "--quality", quality]if output_path:args += ["-o", output_path]- if layout:- args += ["--layout", layout]- if render_mode:- args += ["--render-mode", render_mode]- if style:- args += ["--style", style]- if style_override:- args += ["--style-override", style_override]- if font_file:- args += ["--font-file", font_file]return run_quiet(args)diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/skills/SKILL.md b/videocaptioner/agent-harness/cli_anything/videocaptioner/skills/SKILL.mdindex fcf625b7a..d1a01a87e 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/skills/SKILL.md+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/skills/SKILL.md@@ -2,12 +2,12 @@name: >-cli-anything-videocaptionerdescription: >-- AI-powered video captioning — transcribe speech, optimize/translate subtitles, burn into video with beautiful customizable styles (ASS outline or rounded background). Free ASR and translation included.+ AI-powered video captioning — transcribe speech, optimize/translate subtitles, and burn them into video via the stable VideoCaptioner backend. Free ASR and translation included.---# cli-anything-videocaptioner-AI-powered video captioning tool. Transcribe speech → optimize subtitles → translate → burn into video with beautiful styles.+AI-powered video captioning tool. Transcribe speech → optimize subtitles → translate → burn into video.## Installation@@ -16,7 +16,7 @@ pip install cli-anything-videocaptioner```**Prerequisites:**-- Python 3.10++- Python 3.10-3.12 (`videocaptioner` 1.4.1 requires `>=3.10,<3.13`)- `videocaptioner` must be installed (`pip install videocaptioner`)- FFmpeg required for video synthesis@@ -40,6 +40,17 @@ cli-anything-videocaptioner subtitle input.srt --translator bing --target-langua# Full pipeline: transcribe → translate → burn subtitlescli-anything-videocaptioner process video.mp4 --asr bijian --translator bing --target-language en --subtitle-mode hard+# Review subtitle/script consistency before a final hard-burn+cli-anything-videocaptioner synthesize video.mp4 -s subtitles.srt \+ --subtitle-mode hard \+ --review-script approved_script.txt++# Render a one-frame subtitle preview for review+cli-anything-videocaptioner review subtitles.srt \+ --script approved_script.txt \+ --preview-video video.mp4 \+ --preview-output review_5s.png+# JSON output (for agent consumption)cli-anything-videocaptioner --json transcribe video.mp4 --asr bijian```@@ -72,21 +83,28 @@ subtitle <input.srt> [--translator llm|bing|google] [--target-language CODE] [--### synthesize — Burn subtitles into video```-synthesize <video> -s <subtitle> [--subtitle-mode soft|hard] [--quality ultra|high|medium|low] [--style NAME] [--style-override JSON] [--render-mode ass|rounded] [--font-file PATH] [-o PATH]+synthesize <video> -s <subtitle> [--subtitle-mode soft|hard] [--quality ultra|high|medium|low] [-o PATH]```-- **ASS mode**: Outline/shadow style with presets (default, anime, vertical)-- **Rounded mode**: Modern rounded background boxes-- Customizable via `--style-override '{"outline_color": "#ff0000"}'`+- Mirrors the stable backend synthesize surface+- Subtitle look is controlled by the subtitle asset/backend version, not extra harness flags### process — Full pipeline```-process <input> [--asr ...] [--translator ...] [--target-language ...] [--subtitle-mode ...] [--style ...] [--no-optimize] [--no-translate] [--no-synthesize] [-o PATH]+process <input> [--asr ...] [--translator ...] [--target-language ...] [--subtitle-mode ...] [--layout ...] [--no-optimize] [--no-translate] [--no-synthesize] [-o PATH]+```++### review — Consistency check and preview+```+review <input.srt|input.ass> [--script PATH] [--max-diff-ratio FLOAT] [--preview-video PATH] [--preview-at TC] [--preview-output PATH]```+- Detects subtitle/script drift before a hard-burn+- Can render a single review frame instead of producing a full final video### styles — List style presets```styles```+- Reports whether the installed backend exposes preset styling support### config — Manage settings```@@ -107,16 +125,10 @@ cli-anything-videocaptioner --json transcribe video.mp4 --asr bijian# {"output_path": "/path/to/output.srt"}```-## Style Presets--| Name | Mode | Description |-|------|------|-------------|-| `default` | ASS | White text, black outline — clean and universal |-| `anime` | ASS | Warm white, orange outline — anime/cartoon style |-| `vertical` | ASS | High bottom margin — for portrait/vertical videos |-| `rounded` | Rounded | Dark text on semi-transparent rounded background |+## Backend Notes-Customize any field: `--style-override '{"font_size": 48, "outline_color": "#ff0000"}'`+- The upstream backend currently requires Python `>=3.10,<3.13`; prefer Python `3.12` for matrix runs.+- Advanced synthesize-time style flags are backend-version dependent. Use `styles` to check whether the installed backend exposes them.## Target Languagesdiff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_core.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_core.pyindex 91177f1a0..965af264d 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_core.py+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_core.py@@ -2,6 +2,7 @@import pytestfrom unittest.mock import patch, MagicMock+import sysclass TestTranscribe:@@ -59,28 +60,48 @@ class TestSynthesize:assert "soft" in mock_run.call_args[0][0]@patch("cli_anything.videocaptioner.core.synthesize.run_quiet", return_value="/tmp/o.mp4")- def test_hard_style(self, mock_run):+ def test_hard_quality_output(self, mock_run):from cli_anything.videocaptioner.core.synthesize import synthesize- synthesize("v.mp4", "s.srt", subtitle_mode="hard", style="anime", quality="high")+ synthesize("v.mp4", "s.srt", subtitle_mode="hard", quality="high", output_path="/tmp/o.mp4")a = mock_run.call_args[0][0]- assert "hard" in a and "anime" in a and "high" in a+ assert "hard" in a and "high" in a and "/tmp/o.mp4" in a@patch("cli_anything.videocaptioner.core.synthesize.run_quiet", return_value="/tmp/o.mp4")- def test_rounded(self, mock_run):+ def test_compatibility_args_ignored(self, mock_run):from cli_anything.videocaptioner.core.synthesize import synthesize- synthesize("v.mp4", "s.srt", subtitle_mode="hard", render_mode="rounded",- style_override='{"bg_color":"#000000cc"}')+ synthesize(+ "v.mp4",+ "s.srt",+ subtitle_mode="hard",+ layout="target-above",+ render_mode="rounded",+ style="anime",+ style_override='{"bg_color":"#000000cc"}',+ font_file="/tmp/font.ttf",+ )a = mock_run.call_args[0][0]- assert "rounded" in a and "#000000cc" in str(a)+ assert "--layout" not in a+ assert "--render-mode" not in a+ assert "--style" not in a+ assert "--style-override" not in a+ assert "--font-file" not in a++ @patch("cli_anything.videocaptioner.core.synthesize.ensure_subtitle_consistency")+ @patch("cli_anything.videocaptioner.core.synthesize.run_quiet", return_value="/tmp/o.mp4")+ def test_review_script_blocks_before_burn(self, mock_run, mock_review):+ from cli_anything.videocaptioner.core.synthesize import synthesize+ synthesize("v.mp4", "s.srt", review_script="approved.txt", max_script_diff_ratio=0.2)+ mock_review.assert_called_once_with("s.srt", "approved.txt", max_diff_ratio=0.2)+ assert mock_run.calledclass TestPipeline:@patch("cli_anything.videocaptioner.core.pipeline.run_quiet", return_value="/tmp/o.mp4")def test_full(self, mock_run):from cli_anything.videocaptioner.core.pipeline import process- process("v.mp4", translator="bing", target_language="en", style="anime")+ process("v.mp4", translator="bing", target_language="en", layout="target-above")a = mock_run.call_args[0][0]- assert "process" in a and "bing" in a and "anime" in a+ assert "process" in a and "bing" in a and "target-above" in a@patch("cli_anything.videocaptioner.core.pipeline.run_quiet", return_value="/tmp/o.srt")def test_no_synth(self, mock_run):@@ -88,16 +109,27 @@ class TestPipeline:process("v.mp4", no_synthesize=True)assert "--no-synthesize" in mock_run.call_args[0][0]+ @patch("cli_anything.videocaptioner.core.pipeline.run_quiet", return_value="/tmp/o.mp4")+ def test_compatibility_style_args_ignored(self, mock_run):+ from cli_anything.videocaptioner.core.pipeline import process+ process("v.mp4", style="anime", style_override="{}", render_mode="rounded")+ a = mock_run.call_args[0][0]+ assert "--style" not in a+ assert "--style-override" not in a+ assert "--render-mode" not in a+class TestBackend:+ @patch("cli_anything.videocaptioner.utils.vc_backend._find_vc", return_value="/usr/bin/videocaptioner")@patch("subprocess.run")- def test_success(self, mock_sub):+ def test_success(self, mock_sub, _mock_find):mock_sub.return_value = MagicMock(returncode=0, stdout="/tmp/o.srt\n", stderr="")from cli_anything.videocaptioner.utils.vc_backend import run_quietassert run_quiet(["transcribe", "v.mp4"]) == "/tmp/o.srt"+ @patch("cli_anything.videocaptioner.utils.vc_backend._find_vc", return_value="/usr/bin/videocaptioner")@patch("subprocess.run")- def test_failure(self, mock_sub):+ def test_failure(self, mock_sub, _mock_find):mock_sub.return_value = MagicMock(returncode=5, stdout="", stderr="Error: fail")from cli_anything.videocaptioner.utils.vc_backend import run_quietwith pytest.raises(RuntimeError, match="fail"):@@ -108,3 +140,59 @@ class TestBackend:from cli_anything.videocaptioner.utils.vc_backend import _find_vcwith pytest.raises(RuntimeError, match="not found"):_find_vc()++ @patch("cli_anything.videocaptioner.utils.vc_backend.has_subcommand", return_value=False)+ @patch("cli_anything.videocaptioner.utils.vc_backend.get_version", return_value="videocaptioner 1.4.1")+ def test_get_styles_fallback(self, _mock_version, _mock_has_subcommand):+ from cli_anything.videocaptioner.utils.vc_backend import get_styles+ styles = get_styles()+ assert "does not expose a 'style' subcommand" in styles++ def test_runtime_guidance(self):+ from cli_anything.videocaptioner.utils.vc_backend import get_runtime_guidance+ guidance = get_runtime_guidance()+ assert guidance["upstream_requires_python"] == ">=3.10,<3.13"+ assert guidance["python_runtime"].startswith(f"{sys.version_info.major}.{sys.version_info.minor}")+++class TestReview:+ def test_review_report_passes_for_matching_script(self, tmp_path):+ subtitle_path = tmp_path / "matching.srt"+ script_path = tmp_path / "matching.txt"+ subtitle_path.write_text("1\n00:00:00,000 --> 00:00:01,000\nDark mode ships today.\n", encoding="utf-8")+ script_path.write_text("Dark mode ships today.", encoding="utf-8")++ from cli_anything.videocaptioner.core.review import build_review_report+ report = build_review_report(str(subtitle_path), script_path=str(script_path))+ assert report["status"] == "pass"+ assert report["diff_ratio"] == 0.0++ def test_review_report_flags_mismatch(self, tmp_path):+ subtitle_path = tmp_path / "mismatch.srt"+ script_path = tmp_path / "mismatch.txt"+ subtitle_path.write_text("1\n00:00:00,000 --> 00:00:01,000\nship stark mode today\n", encoding="utf-8")+ script_path.write_text("ships dark mode today", encoding="utf-8")++ from cli_anything.videocaptioner.core.review import ensure_subtitle_consistency+ with pytest.raises(RuntimeError, match="Subtitle/script review failed"):+ ensure_subtitle_consistency(str(subtitle_path), str(script_path), max_diff_ratio=0.1)++ @patch("shutil.which", return_value="/usr/bin/ffmpeg")+ @patch("subprocess.run")+ def test_render_preview_frame(self, mock_run, _mock_which, tmp_path):+ mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")+ video_path = tmp_path / "video.mp4"+ subtitle_path = tmp_path / "sub.srt"+ output_path = tmp_path / "preview.png"+ video_path.write_bytes(b"video")+ subtitle_path.write_text("1\n00:00:00,000 --> 00:00:01,000\nhello\n", encoding="utf-8")++ from cli_anything.videocaptioner.core.review import render_preview_frame+ result = render_preview_frame(+ str(video_path),+ str(subtitle_path),+ at="00:00:05.000",+ output_path=str(output_path),+ )+ assert result == str(output_path)+ assert "-vf" in mock_run.call_args[0][0]diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_full_e2e.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_full_e2e.pyindex 962fb8651..77f4d6f9d 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_full_e2e.py+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_full_e2e.py@@ -34,15 +34,6 @@ class TestCLIEntryPoint:assert result.returncode == 0assert "videocaptioner" in result.stdout- def test_style_list(self):- result = subprocess.run(- ["videocaptioner", "style"],- capture_output=True, text=True, timeout=10,- )- assert result.returncode == 0- assert "default" in result.stdout- assert "anime" in result.stdout or "rounded" in result.stdout-def test_config_show(self):result = subprocess.run(["videocaptioner", "config", "show"],@@ -101,4 +92,4 @@ class TestBackendIntegration:def test_get_styles(self):from cli_anything.videocaptioner.utils.vc_backend import get_stylesstyles = get_styles()- assert "default" in styles+ assert stylesdiff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/utils/vc_backend.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/utils/vc_backend.pyindex 1677cb36c..ca61ff2c0 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/utils/vc_backend.py+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/utils/vc_backend.py@@ -8,17 +8,34 @@ work to the production-tested videocaptioner package.import jsonimport subprocessimport shutil+import sysfrom pathlib import Pathfrom typing import Any+from functools import lru_cache++UPSTREAM_REQUIRES_PYTHON = ">=3.10,<3.13"+UPSTREAM_COMPATIBLE_MINORS = "3.10-3.12"+++def get_runtime_guidance() -> dict[str, str]:+ """Return install/runtime guidance for the upstream backend."""+ return {+ "python_runtime": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",+ "upstream_requires_python": UPSTREAM_REQUIRES_PYTHON,+ "recommended_python": UPSTREAM_COMPATIBLE_MINORS,+ }def _find_vc() -> str:"""Locate the videocaptioner binary."""path = shutil.which("videocaptioner")if not path:+ guidance = get_runtime_guidance()raise RuntimeError("videocaptioner not found on PATH. "- "Install with: pip install videocaptioner"+ "Install with: pip install videocaptioner. "+ f"Upstream videocaptioner 1.4.1 requires Python {guidance['upstream_requires_python']} "+ f"(use Python {guidance['recommended_python']}).")return path@@ -81,7 +98,32 @@ def get_config() -> str:return result["stdout"]+@lru_cache(maxsize=None)+def get_command_help(command: str) -> str:+ """Return backend help text for a subcommand, or an empty string."""+ result = run([command, "--help"])+ if result["exit_code"] != 0:+ return ""+ return result["stdout"]+++@lru_cache(maxsize=None)+def has_subcommand(command: str) -> bool:+ """Check whether the installed backend exposes a subcommand."""+ result = run(["--help"])+ if result["exit_code"] != 0:+ return False+ return command in result["stdout"]++def get_styles() -> str:- """Get available subtitle styles."""+ """Get available subtitle styles, or explain when unsupported."""+ if not has_subcommand("style"):+ version = get_version()+ return (+ f"{version}\n"+ "Installed backend does not expose a 'style' subcommand. "+ "Style presets are not available in this VideoCaptioner version."+ )result = run(["style"])return result["stdout"]diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/videocaptioner_cli.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/videocaptioner_cli.pyindex ef7ef7ab8..be4330fe0 100644--- a/videocaptioner/agent-harness/cli_anything/videocaptioner/videocaptioner_cli.py+++ b/videocaptioner/agent-harness/cli_anything/videocaptioner/videocaptioner_cli.py@@ -2,12 +2,12 @@"""VideoCaptioner CLI — AI-powered video captioning from the command line.Transcribe speech, optimize and translate subtitles, then burn them into-video with beautiful customizable styles (ASS outline or rounded background).+video via the production VideoCaptioner backend.Usage:cli-anything-videocaptioner transcribe video.mp4 --asr bijiancli-anything-videocaptioner subtitle input.srt --translator bing --target-language en- cli-anything-videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hard --style anime+ cli-anything-videocaptioner synthesize video.mp4 -s sub.srt --subtitle-mode hardcli-anything-videocaptioner process video.mp4 --asr bijian --translator bing --target-language jacli-anything-videocaptioner --json transcribe video.mp4 --asr bijian"""@@ -23,6 +23,7 @@ from cli_anything.videocaptioner.core import transcribe as transcribe_modfrom cli_anything.videocaptioner.core import subtitle as subtitle_modfrom cli_anything.videocaptioner.core import synthesize as synthesize_modfrom cli_anything.videocaptioner.core import pipeline as pipeline_mod+from cli_anything.videocaptioner.core import review as review_mod_json_output = False_repl_mode = False@@ -65,7 +66,8 @@ def cli(ctx, use_json):"""VideoCaptioner CLI — AI-powered video captioning.Transcribe speech, optimize/translate subtitles, burn into video with- beautiful styles. Free ASR (bijian) and translation (Bing/Google) included.+ the stable backend surface. Free ASR (bijian) and translation+ (Bing/Google) included.Run without a subcommand to enter interactive REPL mode."""@@ -150,29 +152,25 @@ def subtitle(input_path, translator, target_language, fmt, output_path, layout,@click.option("--quality", type=click.Choice(["ultra", "high", "medium", "low"]),default="medium", help="Video quality (ultra=CRF18, high=CRF23, medium=CRF28, low=CRF32)")@click.option("-o", "--output", "output_path", default=None, help="Output video file path")[email protected]("--layout", type=click.Choice(["target-above", "source-above", "target-only", "source-only"]),- default=None, help="Bilingual subtitle layout")[email protected]("--render-mode", type=click.Choice(["ass", "rounded"]),- default=None, help="ass: outline/shadow, rounded: background boxes")[email protected]("--style", default=None, help="Style preset (default, anime, vertical, rounded)")[email protected]("--style-override", default=None, help='Inline JSON, e.g. \'{"outline_color": "#ff0000"}\'')[email protected]("--font-file", default=None, help="Custom font file (.ttf/.otf)")[email protected]("--review-script", default=None,+ help="Reference script/transcript text to verify before synthesize")[email protected]("--max-script-diff-ratio", default=0.12, show_default=True, type=float,+ help="Fail review when subtitle/script drift exceeds this ratio")@handle_errordef synthesize(video_path, subtitle_path, subtitle_mode, quality, output_path,- layout, render_mode, style, style_override, font_file):- """Burn subtitles into video with customizable styles.-- Two rendering modes for beautiful subtitles:- ASS — traditional outline/shadow (presets: default, anime, vertical)- Rounded — modern rounded background boxes+ review_script, max_script_diff_ratio):+ """Burn subtitles into video.- Use 'cli-anything-videocaptioner styles' to see all presets.+ The harness mirrors the backend's stable synthesize surface. Advanced style+ controls are backend-version dependent and are not exposed here unless the+ installed backend supports them. Use --review-script to block a final burn+ when the subtitle asset drifts too far from an approved script."""result_path = synthesize_mod.synthesize(video_path, subtitle_path, output_path=output_path,- subtitle_mode=subtitle_mode, quality=quality, layout=layout,- render_mode=render_mode, style=style, style_override=style_override,- font_file=font_file,+ subtitle_mode=subtitle_mode, quality=quality,+ review_script=review_script,+ max_script_diff_ratio=max_script_diff_ratio,)output({"output_path": result_path}, f"✓ Video synthesis complete → {result_path}")@@ -190,9 +188,6 @@ def synthesize(video_path, subtitle_path, subtitle_mode, quality, output_path,@click.option("--quality", type=click.Choice(["ultra", "high", "medium", "low"]), default="medium")@click.option("-o", "--output", "output_path", default=None, help="Output file or directory path")@click.option("--layout", type=click.Choice(["target-above", "source-above", "target-only", "source-only"]), default=None)[email protected]("--style", default=None, help="Style preset name")[email protected]("--style-override", default=None, help="Inline JSON style override")[email protected]("--render-mode", type=click.Choice(["ass", "rounded"]), default=None)@click.option("--no-optimize", is_flag=True, help="Skip optimization")@click.option("--no-translate", is_flag=True, help="Skip translation")@click.option("--no-split", is_flag=True, help="Skip re-segmentation")@@ -204,7 +199,7 @@ def synthesize(video_path, subtitle_path, subtitle_mode, quality, output_path,@click.option("--model", default=None, help="LLM model name")@handle_errordef process(input_path, asr, language, translator, target_language, subtitle_mode,- quality, output_path, layout, style, style_override, render_mode,+ quality, output_path, layout,no_optimize, no_translate, no_split, no_synthesize, reflect,prompt, api_key, api_base, model):"""Full pipeline: transcribe → optimize → translate → synthesize.@@ -216,7 +211,6 @@ def process(input_path, asr, language, translator, target_language, subtitle_modinput_path, output_path=output_path, asr=asr, language=language,translator=translator, target_language=target_language,subtitle_mode=subtitle_mode, quality=quality, layout=layout,- style=style, style_override=style_override, render_mode=render_mode,no_optimize=no_optimize, no_translate=no_translate, no_split=no_split,no_synthesize=no_synthesize, reflect=reflect, prompt=prompt,api_key=api_key, api_base=api_base, model=model,@@ -228,7 +222,7 @@ def process(input_path, asr, language, translator, target_language, subtitle_mod@cli.command()@handle_errordef styles():- """List available subtitle style presets."""+ """Show subtitle style availability for the installed backend."""result = vc_backend.get_styles()if _json_output:click.echo(json.dumps({"styles": result}))@@ -236,6 +230,31 @@ def styles():click.echo(result)+# ── Review ──────────────────────────────────────────────────────[email protected]("subtitle_path")[email protected]("--script", "script_path", default=None, help="Reference script/transcript text file")[email protected]("--max-diff-ratio", default=0.12, show_default=True, type=float,+ help="Maximum allowed subtitle/script drift")[email protected]("--preview-video", default=None, help="Video file to render a review frame from")[email protected]("--preview-at", default="00:00:05.000", show_default=True,+ help="Timestamp for preview frame generation")[email protected]("--preview-output", default=None, help="Output PNG/JPG path for the review frame")+@handle_error+def review(subtitle_path, script_path, max_diff_ratio, preview_video, preview_at, preview_output):+ """Review subtitle consistency and optionally render a preview frame."""+ report = review_mod.review_subtitles(+ subtitle_path,+ script_path=script_path,+ max_diff_ratio=max_diff_ratio,+ preview_video=preview_video,+ preview_at=preview_at if preview_output else None,+ preview_output=preview_output,+ )+ status_text = report.get("status", "pass").upper()+ output(report, f"✓ Review {status_text}")++# ── Config ──────────────────────────────────────────────────────@cli.group()def config():@@ -289,7 +308,7 @@ def session():def session_status():"""Show VideoCaptioner version and configuration."""version = vc_backend.get_version()- data = {"version": version, "json_output": _json_output}+ data = {"version": version, "json_output": _json_output, **vc_backend.get_runtime_guidance()}output(data, f"VideoCaptioner {version}")@@ -312,6 +331,7 @@ def repl():"transcribe": "Transcribe audio/video to subtitles","subtitle": "Optimize and/or translate subtitles","synthesize": "Burn subtitles into video",+ "review": "Check subtitle/script drift and optionally render a preview frame","process": "Full pipeline (transcribe → translate → synthesize)","styles": "List subtitle style presets","config": "show|set <key> <value>",diff --git a/videocaptioner/agent-harness/setup.py b/videocaptioner/agent-harness/setup.pyindex 2eea09f02..bdc0e1bd7 100644--- a/videocaptioner/agent-harness/setup.py+++ b/videocaptioner/agent-harness/setup.py@@ -26,7 +26,7 @@ setup("Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12",],- python_requires=">=3.10",+ python_requires=">=3.10,<3.13",install_requires=["click>=8.0.0","prompt-toolkit>=3.0.0",