@cliptude/cli 0.1.53 → 0.1.54

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.
@@ -19,6 +19,21 @@ def _print(payload) -> None:
19
19
  sys.stdout.write("\n")
20
20
 
21
21
 
22
+ def _screenshot_kw(args) -> dict:
23
+ """{"screenshot": True/False} when --screenshot / --no-screenshot was given, else {} (the call is unchanged)."""
24
+ value = getattr(args, "screenshot", None)
25
+ return {} if value is None else {"screenshot": value}
26
+
27
+
28
+ def _add_screenshot_flag(parser) -> None:
29
+ """--screenshot / --no-screenshot: say whether a picture is a screenshot (shown whole and still); default: measured."""
30
+ group = parser.add_mutually_exclusive_group()
31
+ group.add_argument("--screenshot", dest="screenshot", action="store_const", const=True, default=None,
32
+ help="The picture is a screenshot of a post, thread, article or app screen: shown whole and still")
33
+ group.add_argument("--no-screenshot", dest="screenshot", action="store_const", const=False,
34
+ help="The picture is a photo: cropped and moved like any picture, even if it looks like a screenshot")
35
+
36
+
22
37
  def _add_review_args(parser) -> None:
23
38
  parser.add_argument("--review-token", default="", help="Token from the job review (shown when you run without it)")
24
39
  parser.add_argument(
@@ -279,14 +294,14 @@ def _run_media(client: CliptudeClient, args) -> None:
279
294
  if args.name and len(args.paths) != 1:
280
295
  raise CliptudeApiError("--name names one file: upload one file with it.")
281
296
  if args.name:
282
- _print(client.upload_to_library(args.paths[0], folder=args.folder, name=args.name))
297
+ _print(client.upload_to_library(args.paths[0], folder=args.folder, name=args.name, **_screenshot_kw(args)))
283
298
  return
284
- result = client.upload_many_to_library(args.paths, folder=args.folder)
299
+ result = client.upload_many_to_library(args.paths, folder=args.folder, **_screenshot_kw(args))
285
300
  _print(result)
286
301
  if result.get("failed"):
287
302
  raise SystemExit(1)
288
303
  elif cmd == "import":
289
- _print(client.import_media(url=args.url, folder=args.folder, name=args.name))
304
+ _print(client.import_media(url=args.url, folder=args.folder, name=args.name, **_screenshot_kw(args)))
290
305
 
291
306
 
292
307
  def _run_brand_kit(client: CliptudeClient, args) -> None:
@@ -760,10 +775,12 @@ def main(argv: list[str] | None = None) -> None:
760
775
  mdu.add_argument("paths", nargs="+", help="Files: pictures, clips (MP4, MOV, WebM) or audio")
761
776
  mdu.add_argument("--folder", default=None, help="Library folder for all of them (tag it as @folder_name)")
762
777
  mdu.add_argument("--name", default=None, help="A name (its @tag) when you upload one file")
778
+ _add_screenshot_flag(mdu)
763
779
  mdi = md_sub.add_parser("import", help="Download a public https link to a file into your media library")
764
780
  mdi.add_argument("url")
765
781
  mdi.add_argument("--folder", default=None, help="Library folder")
766
782
  mdi.add_argument("--name", default=None, help="File name with extension (its @tag), needed when the link has none")
783
+ _add_screenshot_flag(mdi)
767
784
  bk = sub.add_parser(
768
785
  "brand-kit",
769
786
  help="Brand kits (one per channel): list, options, get, create, update, set-default, delete",
@@ -1192,6 +1209,7 @@ def main(argv: list[str] | None = None) -> None:
1192
1209
  um.add_argument("path", help="Local JPG/PNG/WEBP/GIF (up to 15 MB) or MP4/MOV/WEBM/M4V (up to 300 MB)")
1193
1210
  um.add_argument("--split-shots", action="store_true",
1194
1211
  help="Also cut a long source into 3-12 s clips on its cuts, each checked and kept (prints their keep ids)")
1212
+ _add_screenshot_flag(um)
1195
1213
 
1196
1214
  ed = sub.add_parser("editor", help="Open the timeline editor project for a completed job (prints the timeline)")
1197
1215
  ed.add_argument("job_id")
@@ -1511,7 +1529,7 @@ def main(argv: list[str] | None = None) -> None:
1511
1529
  elif args.cmd == "plan-report":
1512
1530
  _print(client.get_plan_report(args.job_id))
1513
1531
  elif args.cmd == "upload-media":
1514
- _print(client.upload_plan_media(args.job_id, args.path, split_shots=args.split_shots))
1532
+ _print(client.upload_plan_media(args.job_id, args.path, split_shots=args.split_shots, **_screenshot_kw(args)))
1515
1533
  elif args.cmd == "download-voiceover":
1516
1534
  dest = Path(args.out)
1517
1535
  client.download_voiceover_file(args.job_id, dest)
@@ -158,8 +158,10 @@ class CliptudeApiError(Exception):
158
158
  LOCAL_FILES_REFUSED = (
159
159
  "{param} reads a file on the machine running this MCP server, which a remote (hosted) server does not "
160
160
  "allow. Upload the file instead: narration with start_voiceover_upload + finish_voiceover_upload and pass "
161
- "the voiceover_url it returns; pictures and clips for a plan job with start_media_upload + "
162
- "finish_media_upload; a character image as image_url (a public https link). Or run the local "
161
+ "the voiceover_url it returns; files for the media library (clips, A-roll, screenshots, audio) with "
162
+ "start_library_upload + finish_library_upload (both take a list of files) or import_media for a public link; "
163
+ "pictures and clips for a plan job with start_media_upload + finish_media_upload; a logo with "
164
+ "start_brand_upload + finish_brand_upload; a character image as image_url (a public https link). Or run the local "
163
165
  "`cliptude-mcp` / `cliptude` CLI, which can read your files."
164
166
  )
165
167
 
@@ -766,20 +768,24 @@ class CliptudeClient:
766
768
  content_type=content_type)
767
769
 
768
770
  def finish_library_upload(self, *, key: str, upload_id: str, folder: str | None = None,
769
- name: str | None = None) -> Any:
770
- """Returns the file as list_media shows it, with its media_id and @tag."""
771
+ name: str | None = None, screenshot: bool | None = None) -> Any:
772
+ """Returns the file as list_media shows it, with its media_id and @tag. screenshot: True / False says
773
+ whether a picture is a screenshot (shown whole and still); None lets Cliptude measure it."""
771
774
  body: dict[str, Any] = {"key": key, "upload_id": upload_id}
772
775
  if folder:
773
776
  body["folder"] = folder
774
777
  if name:
775
778
  body["name"] = name
779
+ if screenshot is not None:
780
+ body["screenshot"] = bool(screenshot)
776
781
  return self.request("POST", "/api/v1/uploads/library/complete", json_body=body,
777
782
  timeout=max(self.timeout, 180.0))
778
783
 
779
784
  def abort_library_upload(self, *, key: str, upload_id: str) -> Any:
780
785
  return self.request("POST", "/api/v1/uploads/library/abort", json_body={"key": key, "upload_id": upload_id})
781
786
 
782
- def upload_to_library(self, path: str | Path, *, folder: str | None = None, name: str | None = None) -> Any:
787
+ def upload_to_library(self, path: str | Path, *, folder: str | None = None, name: str | None = None,
788
+ screenshot: bool | None = None) -> Any:
783
789
  """Upload one local file to the media library through the signed-URL flow; returns {media_id, tag, url, ...}."""
784
790
  path = self._local_file(path, "path")
785
791
  if not path.is_file():
@@ -792,7 +798,8 @@ class CliptudeClient:
792
798
  body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
793
799
  try:
794
800
  self._upload_parts(path, init, "/api/v1/uploads/library/sign-parts", path.name)
795
- return self.finish_library_upload(key=body["key"], upload_id=body["upload_id"], folder=folder, name=name)
801
+ return self.finish_library_upload(key=body["key"], upload_id=body["upload_id"], folder=folder, name=name,
802
+ screenshot=screenshot)
796
803
  except Exception:
797
804
  try:
798
805
  self.request("POST", "/api/v1/uploads/library/abort", json_body=body)
@@ -800,20 +807,24 @@ class CliptudeClient:
800
807
  pass
801
808
  raise
802
809
 
803
- def upload_many_to_library(self, paths: list[str | Path], *, folder: str | None = None) -> dict[str, Any]:
810
+ def upload_many_to_library(self, paths: list[str | Path], *, folder: str | None = None,
811
+ screenshot: bool | None = None) -> dict[str, Any]:
804
812
  """Upload several local files (one at a time; a failure does not stop the rest). Returns
805
813
  {uploaded: [...], failed: [{path, error}]}."""
806
814
  uploaded, failed = [], []
807
815
  for p in paths:
808
816
  try:
809
- uploaded.append(self.upload_to_library(p, folder=folder))
817
+ uploaded.append(self.upload_to_library(p, folder=folder, screenshot=screenshot))
810
818
  except Exception as exc: # one bad file must not lose the others
811
819
  failed.append({"path": str(p), "error": str(exc)})
812
820
  return {"uploaded": uploaded, "failed": failed}
813
821
 
814
- def import_media(self, *, url: str, folder: str | None = None, name: str | None = None) -> Any:
822
+ def import_media(self, *, url: str, folder: str | None = None, name: str | None = None,
823
+ screenshot: bool | None = None) -> Any:
815
824
  """Download a public https link (picture, clip or audio) into the media library."""
816
825
  body: dict[str, Any] = {"url": url}
826
+ if screenshot is not None:
827
+ body["screenshot"] = bool(screenshot)
817
828
  if folder:
818
829
  body["folder"] = folder
819
830
  if name:
@@ -1410,7 +1421,8 @@ class CliptudeClient:
1410
1421
 
1411
1422
  # Agent-planned videos -------------------------------------------------------------------------
1412
1423
 
1413
- def upload_plan_media(self, job_id: str, path: str | Path, *, split_shots: bool = False) -> Any:
1424
+ def upload_plan_media(self, job_id: str, path: str | Path, *, split_shots: bool = False,
1425
+ screenshot: bool | None = None) -> Any:
1414
1426
  """Send a picture or clip you found to a plan job; returns {keep, file, media_type, size} for media.keep.
1415
1427
 
1416
1428
  split_shots: a long source (a trailer, a featurette) is also cut into clips on its cuts, each checked and
@@ -1432,7 +1444,8 @@ class CliptudeClient:
1432
1444
  try:
1433
1445
  self._upload_parts(path, init, f"{base}/sign-parts", "media")
1434
1446
  return self.request(
1435
- "POST", f"{base}/complete", json_body={**body, **({"split_shots": True} if split_shots else {})},
1447
+ "POST", f"{base}/complete", json_body={**body, **({"split_shots": True} if split_shots else {}),
1448
+ **({} if screenshot is None else {"screenshot": bool(screenshot)})},
1436
1449
  timeout=_complete_timeout(self.timeout, split_shots),
1437
1450
  )
1438
1451
  except Exception as exc:
@@ -1475,8 +1488,10 @@ class CliptudeClient:
1475
1488
  """Signed PUT URLs for a picture or clip of a plan job, for a host that sends the bytes itself."""
1476
1489
  return self._start_signed_upload(f"/api/v1/jobs/{_uuid_seg(job_id)}/media", filename=filename, size=size, content_type=content_type)
1477
1490
 
1478
- def finish_media_upload(self, job_id: str, *, key: str, upload_id: str, split_shots: bool = False) -> Any:
1479
- body = {"key": key, "upload_id": upload_id, **({"split_shots": True} if split_shots else {})}
1491
+ def finish_media_upload(self, job_id: str, *, key: str, upload_id: str, split_shots: bool = False,
1492
+ screenshot: bool | None = None) -> Any:
1493
+ body = {"key": key, "upload_id": upload_id, **({"split_shots": True} if split_shots else {}),
1494
+ **({} if screenshot is None else {"screenshot": bool(screenshot)})}
1480
1495
  return self.request("POST", f"/api/v1/jobs/{_uuid_seg(job_id)}/media/complete", json_body=body,
1481
1496
  timeout=_complete_timeout(self.timeout, split_shots))
1482
1497
 
@@ -28,6 +28,11 @@ logging.basicConfig(stream=sys.stderr, level=logging.INFO)
28
28
  _SERVER_MODE = {"remote": False}
29
29
 
30
30
 
31
+ # One sentence for every tool that takes the screenshot flag (videos/screenshots.py on the server).
32
+ SCREENSHOT_FLAG_DESC = ("true: this picture is a screenshot of a post, thread, article or app screen, shown whole and "
33
+ "still (a stage_shot card on stage Looks); false: a photo, cropped and moved like any picture; "
34
+ "omit to let Cliptude measure it (the upload result says which: screenshot.source).")
35
+
31
36
  def _remote() -> bool:
32
37
  return bool(_SERVER_MODE["remote"])
33
38
 
@@ -827,13 +832,33 @@ def build_server(*, with_http_auth: bool = False):
827
832
  open_world_hint=False),
828
833
  )
829
834
  def start_library_upload(
830
- filename: Annotated[str, Field(min_length=1, description="The file's name with its extension: a picture (JPG, PNG, WebP, GIF; up to 15 MB), a clip (MP4, MOV, WebM; up to 300 MB) or audio (MP3, WAV, M4A, AAC, OGG, FLAC; up to 95 MB). The name becomes its @tag (kress_interview.mp4 -> @kress_interview).")],
831
- size: Annotated[int, Field(gt=0, description="The file's size in bytes (e.g. `wc -c < file`).")],
835
+ filename: Annotated[str | None, Field(description="One file's name with its extension: a picture (JPG, PNG, WebP, GIF; up to 15 MB), a clip (MP4, MOV, WebM; up to 300 MB) or audio (MP3, WAV, M4A, AAC, OGG, FLAC; up to 95 MB). The name becomes its @tag (kress_interview.mp4 -> @kress_interview). For several files use files instead.")] = None,
836
+ size: Annotated[int | None, Field(gt=0, description="That file's size in bytes (e.g. `wc -c < file`).")] = None,
832
837
  content_type: Annotated[str | None, Field(description="MIME type; omit to infer it from the file name.")] = None,
833
- ) -> dict[str, Any]:
834
- """Upload a file to the user's media library from ANY host, remote included: an A-roll clip, a sponsor spot, screenshots, b-roll, music. PUT each part's bytes to its url exactly as for start_media_upload (one part: `curl -sf -X PUT --upload-file FILE "URL"`), then finish_library_upload. URLs expire in 1 hour. One file per call; for many files repeat it (or use upload_to_library on a local MCP). A public https link is simpler: import_media."""
835
- try:
836
- out = _client().start_library_upload(filename=filename, size=size, content_type=content_type)
838
+ files: Annotated[list[dict[str, Any]] | None, Field(max_length=50, description="Many files at once (up to 50): [{\"filename\": \"shot_01.png\", \"size\": 48213}, ...] (content_type optional). Returns one upload per file, in the same order.")] = None,
839
+ ) -> dict[str, Any]:
840
+ """Upload files to the user's media library from ANY host, remote included: an A-roll clip, a sponsor spot, screenshots, b-roll, music. One file (filename + size) or up to 50 (files). PUT each part's bytes to its url exactly as for start_media_upload (one part: `curl -sf -X PUT --upload-file FILE "URL"`), then finish_library_upload with every key and upload_id in one call. URLs expire in 1 hour. A public https link is simpler: import_media."""
841
+ try:
842
+ client = _client()
843
+ if files:
844
+ if filename or size:
845
+ return {"error": "Give filename + size for one file, or files for several, not both."}
846
+ uploads, failed = [], []
847
+ for i, item in enumerate(files):
848
+ item = item if isinstance(item, dict) else {}
849
+ try:
850
+ out = client.start_library_upload(filename=str(item.get("filename") or ""),
851
+ size=int(item.get("size") or 0),
852
+ content_type=item.get("content_type"))
853
+ uploads.append({"filename": item.get("filename"), **out})
854
+ except Exception as exc: # one bad file must not stop the rest
855
+ failed.append({"index": i, "filename": item.get("filename"), "error": str(exc)})
856
+ return {"uploads": uploads, "failed": failed,
857
+ "next": "PUT every part of every upload to its url, then finish_library_upload("
858
+ "uploads=[{key, upload_id}, ...], folder?) in one call."}
859
+ if not filename or not size:
860
+ return {"error": "Give filename and size (one file), or files (several)."}
861
+ out = client.start_library_upload(filename=filename, size=size, content_type=content_type)
837
862
  out["next"] = "PUT every part to its url, then finish_library_upload(key, upload_id, folder?)."
838
863
  return out
839
864
  except Exception as exc:
@@ -845,14 +870,34 @@ def build_server(*, with_http_auth: bool = False):
845
870
  open_world_hint=False),
846
871
  )
847
872
  def finish_library_upload(
848
- key: Annotated[str, Field(min_length=1, description="key from start_library_upload")],
849
- upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_library_upload")],
850
- folder: Annotated[str | None, Field(max_length=80, description="Library folder to keep it in (e.g. jensen_followup); a description tags the whole folder as @folder_name.")] = None,
851
- name: Annotated[str | None, Field(max_length=200, description="A name for it (its @tag); omit to keep the file's name.")] = None,
852
- ) -> dict[str, Any]:
853
- """Close a library upload. Cliptude checks the file really is a picture, clip or audio file and keeps it in the media library, exactly like an upload on cliptude.com/videos/media/. Returns {media_id, tag, name, folder, kind, url}: use tag in a create_job description, as aroll (A-roll with its own sound) or sponsor, or media_id in edit_timeline add_aroll / add_sponsor."""
854
- try:
855
- return _client().finish_library_upload(key=key, upload_id=upload_id, folder=folder, name=name)
873
+ key: Annotated[str | None, Field(description="key from start_library_upload (one file)")] = None,
874
+ upload_id: Annotated[str | None, Field(description="upload_id from start_library_upload (one file)")] = None,
875
+ folder: Annotated[str | None, Field(max_length=80, description="Library folder to keep them in (e.g. jensen_followup); a description tags the whole folder as @folder_name.")] = None,
876
+ name: Annotated[str | None, Field(max_length=200, description="A name for one file (its @tag); omit to keep the file's name.")] = None,
877
+ uploads: Annotated[list[dict[str, Any]] | None, Field(max_length=50, description="Several uploads at once (up to 50): [{\"key\": ..., \"upload_id\": ..., \"name\"?: ..., \"screenshot\"?: true|false}, ...] from start_library_upload's uploads.")] = None,
878
+ screenshot: Annotated[bool | None, Field(description=SCREENSHOT_FLAG_DESC)] = None,
879
+ ) -> dict[str, Any]:
880
+ """Close library uploads (one, or up to 50 with uploads). Cliptude checks each file really is a picture, clip or audio file and keeps it in the media library, exactly like an upload on cliptude.com/videos/media/. Returns {media_id, tag, name, folder, kind, url} for one file, or {uploaded: [...], failed: [...]} for several: use tag in a create_job description, as aroll (A-roll with its own sound) or sponsor, or media_id in edit_timeline add_aroll / add_sponsor."""
881
+ try:
882
+ client = _client()
883
+ if uploads:
884
+ if key or upload_id:
885
+ return {"error": "Give key + upload_id for one file, or uploads for several, not both."}
886
+ done, failed = [], []
887
+ for i, item in enumerate(uploads):
888
+ item = item if isinstance(item, dict) else {}
889
+ try:
890
+ done.append(client.finish_library_upload(key=str(item.get("key") or ""),
891
+ upload_id=str(item.get("upload_id") or ""),
892
+ folder=folder, name=item.get("name"),
893
+ screenshot=item.get("screenshot", screenshot)))
894
+ except Exception as exc: # one bad file must not lose the others
895
+ failed.append({"index": i, "key": item.get("key"), "error": str(exc)})
896
+ return {"uploaded": done, "failed": failed}
897
+ if not key or not upload_id:
898
+ return {"error": "Give key and upload_id (one file), or uploads (several)."}
899
+ return client.finish_library_upload(key=key, upload_id=upload_id, folder=folder, name=name,
900
+ screenshot=screenshot)
856
901
  except Exception as exc:
857
902
  return _err(exc)
858
903
 
@@ -862,15 +907,16 @@ def build_server(*, with_http_auth: bool = False):
862
907
  idempotent_hint=False, open_world_hint=False),
863
908
  )
864
909
  def upload_to_library(
865
- paths: Annotated[list[str], Field(min_length=1, max_length=50, description="Local files to upload, up to 50 a call: pictures (up to 15 MB), clips (up to 300 MB), audio (up to 95 MB). Stdio / local MCP only: on a remote host use start_library_upload + finish_library_upload per file, or import_media for a public link.")],
910
+ paths: Annotated[list[str], Field(min_length=1, max_length=50, description="Local files to upload, up to 50 a call: pictures (up to 15 MB), clips (up to 300 MB), audio (up to 95 MB). Stdio / local MCP only: on a remote host use start_library_upload + finish_library_upload (both take a list of files), or import_media for a public link.")],
866
911
  folder: Annotated[str | None, Field(max_length=80, description="Library folder for all of them (e.g. jensen_followup).")] = None,
912
+ screenshot: Annotated[bool | None, Field(description=SCREENSHOT_FLAG_DESC)] = None,
867
913
  ) -> dict[str, Any]:
868
914
  """Upload one or many local files to the user's media library (each checked like a media-page upload; one failure does not stop the rest). Returns {uploaded: [{media_id, tag, name, kind, url}], failed: [{path, error}]}."""
869
915
  refused = _local_path_refused(remote, ("paths", " ".join(paths or [])))
870
916
  if refused:
871
917
  return refused
872
918
  try:
873
- return _client().upload_many_to_library(paths, folder=folder)
919
+ return _client().upload_many_to_library(paths, folder=folder, screenshot=screenshot)
874
920
  except Exception as exc:
875
921
  return _err(exc)
876
922
 
@@ -883,10 +929,11 @@ def build_server(*, with_http_auth: bool = False):
883
929
  url: Annotated[str, Field(min_length=12, description="Public https link to a picture, clip or audio file (not a web page or a YouTube link). Only send media the user may use.")],
884
930
  folder: Annotated[str | None, Field(max_length=80, description="Library folder to keep it in.")] = None,
885
931
  name: Annotated[str | None, Field(max_length=200, description="File name with extension (its @tag), e.g. kress_interview.mp4; needed when the link does not end in one.")] = None,
932
+ screenshot: Annotated[bool | None, Field(description=SCREENSHOT_FLAG_DESC)] = None,
886
933
  ) -> dict[str, Any]:
887
934
  """Download a file from a public https link into the user's media library (same size limits and checks as an upload). Returns {media_id, tag, name, folder, kind, url}."""
888
935
  try:
889
- return _client().import_media(url=url, folder=folder, name=name)
936
+ return _client().import_media(url=url, folder=folder, name=name, screenshot=screenshot)
890
937
  except Exception as exc:
891
938
  return _err(exc)
892
939
 
@@ -1812,13 +1859,14 @@ def build_server(*, with_http_auth: bool = False):
1812
1859
  Field(description="Local picture (JPG/PNG/WEBP/GIF, up to 15 MB) or clip (MP4/MOV/WEBM/M4V, up to 300 MB). Stdio / local MCP only: on a remote host (mcp.cliptude.com) use start_media_upload + finish_media_upload, which work from any agent that can run curl."),
1813
1860
  ],
1814
1861
  split_shots: Annotated[bool, Field(description="For a long source clip (a trailer, featurette, interview): also cut it into clips of 3-12 s that start and end on its cuts, each checked, measured and kept like an upload, with near-black and white-flash parts left out. Returns shots=[{keep, from_s, seconds, notes?}]. Use it instead of cutting clips yourself.")] = False,
1862
+ screenshot: Annotated[bool | None, Field(description=SCREENSHOT_FLAG_DESC)] = None,
1815
1863
  ) -> dict[str, Any]:
1816
1864
  """Send a picture or clip you found yourself to a plan job. The file goes straight to Cliptude's storage on signed URLs (no storage keys needed) and is checked to be a real picture or video, and for nudity and gore (refused). Returns {keep, file, media_type, size, notes?}: put {"keep": "<id>"} as a beat's media or a graphic's picture slot, with start_s/end_s on a beat to play only part of a clip. notes say where a clip runs into a title or logo card or a weapon aimed at someone (trim it with start_s/end_s as they say), and what the build review will report on the file (a channel watermark, an end screen, captions): use another file then. A render-only job makes no checks (no notes, no refusals): your agent checks every file."""
1817
1865
  refused = _local_path_refused(remote, ("path", path))
1818
1866
  if refused:
1819
1867
  return refused
1820
1868
  try:
1821
- return _client().upload_plan_media(job_id, path, split_shots=split_shots)
1869
+ return _client().upload_plan_media(job_id, path, split_shots=split_shots, screenshot=screenshot)
1822
1870
  except Exception as exc:
1823
1871
  return _err(exc)
1824
1872
 
@@ -1849,10 +1897,12 @@ def build_server(*, with_http_auth: bool = False):
1849
1897
  key: Annotated[str, Field(min_length=1, description="key from start_media_upload")],
1850
1898
  upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_media_upload")],
1851
1899
  split_shots: Annotated[bool, Field(description="For a long source clip (a trailer, featurette, interview): also cut it into clips of 3-12 s that start and end on its cuts, each checked, measured and kept like an upload, with near-black and white-flash parts left out. Returns shots=[{keep, from_s, seconds, notes?}]. Use it instead of cutting clips yourself.")] = False,
1900
+ screenshot: Annotated[bool | None, Field(description=SCREENSHOT_FLAG_DESC)] = None,
1852
1901
  ) -> dict[str, Any]:
1853
- """Close an upload after every part is PUT. Cliptude checks it is a real picture or video (nudity and gore are refused) and returns {keep, file, media_type, size, notes?}: put {"keep": "<id>"} as a beat's media or a graphic's picture slot (start_s/end_s on a beat to play part of a clip). notes say where a clip runs into a title or logo card or a weapon aimed at someone: trim it as they say. A render-only job makes no checks (no notes, no refusals): your agent checks every file."""
1902
+ """Close an upload after every part is PUT. Cliptude checks it is a real picture or video (nudity and gore are refused) and returns {keep, file, media_type, size, notes?, screenshot?}: screenshot (aspect, shown_as) marks a post or article capture, which the build and edit_timeline show whole and still (put it on the line that reads it). Put {"keep": "<id>"} as a beat's media or a graphic's picture slot (start_s/end_s on a beat to play part of a clip). notes say where a clip runs into a title or logo card or a weapon aimed at someone: trim it as they say. A render-only job makes no checks (no notes, no refusals): your agent checks every file."""
1854
1903
  try:
1855
- return _client().finish_media_upload(job_id, key=key, upload_id=upload_id, split_shots=split_shots)
1904
+ return _client().finish_media_upload(job_id, key=key, upload_id=upload_id, split_shots=split_shots,
1905
+ screenshot=screenshot)
1856
1906
  except Exception as exc:
1857
1907
  return _err(exc)
1858
1908
 
@@ -2051,7 +2101,7 @@ def build_server(*, with_http_auth: bool = False):
2051
2101
  "catalog prop_schema); {op:'set_type', item_id, animation_type, props?} (another design, same timing); "
2052
2102
  "{op:'set_picture', item_id, keep|url} (a graphic's picture slot, or a clip's or image's file); "
2053
2103
  "{op:'mute_cues', item_id} (silence a graphic's own sound cues); {op:'add_graphic', animation_type, "
2054
- "start_s, end_s, props, keep?|url?}; {op:'add_clip', keep|url, start_s, end_s, from_s?} (footage layer); "
2104
+ "start_s, end_s, props, keep?|url?}; {op:'add_clip', keep|url, start_s, end_s, from_s?, label?, focus?, screenshot?} (footage layer; a screenshot of a post or article (measured, or screenshot true; false opts out; add_graphic and set_picture take it too) is shown whole and still: on a stage Look as a stage_shot card with label as its pill and focus top|center|bottom for a long one, else full frame uncropped; fit:'cover' opts out); "
2055
2105
  "{op:'set_transition', from_id, to_id, kind, direction?, duration_s?} (the join between two clips; "
2056
2106
  "kind 'none' removes it); {op:'set_captions', enabled:true|false} (captions are off by default on every "
2057
2107
  "video; this shows or hides them all); {op:'set_caption_style', style:{color, activeColor, appearedColor, "
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.53",
3
+ "version": "0.1.54",
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.53"
7
+ version = "0.1.54"
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"