@cliptude/cli 0.1.40 → 0.1.42

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.
@@ -645,6 +645,17 @@ def main(argv: list[str] | None = None) -> None:
645
645
  pg.add_argument("job_id")
646
646
  pv = sub.add_parser("plan-review", help="The built design beat by beat and graphic by graphic (review before rendering)")
647
647
  pv.add_argument("job_id")
648
+ pcd = sub.add_parser("plan-candidates", help="Every picture or clip sourcing checked for some beats, with keep ids")
649
+ pcd.add_argument("job_id")
650
+ pcd.add_argument("--beats", help="Comma-separated beat ids, e.g. b12,b40")
651
+ pcd.add_argument("--start", type=float, help="Or every beat starting in this window: start (s)")
652
+ pcd.add_argument("--end", type=float, help="End of the window (s)")
653
+ pcs = sub.add_parser("plan-candidate-sheets", help="Contact sheets of every candidate for up to 6 beats (saves JPEGs)")
654
+ pcs.add_argument("job_id")
655
+ pcs.add_argument("--beats", help="Comma-separated beat ids (at most 6)")
656
+ pcs.add_argument("--start", type=float, help="Or the beats starting in this window: start (s)")
657
+ pcs.add_argument("--end", type=float, help="End of the window (s)")
658
+ pcs.add_argument("--out", default=".", help="Folder for the sheets (default: here)")
648
659
  pr = sub.add_parser("plan-report", help="What sourcing used for each media request of the locked plan")
649
660
  pr.add_argument("job_id")
650
661
  um = sub.add_parser("upload-media", help="Send a picture or clip you found to a plan job; prints its keep id for media.keep")
@@ -890,6 +901,23 @@ def main(argv: list[str] | None = None) -> None:
890
901
  _print(client.get_plan(args.job_id))
891
902
  elif args.cmd == "plan-review":
892
903
  _print(client.get_plan_review(args.job_id))
904
+ elif args.cmd == "plan-candidate-sheets":
905
+ import base64 as _b64
906
+
907
+ beats = [b.strip() for b in (args.beats or "").split(",") if b.strip()] or None
908
+ data = client.view_candidates(args.job_id, beats=beats, start_s=args.start, end_s=args.end)
909
+ out_dir = Path(args.out).expanduser()
910
+ out_dir.mkdir(parents=True, exist_ok=True)
911
+ saved = []
912
+ for sheet in data.pop("sheets", None) or []:
913
+ dest = out_dir / str(sheet.get("name") or f"candidates_{len(saved) + 1:02d}.jpg")
914
+ dest.write_bytes(_b64.b64decode(sheet["jpeg_base64"]))
915
+ saved.append(str(dest))
916
+ data["saved_sheets"] = saved
917
+ _print(data)
918
+ elif args.cmd == "plan-candidates":
919
+ beats = [b.strip() for b in (args.beats or "").split(",") if b.strip()] or None
920
+ _print(client.get_plan_candidates(args.job_id, beats=beats, start_s=args.start, end_s=args.end))
893
921
  elif args.cmd == "plan-report":
894
922
  _print(client.get_plan_report(args.job_id))
895
923
  elif args.cmd == "upload-media":
@@ -351,6 +351,20 @@ def _motion_control_job_fields(
351
351
  return fields
352
352
 
353
353
 
354
+ # Completing an upload checks the file; with split_shots it also cuts it into clips and checks each one, which
355
+ # takes minutes for a trailer. Wait up to the server's own request limit (300 s) rather than the usual 30 s.
356
+ SPLIT_SHOTS_COMPLETE_TIMEOUT_S = 310.0
357
+ UPLOAD_COMPLETE_TIMEOUT_S = 120.0
358
+
359
+
360
+ def _complete_timeout(default: float, split_shots: bool) -> float:
361
+ return max(default, SPLIT_SHOTS_COMPLETE_TIMEOUT_S if split_shots else UPLOAD_COMPLETE_TIMEOUT_S)
362
+
363
+
364
+ def _timed_out(exc: BaseException) -> bool:
365
+ return isinstance(exc, httpx.TimeoutException) or isinstance(getattr(exc, "__cause__", None), httpx.TimeoutException)
366
+
367
+
354
368
  class CliptudeClient:
355
369
  def __init__(
356
370
  self,
@@ -427,7 +441,9 @@ class CliptudeClient:
427
441
  self.api_key = str(updated.get("access_token") or "")
428
442
  return bool(self.api_key)
429
443
 
430
- def request(self, method: str, path: str, *, params=None, json_body=None, _retried: bool = False) -> Any:
444
+ def request(
445
+ self, method: str, path: str, *, params=None, json_body=None, timeout: float | None = None, _retried: bool = False,
446
+ ) -> Any:
431
447
  url = f"{self.base_url}{path}"
432
448
  try:
433
449
  resp = httpx.request(
@@ -436,12 +452,12 @@ class CliptudeClient:
436
452
  headers=self._headers(),
437
453
  params=params,
438
454
  json=json_body,
439
- timeout=self.timeout,
455
+ timeout=timeout or self.timeout,
440
456
  )
441
457
  except httpx.HTTPError as exc:
442
458
  raise CliptudeApiError(str(exc)) from exc
443
459
  if resp.status_code == 401 and not _retried and self._maybe_refresh():
444
- return self.request(method, path, params=params, json_body=json_body, _retried=True)
460
+ return self.request(method, path, params=params, json_body=json_body, timeout=timeout, _retried=True)
445
461
  try:
446
462
  payload = resp.json()
447
463
  except ValueError:
@@ -955,8 +971,18 @@ class CliptudeClient:
955
971
  body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
956
972
  try:
957
973
  self._upload_parts(path, init, f"{base}/sign-parts", "media")
958
- return self.request("POST", f"{base}/complete", json_body={**body, **({"split_shots": True} if split_shots else {})})
959
- except Exception:
974
+ return self.request(
975
+ "POST", f"{base}/complete", json_body={**body, **({"split_shots": True} if split_shots else {})},
976
+ timeout=_complete_timeout(self.timeout, split_shots),
977
+ )
978
+ except Exception as exc:
979
+ if _timed_out(exc):
980
+ # The bytes are uploaded and Cliptude is still checking (and cutting) them: aborting now would
981
+ # delete a file the server is about to keep.
982
+ raise CliptudeApiError(
983
+ "Cliptude is still processing this upload; it took longer than the wait. Upload a shorter "
984
+ "source (split_shots handles about two minutes at a time) or try again."
985
+ ) from exc
960
986
  try:
961
987
  self.request("POST", f"{base}/abort", json_body=body)
962
988
  except Exception:
@@ -991,7 +1017,8 @@ class CliptudeClient:
991
1017
 
992
1018
  def finish_media_upload(self, job_id: str, *, key: str, upload_id: str, split_shots: bool = False) -> Any:
993
1019
  body = {"key": key, "upload_id": upload_id, **({"split_shots": True} if split_shots else {})}
994
- return self.request("POST", f"/api/v1/jobs/{_uuid_seg(job_id)}/media/complete", json_body=body)
1020
+ return self.request("POST", f"/api/v1/jobs/{_uuid_seg(job_id)}/media/complete", json_body=body,
1021
+ timeout=_complete_timeout(self.timeout, split_shots))
995
1022
 
996
1023
  def abort_media_upload(self, job_id: str, *, key: str, upload_id: str) -> Any:
997
1024
  return self.request("POST", f"/api/v1/jobs/{_uuid_seg(job_id)}/media/abort", json_body={"key": key, "upload_id": upload_id})
@@ -1052,6 +1079,31 @@ class CliptudeClient:
1052
1079
  """The built design, beat by beat and graphic by graphic, with links to the media (review before render)."""
1053
1080
  return self.request("GET", f"/api/v1/jobs/{_uuid_seg(job_id)}/plan/review")
1054
1081
 
1082
+ def get_plan_candidates(self, job_id: str, *, beats: list[str] | None = None,
1083
+ start_s: float | None = None, end_s: float | None = None) -> Any:
1084
+ """Every picture or clip sourcing checked for the chosen beats (passed or turned down), each with a keep id."""
1085
+ params: dict[str, Any] = {}
1086
+ if beats:
1087
+ params["beats"] = ",".join(str(b) for b in beats)
1088
+ if start_s is not None:
1089
+ params["start_s"] = start_s
1090
+ if end_s is not None:
1091
+ params["end_s"] = end_s
1092
+ return self.request("GET", f"/api/v1/jobs/{_uuid_seg(job_id)}/plan/candidates", params=params)
1093
+
1094
+ def view_candidates(self, job_id: str, *, beats: list[str] | None = None,
1095
+ start_s: float | None = None, end_s: float | None = None) -> Any:
1096
+ """The candidates of up to 6 beats as labelled contact sheets (sheets[].jpeg_base64)."""
1097
+ params: dict[str, Any] = {}
1098
+ if beats:
1099
+ params["beats"] = ",".join(str(b) for b in beats)
1100
+ if start_s is not None:
1101
+ params["start_s"] = start_s
1102
+ if end_s is not None:
1103
+ params["end_s"] = end_s
1104
+ return self.request("GET", f"/api/v1/jobs/{_uuid_seg(job_id)}/plan/candidates/sheets", params=params,
1105
+ timeout=180)
1106
+
1055
1107
  def download_voiceover_file(self, job_id: str, dest: Path) -> Path:
1056
1108
  dest = self._local_file(dest, "dest")
1057
1109
  url = f"{self.base_url}/api/v1/jobs/{_uuid_seg(job_id)}/voiceover"
@@ -295,10 +295,10 @@ def build_server(*, with_http_auth: bool = False):
295
295
  "topic with web search, write the narration yourself and show it to the user to review first; then "
296
296
  "create_plan_job with script (prompt only when the user asks Cliptude to write it), poll get_job until "
297
297
  "plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
298
- "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. Before giving the user "
299
- "the editor link, open_editor_project and look at EVERY frame with view_scenes (0 to the end): replace "
298
+ "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. ONE REVIEW: when the first "
299
+ "build is ready, open_editor_project and look at EVERY frame with view_scenes (0 to the end) once: replace "
300
300
  "any dead body or gore, other brands, logos, album art, footage of a game, match or show the video is not about, title cards, pictures whose place or era "
301
- "contradicts the story (a search naming a place can return a namesake elsewhere), near-black frames, clips floating in black bars, broken AI pictures and any picture held over ~8 s, in a free revision, then review again. Generic "
301
+ "contradicts the story (a search naming a place can return a namesake elsewhere), near-black frames, clips floating in black bars, broken AI pictures and any picture held over ~8 s, all in ONE free revision whose fixes carry the replacement itself (footage, pictures or photos you downloaded and uploaded with upload_plan_media, used as keep; corrected board text). A job takes one revision (a second answers 409 review_used): Cliptude renders the revised build itself; poll get_job until render.status is completed and call show_publish_kit. Never review the rebuild or ask the user to. Generic "
302
302
  "shots of places name the story's setting (\"empty bed mud house\", not \"empty bed dark room\"). A video "
303
303
  "about a video game, sport, creator or TV show searches the real thing (\"GTA 6 gameplay driving\", "
304
304
  "\"Bellingham Real Madrid goal\", \"Kai Cenat stream\"): its own footage is the footage, broadcaster and "
@@ -900,7 +900,7 @@ def build_server(*, with_http_auth: bool = False):
900
900
  Field(description=SPEND_REVIEW_TOKEN_HELP),
901
901
  ] = None,
902
902
  ) -> dict[str, Any]:
903
- """Queue a completed script or voiceover job, or a plan job whose plan is locked, as a full video on the same id. This charges the rest of the video price, so the first call returns a review (status 428, detail.review: what it builds and the credits) and queues nothing: show it to the user, wait for their explicit OK, then call again with the same arguments and review_token. Poll get_job until completed. Do not create a second job with the script or audio. Refused with code thumbnail_required when the video has no thumbnail reference or brief: pass one here. Refused with status 402 and code insufficient_credits when the account cannot pay for the rest of the video: nothing is queued or lost (a plan job stays plan_ready with its locked plan and narration). Tell the user the shortfall and detail.billing_url, and once they add credits call continue_job again on the same job id."""
903
+ """Queue a completed script or voiceover job, or a plan job whose plan is locked, as a full video on the same id. This charges the rest of the video price, so the first call returns a review (status 428, detail.review: what it builds and the credits) and queues nothing: show it to the user, wait for their explicit OK, then call again with the same arguments and review_token. Poll get_job until completed. Do not create a second job with the script or audio. Refused with code thumbnail_required when the video has no thumbnail reference or brief: pass one here. Refused with status 402 and code insufficient_credits when the account cannot pay for the rest of the video: nothing is queued or lost (a plan job stays plan_ready with its locked plan and narration). Tell the user the shortfall and detail.billing_url, and once they add credits call continue_job again on the same job id. On a built plan job with a newly locked revision this rebuilds for free (no review): that is the job's one revision, and Cliptude renders its build itself; poll get_job until render.status is completed, then show_publish_kit."""
904
904
  try:
905
905
  return _client().continue_job(job_id, thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
906
906
  review_token=review_token)
@@ -1169,7 +1169,7 @@ def build_server(*, with_http_auth: bool = False):
1169
1169
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
1170
1170
  plan: Annotated[dict[str, Any], Field(description="The plan that check_plan reported valid")],
1171
1171
  ) -> dict[str, Any]:
1172
- """Validate and store the plan, and apply its look (theme, colours, style, music) to the video. You may lock again to replace it until you call continue_job. Then call continue_job."""
1172
+ """Validate and store the plan, and apply its look (theme, colours, style, music) to the video. You may lock again to replace it until you call continue_job. Then call continue_job. After the first build the job takes ONE revised plan (its one review); once that is built, lock_plan answers 409 review_used and Cliptude renders the build itself."""
1173
1173
  try:
1174
1174
  return _client().put_plan(job_id, plan, dry_run=False)
1175
1175
  except Exception as exc:
@@ -1195,12 +1195,50 @@ def build_server(*, with_http_auth: bool = False):
1195
1195
  def get_plan_review(
1196
1196
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
1197
1197
  ) -> dict[str, Any]:
1198
- """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)."""
1198
+ """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 picked.why: why that file won, with a count of the other candidates get_plan_candidates lists for the beat) 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. This is the job's one review: fix everything in one revision (check_plan/lock_plan + continue_job on the same job), choosing each replacement from get_plan_candidates or uploading your own, as keep; Cliptude renders the revised build itself and a second revision is refused (409 review_used). Poll get_job until render.status is completed, then show_publish_kit. If nothing needs fixing, render_project once (it refuses while plan findings remain unless accept_quality_findings is true), then show_publish_kit."""
1199
1199
  try:
1200
1200
  return _untrusted(_client().get_plan_review(job_id))
1201
1201
  except Exception as exc:
1202
1202
  return _err(exc)
1203
1203
 
1204
+ @mcp.tool(
1205
+ title="See what sourcing found for a beat",
1206
+ annotations=ToolAnnotations(title="See what sourcing found for a beat", read_only_hint=True, open_world_hint=False),
1207
+ )
1208
+ def get_plan_candidates(
1209
+ job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
1210
+ beats: Annotated[list[str] | None, Field(description="Beat ids from get_plan_review, e.g. [\"b12\", \"b40\"] (at most 40)")] = None,
1211
+ start_s: Annotated[float | None, Field(description="Or every beat whose sentence starts in this window: start (seconds)")] = None,
1212
+ end_s: Annotated[float | None, Field(description="End of the window (seconds)")] = None,
1213
+ ) -> dict[str, Any]:
1214
+ """The one review's replacements: for each chosen beat, every picture or clip Cliptude downloaded and checked for it (your main query, your alternative queries and its wider searches), including the ones the vision check turned down, each with a link to look at it, its size, its query, its verdict and reason, and a keep id; plus which one shipped (picked) and why. get_plan_review gives each beat's picked.why and how many candidates it has. To use one, put {"keep": "<id>"} as that beat's media (or a board's picture slot) in the revised plan. If none is right, find your own file and upload it (upload_plan_media locally, or start_media_upload + finish_media_upload from any host) and use its keep. Files the search ranked but never downloaded are not listed. To look at them when you cannot open links, call view_candidates (contact sheets)."""
1215
+ try:
1216
+ return _untrusted(_client().get_plan_candidates(job_id, beats=beats, start_s=start_s, end_s=end_s))
1217
+ except Exception as exc:
1218
+ return _err(exc)
1219
+
1220
+ @mcp.tool(
1221
+ title="Look at what sourcing found",
1222
+ annotations=ToolAnnotations(title="Look at what sourcing found", read_only_hint=True, open_world_hint=False),
1223
+ )
1224
+ def view_candidates(
1225
+ job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status ready_for_edit)")],
1226
+ beats: Annotated[list[str] | None, Field(description="Up to 6 beat ids from get_plan_review, e.g. [\"b12\", \"b40\"]")] = None,
1227
+ start_s: Annotated[float | None, Field(description="Or the beats whose sentence starts in this window: start (seconds)")] = None,
1228
+ end_s: Annotated[float | None, Field(description="End of the window (seconds)")] = None,
1229
+ ) -> list[str | Image]:
1230
+ """See every candidate sourcing checked for up to 6 beats, without opening any link: labelled contact sheets, one tile per candidate (a clip shows three frames: start, middle, end), each naming its beat, keep id, SHIPPED / PASSED / REJECTED with the reason and score, its size and the query that found it, plus the same listing as JSON. Use it in the one review to pick a replacement for a wrong beat: put {"keep": "<id>"} as that beat's media in the revised plan. A rejected candidate is often right for the line (it failed on wording); judge by the picture. If none fits, upload your own file (start_media_upload + finish_media_upload from any host) and use its keep."""
1231
+ try:
1232
+ data = _client().view_candidates(job_id, beats=beats, start_s=start_s, end_s=end_s)
1233
+ except Exception as exc:
1234
+ return [json.dumps(_err(exc))]
1235
+ sheets = data.pop("sheets", None) or []
1236
+ data = _untrusted(data)
1237
+ out: list[str | Image] = [json.dumps(data, ensure_ascii=False)]
1238
+ for sheet in sheets:
1239
+ out.append(Image(data=base64.b64decode(sheet["jpeg_base64"]), format="jpeg"))
1240
+ return out
1241
+
1204
1242
  @mcp.tool(
1205
1243
  title="Upload plan media",
1206
1244
  annotations=ToolAnnotations(title="Upload plan media", read_only_hint=False, destructive_hint=False,
@@ -1481,7 +1519,7 @@ def build_server(*, with_http_auth: bool = False):
1481
1519
  Field(description=SPEND_REVIEW_TOKEN_HELP),
1482
1520
  ] = None,
1483
1521
  ) -> dict[str, Any]:
1484
- """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). A paid export first returns a review (status 428, detail.review with the credits) and renders nothing: show it to the user, wait for their explicit OK, then call again with the same arguments and review_token. 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."""
1522
+ """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). A paid export first returns a review (status 428, detail.review with the credits) and renders nothing: show it to the user, wait for their explicit OK, then call again with the same arguments and review_token. Poll get_render for output_url. On an agent-planned job, a first build with quality_findings the plan can fix returns 409 quality_findings_open: fix them in the job's one revision (Cliptude then renders that build itself, so this call is not needed)."""
1485
1523
  try:
1486
1524
  return _client().render_project(project_id, accept_quality_findings=accept_quality_findings,
1487
1525
  review_token=review_token)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.40",
3
+ "version": "0.1.42",
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.40"
7
+ version = "0.1.42"
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"