@cliptude/cli 0.1.19 → 0.1.30
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 +32 -2
- package/cliptude_mcp/apps.py +311 -0
- package/cliptude_mcp/cli.py +103 -21
- package/cliptude_mcp/client.py +288 -66
- package/cliptude_mcp/creation.py +207 -0
- package/cliptude_mcp/credentials.py +31 -5
- package/cliptude_mcp/server.py +285 -77
- package/cliptude_mcp/widgets/avatars.html +287 -0
- package/cliptude_mcp/widgets/base.css +123 -0
- package/cliptude_mcp/widgets/bridge.js +314 -0
- package/cliptude_mcp/widgets/characters.html +108 -0
- package/cliptude_mcp/widgets/choices.html +230 -0
- package/cliptude_mcp/widgets/player.html +126 -0
- package/cliptude_mcp/widgets/publish-kit.html +170 -0
- package/cliptude_mcp/widgets/voices.html +436 -0
- package/package.json +1 -1
- package/pyproject.toml +4 -4
package/README.md
CHANGED
|
@@ -17,6 +17,27 @@ pip install -e .
|
|
|
17
17
|
cliptude auth login
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
+
## Cliptude desktop app
|
|
21
|
+
|
|
22
|
+
The desktop app ships this CLI and MCP server, so nothing needs installing: in the app, open
|
|
23
|
+
**Settings → Connect an AI assistant** and click **Add** for Claude Desktop or Cursor, or copy the
|
|
24
|
+
command for Claude Code or Codex. Videos are then made in the app with your own provider keys.
|
|
25
|
+
ChatGPT only connects to servers on the internet, so it uses cliptude.com.
|
|
26
|
+
|
|
27
|
+
Where the CLI and MCP send jobs:
|
|
28
|
+
|
|
29
|
+
| | |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `cliptude use desktop` | the running desktop app (fails with "Open Cliptude" when it is closed) |
|
|
32
|
+
| `cliptude use cloud` | cliptude.com |
|
|
33
|
+
| `cliptude use auto` (default) | the desktop app while it is running, else cliptude.com |
|
|
34
|
+
| `cliptude use` | show where jobs go now |
|
|
35
|
+
|
|
36
|
+
`CLIPTUDE_TARGET` overrides the saved choice, and `CLIPTUDE_BASE_URL` overrides both. The app's port
|
|
37
|
+
changes every launch: the CLI reads it from `desktop-runtime.json` and its key from `local-api.json`
|
|
38
|
+
in the app's data folder. The desktop gets only that local key and cliptude.com only your cliptude.com
|
|
39
|
+
login. A `CLIPTUDE_API_KEY` in the environment, without `CLIPTUDE_TARGET`, means cliptude.com.
|
|
40
|
+
|
|
20
41
|
## Commands
|
|
21
42
|
|
|
22
43
|
```bash
|
|
@@ -54,7 +75,13 @@ To revise a finished video, `editor` opens its timeline (item ids, times, text),
|
|
|
54
75
|
On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates an agent can plan every visual and leave Cliptude
|
|
55
76
|
only the voicing, sourcing and rendering:
|
|
56
77
|
|
|
57
|
-
1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`.
|
|
78
|
+
1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`. Like every job, it answers first with a
|
|
79
|
+
review of its settings; music, sound effects, transitions, animations and web sources are on by default, and any the
|
|
80
|
+
template turns off (`no_music`, `no_sound_effects`, `no_transitions`, `no_motion_graphics`, ...) need the user's
|
|
81
|
+
approval in `--acknowledge`.
|
|
82
|
+
Your own footage: `cliptude upload-media <job> trailer.mp4 --split-shots` cuts a whole source into checked 3-12 s
|
|
83
|
+
clips on its cuts and prints their keep ids; each upload's notes say what the build review would report (a
|
|
84
|
+
watermark, an end screen, captions).
|
|
58
85
|
2. `cliptude catalog --compact`, then `--types a,b` for full entries (`--premium` lists only the premium boards).
|
|
59
86
|
3. `cliptude plan-check <job> plan.json` until valid, `cliptude plan-lock <job> plan.json`, `cliptude continue <job>`.
|
|
60
87
|
The job stops at `ready_for_edit`: built and charged, not rendered.
|
|
@@ -64,11 +91,14 @@ only the voicing, sourcing and rendering:
|
|
|
64
91
|
media reused, nothing more charged.
|
|
65
92
|
6. Render once: `cliptude editor <job>`, `cliptude render <project> --wait`.
|
|
66
93
|
|
|
94
|
+
Aim for two builds: one to review, one to ship. The skill's "One pass" section has the order of work (footage budget,
|
|
95
|
+
sources split by shot, people's photos first, picture assignment by script, person-card caps).
|
|
96
|
+
|
|
67
97
|
MCP tools: `create_plan_job`, `get_narration`, `get_kind_catalog`, `check_plan`, `lock_plan`, `get_plan`,
|
|
68
98
|
`continue_job`, `get_plan_review`, `get_plan_report`, then `open_editor_project` and `render_project`.
|
|
69
99
|
The plan sets the look (theme, style, colours, music), every graphic with its own data, colours and sound, the
|
|
70
100
|
footage under every beat, the transition on each cut, two-image reveals, and free sound effects; `get_kind_catalog`
|
|
71
|
-
lists the graphics, `transitions`, `reveal_styles` and `sounds` (with previews). The plan schema and rules are in
|
|
101
|
+
lists the graphics, `transitions`, `reveal_styles`, `clip_effects` and `sounds` (with previews). The plan schema and rules are in
|
|
72
102
|
`skills/cliptude-plan/SKILL.md`. The job costs the same as the website price.
|
|
73
103
|
|
|
74
104
|
### Product videos from a store
|
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
"""MCP Apps (interactive widgets) for hosts that render them: Claude Desktop, claude.ai.
|
|
2
|
+
|
|
3
|
+
Spec: https://modelcontextprotocol.io/specification/draft/extensions/apps (SEP-1865, `io.modelcontextprotocol/ui`).
|
|
4
|
+
|
|
5
|
+
Each widget is a `ui://cliptude/...` HTML resource (served as `text/html;profile=mcp-app`) that the host shows in a
|
|
6
|
+
sandboxed iframe next to a tool's result:
|
|
7
|
+
|
|
8
|
+
- list_avatars -> ui://cliptude/avatars.html avatar thumbnails, pick one
|
|
9
|
+
- list_voices -> ui://cliptude/voices.html play voice previews, pick one
|
|
10
|
+
- list_vector_characters -> ui://cliptude/characters.html Vector Explainer cast and uploads, pick one
|
|
11
|
+
- get_render, get_product_video_status, show_video
|
|
12
|
+
-> ui://cliptude/player.html watch the MP4, or "not rendered yet"
|
|
13
|
+
- show_choices -> ui://cliptude/choices.html music (play), backgrounds, style packs, themes, captions
|
|
14
|
+
- show_publish_kit -> ui://cliptude/publish-kit.html thumbnails, title ideas, description, chapters, tags
|
|
15
|
+
|
|
16
|
+
The existing tools keep their names, parameters and JSON (the text content stays the same for clients without
|
|
17
|
+
Apps); only `_meta.ui.resourceUri` is added to them (`bind_existing_tools`). show_choices, show_video and
|
|
18
|
+
show_publish_kit are new, thin tools: binding a widget to get_template_options, get_job or the editor-project
|
|
19
|
+
tools would draw a widget on every one of their (frequent, polling) calls.
|
|
20
|
+
|
|
21
|
+
A widget picks by posting a `ui/message` into the chat ("Use the voice ... (voice_id ...)"), so the model gets the
|
|
22
|
+
id without the user typing it. The avatar and voice pickers can also make new ones in the chat (create_avatar,
|
|
23
|
+
design_voice_previews / save_designed_voice, clone_voice in creation.py), calling those tools with `tools/call`.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
from collections.abc import Callable
|
|
29
|
+
from importlib import resources
|
|
30
|
+
from typing import Annotated, Any
|
|
31
|
+
|
|
32
|
+
from pydantic import Field
|
|
33
|
+
|
|
34
|
+
try: # mcp >= 2.3 ships the Apps extension; older SDKs simply serve no widgets.
|
|
35
|
+
from mcp.server.apps import APP_MIME_TYPE, Apps, ResourceCsp, ResourcePermissions
|
|
36
|
+
except ImportError: # pragma: no cover - exercised only on an old SDK
|
|
37
|
+
Apps = None # type: ignore[assignment,misc]
|
|
38
|
+
APP_MIME_TYPE = "text/html;profile=mcp-app"
|
|
39
|
+
ResourceCsp = ResourcePermissions = None # type: ignore[assignment,misc]
|
|
40
|
+
|
|
41
|
+
AVATARS_URI = "ui://cliptude/avatars.html"
|
|
42
|
+
VOICES_URI = "ui://cliptude/voices.html"
|
|
43
|
+
CHARACTERS_URI = "ui://cliptude/characters.html"
|
|
44
|
+
PLAYER_URI = "ui://cliptude/player.html"
|
|
45
|
+
CHOICES_URI = "ui://cliptude/choices.html"
|
|
46
|
+
PUBLISH_KIT_URI = "ui://cliptude/publish-kit.html"
|
|
47
|
+
|
|
48
|
+
# uri -> (file, name, description)
|
|
49
|
+
WIDGETS: dict[str, tuple[str, str, str]] = {
|
|
50
|
+
AVATARS_URI: ("avatars.html", "Avatar picker", "Avatar thumbnails to pick the presenter of an Avatar Video."),
|
|
51
|
+
VOICES_URI: ("voices.html", "Voice picker", "Voice previews to listen to and pick a narration voice."),
|
|
52
|
+
CHARACTERS_URI: ("characters.html", "Character picker", "Vector Explainer characters to pick from."),
|
|
53
|
+
PLAYER_URI: ("player.html", "Video player", "Plays a finished Cliptude MP4, or shows that it is not rendered yet."),
|
|
54
|
+
CHOICES_URI: ("choices.html", "Setting picker", "Previews of music, backgrounds and styles to pick a template setting."),
|
|
55
|
+
PUBLISH_KIT_URI: ("publish-kit.html", "Publish kit", "Thumbnails, title ideas, description, chapters and tags."),
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
# Existing tools that get a widget, by name.
|
|
59
|
+
BOUND_TOOLS: dict[str, str] = {
|
|
60
|
+
"list_avatars": AVATARS_URI,
|
|
61
|
+
"list_voices": VOICES_URI,
|
|
62
|
+
"list_vector_characters": CHARACTERS_URI,
|
|
63
|
+
"get_render": PLAYER_URI,
|
|
64
|
+
"get_product_video_status": PLAYER_URI,
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
# Where the widgets' pictures, audio and video come from (CSP img-src/media-src via resourceDomains).
|
|
68
|
+
MEDIA_DOMAINS: tuple[str, ...] = (
|
|
69
|
+
# Avatar previews (videos/avatar_preview.py: HeyGen thumbnails proxied and signed, because HeyGen's own
|
|
70
|
+
# files2.heygen.ai links answer 403 to browsers), built-in Vector characters (/static/vector_explainer/),
|
|
71
|
+
# uploaded characters (/media/), library music (/static/music/), thumbnails not yet on the CDN (/media/).
|
|
72
|
+
"https://cliptude.com",
|
|
73
|
+
"https://www.cliptude.com",
|
|
74
|
+
# Public R2 bucket: library background thumbnails, generated thumbnails, uploaded backgrounds, samples.
|
|
75
|
+
"https://cdn.cliptude.com",
|
|
76
|
+
# Signed MP4 links of finished videos and editor renders (private R2 bucket, videos/r2_storage.py).
|
|
77
|
+
"https://*.r2.cloudflarestorage.com",
|
|
78
|
+
# Voice previews: ElevenLabs (shared-library previews on storage.googleapis.com/eleven-public-prod and the
|
|
79
|
+
# API host), Cartesia (preview_file_url), Voicetory (preview_audio). MiniMax and Inworld have none.
|
|
80
|
+
"https://storage.googleapis.com",
|
|
81
|
+
"https://api.us.elevenlabs.io",
|
|
82
|
+
"https://api.elevenlabs.io",
|
|
83
|
+
"https://files.cartesia.ai",
|
|
84
|
+
"https://voicetory.com",
|
|
85
|
+
)
|
|
86
|
+
# The Desktop app serves its own media on a random localhost port (stdio MCP only).
|
|
87
|
+
LOCAL_MEDIA_DOMAINS: tuple[str, ...] = ("http://127.0.0.1:*", "http://localhost:*")
|
|
88
|
+
|
|
89
|
+
# show_choices: field -> (kind the widget draws, heading)
|
|
90
|
+
CHOICE_FIELDS: dict[str, tuple[str, str]] = {
|
|
91
|
+
"background_music_library_file": ("music", "Background music"),
|
|
92
|
+
"background_image": ("image", "Background"),
|
|
93
|
+
"faceless_documentary_style": ("style", "Style pack"),
|
|
94
|
+
"visual_theme": ("theme", "Visual theme"),
|
|
95
|
+
"caption_style": ("caption", "Caption style"),
|
|
96
|
+
"vector_illustration_style": ("text", "Illustration style"),
|
|
97
|
+
"vector_reveal_mode": ("text", "Motion"),
|
|
98
|
+
}
|
|
99
|
+
# Fields an agent-planned video also sets in its plan's look.
|
|
100
|
+
_PLAN_LOOK_FIELDS = frozenset({"background_music_library_file", "visual_theme", "faceless_documentary_style"})
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _permissions() -> dict[str, Any]:
|
|
104
|
+
if ResourcePermissions is None:
|
|
105
|
+
return {}
|
|
106
|
+
return {
|
|
107
|
+
# Copy buttons (titles, description, tags) use the Clipboard API.
|
|
108
|
+
PUBLISH_KIT_URI: ResourcePermissions(clipboard_write={}),
|
|
109
|
+
# "Clone a voice" can record a sample in the widget; uploading a file works without it.
|
|
110
|
+
VOICES_URI: ResourcePermissions(microphone={}),
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
_PERMISSIONS = _permissions()
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def apps_available() -> bool:
|
|
118
|
+
return Apps is not None
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def widget_html(file_name: str) -> str:
|
|
122
|
+
"""A widget's HTML with the shared bridge and stylesheet inlined (no external script or style)."""
|
|
123
|
+
pkg = resources.files("cliptude_mcp") / "widgets"
|
|
124
|
+
html = (pkg / file_name).read_text(encoding="utf-8")
|
|
125
|
+
bridge = (pkg / "bridge.js").read_text(encoding="utf-8")
|
|
126
|
+
css = (pkg / "base.css").read_text(encoding="utf-8")
|
|
127
|
+
return html.replace("/*@BASE_CSS@*/", css).replace("/*@BRIDGE_JS@*/", bridge)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def media_domains(*, local: bool) -> list[str]:
|
|
131
|
+
return list(MEDIA_DOMAINS) + (list(LOCAL_MEDIA_DOMAINS) if local else [])
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def _ui_meta(uri: str) -> dict[str, Any]:
|
|
135
|
+
# `ui.resourceUri` is the spec's key; the flat `ui/resourceUri` is its deprecated form, kept for hosts that
|
|
136
|
+
# shipped before the rename.
|
|
137
|
+
return {"ui": {"resourceUri": uri}, "ui/resourceUri": uri}
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def build_apps(
|
|
141
|
+
client: Callable[[], Any],
|
|
142
|
+
err: Callable[[Exception], dict[str, Any]],
|
|
143
|
+
*,
|
|
144
|
+
local: bool,
|
|
145
|
+
):
|
|
146
|
+
"""The Apps extension with every widget resource and the new show_* tools; None on an SDK without Apps."""
|
|
147
|
+
if Apps is None:
|
|
148
|
+
return None
|
|
149
|
+
from mcp.types import ToolAnnotations
|
|
150
|
+
|
|
151
|
+
apps = Apps()
|
|
152
|
+
csp = ResourceCsp(resource_domains=media_domains(local=local))
|
|
153
|
+
for uri, (file_name, name, description) in WIDGETS.items():
|
|
154
|
+
apps.add_html_resource(
|
|
155
|
+
uri,
|
|
156
|
+
widget_html(file_name),
|
|
157
|
+
name=name,
|
|
158
|
+
title=name,
|
|
159
|
+
description=description,
|
|
160
|
+
csp=csp,
|
|
161
|
+
permissions=_PERMISSIONS.get(uri),
|
|
162
|
+
prefers_border=True,
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
@apps.tool(
|
|
166
|
+
resource_uri=CHOICES_URI,
|
|
167
|
+
meta={"ui/resourceUri": CHOICES_URI},
|
|
168
|
+
name="show_choices",
|
|
169
|
+
title="Show setting choices",
|
|
170
|
+
annotations=ToolAnnotations(title="Show setting choices", read_only_hint=True, open_world_hint=False),
|
|
171
|
+
)
|
|
172
|
+
def show_choices(
|
|
173
|
+
format: Annotated[str, Field(description="Video format, e.g. faceless_documentary or vector_explainer")],
|
|
174
|
+
field: Annotated[
|
|
175
|
+
str,
|
|
176
|
+
Field(description="Setting to choose: " + ", ".join(CHOICE_FIELDS)),
|
|
177
|
+
],
|
|
178
|
+
) -> dict[str, Any]:
|
|
179
|
+
"""Let the user preview and pick one template setting: background music (play each track), background picture, style pack (colour swatches), visual theme, caption style, or the Vector Explainer illustration style / motion. In hosts that show apps the user picks in a widget and the choice arrives as their message; otherwise read choices and ask. Returns {field, choices:[{value, label, ...preview links}], default, usage}."""
|
|
180
|
+
field = (field or "").strip()
|
|
181
|
+
if field not in CHOICE_FIELDS:
|
|
182
|
+
return {"error": f"field must be one of: {', '.join(CHOICE_FIELDS)}"}
|
|
183
|
+
try:
|
|
184
|
+
options = client().template_options(format)
|
|
185
|
+
except Exception as exc:
|
|
186
|
+
return err(exc)
|
|
187
|
+
return choices_payload(options, format, field)
|
|
188
|
+
|
|
189
|
+
@apps.tool(
|
|
190
|
+
resource_uri=PLAYER_URI,
|
|
191
|
+
meta={"ui/resourceUri": PLAYER_URI},
|
|
192
|
+
name="show_video",
|
|
193
|
+
title="Show video",
|
|
194
|
+
annotations=ToolAnnotations(title="Show video", read_only_hint=True, open_world_hint=False),
|
|
195
|
+
)
|
|
196
|
+
def show_video(
|
|
197
|
+
job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
|
|
198
|
+
) -> dict[str, Any]:
|
|
199
|
+
"""Show a finished job's MP4 in a player the user can watch in the chat (hosts that show apps), with an open link. For an edited video, get_render shows its export the same way. Returns {job_id, title, status, url}; url is empty until the video is ready."""
|
|
200
|
+
try:
|
|
201
|
+
job = client().get_job(job_id)
|
|
202
|
+
except Exception as exc:
|
|
203
|
+
return err(exc)
|
|
204
|
+
return video_payload(job, job_id)
|
|
205
|
+
|
|
206
|
+
@apps.tool(
|
|
207
|
+
resource_uri=PUBLISH_KIT_URI,
|
|
208
|
+
meta={"ui/resourceUri": PUBLISH_KIT_URI},
|
|
209
|
+
name="show_publish_kit",
|
|
210
|
+
title="Show publish kit",
|
|
211
|
+
annotations=ToolAnnotations(title="Show publish kit", read_only_hint=False, destructive_hint=False, open_world_hint=False),
|
|
212
|
+
)
|
|
213
|
+
def show_publish_kit(
|
|
214
|
+
job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
|
|
215
|
+
) -> dict[str, Any]:
|
|
216
|
+
"""The generated thumbnails, title ideas, YouTube description, chapters and tags of a finished video, shown as a publish kit with copy buttons (hosts that show apps). Opens the video's editor project like open_editor_project. Returns {job_id, project_id, title, thumbnails, publish_metadata}."""
|
|
217
|
+
try:
|
|
218
|
+
data = client().open_editor_project(job_id)
|
|
219
|
+
except Exception as exc:
|
|
220
|
+
return err(exc)
|
|
221
|
+
return publish_kit_payload(data, job_id)
|
|
222
|
+
|
|
223
|
+
return apps
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def bind_existing_tools(mcp: Any) -> list[str]:
|
|
227
|
+
"""Stamp `_meta.ui.resourceUri` on the existing tools that have a widget; returns the names bound.
|
|
228
|
+
|
|
229
|
+
The tools are registered by server.py as before, so their names, parameters and results do not change.
|
|
230
|
+
"""
|
|
231
|
+
manager = getattr(mcp, "_tool_manager", None)
|
|
232
|
+
bound = []
|
|
233
|
+
for name, uri in BOUND_TOOLS.items():
|
|
234
|
+
tool = manager.get_tool(name) if manager is not None else None
|
|
235
|
+
if tool is None:
|
|
236
|
+
continue
|
|
237
|
+
tool.meta = {**(tool.meta or {}), **_ui_meta(uri)}
|
|
238
|
+
bound.append(name)
|
|
239
|
+
return bound
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def choices_payload(options: Any, format_value: str, field: str) -> dict[str, Any]:
|
|
243
|
+
kind, label = CHOICE_FIELDS[field]
|
|
244
|
+
if not isinstance(options, dict):
|
|
245
|
+
return {"error": "Cliptude returned no template options."}
|
|
246
|
+
if options.get("error"):
|
|
247
|
+
return options
|
|
248
|
+
entry = (options.get("fields") or {}).get(field)
|
|
249
|
+
if not isinstance(entry, dict):
|
|
250
|
+
return {"error": f"{format_value} templates have no {field} setting."}
|
|
251
|
+
details = entry.get("choice_details")
|
|
252
|
+
if not isinstance(details, list): # An older Cliptude server: values only.
|
|
253
|
+
details = [{"value": value, "label": str(value)} for value in entry.get("choices") or []]
|
|
254
|
+
usage = f"Set {field} in create_template settings"
|
|
255
|
+
usage += " (or in the plan's look on an agent-planned video)." if field in _PLAN_LOOK_FIELDS else "."
|
|
256
|
+
if field == "background_music_library_file":
|
|
257
|
+
usage += " With it, set background_music_mode to library; none means no music."
|
|
258
|
+
return {
|
|
259
|
+
"format": format_value,
|
|
260
|
+
"field": field,
|
|
261
|
+
"kind": kind,
|
|
262
|
+
"label": label,
|
|
263
|
+
"description": entry.get("description") or entry.get("note") or "",
|
|
264
|
+
"default": entry.get("default"),
|
|
265
|
+
"current": entry.get("default"),
|
|
266
|
+
"choices": details,
|
|
267
|
+
"usage": usage,
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
def video_payload(job: Any, job_id: str) -> dict[str, Any]:
|
|
272
|
+
if not isinstance(job, dict):
|
|
273
|
+
return {"error": "Cliptude returned no job."}
|
|
274
|
+
if job.get("error") and not job.get("status"):
|
|
275
|
+
return job
|
|
276
|
+
output = job.get("output") if isinstance(job.get("output"), dict) else {}
|
|
277
|
+
return {
|
|
278
|
+
"job_id": str(job.get("id") or job.get("job_id") or job_id),
|
|
279
|
+
"title": job.get("title") or "",
|
|
280
|
+
"status": job.get("status") or "",
|
|
281
|
+
"progress": job.get("progress"),
|
|
282
|
+
"current_step": job.get("current_step") or "",
|
|
283
|
+
"error": job.get("error") or "",
|
|
284
|
+
"url": output.get("url") or "",
|
|
285
|
+
"path": output.get("path") or "",
|
|
286
|
+
"note": (
|
|
287
|
+
"Saved on this computer: open path." if output.get("path") and not output.get("url") else ""
|
|
288
|
+
),
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
|
|
293
|
+
if not isinstance(data, dict):
|
|
294
|
+
return {"error": "Cliptude returned no editor project."}
|
|
295
|
+
if data.get("error"):
|
|
296
|
+
return data
|
|
297
|
+
project = data.get("project") if isinstance(data.get("project"), dict) else data
|
|
298
|
+
meta = project.get("publish_metadata") if isinstance(project.get("publish_metadata"), dict) else {}
|
|
299
|
+
return {
|
|
300
|
+
"job_id": job_id,
|
|
301
|
+
"project_id": project.get("id"),
|
|
302
|
+
"title": project.get("title") or "",
|
|
303
|
+
"thumbnails": project.get("thumbnails") or {"status": "", "items": []},
|
|
304
|
+
"publish_metadata": {
|
|
305
|
+
"title_variants": meta.get("title_variants") or [],
|
|
306
|
+
"description": meta.get("description") or "",
|
|
307
|
+
"chapters": meta.get("chapters") or "",
|
|
308
|
+
"tags": meta.get("tags") or [],
|
|
309
|
+
"downloads": meta.get("downloads") or {},
|
|
310
|
+
},
|
|
311
|
+
}
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -23,38 +23,55 @@ def _add_review_args(parser) -> None:
|
|
|
23
23
|
)
|
|
24
24
|
|
|
25
25
|
|
|
26
|
-
def
|
|
27
|
-
|
|
26
|
+
def _reviewed(args, call, *, heading: str = "Review this video before it is created:",
|
|
27
|
+
question: str = "Create this video?"):
|
|
28
|
+
"""A call that spends credits, behind its review: in a terminal, show it and ask; otherwise print it and stop.
|
|
28
29
|
|
|
29
|
-
Cliptude answers
|
|
30
|
+
Cliptude answers create_job, continue, product script/render, agent and paid render without a review_token
|
|
31
|
+
with the review (HTTP 428) and does nothing. ``call(review_token, acknowledge)`` makes the request.
|
|
30
32
|
"""
|
|
31
33
|
token = (getattr(args, "review_token", "") or "").strip() or None
|
|
32
34
|
acks = [a.strip() for raw in (getattr(args, "acknowledge", None) or []) for a in raw.split(",") if a.strip()]
|
|
33
35
|
try:
|
|
34
|
-
return
|
|
36
|
+
return call(token, acks or None)
|
|
35
37
|
except CliptudeApiError as exc:
|
|
36
38
|
detail = exc.payload if isinstance(exc.payload, dict) else {}
|
|
37
39
|
if exc.status != 428 or "review" not in detail or not sys.stdin.isatty():
|
|
38
40
|
raise
|
|
39
41
|
review = detail["review"]
|
|
40
42
|
out = sys.stderr
|
|
41
|
-
out.write("\
|
|
43
|
+
out.write(f"\n{heading}\n")
|
|
44
|
+
if review.get("summary"):
|
|
45
|
+
out.write(f" {review['summary']}\n")
|
|
42
46
|
for item in review.get("settings") or []:
|
|
43
47
|
out.write(f" {item.get('label')}: {item.get('value')}\n")
|
|
44
48
|
credits = review.get("credits") or {}
|
|
45
49
|
if credits.get("credits_required") is not None:
|
|
46
50
|
out.write(f" Credits: about {credits['credits_required']} (you have {credits.get('credits_available')})\n")
|
|
51
|
+
else:
|
|
52
|
+
for key, value in credits.items():
|
|
53
|
+
out.write(f" Credits, {key.replace('_', ' ')}: {value}\n")
|
|
47
54
|
for warning in review.get("warnings") or []:
|
|
48
55
|
out.write(f" ! {warning}\n")
|
|
49
56
|
approved = []
|
|
50
57
|
for ack in review.get("acknowledgements_required") or []:
|
|
51
58
|
out.write(f"\n {ack['message']}\n")
|
|
52
59
|
if input(f" Approve ({ack['id']})? [y/N] ").strip().lower() != "y":
|
|
53
|
-
raise CliptudeApiError("Not
|
|
60
|
+
raise CliptudeApiError("Not done: change the template and run again.")
|
|
54
61
|
approved.append(ack["id"])
|
|
55
|
-
if input("\
|
|
56
|
-
raise CliptudeApiError("Not
|
|
57
|
-
return
|
|
62
|
+
if input(f"\n{question} [y/N] ").strip().lower() != "y":
|
|
63
|
+
raise CliptudeApiError("Not done: nothing was spent.")
|
|
64
|
+
return call(detail["review_token"], approved or None)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _create_reviewed(client: CliptudeClient, args, **kwargs):
|
|
68
|
+
"""create_job behind the job review (see _reviewed)."""
|
|
69
|
+
return _reviewed(args, lambda token, acks: client.create_job(review_token=token, acknowledge=acks, **kwargs))
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _spend_reviewed(args, call, question: str):
|
|
73
|
+
"""A call on an existing job or project that spends credits, behind its review (see _reviewed)."""
|
|
74
|
+
return _reviewed(args, lambda token, _acks: call(token), heading="This spends credits:", question=question)
|
|
58
75
|
|
|
59
76
|
|
|
60
77
|
def _die(exc: Exception, code: int = 1) -> None:
|
|
@@ -87,8 +104,8 @@ def _add_thumbnail_args(parser: argparse.ArgumentParser, *, scope: str) -> None:
|
|
|
87
104
|
"--thumbnail-reference",
|
|
88
105
|
default="",
|
|
89
106
|
help=(
|
|
90
|
-
f"YouTube video link or https image whose thumbnail style {scope} copies.
|
|
91
|
-
"reference,
|
|
107
|
+
f"YouTube video link or https image whose thumbnail style {scope} copies. Videos need a brief or "
|
|
108
|
+
"reference (here, on the template, or when the job is continued); Cliptude does not guess one."
|
|
92
109
|
),
|
|
93
110
|
)
|
|
94
111
|
|
|
@@ -174,6 +191,16 @@ def _run_auth(auth_cmd: str) -> None:
|
|
|
174
191
|
clear_credentials()
|
|
175
192
|
print("Logged out.")
|
|
176
193
|
return
|
|
194
|
+
from cliptude_mcp.client import resolve_connection
|
|
195
|
+
|
|
196
|
+
conn = resolve_connection()
|
|
197
|
+
if conn["runtime"] == "desktop":
|
|
198
|
+
if conn["error"]:
|
|
199
|
+
print(conn["error"], file=sys.stderr)
|
|
200
|
+
raise SystemExit(1)
|
|
201
|
+
account = CliptudeClient(client_kind="cli").get_account()
|
|
202
|
+
print(f"Using the Cliptude desktop app as {account.get('email')} (no cliptude.com login needed).")
|
|
203
|
+
return
|
|
177
204
|
if not stored_access_token():
|
|
178
205
|
print("Not authenticated. Run: cliptude auth login", file=sys.stderr)
|
|
179
206
|
raise SystemExit(1)
|
|
@@ -185,6 +212,19 @@ def _run_auth(auth_cmd: str) -> None:
|
|
|
185
212
|
print(f"Logged in{f' as {email}' if email else '.'}")
|
|
186
213
|
|
|
187
214
|
|
|
215
|
+
def _run_use(target: str | None) -> None:
|
|
216
|
+
from cliptude_mcp.client import chosen_target, resolve_connection, save_target
|
|
217
|
+
|
|
218
|
+
if target:
|
|
219
|
+
save_target(target)
|
|
220
|
+
conn = resolve_connection()
|
|
221
|
+
where = {"desktop": "the Cliptude desktop app", "cloud": "cliptude.com"}.get(conn["runtime"], conn["base_url"])
|
|
222
|
+
print(f"Target: {chosen_target()} → {where}" + (f" ({conn['base_url']})" if conn["base_url"] else ""))
|
|
223
|
+
if conn["error"]:
|
|
224
|
+
print(conn["error"], file=sys.stderr)
|
|
225
|
+
raise SystemExit(1)
|
|
226
|
+
|
|
227
|
+
|
|
188
228
|
def _review_arg(value: str) -> dict:
|
|
189
229
|
"""--review "quote|author|rating" -> {quote, author, rating}."""
|
|
190
230
|
parts = [p.strip() for p in value.split("|")]
|
|
@@ -214,6 +254,13 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
214
254
|
auth_sub.add_parser("logout", help="Delete the local session")
|
|
215
255
|
auth_sub.add_parser("status", help="Show whether this machine is signed in")
|
|
216
256
|
|
|
257
|
+
use = sub.add_parser(
|
|
258
|
+
"use",
|
|
259
|
+
help="Make videos in the Cliptude desktop app or on cliptude.com (no argument: show where)",
|
|
260
|
+
)
|
|
261
|
+
use.add_argument("target", nargs="?", choices=["desktop", "cloud", "auto"],
|
|
262
|
+
help="auto = the desktop app while it is running, else cliptude.com")
|
|
263
|
+
|
|
217
264
|
t = sub.add_parser("templates", help="List saved templates")
|
|
218
265
|
t.add_argument("--limit", type=int, default=20)
|
|
219
266
|
t.add_argument("--offset", type=int, default=0)
|
|
@@ -378,6 +425,12 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
378
425
|
default=None,
|
|
379
426
|
help="No scene transitions; hard cuts only. Omit to use the template.",
|
|
380
427
|
)
|
|
428
|
+
g.add_argument(
|
|
429
|
+
"--disable-sound-effects",
|
|
430
|
+
action=argparse.BooleanOptionalAction,
|
|
431
|
+
default=None,
|
|
432
|
+
help="No sound effects; --no-disable-sound-effects turns them on for this video even if the template has them off. Omit to use the template.",
|
|
433
|
+
)
|
|
381
434
|
g.add_argument(
|
|
382
435
|
"--exclude-animation-type",
|
|
383
436
|
action="append",
|
|
@@ -445,6 +498,8 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
445
498
|
),
|
|
446
499
|
)
|
|
447
500
|
cont.add_argument("job_id")
|
|
501
|
+
_add_thumbnail_args(cont, scope="this video")
|
|
502
|
+
_add_review_args(cont)
|
|
448
503
|
|
|
449
504
|
prod = sub.add_parser(
|
|
450
505
|
"product",
|
|
@@ -472,9 +527,16 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
472
527
|
ps.add_argument("--cta-url", default="")
|
|
473
528
|
ps.add_argument("--review", action="append", default=[],
|
|
474
529
|
help='A real customer review, "quote|author|rating" (repeat up to 3 times)')
|
|
530
|
+
ps.add_argument("--script-file", default="",
|
|
531
|
+
help="Narration you wrote (text file); the job is script_ready at once. Omit to let Cliptude write it")
|
|
532
|
+
ps.add_argument("--plan", action="store_true",
|
|
533
|
+
help="You plan every visual: the job is voiced and stops at plan_ready (plan-check, plan-lock, then product render)")
|
|
534
|
+
_add_review_args(ps)
|
|
475
535
|
pr = prod_sub.add_parser("render", help="Produce the video from a ready product script")
|
|
476
536
|
pr.add_argument("job_id")
|
|
477
537
|
pr.add_argument("--aspect-ratio", default="16:9")
|
|
538
|
+
_add_thumbnail_args(pr, scope="this video")
|
|
539
|
+
_add_review_args(pr)
|
|
478
540
|
pst = prod_sub.add_parser("status", help="Stage, script, preview link and MP4 of a product video")
|
|
479
541
|
pst.add_argument("job_id")
|
|
480
542
|
|
|
@@ -532,6 +594,8 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
532
594
|
um = sub.add_parser("upload-media", help="Send a picture or clip you found to a plan job; prints its keep id for media.keep")
|
|
533
595
|
um.add_argument("job_id")
|
|
534
596
|
um.add_argument("path", help="Local JPG/PNG/WEBP/GIF (up to 15 MB) or MP4/MOV/WEBM/M4V (up to 300 MB)")
|
|
597
|
+
um.add_argument("--split-shots", action="store_true",
|
|
598
|
+
help="Also cut a long source into 3-12 s clips on its cuts, each checked and kept (prints their keep ids)")
|
|
535
599
|
|
|
536
600
|
ed = sub.add_parser("editor", help="Open the timeline editor project for a completed job (prints the timeline)")
|
|
537
601
|
ed.add_argument("job_id")
|
|
@@ -553,6 +617,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
553
617
|
ag.add_argument("--tier", default="fast", help="fast or smart (see cliptude agent-tiers)")
|
|
554
618
|
ag.add_argument("--chat", default="", help="Continue an existing agent chat id")
|
|
555
619
|
ag.add_argument("--wait", action="store_true", help="Poll until the run finishes")
|
|
620
|
+
_add_review_args(ag)
|
|
556
621
|
|
|
557
622
|
ags = sub.add_parser("agent-status", help="Get a Cliptude Agent run")
|
|
558
623
|
ags.add_argument("project_id")
|
|
@@ -569,6 +634,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
569
634
|
rn.add_argument("--wait", action="store_true", help="Poll until the render finishes")
|
|
570
635
|
rn.add_argument("--accept-quality-findings", action="store_true",
|
|
571
636
|
help="Agent-planned jobs: render although plan-review still lists plan quality findings")
|
|
637
|
+
_add_review_args(rn)
|
|
572
638
|
|
|
573
639
|
rs = sub.add_parser("render-status", help="Get an editor render (output_url when done)")
|
|
574
640
|
rs.add_argument("render_id")
|
|
@@ -591,6 +657,9 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
591
657
|
if args.cmd == "auth":
|
|
592
658
|
_run_auth(args.auth_cmd)
|
|
593
659
|
return
|
|
660
|
+
if args.cmd == "use":
|
|
661
|
+
_run_use(args.target)
|
|
662
|
+
return
|
|
594
663
|
client = CliptudeClient(client_kind="cli")
|
|
595
664
|
try:
|
|
596
665
|
if args.cmd == "templates":
|
|
@@ -685,6 +754,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
685
754
|
disable_overlays=args.disable_overlays,
|
|
686
755
|
disable_effects=args.disable_effects,
|
|
687
756
|
disable_transitions=args.disable_transitions,
|
|
757
|
+
disable_sound_effects=args.disable_sound_effects,
|
|
688
758
|
excluded_animation_types=args.excluded_animation_types,
|
|
689
759
|
excluded_transition_kinds=args.excluded_transition_kinds,
|
|
690
760
|
thumbnail=_thumbnail_from_args(args),
|
|
@@ -762,25 +832,34 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
762
832
|
elif args.cmd == "plan-report":
|
|
763
833
|
_print(client.get_plan_report(args.job_id))
|
|
764
834
|
elif args.cmd == "upload-media":
|
|
765
|
-
_print(client.upload_plan_media(args.job_id, args.path))
|
|
835
|
+
_print(client.upload_plan_media(args.job_id, args.path, split_shots=args.split_shots))
|
|
766
836
|
elif args.cmd == "download-voiceover":
|
|
767
837
|
dest = Path(args.out)
|
|
768
838
|
client.download_voiceover_file(args.job_id, dest)
|
|
769
839
|
_print({"ok": True, "path": str(dest.resolve())})
|
|
770
840
|
elif args.cmd == "continue":
|
|
771
|
-
|
|
841
|
+
thumbnail = _thumbnail_from_args(args)
|
|
842
|
+
_print(_spend_reviewed(
|
|
843
|
+
args, lambda token: client.continue_job(args.job_id, thumbnail=thumbnail, review_token=token),
|
|
844
|
+
"Build this video?",
|
|
845
|
+
))
|
|
772
846
|
elif args.cmd == "product":
|
|
773
847
|
if args.product_cmd == "fetch":
|
|
774
848
|
_print(client.fetch_product_context(args.url_or_query, store_domain=args.store or None))
|
|
775
849
|
elif args.product_cmd == "script":
|
|
776
850
|
angle = int(args.angle) if str(args.angle).isdigit() else args.angle
|
|
777
|
-
|
|
851
|
+
script = Path(args.script_file).read_text(encoding="utf-8") if args.script_file else None
|
|
852
|
+
_print(_reviewed(args, lambda token, acks: client.draft_product_script(
|
|
778
853
|
args.product_id, angle=angle, duration=args.duration, template_id=args.template or None,
|
|
779
854
|
title=args.title or None, discount_code=args.discount_code or None, cta_url=args.cta_url or None,
|
|
780
|
-
reviews=[_review_arg(r) for r in args.review] or None,
|
|
781
|
-
|
|
855
|
+
reviews=[_review_arg(r) for r in args.review] or None, script=script, plan=args.plan,
|
|
856
|
+
review_token=token, acknowledge=acks,
|
|
857
|
+
), question="Start this product video?"))
|
|
782
858
|
elif args.product_cmd == "render":
|
|
783
|
-
|
|
859
|
+
thumbnail = _thumbnail_from_args(args)
|
|
860
|
+
_print(_spend_reviewed(args, lambda token: client.render_product_video(
|
|
861
|
+
args.job_id, aspect_ratio=args.aspect_ratio, thumbnail=thumbnail, review_token=token,
|
|
862
|
+
), "Build this product video?"))
|
|
784
863
|
else:
|
|
785
864
|
_print(client.get_product_video_status(args.job_id))
|
|
786
865
|
elif args.cmd == "editor":
|
|
@@ -792,9 +871,10 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
792
871
|
if not (prompt or "").strip():
|
|
793
872
|
raise CliptudeApiError("Provide --prompt or --prompt-file.")
|
|
794
873
|
items = [i.strip() for i in (args.items or "").split(",") if i.strip()]
|
|
795
|
-
payload = client.run_agent(
|
|
796
|
-
args.project_id, prompt=prompt, tier=args.tier, referenced_item_ids=items, chat_id=args.chat or None
|
|
797
|
-
|
|
874
|
+
payload = _spend_reviewed(args, lambda token: client.run_agent(
|
|
875
|
+
args.project_id, prompt=prompt, tier=args.tier, referenced_item_ids=items, chat_id=args.chat or None,
|
|
876
|
+
review_token=token,
|
|
877
|
+
), "Run the agent?")
|
|
798
878
|
if args.wait:
|
|
799
879
|
run_id = (payload.get("run") or {}).get("id")
|
|
800
880
|
payload = _wait(lambda: client.get_agent_run(args.project_id, run_id), lambda p: (p.get("run") or {}).get("status"))
|
|
@@ -806,7 +886,9 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
806
886
|
elif args.cmd == "agent-tiers":
|
|
807
887
|
_print(client.agent_tiers())
|
|
808
888
|
elif args.cmd == "render":
|
|
809
|
-
payload =
|
|
889
|
+
payload = _spend_reviewed(args, lambda token: client.render_project(
|
|
890
|
+
args.project_id, accept_quality_findings=args.accept_quality_findings, review_token=token,
|
|
891
|
+
), "Render this MP4?")
|
|
810
892
|
if args.wait:
|
|
811
893
|
render_id = (payload.get("render") or {}).get("id")
|
|
812
894
|
payload = _wait(lambda: client.get_render(render_id), lambda p: (p.get("render") or {}).get("status"))
|