@cliptude/cli 0.1.9 → 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 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 iii|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.
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
 
@@ -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=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
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=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
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 for a completed voiceover job")
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=["", "iii", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
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))
@@ -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:
@@ -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: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
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: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
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: "iii", "iv" or "v" (list_avatars shows which each avatar supports). Omit to keep the template.'),
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, and pricing (website price, already charged, due at continue)."""
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:
@@ -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
- return ["python3", "python"];
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
- for (const cmd of pythonCandidates()) {
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
- const systemPy = findPython();
124
- if (!systemPy) {
125
- console.error(
126
- "Python 3.10+ is required. Install it, then re-run: npm i -g @cliptude/cli",
127
- );
128
- process.exit(1);
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 = ensureVenv(systemPy);
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
@@ -1,13 +1,15 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "description": "Cliptude CLI — generate videos from saved templates.",
5
5
  "homepage": "https://github.com/cliptude/cliptude#readme",
6
6
  "bin": {
7
- "cliptude": "./npm/bin/cliptude.js"
7
+ "cliptude": "npm/bin/cliptude.js"
8
8
  },
9
9
  "files": [
10
10
  "cliptude_mcp",
11
+ "!cliptude_mcp/__pycache__",
12
+ "!**/*.pyc",
11
13
  "pyproject.toml",
12
14
  "README.md",
13
15
  "npm"
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cliptude-mcp"
7
- version = "0.1.9"
7
+ version = "0.1.11"
8
8
  description = "Cliptude jobs CLI and MCP server (thin client of /api/v1)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"