@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 +6 -0
- package/cliptude_mcp/cli.py +100 -4
- package/cliptude_mcp/client.py +123 -3
- package/cliptude_mcp/server.py +101 -1
- package/package.json +1 -1
- package/pyproject.toml +1 -1
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`.
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -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
|
-
|
|
319
|
-
|
|
320
|
-
|
|
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":
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -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
|
|
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:
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -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:'
|
|
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
package/pyproject.toml
CHANGED