@cliptude/cli 0.1.10 → 0.1.11
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 +1 -1
- package/cliptude_mcp/cli.py +31 -4
- package/cliptude_mcp/client.py +4 -0
- package/cliptude_mcp/server.py +14 -4
- package/npm/bin/cliptude.js +39 -20
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/README.md
CHANGED
|
@@ -41,7 +41,7 @@ cliptude continue <job-id>
|
|
|
41
41
|
cliptude status <job-id>
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`. For Avatar Video, `avatars` (MCP `list_avatars`) lists your avatars; set one with `--set avatar_profile_id=<id>` on `template-create`, or override it per video with `--avatar <id>` (and `--avatar-engine
|
|
44
|
+
No template yet? `template-create` makes one without the create wizard: pick a `voice_id` from `voices`, and see `template-options` for every other field, its choices and its default (unset fields take the wizard default). Values are validated like the wizard; uploads (custom music, avatars, characters) still need the wizard. MCP tools: `get_template_options`, `list_voices`, `create_template`. For Avatar Video, `avatars` (MCP `list_avatars`) lists your avatars; set one with `--set avatar_profile_id=<id>` on `template-create`, or override it per video with `--avatar <id>` (and `--avatar-engine iv|v`) on `generate`, `plan-job` and `estimate`. The avatar's gender must match the voice. For Vector Explainer, `vector-characters` lists the built-in cast and your uploads, `vector-character-upload --name "Dr. Maya" --file maya.png` (or `--url`) adds your own, and `--set vector_character_id=<id>` on `template-create` (or `--vector-character <id>` on `generate` / `plan-job`) uses it. Motion: `--set vector_reveal_mode=none|video` on the template, or `--vector-motion none|video` on `generate`, `plan-job` and `estimate` (`none` = stills with camera moves, `video` = AI clips). Thumbnails: `--thumbnail-reference <YouTube link or image URL>` or `--thumbnail-prompt "<brief>"` on `template-create` sets the template's look; the same flags on `generate` and `plan-job` set one video's. With neither, each video picks a style reference for its own title.
|
|
45
45
|
|
|
46
46
|
To check the price first, `estimate` (MCP `estimate_credits`, REST `POST /api/v1/jobs/estimate`) takes the same template and prompt/script as `generate` (an upload as `--voiceover-seconds` / `--talking-head-seconds`) and returns the credits the job would need and whether the account has them. It creates and charges nothing.
|
|
47
47
|
|
package/cliptude_mcp/cli.py
CHANGED
|
@@ -51,6 +51,29 @@ def _add_thumbnail_args(parser: argparse.ArgumentParser, *, scope: str) -> None:
|
|
|
51
51
|
)
|
|
52
52
|
|
|
53
53
|
|
|
54
|
+
def _add_pronunciations_arg(parser: argparse.ArgumentParser) -> None:
|
|
55
|
+
parser.add_argument(
|
|
56
|
+
"--pronunciations",
|
|
57
|
+
default="",
|
|
58
|
+
metavar="FILE",
|
|
59
|
+
help='JSON file: a list of {"word": "Gmay", "alias": "guh-MAY"} or {"word", "phoneme", "alphabet": "ipa"} '
|
|
60
|
+
"(ElevenLabs voices). Replaces the template's list for this video.",
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _pronunciations_from_args(args) -> list | None:
|
|
65
|
+
path = (getattr(args, "pronunciations", "") or "").strip()
|
|
66
|
+
if not path:
|
|
67
|
+
return None
|
|
68
|
+
try:
|
|
69
|
+
rules = json.loads(Path(path).read_text(encoding="utf-8"))
|
|
70
|
+
except (OSError, ValueError) as exc:
|
|
71
|
+
raise CliptudeApiError(f"--pronunciations: could not read {path}: {exc}") from exc
|
|
72
|
+
if not isinstance(rules, list):
|
|
73
|
+
raise CliptudeApiError("--pronunciations must be a JSON list of rules.")
|
|
74
|
+
return rules
|
|
75
|
+
|
|
76
|
+
|
|
54
77
|
def _thumbnail_from_args(args) -> dict | None:
|
|
55
78
|
thumbnail = {
|
|
56
79
|
key: value.strip()
|
|
@@ -214,7 +237,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
214
237
|
est.add_argument("--avatar-intro-only", action=argparse.BooleanOptionalAction, default=None)
|
|
215
238
|
est.add_argument("--avatar-ai-footage", action=argparse.BooleanOptionalAction, default=None)
|
|
216
239
|
est.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
217
|
-
est.add_argument("--avatar-engine", default="", choices=["", "
|
|
240
|
+
est.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
218
241
|
est.add_argument("--vector-motion", default="", choices=["", "none", "video"], help="Vector Explainer: price stills (none) or AI clips (video)")
|
|
219
242
|
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)")
|
|
220
243
|
|
|
@@ -279,7 +302,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
279
302
|
),
|
|
280
303
|
)
|
|
281
304
|
g.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
282
|
-
g.add_argument("--avatar-engine", default="", choices=["", "
|
|
305
|
+
g.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
283
306
|
g.add_argument(
|
|
284
307
|
"--disable-animations",
|
|
285
308
|
action=argparse.BooleanOptionalAction,
|
|
@@ -321,6 +344,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
321
344
|
help="Exclude a transition (e.g. flip-horizontal) from auto-selection. Repeatable. Omit to use the template.",
|
|
322
345
|
)
|
|
323
346
|
_add_thumbnail_args(g, scope="this video")
|
|
347
|
+
_add_pronunciations_arg(g)
|
|
324
348
|
g.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
|
|
325
349
|
g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
|
|
326
350
|
|
|
@@ -356,7 +380,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
356
380
|
vo.add_argument("--script-file", default="")
|
|
357
381
|
vo.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 3-4 or 6-8")
|
|
358
382
|
|
|
359
|
-
dv = sub.add_parser("download-voiceover", help="Download voiceover MP3
|
|
383
|
+
dv = sub.add_parser("download-voiceover", help="Download the voiceover MP3 of a voiceover job, or the narration of a plan_ready plan job")
|
|
360
384
|
dv.add_argument("job_id")
|
|
361
385
|
dv.add_argument("--out", default="voiceover.mp3")
|
|
362
386
|
|
|
@@ -394,9 +418,10 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
394
418
|
pj.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it")
|
|
395
419
|
pj.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 6-8")
|
|
396
420
|
pj.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
|
|
397
|
-
pj.add_argument("--avatar-engine", default="", choices=["", "
|
|
421
|
+
pj.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
|
|
398
422
|
pj.add_argument("--render-only", action="store_true", help="You bring everything (needs --voiceover); Cliptude only builds and renders, at the render-only rate")
|
|
399
423
|
_add_thumbnail_args(pj, scope="this video")
|
|
424
|
+
_add_pronunciations_arg(pj)
|
|
400
425
|
pj.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
|
|
401
426
|
pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
|
|
402
427
|
|
|
@@ -578,6 +603,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
578
603
|
thumbnail=_thumbnail_from_args(args),
|
|
579
604
|
vector_character_id=args.vector_character or None,
|
|
580
605
|
vector_reveal_mode=args.vector_motion or None,
|
|
606
|
+
pronunciations=_pronunciations_from_args(args),
|
|
581
607
|
))
|
|
582
608
|
elif args.cmd == "script":
|
|
583
609
|
if not (args.prompt or "").strip():
|
|
@@ -629,6 +655,7 @@ def main(argv: list[str] | None = None) -> None:
|
|
|
629
655
|
thumbnail=_thumbnail_from_args(args),
|
|
630
656
|
vector_character_id=args.vector_character or None,
|
|
631
657
|
vector_reveal_mode=args.vector_motion or None,
|
|
658
|
+
pronunciations=_pronunciations_from_args(args),
|
|
632
659
|
))
|
|
633
660
|
elif args.cmd == "narration":
|
|
634
661
|
_print(client.get_narration(args.job_id))
|
package/cliptude_mcp/client.py
CHANGED
|
@@ -308,6 +308,7 @@ class CliptudeClient:
|
|
|
308
308
|
thumbnail: dict[str, str] | None = None,
|
|
309
309
|
vector_character_id: str | None = None,
|
|
310
310
|
vector_reveal_mode: str | None = None,
|
|
311
|
+
pronunciations: list[dict[str, str]] | None = None,
|
|
311
312
|
) -> Any:
|
|
312
313
|
if voiceover_path and voiceover_url:
|
|
313
314
|
raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
|
|
@@ -381,6 +382,7 @@ class CliptudeClient:
|
|
|
381
382
|
**_thumbnail_job_field(thumbnail, as_string=True),
|
|
382
383
|
**({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
|
|
383
384
|
**({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
|
|
385
|
+
**({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
|
|
384
386
|
}
|
|
385
387
|
return self._create_job_multipart(
|
|
386
388
|
template_id=template_id,
|
|
@@ -415,6 +417,8 @@ class CliptudeClient:
|
|
|
415
417
|
body["vector_character_id"] = str(vector_character_id)
|
|
416
418
|
if vector_reveal_mode:
|
|
417
419
|
body["vector_reveal_mode"] = str(vector_reveal_mode)
|
|
420
|
+
if pronunciations is not None:
|
|
421
|
+
body["pronunciations"] = pronunciations
|
|
418
422
|
return self.request("POST", "/api/v1/jobs", json_body=body)
|
|
419
423
|
|
|
420
424
|
def _raise_http(self, resp, *, payload=None) -> None:
|
package/cliptude_mcp/server.py
CHANGED
|
@@ -249,7 +249,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
249
249
|
] = None,
|
|
250
250
|
avatar_engine: Annotated[
|
|
251
251
|
str | None,
|
|
252
|
-
Field(description='Avatar Video only: "
|
|
252
|
+
Field(description='Avatar Video only: "iv" or "v" (list_avatars shows which each avatar supports; Avatar III is not offered). Omit to keep the template.'),
|
|
253
253
|
] = None,
|
|
254
254
|
render_only: Annotated[
|
|
255
255
|
bool | None,
|
|
@@ -397,7 +397,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
397
397
|
] = None,
|
|
398
398
|
avatar_engine: Annotated[
|
|
399
399
|
str | None,
|
|
400
|
-
Field(description='Avatar Video only: "
|
|
400
|
+
Field(description='Avatar Video only: "iv" or "v" (list_avatars shows which each avatar supports; Avatar III is not offered). Omit to keep the template.'),
|
|
401
401
|
] = None,
|
|
402
402
|
disable_animations: Annotated[
|
|
403
403
|
bool | None,
|
|
@@ -443,6 +443,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
443
443
|
str | None,
|
|
444
444
|
Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
|
|
445
445
|
] = None,
|
|
446
|
+
pronunciations: Annotated[
|
|
447
|
+
list[dict[str, str]] | None,
|
|
448
|
+
Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
|
|
449
|
+
] = None,
|
|
446
450
|
) -> dict[str, Any]:
|
|
447
451
|
"""Start generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt, script, voiceover_path, or talking_head_path. Never copy the title into prompt; for a topic-only request write a spoken script after web search and pass script. Uploaded audio or talking-head video is transcribed. Avatar Video: optional avatar_intro_only and avatar_ai_footage override the template. Any format: optional disable_animations/disable_overlays/disable_effects/disable_transitions and excluded_animation_types/excluded_transition_kinds override the template's motion & effects settings."""
|
|
448
452
|
try:
|
|
@@ -483,6 +487,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
483
487
|
thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
|
|
484
488
|
vector_character_id=vector_character_id,
|
|
485
489
|
vector_reveal_mode=vector_reveal_mode,
|
|
490
|
+
pronunciations=pronunciations,
|
|
486
491
|
)
|
|
487
492
|
except Exception as exc:
|
|
488
493
|
return _err(exc)
|
|
@@ -563,7 +568,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
563
568
|
] = None,
|
|
564
569
|
avatar_engine: Annotated[
|
|
565
570
|
str | None,
|
|
566
|
-
Field(description='Avatar Video only: "
|
|
571
|
+
Field(description='Avatar Video only: "iv" or "v" (list_avatars shows which each avatar supports; Avatar III is not offered). Omit to keep the template.'),
|
|
567
572
|
] = None,
|
|
568
573
|
render_only: Annotated[
|
|
569
574
|
bool | None,
|
|
@@ -585,6 +590,10 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
585
590
|
str | None,
|
|
586
591
|
Field(description='Vector Explainer only: "none" = drawn stills with camera moves (Ken Burns), "video" = every picture beat animated as an AI clip (costs more; check estimate_credits). Omit to use the template\'s.'),
|
|
587
592
|
] = None,
|
|
593
|
+
pronunciations: Annotated[
|
|
594
|
+
list[dict[str, str]] | None,
|
|
595
|
+
Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
|
|
596
|
+
] = None,
|
|
588
597
|
) -> dict[str, Any]:
|
|
589
598
|
"""Start a job whose visuals YOU plan. Cliptude writes (if needed) and voices the narration, then stops at status plan_ready. It needs the full website price in credits but charges only the narration now; the rest is charged when the video completes, and the total equals the website price. Poll get_job until plan_ready, then get_narration."""
|
|
590
599
|
try:
|
|
@@ -605,6 +614,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
605
614
|
thumbnail=_thumbnail_arg(thumbnail_prompt, thumbnail_reference_url),
|
|
606
615
|
vector_character_id=vector_character_id,
|
|
607
616
|
vector_reveal_mode=vector_reveal_mode,
|
|
617
|
+
pronunciations=pronunciations,
|
|
608
618
|
)
|
|
609
619
|
except Exception as exc:
|
|
610
620
|
return _err(exc)
|
|
@@ -616,7 +626,7 @@ def build_server(*, with_http_auth: bool = False):
|
|
|
616
626
|
def get_narration(
|
|
617
627
|
job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
|
|
618
628
|
) -> dict[str, Any]:
|
|
619
|
-
"""The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics,
|
|
629
|
+
"""The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
|
|
620
630
|
try:
|
|
621
631
|
return _client().get_narration(job_id)
|
|
622
632
|
except Exception as exc:
|
package/npm/bin/cliptude.js
CHANGED
|
@@ -11,25 +11,34 @@ const args = process.argv.slice(2);
|
|
|
11
11
|
const venvDir =
|
|
12
12
|
process.env.CLIPTUDE_VENV || path.join(os.homedir(), ".cliptude", "venv");
|
|
13
13
|
|
|
14
|
+
const MINOR_VERSIONS = [14, 13, 12, 11, 10];
|
|
15
|
+
|
|
14
16
|
function pythonCandidates() {
|
|
17
|
+
const fromEnv = process.env.CLIPTUDE_PYTHON ? [process.env.CLIPTUDE_PYTHON] : [];
|
|
15
18
|
if (process.platform === "win32") {
|
|
16
|
-
return ["py", "python", "python3"];
|
|
19
|
+
return [...fromEnv, "py", "python", "python3"];
|
|
17
20
|
}
|
|
18
|
-
|
|
21
|
+
// macOS ships python3 3.9 at /usr/bin; a newer Homebrew, pyenv or python.org
|
|
22
|
+
// install is usually only on PATH under its versioned name.
|
|
23
|
+
const versioned = MINOR_VERSIONS.map((minor) => `python3.${minor}`);
|
|
24
|
+
const dirs = ["/opt/homebrew/bin", "/usr/local/bin"];
|
|
25
|
+
const absolute = dirs.flatMap((dir) =>
|
|
26
|
+
versioned.map((name) => path.join(dir, name)),
|
|
27
|
+
);
|
|
28
|
+
return [...fromEnv, ...versioned, "python3", "python", ...absolute];
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function isPython310(cmd) {
|
|
32
|
+
const probe = spawnSync(
|
|
33
|
+
cmd,
|
|
34
|
+
["-c", "import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"],
|
|
35
|
+
{ encoding: "utf8" },
|
|
36
|
+
);
|
|
37
|
+
return probe.status === 0;
|
|
19
38
|
}
|
|
20
39
|
|
|
21
40
|
function findPython() {
|
|
22
|
-
|
|
23
|
-
const probe = spawnSync(
|
|
24
|
-
cmd,
|
|
25
|
-
["-c", "import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"],
|
|
26
|
-
{ encoding: "utf8" },
|
|
27
|
-
);
|
|
28
|
-
if (probe.status === 0) {
|
|
29
|
-
return cmd;
|
|
30
|
-
}
|
|
31
|
-
}
|
|
32
|
-
return null;
|
|
41
|
+
return pythonCandidates().find(isPython310) || null;
|
|
33
42
|
}
|
|
34
43
|
|
|
35
44
|
function venvPython() {
|
|
@@ -120,14 +129,24 @@ function ensureVenv(systemPy) {
|
|
|
120
129
|
return py;
|
|
121
130
|
}
|
|
122
131
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
132
|
+
function resolvePython() {
|
|
133
|
+
// A working install needs no system Python at all.
|
|
134
|
+
const existing = venvPython();
|
|
135
|
+
if (fs.existsSync(existing) && installedVersionMatches(existing)) {
|
|
136
|
+
return existing;
|
|
137
|
+
}
|
|
138
|
+
const systemPy = findPython();
|
|
139
|
+
if (!systemPy) {
|
|
140
|
+
console.error(
|
|
141
|
+
"Python 3.10+ is required and none was found (tried " +
|
|
142
|
+
pythonCandidates().slice(0, 7).join(", ") +
|
|
143
|
+
", ...). Install it, or point CLIPTUDE_PYTHON at one, then re-run: npm i -g @cliptude/cli",
|
|
144
|
+
);
|
|
145
|
+
process.exit(1);
|
|
146
|
+
}
|
|
147
|
+
return ensureVenv(systemPy);
|
|
129
148
|
}
|
|
130
149
|
|
|
131
|
-
const py =
|
|
150
|
+
const py = resolvePython();
|
|
132
151
|
const result = run(py, ["-m", "cliptude_mcp.cli", ...args]);
|
|
133
152
|
process.exit(result.status ?? 1);
|
package/package.json
CHANGED
package/pyproject.toml
CHANGED