@cliptude/cli 0.1.43 → 0.1.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -58,6 +58,7 @@ cliptude script --template "Finance vector weekly" --title "Why index funds win"
58
58
  cliptude voiceover --template "Finance vector weekly" --title "Why index funds win" --script-file script.txt
59
59
  cliptude download-voiceover <job-id> --out narration.mp3
60
60
  cliptude editor <job-id> # editor project id, revision, timeline item ids
61
+ cliptude edit <project-id> --ops '-' <<< '[{"op": "delete", "item_id": "anim-agent_g10"}, {"op": "retime", "item_id": "anim-agent_g11", "start_s": 109.3}]'
61
62
  cliptude agent <project-id> --prompt "Replace this shot with real footage of a TSMC fab" --items clip-1 --tier smart --wait
62
63
  cliptude render <project-id> --wait # new MP4 of the edited timeline
63
64
  cliptude continue <job-id>
@@ -68,7 +69,7 @@ No template yet? `template-create` makes one without the create wizard: pick a `
68
69
 
69
70
  To check the price first, `estimate` (MCP `estimate_credits`, REST `POST /api/v1/jobs/estimate`) takes the same template and prompt/script as `generate` (an upload as `--voiceover-seconds` / `--talking-head-seconds`) and returns the credits the job would need and whether the account has them. It creates and charges nothing.
70
71
 
71
- To revise a finished video, `editor` opens its timeline (item ids, times, text), `agent` asks Cliptude Agent for an edit (it charges agent credits; reference item ids with `--items`), and `render` exports a new MP4. MCP tools: `open_editor_project`, `get_editor_project`, `run_agent`, `get_agent_run`, `cancel_agent_run`, `render_project`, `get_render`.
72
+ To revise a finished video, `editor` opens its timeline (item ids, times, text). `edit <project-id> --ops ops.json` applies exact edits on those ids, free and in one revision: delete, retime, trim, set opacity/volume, set a graphic's props, design or picture (an uploaded `keep` id or https link), mute a graphic's sound, add a graphic, clip or catalog sound effect, set a transition, restyle captions, set library music, its volume or remove it, set the background. `versions` and `restore` undo. `agent` asks Cliptude Agent for open-ended edits that need sourcing or generation (it charges agent credits; reference item ids with `--items`), and `render` exports a new MP4. MCP tools: `open_editor_project`, `get_editor_project`, `edit_timeline`, `list_editor_versions`, `restore_editor_version`, `run_agent`, `get_agent_run`, `cancel_agent_run`, `render_project`, `get_render`.
72
73
 
73
74
  ### Agent-planned videos
74
75
 
@@ -696,6 +696,20 @@ def main(argv: list[str] | None = None) -> None:
696
696
 
697
697
  sub.add_parser("agent-tiers", help="List Cliptude Agent tiers")
698
698
 
699
+ ed = sub.add_parser("edit", help="Apply exact timeline edits (no model call, no credits)")
700
+ ed.add_argument("project_id")
701
+ ed.add_argument("--ops", required=True,
702
+ help="JSON file (or '-' for stdin) with a list of operations, e.g. [{\"op\": \"delete\", \"item_id\": \"...\"}]")
703
+ ed.add_argument("--expected-revision", type=int, default=None,
704
+ help="The revision the item ids were read from; a newer timeline is refused")
705
+
706
+ vs = sub.add_parser("versions", help="List saved versions of an editor project (undo points)")
707
+ vs.add_argument("project_id")
708
+
709
+ rv = sub.add_parser("restore", help="Restore an editor project to a saved version")
710
+ rv.add_argument("project_id")
711
+ rv.add_argument("version_id")
712
+
699
713
  rn = sub.add_parser("render", help="Render an edited project to a new MP4")
700
714
  rn.add_argument("project_id")
701
715
  rn.add_argument("--wait", action="store_true", help="Poll until the render finishes")
@@ -976,6 +990,19 @@ def main(argv: list[str] | None = None) -> None:
976
990
  _print(client.cancel_agent_run(args.project_id, args.run_id))
977
991
  elif args.cmd == "agent-tiers":
978
992
  _print(client.agent_tiers())
993
+ elif args.cmd == "edit":
994
+ raw = sys.stdin.read() if args.ops == "-" else Path(args.ops).read_text(encoding="utf-8")
995
+ try:
996
+ ops = json.loads(raw)
997
+ except ValueError as exc:
998
+ raise CliptudeApiError(f"--ops is not JSON: {exc}")
999
+ if isinstance(ops, dict):
1000
+ ops = ops.get("operations") or []
1001
+ _print(client.edit_timeline(args.project_id, ops, expected_revision=args.expected_revision))
1002
+ elif args.cmd == "versions":
1003
+ _print(client.list_editor_versions(args.project_id))
1004
+ elif args.cmd == "restore":
1005
+ _print(client.restore_editor_version(args.project_id, args.version_id))
979
1006
  elif args.cmd == "render":
980
1007
  payload = _spend_reviewed(args, lambda token: client.render_project(
981
1008
  args.project_id, accept_quality_findings=args.accept_quality_findings, review_token=token,
@@ -1205,6 +1205,24 @@ class CliptudeClient:
1205
1205
  def cancel_agent_run(self, project_id: int | str, run_id: str) -> Any:
1206
1206
  return self.request("POST", f"/api/v1/editor-projects/{_int_seg(project_id)}/agent/runs/{_uuid_seg(run_id, 'run_id')}/cancel")
1207
1207
 
1208
+ def edit_timeline(
1209
+ self, project_id: int | str, operations: list[dict[str, Any]], *, expected_revision: int | None = None,
1210
+ ) -> Any:
1211
+ """Apply exact timeline operations in one revision: no model call, no credits."""
1212
+ body: dict[str, Any] = {"operations": operations}
1213
+ if expected_revision is not None:
1214
+ body["expected_revision"] = int(expected_revision)
1215
+ return self.request("POST", f"/api/v1/editor-projects/{_int_seg(project_id)}/edits", json_body=body)
1216
+
1217
+ def list_editor_versions(self, project_id: int | str) -> Any:
1218
+ return self.request("GET", f"/api/v1/editor-projects/{_int_seg(project_id)}/versions")
1219
+
1220
+ def restore_editor_version(self, project_id: int | str, version_id: int | str) -> Any:
1221
+ return self.request(
1222
+ "POST",
1223
+ f"/api/v1/editor-projects/{_int_seg(project_id)}/versions/{_int_seg(version_id, 'version_id')}/restore",
1224
+ )
1225
+
1208
1226
  def render_project(
1209
1227
  self, project_id: int | str, *, accept_quality_findings: bool = False, review_token: str | None = None,
1210
1228
  skip_frame_review: bool = False,
@@ -238,8 +238,11 @@ def build_server(*, with_http_auth: bool = False):
238
238
  "Generate Cliptude videos from a saved template. "
239
239
  "Call list_templates, then create_job with template_id + title plus "
240
240
  "(no suitable template? get_template_options + list_voices, then create_template) "
241
- "To revise a finished video: open_editor_project, run_agent with timeline item ids, "
242
- "poll get_agent_run, then render_project and get_render. "
241
+ "To revise a finished video: open_editor_project, then edit_timeline for exact changes on its item ids "
242
+ "(delete, retime, trim, swap a graphic's design or picture, fix its words, add a graphic, clip or catalog sound, "
243
+ "transitions, caption style, library music, background; free, "
244
+ "undo with restore_editor_version) or run_agent for changes that need sourcing or generation (poll "
245
+ "get_agent_run), view_scenes the changed seconds, then render_project and get_render. "
243
246
  "prompt, script, voiceover_path (uploaded audio of at least 6 minutes, transcribed; skips TTS), "
244
247
  "or talking_head_path (presenter video of at least 6 minutes on a Talking Head template). "
245
248
  "create_job returns immediately; poll get_job until completed or failed. "
@@ -1447,6 +1450,72 @@ def build_server(*, with_http_auth: bool = False):
1447
1450
  out.append(Image(data=base64.b64decode(sheet["jpeg_base64"]), format="jpeg"))
1448
1451
  return out
1449
1452
 
1453
+ @mcp.tool(
1454
+ title="Edit timeline",
1455
+ annotations=ToolAnnotations(title="Edit timeline", read_only_hint=False, destructive_hint=True,
1456
+ idempotent_hint=False, open_world_hint=False),
1457
+ )
1458
+ def edit_timeline(
1459
+ project_id: Annotated[int, Field(description="Editor project id")],
1460
+ operations: Annotated[
1461
+ list[dict[str, Any]],
1462
+ Field(description=(
1463
+ "Operations applied in order, in one revision (up to 60). Each is an object with op and its fields: "
1464
+ "{op:'delete', item_id}; {op:'retime', item_id, start_s?, end_s?}; {op:'trim', item_id, from_s, to_s?} "
1465
+ "(clips and audio: which part of the source plays); {op:'set', item_id, opacity?, volume?, playbackRate?} "
1466
+ "(opacity and volume 0-100); {op:'set_props', item_id, props:{...}} (a graphic's fields, as in its "
1467
+ "catalog prop_schema); {op:'set_type', item_id, animation_type, props?} (another design, same timing); "
1468
+ "{op:'set_picture', item_id, keep|url} (a graphic's picture slot, or a clip's or image's file); "
1469
+ "{op:'mute_cues', item_id} (silence a graphic's own sound cues); {op:'add_graphic', animation_type, "
1470
+ "start_s, end_s, props, keep?|url?}; {op:'add_clip', keep|url, start_s, end_s, from_s?} (footage layer); "
1471
+ "{op:'set_transition', from_id, to_id, kind, direction?, duration_s?} (the join between two clips; "
1472
+ "kind 'none' removes it); {op:'set_caption_style', style:{color, activeColor, appearedColor, fontSize, "
1473
+ "...}, item_ids?} (every caption when item_ids is omitted; wording follows the narration); "
1474
+ "{op:'set_music', library_file?|keep?|url?, volume?, remove?} (library_file from get_template_options); "
1475
+ "{op:'set_background', keep|url}; {op:'add_sfx', sound, start_s, volume?} (sound id from "
1476
+ "get_kind_catalog sounds). set_props on a text item sets text, color, fontSize, fontWeight, textAlign. "
1477
+ "keep is a keep id from upload_plan_media / start_media_upload or from get_plan_review; url a public "
1478
+ "https link."
1479
+ )),
1480
+ ],
1481
+ expected_revision: Annotated[
1482
+ int | None, Field(description="The revision you read the item ids from; a newer timeline answers 409")
1483
+ ] = None,
1484
+ ) -> dict[str, Any]:
1485
+ """Change the timeline exactly as asked, on the item ids from open_editor_project or view_scenes: no model call and no credits. Use it whenever you know what to change (delete a board, move or shorten an item, swap a board for another design, fix a board's words or numbers, give a board or clip one of your uploaded files, add a board or a clip, mute a board's sound, change a transition, restyle captions, pick or remove library music or set its volume, set the background, place a sound effect from the catalog). Use run_agent only for open-ended requests that need sourcing or generation (find or generate a picture or clip, regenerate a voiceover range, generate or search new music or sound effects). Delete a full-frame board instead of setting its opacity to 0: a hidden board still covers the picture with black (refused). The narration cannot be deleted. Every call saves a version first: list_editor_versions and restore_editor_version undo it. The answer lists changed_ranges_s: view_scenes only those seconds (the rest keeps its frame review, and boards whose frame did not change keep their drawing), then render_project."""
1486
+ try:
1487
+ return _client().edit_timeline(project_id, operations, expected_revision=expected_revision)
1488
+ except Exception as exc:
1489
+ return _err(exc)
1490
+
1491
+ @mcp.tool(
1492
+ title="List editor versions",
1493
+ annotations=ToolAnnotations(title="List editor versions", read_only_hint=True, open_world_hint=False),
1494
+ )
1495
+ def list_editor_versions(
1496
+ project_id: Annotated[int, Field(description="Editor project id")],
1497
+ ) -> dict[str, Any]:
1498
+ """Saved versions of an editor project, newest first (id, revision, label, time): every editor save, edit_timeline call and agent edit makes one. Pass a version's id to restore_editor_version to undo back to it."""
1499
+ try:
1500
+ return _client().list_editor_versions(project_id)
1501
+ except Exception as exc:
1502
+ return _err(exc)
1503
+
1504
+ @mcp.tool(
1505
+ title="Restore editor version",
1506
+ annotations=ToolAnnotations(title="Restore editor version", read_only_hint=False, destructive_hint=True,
1507
+ idempotent_hint=False, open_world_hint=False),
1508
+ )
1509
+ def restore_editor_version(
1510
+ project_id: Annotated[int, Field(description="Editor project id")],
1511
+ version_id: Annotated[int, Field(description="Version id from list_editor_versions")],
1512
+ ) -> dict[str, Any]:
1513
+ """Put the timeline back to a saved version (an undo). The restore is itself saved as a version, so it can be undone too. Free; view_scenes the video again before render_project."""
1514
+ try:
1515
+ return _client().restore_editor_version(project_id, version_id)
1516
+ except Exception as exc:
1517
+ return _err(exc)
1518
+
1450
1519
  @mcp.tool(
1451
1520
  title="Run Cliptude Agent",
1452
1521
  annotations=ToolAnnotations(title="Run Cliptude Agent", read_only_hint=False, destructive_hint=True,
@@ -1465,7 +1534,7 @@ def build_server(*, with_http_auth: bool = False):
1465
1534
  Field(description=SPEND_REVIEW_TOKEN_HELP),
1466
1535
  ] = None,
1467
1536
  ) -> dict[str, Any]:
1468
- """Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). One kind of change per run: picture swaps and text edits go in separate runs. Several clips can get new pictures in one run: reference them all and describe each one's picture by its item id; a clip with nothing suitable is left unchanged and named in the reply. Swapping a graphic's picture keeps the graphic and its words. To use one exact picture (a product cover, a screenshot), paste its https link in the prompt: it is downloaded and applied as is, not searched for. Charges agent credits, so the first call returns a review (status 428, detail.review: the request and what runs usually cost) and starts nothing: show it to the user, wait for their explicit OK, then call again with the same arguments and review_token. Returns a run; poll get_agent_run. Then render_project for a new MP4, after view_scenes on the changed range."""
1537
+ """Ask Cliptude Agent to edit the timeline from a plain-English request (prefer edit_timeline when you know the exact change: it is exact and free). It can swap footage, regenerate images or voiceover ranges, music, transitions, text, delete clips or graphics. One kind of change per run: picture swaps, text edits and deletions go in separate runs. To delete a graphic, overlay, clip or sound effect, reference its item id and say "delete": the item is removed, with its own sound cues and any transition into it, and the footage under it shows. Never ask for opacity 0 to remove a full-frame board: a hidden board still covers the picture with black. The narration track cannot be deleted. Several clips can get new pictures in one run: reference them all and describe each one's picture by its item id; a clip with nothing suitable is left unchanged and named in the reply. Swapping a graphic's picture keeps the graphic and its words. To use one exact picture (a product cover, a screenshot), paste its https link in the prompt: it is downloaded and applied as is, not searched for. Charges agent credits, so the first call returns a review (status 428, detail.review: the request and what runs usually cost) and starts nothing: show it to the user, wait for their explicit OK, then call again with the same arguments and review_token. Returns a run; poll get_agent_run. Then render_project for a new MP4, after view_scenes on the changed range."""
1469
1538
  try:
1470
1539
  return _compact_agent_run(_client().run_agent(
1471
1540
  project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.43",
3
+ "version": "0.1.44",
4
4
  "description": "Cliptude CLI — generate videos from saved templates.",
5
5
  "homepage": "https://github.com/cliptude/cliptude#readme",
6
6
  "bin": {
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cliptude-mcp"
7
- version = "0.1.43"
7
+ version = "0.1.44"
8
8
  description = "Cliptude jobs CLI and MCP server (thin client of /api/v1)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"