@cliptude/cli 0.1.52 → 0.1.53

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)."""
@@ -269,6 +269,26 @@ def _brand_kit_fields_from_args(args) -> dict:
269
269
  return fields
270
270
 
271
271
 
272
+ def _run_media(client: CliptudeClient, args) -> None:
273
+ cmd = args.media_cmd
274
+ if cmd == "list":
275
+ _print(client.list_media(folder=args.folder, kind=args.kind or None, limit=args.limit, offset=args.offset))
276
+ elif cmd == "upload":
277
+ if len(args.paths) > 50:
278
+ raise CliptudeApiError("Upload at most 50 files a run.")
279
+ if args.name and len(args.paths) != 1:
280
+ raise CliptudeApiError("--name names one file: upload one file with it.")
281
+ if args.name:
282
+ _print(client.upload_to_library(args.paths[0], folder=args.folder, name=args.name))
283
+ return
284
+ result = client.upload_many_to_library(args.paths, folder=args.folder)
285
+ _print(result)
286
+ if result.get("failed"):
287
+ raise SystemExit(1)
288
+ elif cmd == "import":
289
+ _print(client.import_media(url=args.url, folder=args.folder, name=args.name))
290
+
291
+
272
292
  def _run_brand_kit(client: CliptudeClient, args) -> None:
273
293
  cmd = args.bk_cmd
274
294
  if cmd == "list":
@@ -314,10 +334,53 @@ def _add_sponsor_args(parser: argparse.ArgumentParser) -> None:
314
334
  "--no-sponsor-bumpers leaves them out)")
315
335
 
316
336
 
337
+ def _add_aroll_args(parser: argparse.ArgumentParser, *, include: bool = True) -> None:
338
+ parser.add_argument(
339
+ "--aroll", action="append", default=[], metavar="SPEC",
340
+ help='Your own A-roll clip, played with its own sound (the narration pauses for it): a media-library video '
341
+ 'or audio file and, optionally, where and what it says, e.g. '
342
+ '\'@kress_cnbc after "they refused to take any more questions"\' or '
343
+ '\'@phone_call halfway says "We will not reinstate him"\'. A quoted line must be in the script word for '
344
+ 'word. JSON works too: \'{"media": "@clip", "after": "a line"}\'. Repeatable, up to 4; at most 3 '
345
+ 'minutes each. Upload clips with `cliptude media upload`.')
346
+ if include:
347
+ parser.add_argument(
348
+ "--include-aroll", action=argparse.BooleanOptionalAction, default=None,
349
+ help="Cliptude's own A-roll inserts (Faceless Documentary): it finds 2-4 clips of people speaking on "
350
+ "YouTube and splices them in with their sound. --no-include-aroll turns them off. Default: the "
351
+ "template's setting.")
352
+
353
+
354
+ def _aroll_from_args(args) -> list | None:
355
+ """--aroll SPEC values: '@clip <placement words>' or a JSON object."""
356
+ out = []
357
+ for spec in getattr(args, "aroll", None) or []:
358
+ spec = str(spec or "").strip()
359
+ if not spec:
360
+ continue
361
+ if spec.startswith("{"):
362
+ try:
363
+ item = json.loads(spec)
364
+ except ValueError as exc:
365
+ raise CliptudeApiError(f"--aroll is not valid JSON: {exc}") from exc
366
+ if not isinstance(item, dict):
367
+ raise CliptudeApiError("--aroll JSON must be an object, like {\"media\": \"@clip\", \"after\": \"a line\"}.")
368
+ out.append(item)
369
+ continue
370
+ media, _, where = spec.partition(" ")
371
+ out.append({"media": media, "placement": where.strip()} if where.strip() else media)
372
+ return out or None
373
+
374
+
317
375
  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)}
376
+ """The sponsor, A-roll and include-A-roll flags, shared by estimate, generate and plan-job."""
377
+ out = {"sponsor": getattr(args, "sponsor", None) or None,
378
+ "sponsor_placement": getattr(args, "sponsor_placement", None) or None,
379
+ "sponsor_bumpers": getattr(args, "sponsor_bumpers", None),
380
+ "aroll": _aroll_from_args(args)}
381
+ if getattr(args, "include_aroll", None) is not None:
382
+ out["include_aroll"] = args.include_aroll
383
+ return out
321
384
 
322
385
 
323
386
  def _add_voice_setting_args(parser: argparse.ArgumentParser) -> None:
@@ -673,6 +736,34 @@ def main(argv: list[str] | None = None) -> None:
673
736
  dcl = dc_sub.add_parser("list", help="Every docs page: slug, title, category")
674
737
  dcl.add_argument("--category", default="", help="Only this sidebar group (Getting Started, Guides, Editor, ...)")
675
738
  dcl.add_argument("--json", action="store_true", help="Print the JSON response")
739
+ md = sub.add_parser(
740
+ "media",
741
+ help="Your media library: list, upload files (clips, pictures, audio), import a public link",
742
+ formatter_class=argparse.RawDescriptionHelpFormatter,
743
+ epilog=(
744
+ "examples:\n"
745
+ " cliptude media list --folder jensen_followup\n"
746
+ " cliptude media upload ./jensen.mp4 ./shots/*.png --folder jensen_followup\n"
747
+ " cliptude media upload ./kress.mp4 --name kress_cnbc.mp4\n"
748
+ " cliptude media import https://example.com/clip.mp4 --folder b_roll\n"
749
+ "Each file comes back with its @tag (kress_cnbc.mp4 -> @kress_cnbc) for --prompt, --aroll or --sponsor.\n"
750
+ "Limits: pictures 15 MB, clips 300 MB, audio 95 MB."
751
+ ),
752
+ )
753
+ md_sub = md.add_subparsers(dest="media_cmd", required=True)
754
+ mdl = md_sub.add_parser("list", help="List your media library (each file's url and @tag)")
755
+ mdl.add_argument("--folder", default=None, help="Only this folder ('' = files in no folder)")
756
+ mdl.add_argument("--kind", default="", choices=["", "image", "video", "audio"], help="Only this kind")
757
+ mdl.add_argument("--limit", type=int, default=50)
758
+ mdl.add_argument("--offset", type=int, default=0)
759
+ mdu = md_sub.add_parser("upload", help="Upload local files to your media library (up to 50 a run)")
760
+ mdu.add_argument("paths", nargs="+", help="Files: pictures, clips (MP4, MOV, WebM) or audio")
761
+ mdu.add_argument("--folder", default=None, help="Library folder for all of them (tag it as @folder_name)")
762
+ mdu.add_argument("--name", default=None, help="A name (its @tag) when you upload one file")
763
+ mdi = md_sub.add_parser("import", help="Download a public https link to a file into your media library")
764
+ mdi.add_argument("url")
765
+ mdi.add_argument("--folder", default=None, help="Library folder")
766
+ mdi.add_argument("--name", default=None, help="File name with extension (its @tag), needed when the link has none")
676
767
  bk = sub.add_parser(
677
768
  "brand-kit",
678
769
  help="Brand kits (one per channel): list, options, get, create, update, set-default, delete",
@@ -815,6 +906,7 @@ def main(argv: list[str] | None = None) -> None:
815
906
  _add_captions_arg(est, scope="this video")
816
907
  _add_job_look_arg(est)
817
908
  _add_sponsor_args(est)
909
+ _add_aroll_args(est)
818
910
  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
911
 
820
912
  g = sub.add_parser(
@@ -935,6 +1027,7 @@ def main(argv: list[str] | None = None) -> None:
935
1027
  _add_captions_arg(g, scope="this video")
936
1028
  _add_job_look_arg(g)
937
1029
  _add_sponsor_args(g)
1030
+ _add_aroll_args(g)
938
1031
  g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
939
1032
 
940
1033
  sc = sub.add_parser(
@@ -1058,6 +1151,7 @@ def main(argv: list[str] | None = None) -> None:
1058
1151
  _add_captions_arg(pj, scope="this video")
1059
1152
  _add_job_look_arg(pj)
1060
1153
  _add_sponsor_args(pj)
1154
+ _add_aroll_args(pj, include=False)
1061
1155
  pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
1062
1156
 
1063
1157
  nr = sub.add_parser("narration", help="Numbered sentences and word timings of a plan_ready job")
@@ -1222,6 +1316,8 @@ def main(argv: list[str] | None = None) -> None:
1222
1316
  _print(client.list_brand_kits())
1223
1317
  elif args.cmd == "brand-kit":
1224
1318
  _run_brand_kit(client, args)
1319
+ elif args.cmd == "media":
1320
+ _run_media(client, args)
1225
1321
  elif args.cmd == "voice-design":
1226
1322
  _run_voice_design(client, args)
1227
1323
  elif args.cmd == "template-options":
@@ -337,6 +337,54 @@ def merge_sponsor(prompt: str | None, sponsor: str | None, placement: str | None
337
337
  return f"{text}\n\n{sentence}".strip() if text else sentence
338
338
 
339
339
 
340
+ MAX_AROLLS = 4
341
+
342
+
343
+ def merge_aroll(prompt: str | None, aroll: Any) -> str | None:
344
+ """The prompt with one "A-roll: @clip after "<a line of the script>"." sentence per ``aroll`` item: the user's own
345
+ clip of someone speaking, spliced in between two sentences with its own sound (the narration pauses for it).
346
+ Items: "@clip" or {"media": "@clip", "placement": 'after "a line"'} (or "after": "a line"). The server reads the
347
+ sentence (videos/sponsor_segments.py) and refuses a line the script does not say."""
348
+ import re as _re
349
+
350
+ text = (prompt or "").strip()
351
+ items = aroll if isinstance(aroll, (list, tuple)) else ([aroll] if aroll else [])
352
+ if len(items) > MAX_AROLLS:
353
+ raise CliptudeApiError(f"A video can have at most {MAX_AROLLS} A-roll clips; you sent {len(items)}.")
354
+ sentences = []
355
+ for item in items:
356
+ if isinstance(item, dict):
357
+ raw = str(item.get("media") or item.get("file") or item.get("token") or "")
358
+ where = str(item.get("placement") or "")
359
+ if not where and item.get("after"):
360
+ where = f'after "{item["after"]}"'
361
+ if not where and item.get("before"):
362
+ where = f'before "{item["before"]}"'
363
+ says = str(item.get("says") or item.get("transcript") or "").strip()
364
+ if says:
365
+ where = f'{where} says "{says}"'.strip()
366
+ else:
367
+ raw, where = str(item or ""), ""
368
+ raw = raw.strip().lstrip("@")
369
+ token = _re.sub(r"[^0-9a-z]+", "_", _re.sub(r"\.[A-Za-z0-9]{2,4}$", "", raw).lower()).strip("_")
370
+ if not token:
371
+ raise CliptudeApiError("Each aroll item names a media-library video, like @kress_interview.")
372
+ if f"@{token}" in text.lower() and _re.search(r"\ba[- ]?roll", text, _re.I):
373
+ continue
374
+ # . ! ? inside a quoted line would end the tag's sentence early on the server; the line matches without them.
375
+ where = _re.sub(r'(["“])([^"“”]*)(["”])',
376
+ lambda q: q.group(1) + " ".join(_re.sub(r"[.!?…\n]+", " ", q.group(2)).split()) + q.group(3),
377
+ where)
378
+ where = " ".join(where.split()).strip().rstrip(".")
379
+ if _re.fullmatch(r"(?i)auto(matic)?|anywhere|", where):
380
+ where = ""
381
+ sentences.append(f"A-roll: @{token}" + (f" {where}" if where else "") + ".")
382
+ if not sentences:
383
+ return text or None
384
+ joined = "\n".join(sentences)
385
+ return f"{text}\n\n{joined}".strip() if text else joined
386
+
387
+
340
388
  def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
341
389
  *, as_strings: bool = False) -> dict[str, Any]:
342
390
  """The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
@@ -709,6 +757,69 @@ class CliptudeClient:
709
757
  pass
710
758
  raise
711
759
 
760
+ # --- media library uploads (pictures, clips, audio; videos/library_upload.py) -------------------------------
761
+
762
+ def start_library_upload(self, *, filename: str, size: int, content_type: str | None = None) -> dict[str, Any]:
763
+ """Signed PUT URLs for one media-library file (picture up to 15 MB, clip up to 300 MB, audio up to 95 MB),
764
+ for a host that sends the bytes itself."""
765
+ return self._start_signed_upload("/api/v1/uploads/library", filename=filename, size=size,
766
+ content_type=content_type)
767
+
768
+ 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
+ body: dict[str, Any] = {"key": key, "upload_id": upload_id}
772
+ if folder:
773
+ body["folder"] = folder
774
+ if name:
775
+ body["name"] = name
776
+ return self.request("POST", "/api/v1/uploads/library/complete", json_body=body,
777
+ timeout=max(self.timeout, 180.0))
778
+
779
+ def abort_library_upload(self, *, key: str, upload_id: str) -> Any:
780
+ return self.request("POST", "/api/v1/uploads/library/abort", json_body={"key": key, "upload_id": upload_id})
781
+
782
+ def upload_to_library(self, path: str | Path, *, folder: str | None = None, name: str | None = None) -> Any:
783
+ """Upload one local file to the media library through the signed-URL flow; returns {media_id, tag, url, ...}."""
784
+ path = self._local_file(path, "path")
785
+ if not path.is_file():
786
+ raise CliptudeApiError(f"File not found: {path}")
787
+ init = self.request("POST", "/api/v1/uploads/library/init", json_body={
788
+ "filename": path.name,
789
+ "size": path.stat().st_size,
790
+ "content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
791
+ })
792
+ body = {"key": (init or {}).get("key"), "upload_id": (init or {}).get("upload_id")}
793
+ try:
794
+ 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)
796
+ except Exception:
797
+ try:
798
+ self.request("POST", "/api/v1/uploads/library/abort", json_body=body)
799
+ except Exception:
800
+ pass
801
+ raise
802
+
803
+ def upload_many_to_library(self, paths: list[str | Path], *, folder: str | None = None) -> dict[str, Any]:
804
+ """Upload several local files (one at a time; a failure does not stop the rest). Returns
805
+ {uploaded: [...], failed: [{path, error}]}."""
806
+ uploaded, failed = [], []
807
+ for p in paths:
808
+ try:
809
+ uploaded.append(self.upload_to_library(p, folder=folder))
810
+ except Exception as exc: # one bad file must not lose the others
811
+ failed.append({"path": str(p), "error": str(exc)})
812
+ return {"uploaded": uploaded, "failed": failed}
813
+
814
+ def import_media(self, *, url: str, folder: str | None = None, name: str | None = None) -> Any:
815
+ """Download a public https link (picture, clip or audio) into the media library."""
816
+ body: dict[str, Any] = {"url": url}
817
+ if folder:
818
+ body["folder"] = folder
819
+ if name:
820
+ body["name"] = name
821
+ return self.request("POST", "/api/v1/media/import", json_body=body, timeout=max(self.timeout, 180.0))
822
+
712
823
  def list_media(self, *, folder: str | None = None, kind: str | None = None, limit: int = 50,
713
824
  offset: int = 0) -> Any:
714
825
  """The user's media library (images, clips, audio; shared with the editor's uploads)."""
@@ -815,11 +926,13 @@ class CliptudeClient:
815
926
  sponsor: str | None = None,
816
927
  sponsor_placement: str | None = None,
817
928
  sponsor_bumpers: bool | None = None,
929
+ aroll: Any = None,
930
+ include_aroll: bool | None = None,
818
931
  ) -> Any:
819
932
  if voiceover_path and voiceover_url:
820
933
  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)
934
+ # A sponsored segment and A-roll clips are sentences in the description, the same on every path.
935
+ prompt = merge_aroll(merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers), aroll)
823
936
  # visual_direction is deprecated: the description (prompt) carries the visual direction. Older callers still
824
937
  # send it, so it is appended to the prompt here, the same on every path (JSON, voiceover upload, talking head).
825
938
  prompt = merge_visual_direction(prompt, visual_direction)
@@ -913,6 +1026,7 @@ class CliptudeClient:
913
1026
  **({"captions": "true" if captions else "false"} if captions is not None else {}),
914
1027
  **({"look": str(look).strip() or "none"} if look is not None else {}),
915
1028
  **({"brand_kit_id": str(int(brand_kit_id))} if brand_kit_id is not None else {}),
1029
+ **({"include_aroll": "true" if include_aroll else "false"} if include_aroll is not None else {}),
916
1030
  **({"prompt": prompt} if prompt else {}),
917
1031
  **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
918
1032
  }
@@ -939,6 +1053,8 @@ class CliptudeClient:
939
1053
  body["voiceover_url"] = str(voiceover_url).strip()
940
1054
  if render_only:
941
1055
  body["render_only"] = True
1056
+ if include_aroll is not None:
1057
+ body["include_aroll"] = bool(include_aroll)
942
1058
  body.update(_avatar_job_fields(
943
1059
  avatar_intro_only, avatar_ai_footage,
944
1060
  avatar_profile_id=avatar_profile_id, avatar_engine=avatar_engine,
@@ -1636,10 +1752,14 @@ class CliptudeClient:
1636
1752
  sponsor_placement: str | None = None,
1637
1753
  sponsor_bumpers: bool | None = None,
1638
1754
  brand_kit_id: int | None = None,
1755
+ aroll: Any = None,
1756
+ include_aroll: bool | None = None,
1639
1757
  ) -> Any:
1640
1758
  """Credits a job would need; creates nothing."""
1641
- prompt = merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers)
1759
+ prompt = merge_aroll(merge_sponsor(prompt, sponsor, sponsor_placement, sponsor_bumpers), aroll)
1642
1760
  body: dict[str, Any] = {"template_id": template_id}
1761
+ if include_aroll is not None:
1762
+ body["include_aroll"] = bool(include_aroll)
1643
1763
  if captions is not None:
1644
1764
  body["captions"] = bool(captions)
1645
1765
  if look is not None:
@@ -321,6 +321,10 @@ def build_server(*, with_http_auth: bool = False):
321
321
  "can lower video quality a lot; no_video_footage; no_motion_graphics; no_music; no_sound_effects; "
322
322
  "no_transitions) tell the user what it costs and pass "
323
323
  "its id in acknowledge only after they explicitly approve; otherwise fix the template. "
324
+ "unverified_subjects means Cliptude couldn't confirm the named people, places or events are real (it may "
325
+ "be a fictional story, or a real one too little covered for Cliptude to know): ask the user whether it is a "
326
+ "true story and pass it only if they say yes. A content policy refusal (code content_policy) is final: "
327
+ "there is nothing to acknowledge. "
324
328
  "In hosts that show MCP Apps the review appears as a card with every setting, warning, acknowledgement "
325
329
  "checkbox and the credits: the user confirms there with a click (the card resends the call itself, or saves "
326
330
  "\"I confirm: ... review_token=... acknowledge=...\", which get_choice returns when they then say next, for "
@@ -817,6 +821,75 @@ def build_server(*, with_http_auth: bool = False):
817
821
  except Exception as exc:
818
822
  return _err(exc)
819
823
 
824
+ @mcp.tool(
825
+ title="Start library upload",
826
+ annotations=ToolAnnotations(title="Start library upload", read_only_hint=False, destructive_hint=False,
827
+ open_world_hint=False),
828
+ )
829
+ 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`).")],
832
+ 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)
837
+ out["next"] = "PUT every part to its url, then finish_library_upload(key, upload_id, folder?)."
838
+ return out
839
+ except Exception as exc:
840
+ return _err(exc)
841
+
842
+ @mcp.tool(
843
+ title="Finish library upload",
844
+ annotations=ToolAnnotations(title="Finish library upload", read_only_hint=False, destructive_hint=False,
845
+ open_world_hint=False),
846
+ )
847
+ 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)
856
+ except Exception as exc:
857
+ return _err(exc)
858
+
859
+ @mcp.tool(
860
+ title="Upload to media library",
861
+ annotations=ToolAnnotations(title="Upload to media library", read_only_hint=False, destructive_hint=False,
862
+ idempotent_hint=False, open_world_hint=False),
863
+ )
864
+ 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.")],
866
+ folder: Annotated[str | None, Field(max_length=80, description="Library folder for all of them (e.g. jensen_followup).")] = None,
867
+ ) -> dict[str, Any]:
868
+ """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
+ refused = _local_path_refused(remote, ("paths", " ".join(paths or [])))
870
+ if refused:
871
+ return refused
872
+ try:
873
+ return _client().upload_many_to_library(paths, folder=folder)
874
+ except Exception as exc:
875
+ return _err(exc)
876
+
877
+ @mcp.tool(
878
+ title="Import media from a link",
879
+ annotations=ToolAnnotations(title="Import media from a link", read_only_hint=False, destructive_hint=False,
880
+ idempotent_hint=False, open_world_hint=True),
881
+ )
882
+ def import_media(
883
+ 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
+ folder: Annotated[str | None, Field(max_length=80, description="Library folder to keep it in.")] = None,
885
+ 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,
886
+ ) -> dict[str, Any]:
887
+ """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
+ try:
889
+ return _client().import_media(url=url, folder=folder, name=name)
890
+ except Exception as exc:
891
+ return _err(exc)
892
+
820
893
  @mcp.tool(
821
894
  title="List media library",
822
895
  annotations=ToolAnnotations(title="List media library", read_only_hint=True, open_world_hint=False),
@@ -895,6 +968,14 @@ def build_server(*, with_http_auth: bool = False):
895
968
  bool | None,
896
969
  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
970
  ] = None,
971
+ aroll: Annotated[
972
+ list[Any] | None,
973
+ 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)."),
974
+ ] = None,
975
+ include_aroll: Annotated[
976
+ bool | None,
977
+ 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."),
978
+ ] = None,
898
979
  brand_kit_id: Annotated[
899
980
  int | None,
900
981
  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 +1010,8 @@ def build_server(*, with_http_auth: bool = False):
929
1010
  sponsor=sponsor,
930
1011
  sponsor_placement=sponsor_placement,
931
1012
  sponsor_bumpers=sponsor_bumpers,
1013
+ aroll=aroll,
1014
+ include_aroll=include_aroll,
932
1015
  brand_kit_id=brand_kit_id,
933
1016
  )
934
1017
  except Exception as exc:
@@ -1158,6 +1241,14 @@ def build_server(*, with_http_auth: bool = False):
1158
1241
  bool | None,
1159
1242
  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
1243
  ] = None,
1244
+ aroll: Annotated[
1245
+ list[Any] | None,
1246
+ 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)."),
1247
+ ] = None,
1248
+ include_aroll: Annotated[
1249
+ bool | None,
1250
+ 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."),
1251
+ ] = None,
1161
1252
  brand_kit_id: Annotated[
1162
1253
  int | None,
1163
1254
  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 +1316,8 @@ def build_server(*, with_http_auth: bool = False):
1225
1316
  sponsor=sponsor,
1226
1317
  sponsor_placement=sponsor_placement,
1227
1318
  sponsor_bumpers=sponsor_bumpers,
1319
+ aroll=aroll,
1320
+ include_aroll=include_aroll,
1228
1321
  brand_kit_id=brand_kit_id,
1229
1322
  )
1230
1323
  except Exception as exc:
@@ -1525,6 +1618,10 @@ def build_server(*, with_http_auth: bool = False):
1525
1618
  bool | None,
1526
1619
  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
1620
  ] = None,
1621
+ aroll: Annotated[
1622
+ list[Any] | None,
1623
+ 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)."),
1624
+ ] = None,
1528
1625
  brand_kit_id: Annotated[
1529
1626
  int | None,
1530
1627
  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 +1666,7 @@ def build_server(*, with_http_auth: bool = False):
1569
1666
  sponsor=sponsor,
1570
1667
  sponsor_placement=sponsor_placement,
1571
1668
  sponsor_bumpers=sponsor_bumpers,
1669
+ aroll=aroll,
1572
1670
  brand_kit_id=brand_kit_id,
1573
1671
  )
1574
1672
  except Exception as exc:
@@ -1964,7 +2062,9 @@ def build_server(*, with_http_auth: bool = False):
1964
2062
  "get_kind_catalog sounds); {op:'add_sponsor', media_id, at_s?|placement?, bumpers?} (a media-library "
1965
2063
  "video, id from list_media, spliced in as a sponsored segment with its own sound: the narration pauses "
1966
2064
  "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?, "
2065
+ "'halfway', 'before the ending'; omit both for Cliptude's choice); {op:'add_aroll', media_id, "
2066
+ "at_s?|placement?} (the same splice for the user's own A-roll clip of someone speaking: no cards, "
2067
+ "labelled A-roll; placement may also be 'after \"<a line of the narration>\"'); {op:'move_sponsor', segment_id?, "
1968
2068
  "at_s?|placement?}; {op:'remove_sponsor', segment_id?} (segment ids in the design's "
1969
2069
  "metadata.sponsorSegments; the sponsor's own items cannot be deleted or retimed one by one). "
1970
2070
  "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.53",
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.53"
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"