@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.
- package/cliptude_mcp/cli.py +28 -0
- package/cliptude_mcp/client.py +58 -6
- package/cliptude_mcp/server.py +45 -7
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/cliptude_mcp/cli.py
CHANGED
|
@@ -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":
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -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(
|
|
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(
|
|
959
|
-
|
|
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"
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -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.
|
|
299
|
-
"
|
|
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
|
|
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.
|
|
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:
|
|
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
package/pyproject.toml
CHANGED