@cliptude/cli 0.1.13 → 0.1.15

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.
@@ -525,6 +525,8 @@ def main(argv: list[str] | None = None) -> None:
525
525
  rn = sub.add_parser("render", help="Render an edited project to a new MP4")
526
526
  rn.add_argument("project_id")
527
527
  rn.add_argument("--wait", action="store_true", help="Poll until the render finishes")
528
+ rn.add_argument("--accept-quality-findings", action="store_true",
529
+ help="Agent-planned jobs: render although plan-review still lists plan quality findings")
528
530
 
529
531
  rs = sub.add_parser("render-status", help="Get an editor render (output_url when done)")
530
532
  rs.add_argument("render_id")
@@ -760,7 +762,7 @@ def main(argv: list[str] | None = None) -> None:
760
762
  elif args.cmd == "agent-tiers":
761
763
  _print(client.agent_tiers())
762
764
  elif args.cmd == "render":
763
- payload = client.render_project(args.project_id)
765
+ payload = client.render_project(args.project_id, accept_quality_findings=args.accept_quality_findings)
764
766
  if args.wait:
765
767
  render_id = (payload.get("render") or {}).get("id")
766
768
  payload = _wait(lambda: client.get_render(render_id), lambda p: (p.get("render") or {}).get("status"))
@@ -860,6 +860,13 @@ class CliptudeClient:
860
860
  params = {"design": "1"} if design else None
861
861
  return self.request("GET", f"/api/v1/editor-projects/{project_id}", params=params)
862
862
 
863
+ def view_scenes(self, project_id: int | str, *, start_s: float = 0.0, end_s: float | None = None) -> Any:
864
+ """Contact sheets (base64 JPEG) of the timeline's pictures, clip frames and graphics, with a legend."""
865
+ params: dict[str, Any] = {"start_s": start_s}
866
+ if end_s is not None:
867
+ params["end_s"] = end_s
868
+ return self.request("GET", f"/api/v1/editor-projects/{project_id}/scenes", params=params)
869
+
863
870
  def agent_tiers(self) -> Any:
864
871
  return self.request("GET", "/api/v1/agent/tiers")
865
872
 
@@ -897,9 +904,10 @@ class CliptudeClient:
897
904
  def cancel_agent_run(self, project_id: int | str, run_id: str) -> Any:
898
905
  return self.request("POST", f"/api/v1/editor-projects/{project_id}/agent/runs/{run_id}/cancel")
899
906
 
900
- def render_project(self, project_id: int | str) -> Any:
907
+ def render_project(self, project_id: int | str, *, accept_quality_findings: bool = False) -> Any:
901
908
  """Render the edited timeline to a new MP4: free the first time, then 10% of the original generation."""
902
- return self.request("POST", f"/api/v1/editor-projects/{project_id}/render")
909
+ body = {"accept_quality_findings": True} if accept_quality_findings else None
910
+ return self.request("POST", f"/api/v1/editor-projects/{project_id}/render", json_body=body)
903
911
 
904
912
  def get_render(self, render_id: int | str) -> Any:
905
913
  return self.request("GET", f"/api/v1/editor-renders/{render_id}")
@@ -2,11 +2,14 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import base64
6
+ import json
5
7
  import logging
6
8
  import os
7
9
  import sys
8
10
  from typing import Annotated, Any
9
11
 
12
+ from mcp.server.mcpserver import Image
10
13
  from pydantic import Field
11
14
 
12
15
  from cliptude_mcp.client import CliptudeApiError, CliptudeClient, set_request_token
@@ -119,6 +122,8 @@ def build_server(*, with_http_auth: bool = False):
119
122
  "prompt/script/voiceover_path (template format must be talking_head). "
120
123
  "Avatar Video: list_avatars gives avatar ids; put one in create_template settings as "
121
124
  "avatar_profile_id (with the voice), or pass avatar_profile_id on create_job to override. "
125
+ "Before you create a template or job with an avatar, show the user its thumbnail_url and name and "
126
+ "wait for them to confirm it is the presenter they want (names repeat; the avatar is paid for). "
122
127
  "Avatar Video templates may include avatar_intro_only "
123
128
  "(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
124
129
  "on create_job to override the template, or omit them to keep the template. "
@@ -127,11 +132,13 @@ def build_server(*, with_http_auth: bool = False):
127
132
  "plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
128
133
  "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
129
134
  "cliptude-plan skill. "
130
- "PRODUCT VIDEOS (Shopify product URLs, a connected store, or any store's product page): "
135
+ "PRODUCT VIDEOS (the user's connected store, or a product page from a store they sell for): "
131
136
  "fetch_product_context, show the user the 3 angles, draft_product_script with their pick and a "
132
137
  "duration (6-8 to 50-60 minutes), poll get_product_video_status until script_ready, let the user "
133
- "review the script, render_product_video, poll until ready_for_review, give the user editor_url, "
134
- "and only after they approve render with open_editor_project + render_project + get_render. "
138
+ "review the script, render_product_video (this starts the build, not the final MP4), poll until "
139
+ "ready_for_review, open_editor_project and look at every picture and graphic yourself with "
140
+ "view_scenes (contact sheets; media links may not open for you), give the user editor_url, and only after they approve render with "
141
+ "render_project + get_render. "
135
142
  "Never publish anything to a store or YouTube without the user's explicit go-ahead."
136
143
  ),
137
144
  }
@@ -308,7 +315,7 @@ def build_server(*, with_http_auth: bool = False):
308
315
  limit: Annotated[int, Field(ge=1, le=100)] = 50,
309
316
  offset: Annotated[int, Field(ge=0)] = 0,
310
317
  ) -> dict[str, Any]:
311
- """Avatars the user can put in an Avatar Video: id, name, section, gender, engines, thumbnail_url. Pass an id as avatar_profile_id to create_template (in settings), create_job, create_plan_job or estimate_credits. The avatar's gender must match the voice."""
318
+ """Avatars the user can put in an Avatar Video: id, name, section, gender, engines, thumbnail_url. Pass an id as avatar_profile_id to create_template (in settings), create_job, create_plan_job or estimate_credits. The avatar's gender must match the voice. Show the user the thumbnail_url and name and get their OK before you spend credits on it: several avatars share a name."""
312
319
  try:
313
320
  return _client().list_avatars(section=section, search=search, gender=gender, limit=limit, offset=offset)
314
321
  except Exception as exc:
@@ -584,8 +591,8 @@ def build_server(*, with_http_auth: bool = False):
584
591
  )
585
592
  def fetch_product_context(
586
593
  product_url_or_query: Annotated[str, Field(min_length=1, description=(
587
- "A product page URL (any Shopify store, e.g. https://store.com/products/handle; other stores "
588
- "such as WooCommerce or Etsy work through the page's structured data), a connected store's "
594
+ "A product page URL from the user's own store (Shopify, e.g. https://store.com/products/handle; "
595
+ "WooCommerce or Etsy work through the page's structured data), a connected store's "
589
596
  "product id/handle, or a search term together with store_domain."))],
590
597
  store_domain: Annotated[str | None, Field(description=(
591
598
  "Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
@@ -639,7 +646,7 @@ def build_server(*, with_http_auth: bool = False):
639
646
  script_id: Annotated[str, Field(min_length=8, description="script_id / job_id from draft_product_script, once script_ready")],
640
647
  aspect_ratio: Annotated[str, Field(description="16:9 (YouTube), 9:16, 1:1 or 4:5")] = "16:9",
641
648
  ) -> dict[str, Any]:
642
- """Produce the video from the approved script on the same job id: voiceover, sourcing, motion graphics, and the merchant's real product photos composited into the closing product boards. Returns {job_id, status, editor_url, estimated_minutes} immediately; never wait in this call. Poll get_product_video_status."""
649
+ """Start BUILDING the video from the approved script on the same job id: voiceover, sourcing, motion graphics, and the merchant's real product photos composited into the closing product boards. This does not render the final MP4: when the build is done (ready_for_review) review it, show the user the editor_url and wait for their go-ahead before render_project. Returns {job_id, status, stage, editor_url, estimated_minutes} immediately; never wait in this call. Poll get_product_video_status."""
643
650
  try:
644
651
  return _client().render_product_video(script_id, aspect_ratio=aspect_ratio)
645
652
  except Exception as exc:
@@ -808,7 +815,7 @@ def build_server(*, with_http_auth: bool = False):
808
815
  def get_plan_review(
809
816
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
810
817
  ) -> dict[str, Any]:
811
- """What the built design shows, before any render: every picture/clip in order (beat, time, the sentence under it, what you asked for, what was used, a link to the file) and every graphic (time on screen and the props it will be drawn with, or why it is missing). Review this, revise with check_plan/lock_plan + continue_job on the same job if needed, then render_project once."""
818
+ """What the built design shows, before any render: every picture/clip in order (beat, time, the sentence under it, what you asked for, what was used, a link to the file) and every graphic (time on screen and the props it will be drawn with, or why it is missing), plus quality_findings: Cliptude's quality checks on the build. Fix every finding with fix_in "plan" (follow its how); fix_in "cliptude" ones are not yours. Revise with check_plan/lock_plan + continue_job on the same job, review again, then render_project once (it refuses while plan findings remain unless accept_quality_findings is true)."""
812
819
  try:
813
820
  return _client().get_plan_review(job_id)
814
821
  except Exception as exc:
@@ -990,6 +997,26 @@ def build_server(*, with_http_auth: bool = False):
990
997
  except Exception as exc:
991
998
  return _err(exc)
992
999
 
1000
+ @mcp.tool(
1001
+ title="View scenes",
1002
+ annotations=ToolAnnotations(title="View scenes", read_only_hint=True, open_world_hint=False),
1003
+ )
1004
+ def view_scenes(
1005
+ project_id: Annotated[int, Field(description="Editor project id")],
1006
+ start_s: Annotated[float, Field(ge=0, description="First second to show")] = 0.0,
1007
+ end_s: Annotated[float | None, Field(description="Stop before this second (default: the end)")] = None,
1008
+ ) -> list[str | Image]:
1009
+ """See what the timeline shows, without opening any link: numbered contact sheets of every picture, a frame of every clip and each graphic's picture with its words, with the narration under each, plus a legend (tile, item_id, start_s, end_s, words, said, flags). Up to 24 tiles per call; call again from next_start_s. Use it to review a built video yourself (other brands, wrong pictures, repeats, leftover text) before giving the user the editor link, and again after run_agent to check the change."""
1010
+ try:
1011
+ data = _client().view_scenes(project_id, start_s=start_s, end_s=end_s)
1012
+ except Exception as exc:
1013
+ return [json.dumps(_err(exc))]
1014
+ sheets = data.pop("sheets", None) or []
1015
+ out: list[str | Image] = [json.dumps(data, ensure_ascii=False)]
1016
+ for sheet in sheets:
1017
+ out.append(Image(data=base64.b64decode(sheet["jpeg_base64"]), format="jpeg"))
1018
+ return out
1019
+
993
1020
  @mcp.tool(
994
1021
  title="Run Cliptude Agent",
995
1022
  annotations=ToolAnnotations(title="Run Cliptude Agent", read_only_hint=False, destructive_hint=False),
@@ -1003,7 +1030,7 @@ def build_server(*, with_http_auth: bool = False):
1003
1030
  tier: Annotated[str, Field(description="fast or smart")] = "fast",
1004
1031
  chat_id: Annotated[str | None, Field(description="Continue an existing agent chat")] = None,
1005
1032
  ) -> dict[str, Any]:
1006
- """Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4."""
1033
+ """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. Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4, after view_scenes on the changed range."""
1007
1034
  try:
1008
1035
  return _client().run_agent(
1009
1036
  project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id
@@ -1045,10 +1072,14 @@ def build_server(*, with_http_auth: bool = False):
1045
1072
  )
1046
1073
  def render_project(
1047
1074
  project_id: Annotated[int, Field(description="Editor project id")],
1075
+ accept_quality_findings: Annotated[
1076
+ bool,
1077
+ Field(description="Agent-planned jobs only: render although get_plan_review still lists quality_findings with fix_in \"plan\". Set it only after trying to fix them, or when the user says to ship as is."),
1078
+ ] = False,
1048
1079
  ) -> dict[str, Any]:
1049
- """Render the edited timeline to a new MP4. The first export of a project is free; later exports cost 10% of the original generation (export_credits_due on the project says the exact amount). Poll get_render for output_url."""
1080
+ """Render the edited timeline to a new MP4. The first export of a project is free; later exports cost 10% of the original generation (export_credits_due on the project says the exact amount). Poll get_render for output_url. On an agent-planned job, a build with quality_findings the plan can fix returns 409 quality_findings_open: revise the plan and review again first."""
1050
1081
  try:
1051
- return _client().render_project(project_id)
1082
+ return _client().render_project(project_id, accept_quality_findings=accept_quality_findings)
1052
1083
  except Exception as exc:
1053
1084
  return _err(exc)
1054
1085
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.13",
3
+ "version": "0.1.15",
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.13"
7
+ version = "0.1.15"
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"