@cliptude/cli 0.1.46 → 0.1.51

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
@@ -45,8 +45,13 @@ cliptude templates
45
45
  cliptude template-options --format faceless_documentary
46
46
  cliptude voices --provider elevenlabs
47
47
  cliptude template-create --name "TSMC doc" --format faceless_documentary --set voice_id=<id> --set voice_name=George --set generation_model=pro --set faceless_documentary_style=investigative
48
- cliptude template-create --name "TSMC doc" --format faceless_documentary --settings-file settings.json
49
- 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 3-4
48
+ cliptude template-create --name "TSMC doc" --format faceless_documentary --settings-file settings.json --look cold-case-board --brand-kit 3
49
+ cliptude template-update "TSMC doc" --look "" --no-show-logo # remove the Look, logo off
50
+ cliptude looks # prebuilt Looks; look-template <slug> saves one as a template
51
+ cliptude brand-kits
52
+ cliptude voice-design previews --description "Calm male narrator, late thirties, low and warm" --model-id eleven_ttv_v3
53
+ cliptude voice-design settings <design-id> --stability 0.4 --speed 1.05
54
+ 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
50
55
  cliptude estimate --template "Finance vector weekly" --script-file script.txt
51
56
  cliptude avatars --section mine
52
57
  cliptude generate --template "My avatar weekly" --title "Episode one" --script-file script.txt --avatar 42
@@ -54,7 +59,7 @@ cliptude generate --template "Finance vector weekly" --title "Why index funds wi
54
59
  cliptude generate --template "Finance vector weekly" --title "Why index funds win" --voiceover narration.mp3
55
60
  cliptude generate --template "My talking head" --title "Weekly recap" --talking-head clip.mp4
56
61
  cliptude generate --template "My avatar weekly" --title "Grandma egg trick" --script-file script.txt --avatar-ai-footage --avatar-intro-only
57
- cliptude script --template "Finance vector weekly" --title "Why index funds win" --prompt "why most retail traders underperform the S&P" --duration 3-4
62
+ cliptude script --template "Finance vector weekly" --title "Why index funds win" --prompt "why most retail traders underperform the S&P" --duration 6-8
58
63
  cliptude voiceover --template "Finance vector weekly" --title "Why index funds win" --script-file script.txt
59
64
  cliptude download-voiceover <job-id> --out narration.mp3
60
65
  cliptude editor <job-id> # editor project id, revision, timeline item ids
@@ -65,20 +70,26 @@ cliptude continue <job-id>
65
70
  cliptude status <job-id>
66
71
  ```
67
72
 
68
- 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.
73
+ Live formats: `faceless_documentary`, `faceless_top_10`, `avatar_video`, `talking_head` and `vector_explainer`, all 16:9. Every other format (whiteboard, stickman, Faceless Explainer, Music Video, Avatar Explainer, ...) is retired: `template-options`, `template-create`, `template-update`, `generate` and `plan-job` refuse it; existing videos and templates still open and export. Captions are off by default on every video: turn them on only when the user asks, with `--captions` on `generate`, `plan-job`, `estimate`, `template-create` or `template-update` (MCP and REST `captions: true`), or after the build with `edit` and `{"op": "set_captions", "enabled": true}`.
74
+
75
+ 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`: Avatar IV is the only engine) 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.
69
76
 
70
77
  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.
71
78
 
72
- To revise a finished video, `editor` opens its timeline (item ids, times, text). `edit <project-id> --ops ops.json` applies exact edits on those ids, free and in one revision: delete, retime, trim, set opacity/volume, set a graphic's props, design or picture (an uploaded `keep` id or https link), mute a graphic's sound, add a graphic, clip or catalog sound effect, set a transition, restyle captions, set library music, its volume or remove it, set the background. `versions` and `restore` undo. `agent` asks Cliptude Agent for open-ended edits that need sourcing or generation (it charges agent credits; reference item ids with `--items`), and `render` exports a new MP4. MCP tools: `open_editor_project`, `get_editor_project`, `edit_timeline`, `list_editor_versions`, `restore_editor_version`, `run_agent`, `get_agent_run`, `cancel_agent_run`, `render_project`, `get_render`.
79
+ To revise a finished video, `editor` opens its timeline (item ids, times, text). `edit <project-id> --ops ops.json` applies exact edits on those ids, free and in one revision: delete, retime, trim, set opacity/volume, set a graphic's props, design or picture (an uploaded `keep` id or https link), mute a graphic's sound, add a graphic, clip or catalog sound effect, set a transition, turn captions on or off (`set_captions`; off by default) or restyle them, set library music, its volume or remove it, set the background. `versions` and `restore` undo. `agent` asks Cliptude Agent for open-ended edits that need sourcing or generation (it charges agent credits; reference item ids with `--items`), and `render` exports a new MP4. MCP tools: `open_editor_project`, `get_editor_project`, `edit_timeline`, `list_editor_versions`, `restore_editor_version`, `run_agent`, `get_agent_run`, `cancel_agent_run`, `render_project`, `get_render`.
73
80
 
74
81
  To answer a copyright claim or credit Creative Commons footage, MCP `get_video_sources` lists where every visual in a finished video came from (times on screen, provider, author, license, link) plus the description credits, and `find_media_source` finds every video that used a link, YouTube channel or author.
75
82
 
76
- Brand kits and media: `list_brand_kits` lists the user's brand kits (one per channel: logo, colours, fonts; one is the default); `create_template` and `update_template` take `brand_kit_id` and `show_logo` (the logo is off by default). `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`.
83
+ Brand kits and media: `list_brand_kits` (CLI `brand-kits`) lists the user's brand kits (one per channel: logo, colours, fonts; one is the default); `create_template` and `update_template` (CLI `template-create` / `template-update` with `--brand-kit` and `--show-logo`) take `brand_kit_id` and `show_logo` (the logo is off by default).
84
+
85
+ Looks: `list_looks` (CLI `looks`) lists the prebuilt styles; `create_template` / `update_template` take `look` (CLI `--look`), and `save_look_as_template` (CLI `look-template <slug>`) makes a template from a Look alone. The five motion-graphics Looks (`neon-noir`, `paper-atlas`, `editorial-explainer`, `business-ledger`, `route-atlas`) draw every shot from a component library: make them with `generate` / `create_job`, not `plan-job`. Painted Looks (`painted: true`) AI-paint every scene on Faceless Documentary and add +20 credits/min to the voice rate there (`estimate` shows it as `painted_look_credits_per_minute`, and the job review's Look line says "painted +20/min").
86
+
87
+ 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`.
77
88
 
78
89
  ### Agent-planned videos
79
90
 
80
- On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates an agent can plan every visual and leave Cliptude
81
- only the voicing, sourcing and rendering:
91
+ On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates (not one with a motion-graphics
92
+ Look) an agent can plan every visual and leave Cliptude only the voicing, sourcing and rendering:
82
93
 
83
94
  1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`. Like every job, it answers first with a
84
95
  review of its settings; music, sound effects, transitions, animations and web sources are on by default, and any the
@@ -117,14 +128,14 @@ installed the Cliptude Shopify app) can also be searched.
117
128
  cliptude product fetch https://store.com/products/handle # product_id + 3 angles
118
129
  cliptude product script <product-id> --angle 1 --duration 10-12 --discount-code YOUTUBE15
119
130
  cliptude product status <job-id> # until script_ready; review the script
120
- cliptude product render <job-id> --aspect-ratio 16:9 # returns at once
131
+ cliptude product render <job-id> # 16:9; returns at once
121
132
  cliptude product status <job-id> # until ready_for_review; open editor_url
122
133
  ```
123
134
 
124
135
  MCP tools: `fetch_product_context`, `draft_product_script`, `render_product_video`, `get_product_video_status`.
125
136
  None of them waits for a render; poll the status tool.
126
137
 
127
- `--title` is required. Provide **one** of `--prompt`, `--script` / `--script-file`, `--voiceover`, or `--talking-head`. Never copy the title into `--prompt`. If you only have a topic, follow **cliptude-script** (web search → spoken narration → `--script-file`), or ask Cliptude to write it with `cliptude script`. After a completed `script` or `voiceover` job, `cliptude continue <job-id>` turns that same job into a full video (reuses the script; voiceover jobs reuse the TTS file). `--voiceover` is a local audio file (same as create.html); it is transcribed and skips TTS — do not combine it with prompt/script. `--talking-head` is a presenter video on a Talking Head template (MP4, MOV, WEBM, AVI); it is transcribed and skips TTS. Optional `--duration` is a wizard bucket (`3-4`, `6-8`, `10-12`, …). Omit it to use the template duration, or the word-count estimate when you pass `--script`. Uploaded audio or talking-head video sets duration from the file. Avatar Video templates can override **Avatar Intro Only** and **AI Image + AI Video** with `--avatar-intro-only` / `--no-avatar-intro-only` and `--avatar-ai-footage` / `--no-avatar-ai-footage`. Omit those flags to keep the template. `generate` / `script` / `voiceover` / `continue` return immediately (`queued`). Poll `status`.
138
+ `--title` is required. Provide **one** narration: `--prompt` (Cliptude writes it), `--script` / `--script-file`, `--voiceover` / `--voiceover-url`, or `--talking-head`; a `--prompt` may come with a script, voiceover or talking head as direction for the visuals. Never copy the title into `--prompt`. If you only have a topic, follow **cliptude-script** (web search → spoken narration → `--script-file`), or ask Cliptude to write it with `cliptude script`. After a completed `script` or `voiceover` job, `cliptude continue <job-id>` turns that same job into a full video (reuses the script; voiceover jobs reuse the TTS file). `--voiceover` is a local audio file (same as create.html); it is transcribed and skips TTS — not with `--script` (a `--prompt` with it is direction for the visuals). `--talking-head` is a presenter video on a Talking Head template (MP4, MOV, WEBM, AVI); it is transcribed and skips TTS. Optional `--duration` is a bucket (`6-8`, `8-10`, `10-12`, `18-20`, `30-40`, `50-60`; videos start at 6 minutes). Omit it to use the template duration, or the word-count estimate when you pass `--script`. Uploaded audio or talking-head video sets duration from the file. Avatar Video templates can override **Avatar Intro Only** and **AI Image + AI Video** with `--avatar-intro-only` / `--no-avatar-intro-only` and `--avatar-ai-footage` / `--no-avatar-ai-footage`. Omit those flags to keep the template. `generate` / `script` / `voiceover` / `continue` return immediately (`queued`). Poll `status`.
128
139
 
129
140
  ## MCP
130
141
 
@@ -151,7 +151,6 @@ CHOICE_FIELDS: dict[str, tuple[str, str]] = {
151
151
  "caption_style": ("caption", "Caption style"),
152
152
  "vector_illustration_style": ("text", "Illustration style"),
153
153
  "vector_reveal_mode": ("text", "Motion"),
154
- "faceless_explainer_style": ("text", "Explainer style"),
155
154
  }
156
155
  # Fields an agent-planned video also sets in its plan's look.
157
156
  _PLAN_LOOK_FIELDS = frozenset({"background_music_library_file", "visual_theme", "faceless_documentary_style"})
@@ -266,7 +265,7 @@ def build_apps(
266
265
  Field(description="Setting to choose: " + ", ".join(CHOICE_FIELDS)),
267
266
  ],
268
267
  ) -> dict[str, Any]:
269
- """Let the user preview and pick one template setting: background music (play each track), background picture, style pack (colour swatches), visual theme, caption style, the Vector Explainer illustration style / motion, or the Faceless Explainer style pack. 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}."""
268
+ """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}."""
270
269
  field = (field or "").strip()
271
270
  if field not in CHOICE_FIELDS:
272
271
  return {"error": f"field must be one of: {', '.join(CHOICE_FIELDS)}"}
@@ -1,4 +1,8 @@
1
- """Tiny CLI wrapping /api/v1: auth | pick | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
1
+ """Tiny CLI wrapping /api/v1: auth | pick | templates | template-create | template-update | template-options | looks |
2
+ look-template | brand-kits | voices | voice-design | avatars | estimate | generate | editor | agent | render | script |
3
+ voiceover | continue | status | jobs | account | cancel.
4
+
5
+ Live formats: faceless_documentary, faceless_top_10, avatar_video, talking_head, vector_explainer (16:9 only)."""
2
6
 
3
7
  from __future__ import annotations
4
8
 
@@ -48,6 +52,8 @@ def _reviewed(args, call, *, heading: str = "Review this video before it is crea
48
52
  credits = review.get("credits") or {}
49
53
  if credits.get("credits_required") is not None:
50
54
  out.write(f" Credits: about {credits['credits_required']} (you have {credits.get('credits_available')})\n")
55
+ for line in _rate_lines(review):
56
+ out.write(f" {line}\n")
51
57
  else:
52
58
  for key, value in credits.items():
53
59
  out.write(f" Credits, {key.replace('_', ' ')}: {value}\n")
@@ -64,6 +70,19 @@ def _reviewed(args, call, *, heading: str = "Review this video before it is crea
64
70
  return call(detail["review_token"], approved or None)
65
71
 
66
72
 
73
+ def _rate_lines(review: dict) -> list[str]:
74
+ """The per-minute rate and the painted-Look add-on when there is one, for a job review."""
75
+ credits = review.get("credits") or {}
76
+ lines = []
77
+ if credits.get("credits_per_minute"):
78
+ lines.append(f"Credits per minute: {credits['credits_per_minute']}")
79
+ painted = credits.get("painted_look_credits_per_minute")
80
+ if painted:
81
+ lines.append(f"Painted Look add-on: +{painted} credits/min (AI-painted scenes; included above)")
82
+ # The Look itself is a review setting ("Look: Empire Story (empire-story), painted +20/min ..."), printed above.
83
+ return lines
84
+
85
+
67
86
  def _create_reviewed(client: CliptudeClient, args, **kwargs):
68
87
  """create_job behind the job review (see _reviewed)."""
69
88
  return _reviewed(args, lambda token, acks: client.create_job(review_token=token, acknowledge=acks, **kwargs))
@@ -145,6 +164,54 @@ def _thumbnail_from_args(args) -> dict | None:
145
164
  return thumbnail or None
146
165
 
147
166
 
167
+ def _add_branding_args(parser: argparse.ArgumentParser) -> None:
168
+ parser.add_argument("--look", default=None,
169
+ help='A Look slug from `cliptude looks` whose formats include this one ("" removes it)')
170
+ parser.add_argument("--brand-kit", type=int, default=None,
171
+ help="Brand kit id from `cliptude brand-kits` (0 = your default kit)")
172
+ parser.add_argument("--show-logo", action=argparse.BooleanOptionalAction, default=None,
173
+ help="Put the brand kit's logo on the videos (--no-show-logo: off)")
174
+
175
+
176
+ def _add_captions_arg(parser: argparse.ArgumentParser, *, scope: str) -> None:
177
+ parser.add_argument("--captions", action=argparse.BooleanOptionalAction, default=None,
178
+ help=f"Whole-video captions on {scope}, in the caption style. Off by default; "
179
+ "--no-captions turns them off. Omit to keep the template's.")
180
+
181
+
182
+ def _add_voice_setting_args(parser: argparse.ArgumentParser) -> None:
183
+ parser.add_argument("--stability", type=float, default=None, help="0 to 1")
184
+ parser.add_argument("--similarity-boost", type=float, default=None, help="0 to 1")
185
+ parser.add_argument("--style", type=float, default=None, help="0 to 1")
186
+ parser.add_argument("--speed", type=float, default=None, help="0.7 to 1.2")
187
+ parser.add_argument("--speaker-boost", action=argparse.BooleanOptionalAction, default=None,
188
+ dest="use_speaker_boost")
189
+
190
+
191
+ def _voice_settings_from_args(args) -> dict:
192
+ keys = ("stability", "similarity_boost", "style", "speed", "use_speaker_boost")
193
+ return {k: getattr(args, k) for k in keys if getattr(args, k, None) is not None}
194
+
195
+
196
+ def _save_previews(payload, out_dir: str) -> dict:
197
+ """Write each preview's data: URL audio to a file and replace it with the path."""
198
+ import base64 as _b64
199
+
200
+ if not isinstance(payload, dict):
201
+ return payload
202
+ folder = Path(out_dir).expanduser()
203
+ folder.mkdir(parents=True, exist_ok=True)
204
+ for preview in payload.get("previews") or []:
205
+ url = str(preview.pop("audio_url", "") or "")
206
+ if url.startswith("data:") and ";base64," in url:
207
+ mime, data = url[5:].split(";base64,", 1)
208
+ ext = {"audio/wav": "wav", "audio/ogg": "ogg"}.get(mime, "mp3")
209
+ dest = folder / f"preview_{preview.get('preview_id')}.{ext}"
210
+ dest.write_bytes(_b64.b64decode(data))
211
+ preview["file"] = str(dest)
212
+ return payload
213
+
214
+
148
215
  def _parse_set_args(pairs: list[str]) -> dict:
149
216
  out = {}
150
217
  for pair in pairs:
@@ -175,6 +242,49 @@ def _wait(fetch, status_of, *, interval: float = 10.0, timeout: float = 3600.0):
175
242
  time.sleep(interval)
176
243
 
177
244
 
245
+ def _run_voice_design(client: CliptudeClient, args) -> None:
246
+ import base64 as _b64
247
+
248
+ cmd = args.vd_cmd
249
+ if cmd == "options":
250
+ _print(client.voice_design_options())
251
+ elif cmd == "previews":
252
+ options = {"model_id": args.model_id or None, "should_enhance": args.should_enhance, "text": args.text or None,
253
+ "auto_generate_text": True if args.auto_text else None, "loudness": args.loudness,
254
+ "guidance_scale": args.guidance_scale, "quality": args.quality,
255
+ "prompt_strength": args.prompt_strength, "seed": args.seed}
256
+ payload = client.design_voice_previews(args.provider, args.description, language=args.language or None,
257
+ options=options)
258
+ _print(_save_previews(payload, args.out))
259
+ elif cmd == "save":
260
+ _print(client.save_designed_voice(args.provider, args.preview_id, args.name,
261
+ voice_settings=_voice_settings_from_args(args)))
262
+ elif cmd == "settings":
263
+ settings = _voice_settings_from_args(args)
264
+ if not settings:
265
+ raise CliptudeApiError("Give at least one of --stability, --similarity-boost, --style, --speed, --speaker-boost.")
266
+ _print(client.update_designed_voice_settings(args.design_id, settings))
267
+ elif cmd == "try":
268
+ payload = client.try_designed_voice(args.design_id, text=args.text or None,
269
+ voice_settings=_voice_settings_from_args(args),
270
+ model_id=args.model_id or None, language_code=args.language_code or None)
271
+ url = str((payload or {}).pop("audio_url", "") or "")
272
+ if ";base64," in url:
273
+ dest = Path(args.out).expanduser()
274
+ dest.write_bytes(_b64.b64decode(url.split(";base64,", 1)[1]))
275
+ payload["file"] = str(dest.resolve())
276
+ _print(payload)
277
+ elif cmd == "remix":
278
+ payload = client.remix_designed_voice(args.design_id, args.description, options={
279
+ "guidance_scale": args.guidance_scale, "loudness": args.loudness, "text": args.text or None,
280
+ "seed": args.seed})
281
+ _print(_save_previews(payload, args.out))
282
+ elif cmd == "remix-save":
283
+ _print(client.save_remixed_voice(args.design_id, args.preview_id, voice_name=args.name or None))
284
+ elif cmd == "delete":
285
+ _print(client.delete_designed_voice(args.provider, args.design_id))
286
+
287
+
178
288
  def _run_pick(client: CliptudeClient, args) -> dict:
179
289
  """Open a browser picker (made here with --kind, or one an agent got as browser_picker_url) and wait for it.
180
290
 
@@ -280,7 +390,7 @@ def main(argv: list[str] | None = None) -> None:
280
390
  "example:\n"
281
391
  ' cliptude generate --template "Finance vector weekly" --title "Why index funds win" '
282
392
  '--prompt "why most retail traders underperform the S&P over 10 years, keep it for beginners" '
283
- '--duration 3-4'
393
+ '--duration 6-8'
284
394
  ),
285
395
  )
286
396
  sub = parser.add_subparsers(dest="cmd", required=True)
@@ -345,6 +455,95 @@ def main(argv: list[str] | None = None) -> None:
345
455
  help="One setting; VALUE is parsed as JSON when possible (true, 0.4, [\"a\"]), else a string. Repeatable.",
346
456
  )
347
457
  _add_thumbnail_args(tc, scope="every video from this template")
458
+ _add_branding_args(tc)
459
+ _add_captions_arg(tc, scope="every video from this template")
460
+
461
+ tu = sub.add_parser(
462
+ "template-update",
463
+ help="Rename a template, set its Look, brand kit or logo",
464
+ formatter_class=argparse.RawDescriptionHelpFormatter,
465
+ epilog=(
466
+ "example:\n"
467
+ ' cliptude template-update "TSMC doc" --look cold-case-board --brand-kit 3 --show-logo\n'
468
+ ' cliptude template-update "TSMC doc" --look "" (removes the Look)'
469
+ ),
470
+ )
471
+ tu.add_argument("template", help="Template name or UUID")
472
+ tu.add_argument("--name", default=None, help="New name")
473
+ _add_branding_args(tu)
474
+ _add_captions_arg(tu, scope="every video from this template")
475
+
476
+ lk = sub.add_parser("looks", help="List the prebuilt Looks (formats, colours, painted +20 credits/min, motion graphics)")
477
+ lk.add_argument("--topic", default="", help="The video's title or description: the Looks that fit it come first with suggested=true and a reason")
478
+ lk.add_argument("--format", default="", help="Only suggest Looks that work with this format")
479
+ lt = sub.add_parser("look-template", help="Save a Look as one of your templates; prints the template")
480
+ lt.add_argument("slug", help="Look slug from `cliptude looks`")
481
+ lt.add_argument("--name", default="", help="Template name (default: the Look's name)")
482
+ lt.add_argument("--format", default="", help="One of the Look's formats (default: its own)")
483
+ sub.add_parser("brand-kits", help="List your brand kits (id for --brand-kit)")
484
+
485
+ vd = sub.add_parser(
486
+ "voice-design",
487
+ help="Design your own voice: options, previews, save, settings, try, remix, delete",
488
+ formatter_class=argparse.RawDescriptionHelpFormatter,
489
+ epilog=(
490
+ "examples:\n"
491
+ " cliptude voice-design options\n"
492
+ ' cliptude voice-design previews --description "Calm male narrator, late thirties, low and warm" '
493
+ "--model-id eleven_ttv_v3 --guidance-scale 6\n"
494
+ " cliptude voice-design save <preview-id> --name \"Night Narrator\" --stability 0.4\n"
495
+ " cliptude voice-design settings <design-id> --speed 1.05 --no-speaker-boost\n"
496
+ ' cliptude voice-design try <design-id> --text "One line to hear it." --out try.mp3\n'
497
+ ' cliptude voice-design remix <design-id> --description "a little warmer"\n'
498
+ " cliptude voice-design remix-save <design-id> <preview-id>\n"
499
+ " cliptude voice-design delete <design-id>\n"
500
+ "Design ids are design_id in `cliptude voices` (my_voices). Numbers outside a range are clamped."
501
+ ),
502
+ )
503
+ vd_sub = vd.add_subparsers(dest="vd_cmd", required=True)
504
+ vd_sub.add_parser("options", help="Design models, option ranges and defaults, voice setting ranges")
505
+ vdp = vd_sub.add_parser("previews", help="Design previews from a description (preview audio saved as files)")
506
+ vdp.add_argument("--provider", default="elevenlabs", choices=["elevenlabs", "minimax", "inworld"])
507
+ vdp.add_argument("--description", required=True)
508
+ vdp.add_argument("--language", default="")
509
+ vdp.add_argument("--model-id", default="")
510
+ vdp.add_argument("--enhance", action=argparse.BooleanOptionalAction, default=None, dest="should_enhance")
511
+ vdp.add_argument("--text", default="", help="Preview line, 100-1000 characters")
512
+ vdp.add_argument("--auto-text", action="store_true", help="ElevenLabs writes the preview line")
513
+ for flag in ("loudness", "guidance-scale", "quality", "prompt-strength"):
514
+ vdp.add_argument(f"--{flag}", type=float, default=None)
515
+ vdp.add_argument("--seed", type=int, default=None)
516
+ vdp.add_argument("--out", default=".", help="Folder for the preview audio files")
517
+ vds = vd_sub.add_parser("save", help="Keep one preview as your voice")
518
+ vds.add_argument("preview_id")
519
+ vds.add_argument("--name", required=True)
520
+ vds.add_argument("--provider", default="elevenlabs", choices=["elevenlabs", "minimax", "inworld"])
521
+ _add_voice_setting_args(vds)
522
+ vdt = vd_sub.add_parser("settings", help="Change a designed ElevenLabs voice's settings (others keep theirs)")
523
+ vdt.add_argument("design_id")
524
+ _add_voice_setting_args(vdt)
525
+ vdy = vd_sub.add_parser("try", help="Speak a test line with these settings (saves an MP3)")
526
+ vdy.add_argument("design_id")
527
+ vdy.add_argument("--text", default="")
528
+ vdy.add_argument("--model-id", default="")
529
+ vdy.add_argument("--language-code", default="")
530
+ vdy.add_argument("--out", default="voice_try.mp3")
531
+ _add_voice_setting_args(vdy)
532
+ vdr = vd_sub.add_parser("remix", help="Previews of a designed ElevenLabs voice with a change")
533
+ vdr.add_argument("design_id")
534
+ vdr.add_argument("--description", required=True)
535
+ vdr.add_argument("--guidance-scale", type=float, default=None)
536
+ vdr.add_argument("--loudness", type=float, default=None)
537
+ vdr.add_argument("--text", default="")
538
+ vdr.add_argument("--seed", type=int, default=None)
539
+ vdr.add_argument("--out", default=".", help="Folder for the preview audio files")
540
+ vdrs = vd_sub.add_parser("remix-save", help="Replace the voice with a remix preview")
541
+ vdrs.add_argument("design_id")
542
+ vdrs.add_argument("preview_id")
543
+ vdrs.add_argument("--name", default="")
544
+ vdd = vd_sub.add_parser("delete", help="Delete a designed voice here and at the provider")
545
+ vdd.add_argument("design_id")
546
+ vdd.add_argument("--provider", default="elevenlabs", choices=["elevenlabs", "minimax", "inworld"])
348
547
 
349
548
  to = sub.add_parser("template-options", help="Fields, choices and defaults for template-create")
350
549
  to.add_argument("--format", required=True)
@@ -391,8 +590,9 @@ def main(argv: list[str] | None = None) -> None:
391
590
  est.add_argument("--avatar-intro-only", action=argparse.BooleanOptionalAction, default=None)
392
591
  est.add_argument("--avatar-ai-footage", action=argparse.BooleanOptionalAction, default=None)
393
592
  est.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
394
- est.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
593
+ est.add_argument("--avatar-engine", default="", choices=["", "iv"], help="Avatar Video: iv (Avatar IV, the only engine). Default: the template's")
395
594
  est.add_argument("--vector-motion", default="", choices=["", "none", "video"], help="Vector Explainer: price stills (none) or AI clips (video)")
595
+ _add_captions_arg(est, scope="this video")
396
596
  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)")
397
597
 
398
598
  g = sub.add_parser(
@@ -403,7 +603,7 @@ def main(argv: list[str] | None = None) -> None:
403
603
  "example:\n"
404
604
  ' cliptude generate --template "Finance vector weekly" --title "Why index funds win" '
405
605
  '--prompt "why most retail traders underperform the S&P over 10 years, keep it for beginners" '
406
- '--duration 3-4\n'
606
+ '--duration 6-8\n'
407
607
  ' cliptude generate --template "Finance vector weekly" --title "Why index funds win" '
408
608
  '--script-file script.txt\n'
409
609
  ' cliptude generate --template "Finance vector weekly" --title "Why index funds win" '
@@ -417,25 +617,27 @@ def main(argv: list[str] | None = None) -> None:
417
617
  g.add_argument(
418
618
  "--prompt",
419
619
  default="",
420
- help='Topic or brief, e.g. "why most retail traders underperform the S&P over 10 years, keep it for beginners"',
620
+ help='The description: a topic or brief (only when Cliptude should write the narration), and any direction '
621
+ 'for the visuals ("Open with a map of Europe. Use @founder_photo"). With --script, --voiceover or --talking-head '
622
+ "it is direction only. Captions are off by default (turn them on later with `edit` and set_captions).",
421
623
  )
422
624
  g.add_argument("--script", default="")
423
625
  g.add_argument("--script-file", default="")
424
626
  g.add_argument(
425
627
  "--voiceover",
426
628
  default="",
427
- help="Path to a narration audio file (MP3, M4A, WAV, …), at least 6 minutes long. Transcribed; skips TTS. Do not combine with --prompt or --script.",
629
+ help="Path to a narration audio file (MP3, M4A, WAV, …), at least 6 minutes long. Transcribed; skips TTS. Not with --script; a --prompt with it is direction for the visuals.",
428
630
  )
429
- g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio (at least 6 minutes long); Cliptude downloads it.")
631
+ g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio (at least 6 minutes long); Cliptude downloads it. Not with --script; --prompt is direction.")
430
632
  g.add_argument(
431
633
  "--talking-head",
432
634
  default="",
433
- help="Path to a talking-head presenter video (MP4, MOV, WEBM, AVI), at least 6 minutes long. Requires a Talking Head template. Transcribed; skips TTS. Do not combine with --prompt, --script, or --voiceover.",
635
+ help="Path to a talking-head presenter video (MP4, MOV, WEBM, AVI), at least 6 minutes long. Requires a Talking Head template. Transcribed; skips TTS. Not with --script or --voiceover; a --prompt with it is direction for the visuals.",
434
636
  )
435
637
  g.add_argument(
436
638
  "--duration",
437
639
  default="",
438
- help="Wizard duration bucket, e.g. 3-4 or 6-8. Default: template duration (or estimated from --script)",
640
+ help="Duration bucket: 6-8, 8-10, 10-12, 18-20, 30-40 or 50-60 (videos start at 6 minutes). Default: template duration (or estimated from --script)",
439
641
  )
440
642
  g.add_argument(
441
643
  "--avatar-intro-only",
@@ -456,7 +658,7 @@ def main(argv: list[str] | None = None) -> None:
456
658
  ),
457
659
  )
458
660
  g.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
459
- g.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
661
+ g.add_argument("--avatar-engine", default="", choices=["", "iv"], help="Avatar Video: iv (Avatar IV, the only engine). Default: the template's")
460
662
  g.add_argument(
461
663
  "--disable-animations",
462
664
  action=argparse.BooleanOptionalAction,
@@ -506,6 +708,7 @@ def main(argv: list[str] | None = None) -> None:
506
708
  _add_thumbnail_args(g, scope="this video")
507
709
  _add_pronunciations_arg(g)
508
710
  g.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
711
+ _add_captions_arg(g, scope="this video")
509
712
  g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
510
713
 
511
714
  sc = sub.add_parser(
@@ -515,13 +718,13 @@ def main(argv: list[str] | None = None) -> None:
515
718
  epilog=(
516
719
  "example:\n"
517
720
  ' cliptude script --template "Finance vector weekly" --title "Why index funds win" '
518
- '--prompt "why most retail traders underperform the S&P" --duration 3-4'
721
+ '--prompt "why most retail traders underperform the S&P" --duration 6-8'
519
722
  ),
520
723
  )
521
724
  sc.add_argument("--template", required=True, help="Template name or UUID")
522
725
  sc.add_argument("--title", required=True)
523
726
  sc.add_argument("--prompt", required=True, help="Topic or brief. Cliptude writes the narration.")
524
- sc.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 3-4 or 6-8")
727
+ sc.add_argument("--duration", default="", help="Duration bucket, e.g. 6-8 or 10-12 (videos start at 6 minutes)")
525
728
 
526
729
  vo = sub.add_parser(
527
730
  "voiceover",
@@ -538,7 +741,7 @@ def main(argv: list[str] | None = None) -> None:
538
741
  vo.add_argument("--prompt", default="", help="Topic or brief. Cliptude writes the narration then voices it.")
539
742
  vo.add_argument("--script", default="")
540
743
  vo.add_argument("--script-file", default="")
541
- vo.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 3-4 or 6-8")
744
+ vo.add_argument("--duration", default="", help="Duration bucket, e.g. 6-8 or 10-12 (videos start at 6 minutes)")
542
745
 
543
746
  dv = sub.add_parser("download-voiceover", help="Download the voiceover MP3 of a voiceover job, or the narration of a plan_ready plan job")
544
747
  dv.add_argument("job_id")
@@ -590,7 +793,7 @@ def main(argv: list[str] | None = None) -> None:
590
793
  _add_review_args(ps)
591
794
  pr = prod_sub.add_parser("render", help="Produce the video from a ready product script")
592
795
  pr.add_argument("job_id")
593
- pr.add_argument("--aspect-ratio", default="16:9")
796
+ pr.add_argument("--aspect-ratio", default="16:9", choices=["16:9"], help="Cliptude makes 16:9 videos only")
594
797
  _add_thumbnail_args(pr, scope="this video")
595
798
  _add_review_args(pr)
596
799
  pst = prod_sub.add_parser("status", help="Stage, script, preview link and MP4 of a product video")
@@ -610,20 +813,21 @@ def main(argv: list[str] | None = None) -> None:
610
813
  " cliptude plan-report <job-id>"
611
814
  ),
612
815
  )
613
- pj.add_argument("--template", required=True, help="Template name or UUID (Faceless Documentary, Top 10, Avatar Video)")
816
+ pj.add_argument("--template", required=True, help="Template name or UUID (Faceless Documentary, Top 10, Avatar Video, Vector Explainer; not a motion-graphics Look: use generate)")
614
817
  pj.add_argument("--title", required=True)
615
- pj.add_argument("--prompt", default="", help="Topic or brief. Cliptude writes the narration.")
818
+ pj.add_argument("--prompt", default="", help="Topic or brief, only when Cliptude writes the narration. Omit it with --script or --voiceover: your plan is the visual direction.")
616
819
  pj.add_argument("--script", default="")
617
820
  pj.add_argument("--script-file", default="")
618
821
  pj.add_argument("--voiceover", default="", help="Local audio to use as the narration (aligned, not re-voiced)")
619
822
  pj.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it")
620
823
  pj.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 6-8")
621
824
  pj.add_argument("--avatar", type=int, default=None, help="Avatar Video: avatar id from `cliptude avatars`. Default: the template's avatar")
622
- pj.add_argument("--avatar-engine", default="", choices=["", "iv", "v"], help="Avatar Video: HeyGen engine. Default: the template's")
825
+ pj.add_argument("--avatar-engine", default="", choices=["", "iv"], help="Avatar Video: iv (Avatar IV, the only engine). Default: the template's")
623
826
  pj.add_argument("--render-only", action="store_true", help="You bring everything (needs --voiceover); Cliptude only builds and renders, at the render-only rate")
624
827
  _add_thumbnail_args(pj, scope="this video")
625
828
  _add_pronunciations_arg(pj)
626
829
  pj.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
830
+ _add_captions_arg(pj, scope="this video")
627
831
  pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
628
832
 
629
833
  nr = sub.add_parser("narration", help="Numbered sentences and word timings of a plan_ready job")
@@ -762,7 +966,24 @@ def main(argv: list[str] | None = None) -> None:
762
966
  thumbnail = _thumbnail_from_args(args)
763
967
  if thumbnail:
764
968
  settings["thumbnail"] = thumbnail
765
- _print(client.create_template(name=args.name, format=args.format, settings=settings))
969
+ _print(client.create_template(name=args.name, format=args.format, settings=settings,
970
+ brand_kit_id=args.brand_kit, show_logo=args.show_logo, look=args.look or None,
971
+ captions=args.captions))
972
+ elif args.cmd == "template-update":
973
+ if (args.name is None and args.look is None and args.brand_kit is None and args.show_logo is None
974
+ and args.captions is None):
975
+ raise CliptudeApiError("Give --name, --look, --brand-kit, --show-logo / --no-show-logo or --captions / --no-captions.")
976
+ _print(client.update_template(_resolve_template_id(client, args.template), name=args.name,
977
+ brand_kit_id=args.brand_kit, show_logo=args.show_logo, look=args.look,
978
+ captions=args.captions))
979
+ elif args.cmd == "looks":
980
+ _print(client.list_looks(topic=args.topic or None, format=args.format or None))
981
+ elif args.cmd == "look-template":
982
+ _print(client.save_look_as_template(args.slug, name=args.name or None, format=args.format or None))
983
+ elif args.cmd == "brand-kits":
984
+ _print(client.list_brand_kits())
985
+ elif args.cmd == "voice-design":
986
+ _run_voice_design(client, args)
766
987
  elif args.cmd == "template-options":
767
988
  _print(client.template_options(args.format))
768
989
  elif args.cmd == "voices":
@@ -800,6 +1021,7 @@ def main(argv: list[str] | None = None) -> None:
800
1021
  avatar_engine=args.avatar_engine or None,
801
1022
  render_only=args.render_only or None,
802
1023
  vector_reveal_mode=args.vector_motion or None,
1024
+ captions=args.captions,
803
1025
  ))
804
1026
  elif args.cmd == "generate":
805
1027
  script = args.script
@@ -810,19 +1032,20 @@ def main(argv: list[str] | None = None) -> None:
810
1032
  talking_head = (args.talking_head or "").strip()
811
1033
  if talking_head and (voiceover or voiceover_url):
812
1034
  raise CliptudeApiError("Use --talking-head or --voiceover, not both.")
813
- if talking_head and (args.prompt or script):
1035
+ # --prompt may come with any narration as direction for the visuals; two narrations may not.
1036
+ if talking_head and script:
814
1037
  raise CliptudeApiError(
815
- "Use --talking-head or --prompt/--script, not both. "
816
- "An uploaded talking head is transcribed and used as the narration."
1038
+ "Use --talking-head or --script, not both. "
1039
+ "An uploaded talking head is transcribed and used as the narration; --prompt is fine as direction."
817
1040
  )
818
- if voiceover and (args.prompt or script):
1041
+ if (voiceover or voiceover_url) and script:
819
1042
  raise CliptudeApiError(
820
- "Use --voiceover or --prompt/--script, not both. "
821
- "An uploaded file is transcribed and used as the narration."
1043
+ "Use --voiceover or --script, not both. "
1044
+ "An uploaded file is transcribed and used as the narration; --prompt is fine as direction."
822
1045
  )
823
- if not talking_head and not voiceover and not (args.prompt or script):
1046
+ if not talking_head and not voiceover and not voiceover_url and not (args.prompt or script):
824
1047
  raise CliptudeApiError(
825
- "Provide --prompt, --script / --script-file, --voiceover, or --talking-head."
1048
+ "Provide --prompt, --script / --script-file, --voiceover, --voiceover-url, or --talking-head."
826
1049
  )
827
1050
  template_id = _resolve_template_id(client, args.template)
828
1051
  _print(_create_reviewed(client, args,
@@ -849,6 +1072,7 @@ def main(argv: list[str] | None = None) -> None:
849
1072
  vector_character_id=args.vector_character or None,
850
1073
  vector_reveal_mode=args.vector_motion or None,
851
1074
  pronunciations=_pronunciations_from_args(args),
1075
+ captions=args.captions,
852
1076
  ))
853
1077
  elif args.cmd == "script":
854
1078
  if not (args.prompt or "").strip():
@@ -901,6 +1125,7 @@ def main(argv: list[str] | None = None) -> None:
901
1125
  vector_character_id=args.vector_character or None,
902
1126
  vector_reveal_mode=args.vector_motion or None,
903
1127
  pronunciations=_pronunciations_from_args(args),
1128
+ captions=args.captions,
904
1129
  ))
905
1130
  elif args.cmd == "narration":
906
1131
  _print(client.get_narration(args.job_id))