@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 +2 -1
- package/cliptude_mcp/cli.py +27 -0
- package/cliptude_mcp/client.py +18 -0
- package/cliptude_mcp/server.py +72 -3
- package/package.json +1 -1
- package/pyproject.toml +1 -1
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
|
|
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
|
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -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,
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -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,
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -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,
|
|
242
|
-
"
|
|
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
|
|
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
package/pyproject.toml
CHANGED