@cliptude/cli 0.1.52 → 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.
package/README.md CHANGED
@@ -51,6 +51,8 @@ cliptude looks # prebuilt Looks; loo
51
51
  cliptude brand-kits
52
52
  cliptude brand-kit create --name "Northwind Notes" --channel-handle @northwindnotes --color '#1F6FEB' --color '#FFFFFF' --font title=Oswald:700 --logo ./logo.png
53
53
  cliptude brand-kit update 3 --logo https://example.com/logo.png --logo-position top_left # list | options | get | set-default | delete
54
+ cliptude media upload ./kress_cnbc.mp4 ./shots/*.png --folder jensen_followup # list | upload | import; each file's @tag
55
+ cliptude generate --template "News doc" --title "Why the board said no" --script-file script.txt --aroll '@kress_cnbc after "they refused to take any more questions"'
54
56
  cliptude voice-design previews --description "Calm male narrator, late thirties, low and warm" --model-id eleven_ttv_v3
55
57
  cliptude voice-design settings <design-id> --stability 0.4 --speed 1.05
56
58
  cliptude generate --template "Finance vector weekly" --title "Why index funds win" --prompt "why most retail traders underperform the S&P over 10 years, keep it for beginners" --duration 6-8
@@ -89,6 +91,10 @@ Docs: `search_docs` (CLI `docs search`) ranks the sections of every cliptude.com
89
91
 
90
92
  Brand kits and media: `list_brand_kits` (CLI `brand-kit list`) lists the user's brand kits (one per channel: logo, colours, fonts, channel name and handle for the subscribe card; one is the default). `create_brand_kit`, `update_brand_kit` (only the fields sent change), `get_brand_kit`, `set_default_brand_kit` and `delete_brand_kit` (destructive: only when the user asks) manage them, with `brand_kit_options` for the allowed fonts, weights and logo positions (CLI `brand-kit create|update|get|set-default|delete|options`; REST `/api/v1/brand-kits`). Colours are `#RRGGBB` (up to five); fonts are `{role: {family, weight}}` for title, subtitle, body and label. The logo (PNG, JPG or WebP, up to 5 MB, no SVG; kept in the media library's Brand folder) is `logo_url` (a public link), `logo_media_id` (a library image), `logo_path` (local MCP / CLI `--logo PATH`), or `start_brand_upload` + `finish_brand_upload` (signed PUT from any host; `kit_id` attaches it). `create_template` and `update_template` (CLI `template-create` / `template-update` with `--brand-kit`, `--new-brand-kit '{...}'` and `--show-logo`) take `brand_kit_id`, or `brand_kit` (a new kit made and attached in the same call), and `show_logo` (the logo is off by default). `create_job`, `create_plan_job` and `estimate_credits` (CLI `--brand-kit`) take `brand_kit_id` for one video (0 = the default kit).
91
93
 
94
+ Media library uploads: `upload_to_library` (local MCP, up to 50 paths a call, optional `folder`; CLI `media upload`, with `media list` and `media import`), `start_library_upload` + `finish_library_upload` (signed PUT from any host; REST `/api/v1/uploads/library/*`) and `import_media` (a public https link; REST `/api/v1/media/import`) keep pictures (15 MB), clips (300 MB) and audio (95 MB) in the user's library, each checked by its content; results and `list_media` rows carry `media_id` and its `@tag`.
95
+
96
+ A-roll: `aroll` on `create_job`, `create_plan_job` and `estimate_credits` (CLI `--aroll SPEC`, repeatable) splices the user's own clips (up to 4; a video, or an audio file shown on a waveform card) in with their own sound at the end of the sentence holding a quoted line (`{"media": "@clip", "after": "<a line of the script>"}`), the narration pausing for each; `edit_timeline` `add_aroll` adds one after the build. `include_aroll` (create_job, Faceless Documentary; CLI `--include-aroll`) turns Cliptude's own YouTube A-roll inserts on or off for one video.
97
+
92
98
  Looks: `list_looks` (CLI `looks`) lists the twelve offered styles (Empire Story, Geo Explained, Claim Check, Mega Build, Mission Archive, Old Frontier, Screen Trail, Bold Lessons, Case Reel, Patch Notes, Wild Matchup, Level Playbook); `create_template` / `update_template` take `look` (CLI `--look`), `create_job` / `create_plan_job` / `estimate_credits` take `look` for one video (CLI `generate` / `plan-job` / `estimate --look`), and `save_look_as_template` (CLI `look-template <slug>`) makes a template from a Look alone. Only an offered Look can be picked for a new template or job: any other is refused with code `look_hidden` (and the offered list), while a template or video that already uses a Look no longer listed keeps it and still builds. No motion-graphics Look and no Vector Explainer Look is offered now; an older template that still has a motion-graphics Look makes videos with `generate` / `create_job`, not `plan-job` (code `motion_graphics_look_plan`). The presenter Look (`level-playbook`) works only on Talking Head and Avatar Video. Each Look lists `look_only_boards`: boards drawn for it alone (e.g. `stage_shot` on Empire Story), which a plan may use only on a video with that Look. No Look uses AI pictures (a shot with no real picture becomes a graphic drawn in code); for a cartoon or drawn video use the Vector Explainer format and its `vector_art_style` (e.g. `flat_cartoon`). A finished job may carry `warnings` (each `{code, message}`, e.g. `sponsor_skipped`): tell the user.
93
99
 
94
100
  Designed voices: `voice-design options|previews|save|settings|try|remix|remix-save|delete` (MCP `voice_design_options`, `design_voice_previews`, `save_designed_voice`, `update_designed_voice_settings`, `try_designed_voice`, `remix_designed_voice`, `save_remixed_voice`, `delete_designed_voice`) with the web page's ElevenLabs design options and voice settings (stability, similarity_boost, style, use_speaker_boost, speed) and the same ranges. `list_media` lists the user's own images, clips and audio (their media library, shared with the editor's uploads), with a `url` to use in a plan or `edit_timeline`.
@@ -1,5 +1,5 @@
1
1
  """Tiny CLI wrapping /api/v1: auth | pick | templates | template-create | template-update | template-options | looks |
2
- look-template | brand-kits | brand-kit | voices | voice-design | avatars | estimate | generate | editor | agent | render | script |
2
+ look-template | brand-kits | brand-kit | media | voices | voice-design | avatars | estimate | generate | editor | agent | render | script |
3
3
  voiceover | continue | status | jobs | account | cancel | docs.
4
4
 
5
5
  Live formats: faceless_documentary, faceless_top_10, avatar_video, talking_head, vector_explainer (16:9 only)."""
@@ -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(
@@ -269,6 +284,26 @@ def _brand_kit_fields_from_args(args) -> dict:
269
284
  return fields
270
285
 
271
286
 
287
+ def _run_media(client: CliptudeClient, args) -> None:
288
+ cmd = args.media_cmd
289
+ if cmd == "list":
290
+ _print(client.list_media(folder=args.folder, kind=args.kind or None, limit=args.limit, offset=args.offset))
291
+ elif cmd == "upload":
292
+ if len(args.paths) > 50:
293
+ raise CliptudeApiError("Upload at most 50 files a run.")
294
+ if args.name and len(args.paths) != 1:
295
+ raise CliptudeApiError("--name names one file: upload one file with it.")
296
+ if args.name:
297
+ _print(client.upload_to_library(args.paths[0], folder=args.folder, name=args.name, **_screenshot_kw(args)))
298
+ return
299
+ result = client.upload_many_to_library(args.paths, folder=args.folder, **_screenshot_kw(args))
300
+ _print(result)
301
+ if result.get("failed"):
302
+ raise SystemExit(1)
303
+ elif cmd == "import":
304
+ _print(client.import_media(url=args.url, folder=args.folder, name=args.name, **_screenshot_kw(args)))
305
+
306
+
272
307
  def _run_brand_kit(client: CliptudeClient, args) -> None:
273
308
  cmd = args.bk_cmd
274
309
  if cmd == "list":
@@ -314,10 +349,53 @@ def _add_sponsor_args(parser: argparse.ArgumentParser) -> None:
314
349
  "--no-sponsor-bumpers leaves them out)")
315
350
 
316
351
 
352
+ def _add_aroll_args(parser: argparse.ArgumentParser, *, include: bool = True) -> None:
353
+ parser.add_argument(
354
+ "--aroll", action="append", default=[], metavar="SPEC",
355
+ help='Your own A-roll clip, played with its own sound (the narration pauses for it): a media-library video '
356
+ 'or audio file and, optionally, where and what it says, e.g. '
357
+ '\'@kress_cnbc after "they refused to take any more questions"\' or '
358
+ '\'@phone_call halfway says "We will not reinstate him"\'. A quoted line must be in the script word for '
359
+ 'word. JSON works too: \'{"media": "@clip", "after": "a line"}\'. Repeatable, up to 4; at most 3 '
360
+ 'minutes each. Upload clips with `cliptude media upload`.')
361
+ if include:
362
+ parser.add_argument(
363
+ "--include-aroll", action=argparse.BooleanOptionalAction, default=None,
364
+ help="Cliptude's own A-roll inserts (Faceless Documentary): it finds 2-4 clips of people speaking on "
365
+ "YouTube and splices them in with their sound. --no-include-aroll turns them off. Default: the "
366
+ "template's setting.")
367
+
368
+
369
+ def _aroll_from_args(args) -> list | None:
370
+ """--aroll SPEC values: '@clip <placement words>' or a JSON object."""
371
+ out = []
372
+ for spec in getattr(args, "aroll", None) or []:
373
+ spec = str(spec or "").strip()
374
+ if not spec:
375
+ continue
376
+ if spec.startswith("{"):
377
+ try:
378
+ item = json.loads(spec)
379
+ except ValueError as exc:
380
+ raise CliptudeApiError(f"--aroll is not valid JSON: {exc}") from exc
381
+ if not isinstance(item, dict):
382
+ raise CliptudeApiError("--aroll JSON must be an object, like {\"media\": \"@clip\", \"after\": \"a line\"}.")
383
+ out.append(item)
384
+ continue
385
+ media, _, where = spec.partition(" ")
386
+ out.append({"media": media, "placement": where.strip()} if where.strip() else media)
387
+ return out or None
388
+
389
+
317
390
  def _sponsor_kwargs(args) -> dict:
318
- return {"sponsor": getattr(args, "sponsor", None) or None,
319
- "sponsor_placement": getattr(args, "sponsor_placement", None) or None,
320
- "sponsor_bumpers": getattr(args, "sponsor_bumpers", None)}
391
+ """The sponsor, A-roll and include-A-roll flags, shared by estimate, generate and plan-job."""
392
+ out = {"sponsor": getattr(args, "sponsor", None) or None,
393
+ "sponsor_placement": getattr(args, "sponsor_placement", None) or None,
394
+ "sponsor_bumpers": getattr(args, "sponsor_bumpers", None),
395
+ "aroll": _aroll_from_args(args)}
396
+ if getattr(args, "include_aroll", None) is not None:
397
+ out["include_aroll"] = args.include_aroll
398
+ return out
321
399
 
322
400
 
323
401
  def _add_voice_setting_args(parser: argparse.ArgumentParser) -> None:
@@ -673,6 +751,36 @@ def main(argv: list[str] | None = None) -> None:
673
751
  dcl = dc_sub.add_parser("list", help="Every docs page: slug, title, category")
674
752
  dcl.add_argument("--category", default="", help="Only this sidebar group (Getting Started, Guides, Editor, ...)")
675
753
  dcl.add_argument("--json", action="store_true", help="Print the JSON response")
754
+ md = sub.add_parser(
755
+ "media",
756
+ help="Your media library: list, upload files (clips, pictures, audio), import a public link",
757
+ formatter_class=argparse.RawDescriptionHelpFormatter,
758
+ epilog=(
759
+ "examples:\n"
760
+ " cliptude media list --folder jensen_followup\n"
761
+ " cliptude media upload ./jensen.mp4 ./shots/*.png --folder jensen_followup\n"
762
+ " cliptude media upload ./kress.mp4 --name kress_cnbc.mp4\n"
763
+ " cliptude media import https://example.com/clip.mp4 --folder b_roll\n"
764
+ "Each file comes back with its @tag (kress_cnbc.mp4 -> @kress_cnbc) for --prompt, --aroll or --sponsor.\n"
765
+ "Limits: pictures 15 MB, clips 300 MB, audio 95 MB."
766
+ ),
767
+ )
768
+ md_sub = md.add_subparsers(dest="media_cmd", required=True)
769
+ mdl = md_sub.add_parser("list", help="List your media library (each file's url and @tag)")
770
+ mdl.add_argument("--folder", default=None, help="Only this folder ('' = files in no folder)")
771
+ mdl.add_argument("--kind", default="", choices=["", "image", "video", "audio"], help="Only this kind")
772
+ mdl.add_argument("--limit", type=int, default=50)
773
+ mdl.add_argument("--offset", type=int, default=0)
774
+ mdu = md_sub.add_parser("upload", help="Upload local files to your media library (up to 50 a run)")
775
+ mdu.add_argument("paths", nargs="+", help="Files: pictures, clips (MP4, MOV, WebM) or audio")
776
+ mdu.add_argument("--folder", default=None, help="Library folder for all of them (tag it as @folder_name)")
777
+ mdu.add_argument("--name", default=None, help="A name (its @tag) when you upload one file")
778
+ _add_screenshot_flag(mdu)
779
+ mdi = md_sub.add_parser("import", help="Download a public https link to a file into your media library")
780
+ mdi.add_argument("url")
781
+ mdi.add_argument("--folder", default=None, help="Library folder")
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)
676
784
  bk = sub.add_parser(
677
785
  "brand-kit",
678
786
  help="Brand kits (one per channel): list, options, get, create, update, set-default, delete",
@@ -815,6 +923,7 @@ def main(argv: list[str] | None = None) -> None:
815
923
  _add_captions_arg(est, scope="this video")
816
924
  _add_job_look_arg(est)
817
925
  _add_sponsor_args(est)
926
+ _add_aroll_args(est)
818
927
  est.add_argument("--render-only", action="store_true", help="Plan job where you bring the voiceover, pictures, clips and graphics (with --output plan --voiceover-seconds)")
819
928
 
820
929
  g = sub.add_parser(
@@ -935,6 +1044,7 @@ def main(argv: list[str] | None = None) -> None:
935
1044
  _add_captions_arg(g, scope="this video")
936
1045
  _add_job_look_arg(g)
937
1046
  _add_sponsor_args(g)
1047
+ _add_aroll_args(g)
938
1048
  g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
939
1049
 
940
1050
  sc = sub.add_parser(
@@ -1058,6 +1168,7 @@ def main(argv: list[str] | None = None) -> None:
1058
1168
  _add_captions_arg(pj, scope="this video")
1059
1169
  _add_job_look_arg(pj)
1060
1170
  _add_sponsor_args(pj)
1171
+ _add_aroll_args(pj, include=False)
1061
1172
  pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
1062
1173
 
1063
1174
  nr = sub.add_parser("narration", help="Numbered sentences and word timings of a plan_ready job")
@@ -1098,6 +1209,7 @@ def main(argv: list[str] | None = None) -> None:
1098
1209
  um.add_argument("path", help="Local JPG/PNG/WEBP/GIF (up to 15 MB) or MP4/MOV/WEBM/M4V (up to 300 MB)")
1099
1210
  um.add_argument("--split-shots", action="store_true",
1100
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)
1101
1213
 
1102
1214
  ed = sub.add_parser("editor", help="Open the timeline editor project for a completed job (prints the timeline)")
1103
1215
  ed.add_argument("job_id")
@@ -1222,6 +1334,8 @@ def main(argv: list[str] | None = None) -> None:
1222
1334
  _print(client.list_brand_kits())
1223
1335
  elif args.cmd == "brand-kit":
1224
1336
  _run_brand_kit(client, args)
1337
+ elif args.cmd == "media":
1338
+ _run_media(client, args)
1225
1339
  elif args.cmd == "voice-design":
1226
1340
  _run_voice_design(client, args)
1227
1341
  elif args.cmd == "template-options":
@@ -1415,7 +1529,7 @@ def main(argv: list[str] | None = None) -> None:
1415
1529
  elif args.cmd == "plan-report":
1416
1530
  _print(client.get_plan_report(args.job_id))
1417
1531
  elif args.cmd == "upload-media":
1418
- _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)))
1419
1533
  elif args.cmd == "download-voiceover":
1420
1534
  dest = Path(args.out)
1421
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
 
@@ -337,6 +339,54 @@ def merge_sponsor(prompt: str | None, sponsor: str | None, placement: str | None
337
339
  return f"{text}\n\n{sentence}".strip() if text else sentence
338
340
 
339
341
 
342
+ MAX_AROLLS = 4
343
+
344
+
345
+ def merge_aroll(prompt: str | None, aroll: Any) -> str | None:
346
+ """The prompt with one "A-roll: @clip after "<a line of the script>"." sentence per ``aroll`` item: the user's own
347
+ clip of someone speaking, spliced in between two sentences with its own sound (the narration pauses for it).
348
+ Items: "@clip" or {"media": "@clip", "placement": 'after "a line"'} (or "after": "a line"). The server reads the
349
+ sentence (videos/sponsor_segments.py) and refuses a line the script does not say."""
350
+ import re as _re
351
+
352
+ text = (prompt or "").strip()
353
+ items = aroll if isinstance(aroll, (list, tuple)) else ([aroll] if aroll else [])
354
+ if len(items) > MAX_AROLLS:
355
+ raise CliptudeApiError(f"A video can have at most {MAX_AROLLS} A-roll clips; you sent {len(items)}.")
356
+ sentences = []
357
+ for item in items:
358
+ if isinstance(item, dict):
359
+ raw = str(item.get("media") or item.get("file") or item.get("token") or "")
360
+ where = str(item.get("placement") or "")
361
+ if not where and item.get("after"):
362
+ where = f'after "{item["after"]}"'
363
+ if not where and item.get("before"):
364
+ where = f'before "{item["before"]}"'
365
+ says = str(item.get("says") or item.get("transcript") or "").strip()
366
+ if says:
367
+ where = f'{where} says "{says}"'.strip()
368
+ else:
369
+ raw, where = str(item or ""), ""
370
+ raw = raw.strip().lstrip("@")
371
+ token = _re.sub(r"[^0-9a-z]+", "_", _re.sub(r"\.[A-Za-z0-9]{2,4}$", "", raw).lower()).strip("_")
372
+ if not token:
373
+ raise CliptudeApiError("Each aroll item names a media-library video, like @kress_interview.")
374
+ if f"@{token}" in text.lower() and _re.search(r"\ba[- ]?roll", text, _re.I):
375
+ continue
376
+ # . ! ? inside a quoted line would end the tag's sentence early on the server; the line matches without them.
377
+ where = _re.sub(r'(["“])([^"“”]*)(["”])',
378
+ lambda q: q.group(1) + " ".join(_re.sub(r"[.!?…\n]+", " ", q.group(2)).split()) + q.group(3),
379
+ where)
380
+ where = " ".join(where.split()).strip().rstrip(".")
381
+ if _re.fullmatch(r"(?i)auto(matic)?|anywhere|", where):
382
+ where = ""
383
+ sentences.append(f"A-roll: @{token}" + (f" {where}" if where else "") + ".")
384
+ if not sentences:
385
+ return text or None
386
+ joined = "\n".join(sentences)
387
+ return f"{text}\n\n{joined}".strip() if text else joined
388
+
389
+
340
390
  def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
341
391
  *, as_strings: bool = False) -> dict[str, Any]:
342
392
  """The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
@@ -709,6 +759,78 @@ class CliptudeClient:
709
759
  pass
710
760
  raise
711
761
 
762
+ # --- media library uploads (pictures, clips, audio; videos/library_upload.py) -------------------------------
763
+
764
+ def start_library_upload(self, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
765
+ """Signed PUT URLs for one media-library file (picture up to 15 MB, clip up to 300 MB, audio up to 95 MB),
766
+ for a host that sends the bytes itself."""
767
+ return self._start_signed_upload("/api/v1/uploads/library", filename=filename, size=size,
768
+ content_type=content_type)
769
+
770
+ def finish_library_upload(self, *, key: str, upload_id: str, folder: str | None = None,
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."""
774
+ body: dict[str, Any] = {"key": key, "upload_id": upload_id}
775
+ if folder:
776
+ body["folder"] = folder
777
+ if name:
778
+ body["name"] = name
779
+ if screenshot is not None:
780
+ body["screenshot"] = bool(screenshot)
781
+ return self.request("POST", "/api/v1/uploads/library/complete", json_body=body,
782
+ timeout=max(self.timeout, 180.0))
783
+
784
+ def abort_library_upload(self, *, key: str, upload_id: str) -> Any:
785
+ return self.request("POST", "/api/v1/uploads/library/abort", json_body={"key": key, "upload_id": upload_id})
786
+
787
+ def upload_to_library(self, path: str | Path, *, folder: str | None = None, name: str | None = None,
788
+ screenshot: bool | None = None) -> Any:
789
+ """Upload one local file to the media library through the signed-URL flow; returns {media_id, tag, url, ...}."""
790
+ path = self._local_file(path, "path")
791
+ if not path.is_file():
792
+ raise CliptudeApiError(f"File not found: {path}")
793
+ init = self.request("POST", "/api/v1/uploads/library/init", json_body={
794
+ "filename": path.name,
795
+ "size": path.stat().st_size,
796
+ "content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
797
+ })
798
+ body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
799
+ try:
800
+ self._upload_parts(path, init, "/api/v1/uploads/library/sign-parts", path.name)
801
+ return self.finish_library_upload(key=body["key"], upload_id=body["upload_id"], folder=folder, name=name,
802
+ screenshot=screenshot)
803
+ except Exception:
804
+ try:
805
+ self.request("POST", "/api/v1/uploads/library/abort", json_body=body)
806
+ except Exception:
807
+ pass
808
+ raise
809
+
810
+ def upload_many_to_library(self, paths: list[str | Path], *, folder: str | None = None,
811
+ screenshot: bool | None = None) -> dict[str, Any]:
812
+ """Upload several local files (one at a time; a failure does not stop the rest). Returns
813
+ {uploaded: [...], failed: [{path, error}]}."""
814
+ uploaded, failed = [], []
815
+ for p in paths:
816
+ try:
817
+ uploaded.append(self.upload_to_library(p, folder=folder, screenshot=screenshot))
818
+ except Exception as exc: # one bad file must not lose the others
819
+ failed.append({"path": str(p), "error": str(exc)})
820
+ return {"uploaded": uploaded, "failed": failed}
821
+
822
+ def import_media(self, *, url: str, folder: str | None = None, name: str | None = None,
823
+ screenshot: bool | None = None) -> Any:
824
+ """Download a public https link (picture, clip or audio) into the media library."""
825
+ body: dict[str, Any] = {"url": url}
826
+ if screenshot is not None:
827
+ body["screenshot"] = bool(screenshot)
828
+ if folder:
829
+ body["folder"] = folder
830
+ if name:
831
+ body["name"] = name
832
+ return self.request("POST", "/api/v1/media/import", json_body=body, timeout=max(self.timeout, 180.0))
833
+
712
834
  def list_media(self, *, folder: str | None = None, kind: str | None = None, limit: int = 50,
713
835
  offset: int = 0) -> Any:
714
836
  """The user's media library (images, clips, audio; shared with the editor's uploads)."""
@@ -815,11 +937,13 @@ class CliptudeClient:
815
937
  sponsor: str | None = None,
816
938
  sponsor_placement: str | None = None,
817
939
  sponsor_bumpers: bool | None = None,
940
+ aroll: Any = None,
941
+ include_aroll: bool | None = None,
818
942
  ) -> Any:
819
943
  if voiceover_path and voiceover_url:
820
944
  raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
821
- # A sponsored segment is a sentence in the description, the same on every path.
822
- prompt = merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers)
945
+ # A sponsored segment and A-roll clips are sentences in the description, the same on every path.
946
+ prompt = merge_aroll(merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers), aroll)
823
947
  # visual_direction is deprecated: the description (prompt) carries the visual direction. Older callers still
824
948
  # send it, so it is appended to the prompt here, the same on every path (JSON, voiceover upload, talking head).
825
949
  prompt = merge_visual_direction(prompt, visual_direction)
@@ -913,6 +1037,7 @@ class CliptudeClient:
913
1037
  **({"captions": "true" if captions else "false"} if captions is not None else {}),
914
1038
  **({"look": str(look).strip() or "none"} if look is not None else {}),
915
1039
  **({"brand_kit_id": str(int(brand_kit_id))} if brand_kit_id is not None else {}),
1040
+ **({"include_aroll": "true" if include_aroll else "false"} if include_aroll is not None else {}),
916
1041
  **({"prompt": prompt} if prompt else {}),
917
1042
  **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
918
1043
  }
@@ -939,6 +1064,8 @@ class CliptudeClient:
939
1064
  body["voiceover_url"] = str(voiceover_url).strip()
940
1065
  if render_only:
941
1066
  body["render_only"] = True
1067
+ if include_aroll is not None:
1068
+ body["include_aroll"] = bool(include_aroll)
942
1069
  body.update(_avatar_job_fields(
943
1070
  avatar_intro_only, avatar_ai_footage,
944
1071
  avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
@@ -1294,7 +1421,8 @@ class CliptudeClient:
1294
1421
 
1295
1422
  # Agent-planned videos -------------------------------------------------------------------------
1296
1423
 
1297
- 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:
1298
1426
  """Send a picture or clip you found to a plan job; returns {keep, file, media_type, size} for media.keep.
1299
1427
 
1300
1428
  split_shots: a long source (a trailer, a featurette) is also cut into clips on its cuts, each checked and
@@ -1316,7 +1444,8 @@ class CliptudeClient:
1316
1444
  try:
1317
1445
  self._upload_parts(path, init, f"{base}/sign-parts", "media")
1318
1446
  return self.request(
1319
- "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)})},
1320
1449
  timeout=_complete_timeout(self.timeout, split_shots),
1321
1450
  )
1322
1451
  except Exception as exc:
@@ -1359,8 +1488,10 @@ class CliptudeClient:
1359
1488
  """Signed PUT URLs for a picture or clip of a plan job, for a host that sends the bytes itself."""
1360
1489
  return self._start_signed_upload(f"/api/v1/jobs/{_uuid_seg(job_id)}/media", filename=filename, size=size, content_type=content_type)
1361
1490
 
1362
- def finish_media_upload(self, job_id: str, *, key: str, upload_id: str, split_shots: bool = False) -> Any:
1363
- 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)})}
1364
1495
  return self.request("POST", f"/api/v1/jobs/{_uuid_seg(job_id)}/media/complete", json_body=body,
1365
1496
  timeout=_complete_timeout(self.timeout, split_shots))
1366
1497
 
@@ -1636,10 +1767,14 @@ class CliptudeClient:
1636
1767
  sponsor_placement: str | None = None,
1637
1768
  sponsor_bumpers: bool | None = None,
1638
1769
  brand_kit_id: int | None = None,
1770
+ aroll: Any = None,
1771
+ include_aroll: bool | None = None,
1639
1772
  ) -> Any:
1640
1773
  """Credits a job would need; creates nothing."""
1641
- prompt = merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers)
1774
+ prompt = merge_aroll(merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers), aroll)
1642
1775
  body: dict[str, Any] = {"template_id": template_id}
1776
+ if include_aroll is not None:
1777
+ body["include_aroll"] = bool(include_aroll)
1643
1778
  if captions is not None:
1644
1779
  body["captions"] = bool(captions)
1645
1780
  if look is not None:
@@ -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
 
@@ -321,6 +326,10 @@ def build_server(*, with_http_auth: bool = False):
321
326
  "can lower video quality a lot; no_video_footage; no_motion_graphics; no_music; no_sound_effects; "
322
327
  "no_transitions) tell the user what it costs and pass "
323
328
  "its id in acknowledge only after they explicitly approve; otherwise fix the template. "
329
+ "unverified_subjects means Cliptude couldn't confirm the named people, places or events are real (it may "
330
+ "be a fictional story, or a real one too little covered for Cliptude to know): ask the user whether it is a "
331
+ "true story and pass it only if they say yes. A content policy refusal (code content_policy) is final: "
332
+ "there is nothing to acknowledge. "
324
333
  "In hosts that show MCP Apps the review appears as a card with every setting, warning, acknowledgement "
325
334
  "checkbox and the credits: the user confirms there with a click (the card resends the call itself, or saves "
326
335
  "\"I confirm: ... review_token=... acknowledge=...\", which get_choice returns when they then say next, for "
@@ -817,6 +826,117 @@ def build_server(*, with_http_auth: bool = False):
817
826
  except Exception as exc:
818
827
  return _err(exc)
819
828
 
829
+ @mcp.tool(
830
+ title="Start library upload",
831
+ annotations=ToolAnnotations(title="Start library upload", read_only_hint=False, destructive_hint=False,
832
+ open_world_hint=False),
833
+ )
834
+ def start_library_upload(
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,
837
+ content_type: Annotated[str | None, Field(description="MIME type; omit to infer it from the file name.")] = None,
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)
862
+ out["next"] = "PUT every part to its url, then finish_library_upload(key, upload_id, folder?)."
863
+ return out
864
+ except Exception as exc:
865
+ return _err(exc)
866
+
867
+ @mcp.tool(
868
+ title="Finish library upload",
869
+ annotations=ToolAnnotations(title="Finish library upload", read_only_hint=False, destructive_hint=False,
870
+ open_world_hint=False),
871
+ )
872
+ def finish_library_upload(
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)
901
+ except Exception as exc:
902
+ return _err(exc)
903
+
904
+ @mcp.tool(
905
+ title="Upload to media library",
906
+ annotations=ToolAnnotations(title="Upload to media library", read_only_hint=False, destructive_hint=False,
907
+ idempotent_hint=False, open_world_hint=False),
908
+ )
909
+ def upload_to_library(
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.")],
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,
913
+ ) -> dict[str, Any]:
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}]}."""
915
+ refused = _local_path_refused(remote, ("paths", " ".join(paths or [])))
916
+ if refused:
917
+ return refused
918
+ try:
919
+ return _client().upload_many_to_library(paths, folder=folder, screenshot=screenshot)
920
+ except Exception as exc:
921
+ return _err(exc)
922
+
923
+ @mcp.tool(
924
+ title="Import media from a link",
925
+ annotations=ToolAnnotations(title="Import media from a link", read_only_hint=False, destructive_hint=False,
926
+ idempotent_hint=False, open_world_hint=True),
927
+ )
928
+ def import_media(
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.")],
930
+ folder: Annotated[str | None, Field(max_length=80, description="Library folder to keep it in.")] = None,
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,
933
+ ) -> dict[str, Any]:
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}."""
935
+ try:
936
+ return _client().import_media(url=url, folder=folder, name=name, screenshot=screenshot)
937
+ except Exception as exc:
938
+ return _err(exc)
939
+
820
940
  @mcp.tool(
821
941
  title="List media library",
822
942
  annotations=ToolAnnotations(title="List media library", read_only_hint=True, open_world_hint=False),
@@ -895,6 +1015,14 @@ def build_server(*, with_http_auth: bool = False):
895
1015
  bool | None,
896
1016
  Field(description="Short code-drawn cards in the Look's style before ('A word from our sponsor') and after ('Back to the story') the sponsor. On by default; false leaves them out."),
897
1017
  ] = None,
1018
+ aroll: Annotated[
1019
+ list[Any] | None,
1020
+ Field(description="The user's own A-roll clips (up to 4): media-library videos of someone speaking (an interview answer, a statement, a keynote line), each spliced in between two sentences with its OWN sound and picture: the narration pauses, the clip plays full frame, then the narration resumes, so the video gets that much longer. No cards, labelled A-roll in the editor. Items: \"@clip\" or {\"media\": \"@clip\", \"after\": \"<a line of the script, quoted exactly>\"} (or \"before\": ..., or \"placement\": \"at 2:00\" / \"halfway\" / \"after chapter 2\"). The clip plays at the end of the sentence holding that line; a line the script does not say is refused (code aroll_line_not_in_script). Each clip: a video of at most 3 minutes (trim it first), or an AUDIO file (a call, a voicemail, a podcast or radio quote): it plays over a full-frame waveform card (recorder, clock, playhead) with its words typed as they are heard: give them as \"says\": \"...\" or Cliptude transcribes it. Upload one with start_library_upload / upload_to_library / import_media. Write the narration so it leads into the clip and do not narrate what the clip says. Billed like a sponsor's seconds (render-only rate). Works on plan jobs too (do not plan a shot for it)."),
1021
+ ] = None,
1022
+ include_aroll: Annotated[
1023
+ bool | None,
1024
+ Field(description="Cliptude's own A-roll inserts (Faceless Documentary create_job videos only): it reads the script, searches YouTube for 2-4 real clips of people speaking that fit (fewer on short videos) and splices them in with their sound. It picks the clips itself; for a specific clip use aroll. true = on, false = off, omit = the template's setting. Needs general web crawling on."),
1025
+ ] = None,
898
1026
  brand_kit_id: Annotated[
899
1027
  int | None,
900
1028
  Field(description="The brand kit the job would use (id from list_brand_kits), overriding the template's: its colours and fonts on the graphics, its channel name and handle on the subscribe card, and its logo when the template shows the logo. 0 = no kit of its own (the user's default kit). Omit to keep the template's. People with several channels: ask which channel the video is for."),
@@ -929,6 +1057,8 @@ def build_server(*, with_http_auth: bool = False):
929
1057
  sponsor=sponsor,
930
1058
  sponsor_placement=sponsor_placement,
931
1059
  sponsor_bumpers=sponsor_bumpers,
1060
+ aroll=aroll,
1061
+ include_aroll=include_aroll,
932
1062
  brand_kit_id=brand_kit_id,
933
1063
  )
934
1064
  except Exception as exc:
@@ -1158,6 +1288,14 @@ def build_server(*, with_http_auth: bool = False):
1158
1288
  bool | None,
1159
1289
  Field(description="Short code-drawn cards in the Look's style before ('A word from our sponsor') and after ('Back to the story') the sponsor. On by default; false leaves them out."),
1160
1290
  ] = None,
1291
+ aroll: Annotated[
1292
+ list[Any] | None,
1293
+ Field(description="The user's own A-roll clips (up to 4): media-library videos of someone speaking (an interview answer, a statement, a keynote line), each spliced in between two sentences with its OWN sound and picture: the narration pauses, the clip plays full frame, then the narration resumes, so the video gets that much longer. No cards, labelled A-roll in the editor. Items: \"@clip\" or {\"media\": \"@clip\", \"after\": \"<a line of the script, quoted exactly>\"} (or \"before\": ..., or \"placement\": \"at 2:00\" / \"halfway\" / \"after chapter 2\"). The clip plays at the end of the sentence holding that line; a line the script does not say is refused (code aroll_line_not_in_script). Each clip: a video of at most 3 minutes (trim it first), or an AUDIO file (a call, a voicemail, a podcast or radio quote): it plays over a full-frame waveform card (recorder, clock, playhead) with its words typed as they are heard: give them as \"says\": \"...\" or Cliptude transcribes it. Upload one with start_library_upload / upload_to_library / import_media. Write the narration so it leads into the clip and do not narrate what the clip says. Billed like a sponsor's seconds (render-only rate). Works on plan jobs too (do not plan a shot for it)."),
1294
+ ] = None,
1295
+ include_aroll: Annotated[
1296
+ bool | None,
1297
+ Field(description="Cliptude's own A-roll inserts (Faceless Documentary create_job videos only): it reads the script, searches YouTube for 2-4 real clips of people speaking that fit (fewer on short videos) and splices them in with their sound. It picks the clips itself; for a specific clip use aroll. true = on, false = off, omit = the template's setting. Needs general web crawling on."),
1298
+ ] = None,
1161
1299
  brand_kit_id: Annotated[
1162
1300
  int | None,
1163
1301
  Field(description="A brand kit for this video only (id from list_brand_kits), overriding the template's: its colours and fonts on the graphics, its channel name and handle on the subscribe card, and its logo when the template shows the logo. 0 = no kit of its own (the user's default kit). Omit to keep the template's. People with several channels: ask which channel the video is for."),
@@ -1225,6 +1363,8 @@ def build_server(*, with_http_auth: bool = False):
1225
1363
  sponsor=sponsor,
1226
1364
  sponsor_placement=sponsor_placement,
1227
1365
  sponsor_bumpers=sponsor_bumpers,
1366
+ aroll=aroll,
1367
+ include_aroll=include_aroll,
1228
1368
  brand_kit_id=brand_kit_id,
1229
1369
  )
1230
1370
  except Exception as exc:
@@ -1525,6 +1665,10 @@ def build_server(*, with_http_auth: bool = False):
1525
1665
  bool | None,
1526
1666
  Field(description="Short code-drawn cards in the Look's style before ('A word from our sponsor') and after ('Back to the story') the sponsor. On by default; false leaves them out."),
1527
1667
  ] = None,
1668
+ aroll: Annotated[
1669
+ list[Any] | None,
1670
+ Field(description="The user's own A-roll clips (up to 4): media-library videos of someone speaking (an interview answer, a statement, a keynote line), each spliced in between two sentences with its OWN sound and picture: the narration pauses, the clip plays full frame, then the narration resumes, so the video gets that much longer. No cards, labelled A-roll in the editor. Items: \"@clip\" or {\"media\": \"@clip\", \"after\": \"<a line of the script, quoted exactly>\"} (or \"before\": ..., or \"placement\": \"at 2:00\" / \"halfway\" / \"after chapter 2\"). The clip plays at the end of the sentence holding that line; a line the script does not say is refused (code aroll_line_not_in_script). Each clip: a video of at most 3 minutes (trim it first), or an AUDIO file (a call, a voicemail, a podcast or radio quote): it plays over a full-frame waveform card (recorder, clock, playhead) with its words typed as they are heard: give them as \"says\": \"...\" or Cliptude transcribes it. Upload one with start_library_upload / upload_to_library / import_media. Write the narration so it leads into the clip and do not narrate what the clip says. Billed like a sponsor's seconds (render-only rate). Works on plan jobs too (do not plan a shot for it)."),
1671
+ ] = None,
1528
1672
  brand_kit_id: Annotated[
1529
1673
  int | None,
1530
1674
  Field(description="A brand kit for this video only (id from list_brand_kits), overriding the template's: its colours and fonts on the graphics, its channel name and handle on the subscribe card, and its logo when the template shows the logo. 0 = no kit of its own (the user's default kit). Omit to keep the template's. People with several channels: ask which channel the video is for."),
@@ -1569,6 +1713,7 @@ def build_server(*, with_http_auth: bool = False):
1569
1713
  sponsor=sponsor,
1570
1714
  sponsor_placement=sponsor_placement,
1571
1715
  sponsor_bumpers=sponsor_bumpers,
1716
+ aroll=aroll,
1572
1717
  brand_kit_id=brand_kit_id,
1573
1718
  )
1574
1719
  except Exception as exc:
@@ -1714,13 +1859,14 @@ def build_server(*, with_http_auth: bool = False):
1714
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."),
1715
1860
  ],
1716
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,
1717
1863
  ) -> dict[str, Any]:
1718
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."""
1719
1865
  refused = _local_path_refused(remote, ("path", path))
1720
1866
  if refused:
1721
1867
  return refused
1722
1868
  try:
1723
- 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)
1724
1870
  except Exception as exc:
1725
1871
  return _err(exc)
1726
1872
 
@@ -1751,10 +1897,12 @@ def build_server(*, with_http_auth: bool = False):
1751
1897
  key: Annotated[str, Field(min_length=1, description="key from start_media_upload")],
1752
1898
  upload_id: Annotated[str, Field(min_length=1, description="upload_id from start_media_upload")],
1753
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,
1754
1901
  ) -> dict[str, Any]:
1755
- """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."""
1756
1903
  try:
1757
- 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)
1758
1906
  except Exception as exc:
1759
1907
  return _err(exc)
1760
1908
 
@@ -1953,7 +2101,7 @@ def build_server(*, with_http_auth: bool = False):
1953
2101
  "catalog prop_schema); {op:'set_type', item_id, animation_type, props?} (another design, same timing); "
1954
2102
  "{op:'set_picture', item_id, keep|url} (a graphic's picture slot, or a clip's or image's file); "
1955
2103
  "{op:'mute_cues', item_id} (silence a graphic's own sound cues); {op:'add_graphic', animation_type, "
1956
- "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); "
1957
2105
  "{op:'set_transition', from_id, to_id, kind, direction?, duration_s?} (the join between two clips; "
1958
2106
  "kind 'none' removes it); {op:'set_captions', enabled:true|false} (captions are off by default on every "
1959
2107
  "video; this shows or hides them all); {op:'set_caption_style', style:{color, activeColor, appearedColor, "
@@ -1964,7 +2112,9 @@ def build_server(*, with_http_auth: bool = False):
1964
2112
  "get_kind_catalog sounds); {op:'add_sponsor', media_id, at_s?|placement?, bumpers?} (a media-library "
1965
2113
  "video, id from list_media, spliced in as a sponsored segment with its own sound: the narration pauses "
1966
2114
  "for it; at_s is a narration second snapped to a sentence end, placement words like 'after the intro', "
1967
- "'halfway', 'before the ending'; omit both for Cliptude's choice); {op:'move_sponsor', segment_id?, "
2115
+ "'halfway', 'before the ending'; omit both for Cliptude's choice); {op:'add_aroll', media_id, "
2116
+ "at_s?|placement?} (the same splice for the user's own A-roll clip of someone speaking: no cards, "
2117
+ "labelled A-roll; placement may also be 'after \"<a line of the narration>\"'); {op:'move_sponsor', segment_id?, "
1968
2118
  "at_s?|placement?}; {op:'remove_sponsor', segment_id?} (segment ids in the design's "
1969
2119
  "metadata.sponsorSegments; the sponsor's own items cannot be deleted or retimed one by one). "
1970
2120
  "set_props on a text item sets text, color, fontSize, fontWeight, textAlign. "
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.52",
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.52"
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"