Skip to content

"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.py
index 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(
continue
layer_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.py
index 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", context_settings={"ignore_unknown_options": True, "allow_extra_args": True})
@click.argument("index", type=int)
@click.argument("prop")
[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_error
def 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.py
index 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 os
import sys
import tempfile
import pytest
+from click.testing import CliRunner
sys.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 layer
assert "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.py
index 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.py
index 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_x
obj_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 = line
return elem
elif obj_type == "image":
diff --git a/inkscape/agent-harness/cli_anything/inkscape/core/export.py b/inkscape/agent-harness/cli_anything/inkscape/core/export.py
index 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 shutil
from typing import Dict, Any, List, Optional
from cli_anything.inkscape.core.document import project_to_svg, save_svg
+from cli_anything.inkscape.core.text import layout_text_lines, text_anchor_x
from 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) * sx
y = 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 ImageFont
font = 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_x
diff --git a/inkscape/agent-harness/cli_anything/inkscape/core/text.py b/inkscape/agent-harness/cli_anything/inkscape/core/text.py
index 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 string
style_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_height
if 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.py
index 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_run
if 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 command
ctx.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.py
index 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 os
import sys
import tempfile
import pytest
+from click.testing import CliRunner
sys.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_presets
from 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 style
assert "#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.py
index 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 dB
gain = 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 None
try:
- 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 None
diff --git a/shotcut/agent-harness/cli_anything/shotcut/core/filters.py b/shotcut/agent-harness/cli_anything/shotcut/core/filters.py
index 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 Optional
from lxml import etree
from ..utils import mlt_xml
+from ..utils.time import parse_time_input, frames_to_timecode
from .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 result
diff --git a/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py b/shotcut/agent-harness/cli_anything/shotcut/core/timeline.py
index 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 clip
caption: 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 playlist
playlist = _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.py
index 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]")
continue
resource = args[0]
track = int(args[1])
in_pt = args[2] if len(args) > 2 else None
out_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.py
index 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_mod
from cli_anything.shotcut.core import export as export_mod
from cli_anything.shotcut.core import transitions as trans_mod
from cli_anything.shotcut.core import compositing as comp_mod
+from cli_anything.shotcut.core.export import _build_volume_expression
from 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 names
assert "h264-high" in names
diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/README.md b/videocaptioner/agent-harness/cli_anything/videocaptioner/README.md
index 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 subtitles
cli-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 bijian
cli-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.py
index 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.py
index 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_consistency
def 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.md
index 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-videocaptioner
description: >-
- 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 subtitles
cli-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 Languages
diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_core.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/tests/test_core.py
index 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 pytest
from unittest.mock import patch, MagicMock
+import sys
class 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.called
class 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_quiet
assert 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_quiet
with pytest.raises(RuntimeError, match="fail"):
@@ -108,3 +140,59 @@ class TestBackend:
from cli_anything.videocaptioner.utils.vc_backend import _find_vc
with 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.py
index 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 == 0
assert "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_styles
styles = get_styles()
- assert "default" in styles
+ assert styles
diff --git a/videocaptioner/agent-harness/cli_anything/videocaptioner/utils/vc_backend.py b/videocaptioner/agent-harness/cli_anything/videocaptioner/utils/vc_backend.py
index 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 json
import subprocess
import shutil
+import sys
from pathlib import Path
from 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.py
index 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 bijian
cli-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 hard
cli-anything-videocaptioner process video.mp4 --asr bijian --translator bing --target-language ja
cli-anything-videocaptioner --json transcribe video.mp4 --asr bijian
"""
@@ -23,6 +23,7 @@ from cli_anything.videocaptioner.core import transcribe as transcribe_mod
from cli_anything.videocaptioner.core import subtitle as subtitle_mod
from cli_anything.videocaptioner.core import synthesize as synthesize_mod
from 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_error
def 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_error
def 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_mod
input_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_error
def 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.py
index 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",