@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 +6 -0
- package/cliptude_mcp/cli.py +119 -5
- package/cliptude_mcp/client.py +144 -9
- package/cliptude_mcp/server.py +155 -5
- 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)."""
|
|
@@ -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
|
-
|
|
319
|
-
|
|
320
|
-
|
|
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)
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -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;
|
|
162
|
-
"
|
|
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
|
|
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
|
|
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
|
|
1363
|
-
|
|
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:
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -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:'
|
|
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
package/pyproject.toml
CHANGED