@cliptude/cli 0.1.44 → 0.1.50

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,16 +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`.
80
+
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.
82
+
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`.
73
88
 
74
89
  ### Agent-planned videos
75
90
 
76
- On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates an agent can plan every visual and leave Cliptude
77
- 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:
78
93
 
79
94
  1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`. Like every job, it answers first with a
80
95
  review of its settings; music, sound effects, transitions, animations and web sources are on by default, and any the
@@ -113,14 +128,14 @@ installed the Cliptude Shopify app) can also be searched.
113
128
  cliptude product fetch https://store.com/products/handle # product_id + 3 angles
114
129
  cliptude product script <product-id> --angle 1 --duration 10-12 --discount-code YOUTUBE15
115
130
  cliptude product status <job-id> # until script_ready; review the script
116
- cliptude product render <job-id> --aspect-ratio 16:9 # returns at once
131
+ cliptude product render <job-id> # 16:9; returns at once
117
132
  cliptude product status <job-id> # until ready_for_review; open editor_url
118
133
  ```
119
134
 
120
135
  MCP tools: `fetch_product_context`, `draft_product_script`, `render_product_video`, `get_product_video_status`.
121
136
  None of them waits for a render; poll the status tool.
122
137
 
123
- `--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`.
124
139
 
125
140
  ## MCP
126
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)}"}
@@ -444,4 +443,9 @@ def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
444
443
  "tags": meta.get("tags") or [],
445
444
  "downloads": meta.get("downloads") or {},
446
445
  },
446
+ "sources": {
447
+ "items": meta.get("sources") or [],
448
+ "complete": meta.get("sources_complete", True),
449
+ "credits_text": meta.get("credits_text") or "",
450
+ },
447
451
  }
@@ -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,93 @@ 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
+ sub.add_parser("looks", help="List the prebuilt Looks (formats, colours, painted +20 credits/min, motion graphics)")
477
+ lt = sub.add_parser("look-template", help="Save a Look as one of your templates; prints the template")
478
+ lt.add_argument("slug", help="Look slug from `cliptude looks`")
479
+ lt.add_argument("--name", default="", help="Template name (default: the Look's name)")
480
+ lt.add_argument("--format", default="", help="One of the Look's formats (default: its own)")
481
+ sub.add_parser("brand-kits", help="List your brand kits (id for --brand-kit)")
482
+
483
+ vd = sub.add_parser(
484
+ "voice-design",
485
+ help="Design your own voice: options, previews, save, settings, try, remix, delete",
486
+ formatter_class=argparse.RawDescriptionHelpFormatter,
487
+ epilog=(
488
+ "examples:\n"
489
+ " cliptude voice-design options\n"
490
+ ' cliptude voice-design previews --description "Calm male narrator, late thirties, low and warm" '
491
+ "--model-id eleven_ttv_v3 --guidance-scale 6\n"
492
+ " cliptude voice-design save <preview-id> --name \"Night Narrator\" --stability 0.4\n"
493
+ " cliptude voice-design settings <design-id> --speed 1.05 --no-speaker-boost\n"
494
+ ' cliptude voice-design try <design-id> --text "One line to hear it." --out try.mp3\n'
495
+ ' cliptude voice-design remix <design-id> --description "a little warmer"\n'
496
+ " cliptude voice-design remix-save <design-id> <preview-id>\n"
497
+ " cliptude voice-design delete <design-id>\n"
498
+ "Design ids are design_id in `cliptude voices` (my_voices). Numbers outside a range are clamped."
499
+ ),
500
+ )
501
+ vd_sub = vd.add_subparsers(dest="vd_cmd", required=True)
502
+ vd_sub.add_parser("options", help="Design models, option ranges and defaults, voice setting ranges")
503
+ vdp = vd_sub.add_parser("previews", help="Design previews from a description (preview audio saved as files)")
504
+ vdp.add_argument("--provider", default="elevenlabs", choices=["elevenlabs", "minimax", "inworld"])
505
+ vdp.add_argument("--description", required=True)
506
+ vdp.add_argument("--language", default="")
507
+ vdp.add_argument("--model-id", default="")
508
+ vdp.add_argument("--enhance", action=argparse.BooleanOptionalAction, default=None, dest="should_enhance")
509
+ vdp.add_argument("--text", default="", help="Preview line, 100-1000 characters")
510
+ vdp.add_argument("--auto-text", action="store_true", help="ElevenLabs writes the preview line")
511
+ for flag in ("loudness", "guidance-scale", "quality", "prompt-strength"):
512
+ vdp.add_argument(f"--{flag}", type=float, default=None)
513
+ vdp.add_argument("--seed", type=int, default=None)
514
+ vdp.add_argument("--out", default=".", help="Folder for the preview audio files")
515
+ vds = vd_sub.add_parser("save", help="Keep one preview as your voice")
516
+ vds.add_argument("preview_id")
517
+ vds.add_argument("--name", required=True)
518
+ vds.add_argument("--provider", default="elevenlabs", choices=["elevenlabs", "minimax", "inworld"])
519
+ _add_voice_setting_args(vds)
520
+ vdt = vd_sub.add_parser("settings", help="Change a designed ElevenLabs voice's settings (others keep theirs)")
521
+ vdt.add_argument("design_id")
522
+ _add_voice_setting_args(vdt)
523
+ vdy = vd_sub.add_parser("try", help="Speak a test line with these settings (saves an MP3)")
524
+ vdy.add_argument("design_id")
525
+ vdy.add_argument("--text", default="")
526
+ vdy.add_argument("--model-id", default="")
527
+ vdy.add_argument("--language-code", default="")
528
+ vdy.add_argument("--out", default="voice_try.mp3")
529
+ _add_voice_setting_args(vdy)
530
+ vdr = vd_sub.add_parser("remix", help="Previews of a designed ElevenLabs voice with a change")
531
+ vdr.add_argument("design_id")
532
+ vdr.add_argument("--description", required=True)
533
+ vdr.add_argument("--guidance-scale", type=float, default=None)
534
+ vdr.add_argument("--loudness", type=float, default=None)
535
+ vdr.add_argument("--text", default="")
536
+ vdr.add_argument("--seed", type=int, default=None)
537
+ vdr.add_argument("--out", default=".", help="Folder for the preview audio files")
538
+ vdrs = vd_sub.add_parser("remix-save", help="Replace the voice with a remix preview")
539
+ vdrs.add_argument("design_id")
540
+ vdrs.add_argument("preview_id")
541
+ vdrs.add_argument("--name", default="")
542
+ vdd = vd_sub.add_parser("delete", help="Delete a designed voice here and at the provider")
543
+ vdd.add_argument("design_id")
544
+ vdd.add_argument("--provider", default="elevenlabs", choices=["elevenlabs", "minimax", "inworld"])
348
545
 
349
546
  to = sub.add_parser("template-options", help="Fields, choices and defaults for template-create")
350
547
  to.add_argument("--format", required=True)
@@ -391,8 +588,9 @@ def main(argv: list[str] | None = None) -> None:
391
588
  est.add_argument("--avatar-intro-only", action=argparse.BooleanOptionalAction, default=None)
392
589
  est.add_argument("--avatar-ai-footage", action=argparse.BooleanOptionalAction, default=None)
393
590
  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")
591
+ est.add_argument("--avatar-engine", default="", choices=["", "iv"], help="Avatar Video: iv (Avatar IV, the only engine). Default: the template's")
395
592
  est.add_argument("--vector-motion", default="", choices=["", "none", "video"], help="Vector Explainer: price stills (none) or AI clips (video)")
593
+ _add_captions_arg(est, scope="this video")
396
594
  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
595
 
398
596
  g = sub.add_parser(
@@ -403,7 +601,7 @@ def main(argv: list[str] | None = None) -> None:
403
601
  "example:\n"
404
602
  ' cliptude generate --template "Finance vector weekly" --title "Why index funds win" '
405
603
  '--prompt "why most retail traders underperform the S&P over 10 years, keep it for beginners" '
406
- '--duration 3-4\n'
604
+ '--duration 6-8\n'
407
605
  ' cliptude generate --template "Finance vector weekly" --title "Why index funds win" '
408
606
  '--script-file script.txt\n'
409
607
  ' cliptude generate --template "Finance vector weekly" --title "Why index funds win" '
@@ -417,25 +615,27 @@ def main(argv: list[str] | None = None) -> None:
417
615
  g.add_argument(
418
616
  "--prompt",
419
617
  default="",
420
- help='Topic or brief, e.g. "why most retail traders underperform the S&P over 10 years, keep it for beginners"',
618
+ help='The description: a topic or brief (only when Cliptude should write the narration), and any direction '
619
+ 'for the visuals ("Open with a map of Europe. Use @founder_photo"). With --script, --voiceover or --talking-head '
620
+ "it is direction only. Captions are off by default (turn them on later with `edit` and set_captions).",
421
621
  )
422
622
  g.add_argument("--script", default="")
423
623
  g.add_argument("--script-file", default="")
424
624
  g.add_argument(
425
625
  "--voiceover",
426
626
  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.",
627
+ 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
628
  )
429
- g.add_argument("--voiceover-url", default="", help="Public https link to the narration audio (at least 6 minutes long); Cliptude downloads it.")
629
+ 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
630
  g.add_argument(
431
631
  "--talking-head",
432
632
  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.",
633
+ 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
634
  )
435
635
  g.add_argument(
436
636
  "--duration",
437
637
  default="",
438
- help="Wizard duration bucket, e.g. 3-4 or 6-8. Default: template duration (or estimated from --script)",
638
+ 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
639
  )
440
640
  g.add_argument(
441
641
  "--avatar-intro-only",
@@ -456,7 +656,7 @@ def main(argv: list[str] | None = None) -> None:
456
656
  ),
457
657
  )
458
658
  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")
659
+ g.add_argument("--avatar-engine", default="", choices=["", "iv"], help="Avatar Video: iv (Avatar IV, the only engine). Default: the template's")
460
660
  g.add_argument(
461
661
  "--disable-animations",
462
662
  action=argparse.BooleanOptionalAction,
@@ -506,6 +706,7 @@ def main(argv: list[str] | None = None) -> None:
506
706
  _add_thumbnail_args(g, scope="this video")
507
707
  _add_pronunciations_arg(g)
508
708
  g.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
709
+ _add_captions_arg(g, scope="this video")
509
710
  g.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
510
711
 
511
712
  sc = sub.add_parser(
@@ -515,13 +716,13 @@ def main(argv: list[str] | None = None) -> None:
515
716
  epilog=(
516
717
  "example:\n"
517
718
  ' cliptude script --template "Finance vector weekly" --title "Why index funds win" '
518
- '--prompt "why most retail traders underperform the S&P" --duration 3-4'
719
+ '--prompt "why most retail traders underperform the S&P" --duration 6-8'
519
720
  ),
520
721
  )
521
722
  sc.add_argument("--template", required=True, help="Template name or UUID")
522
723
  sc.add_argument("--title", required=True)
523
724
  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")
725
+ sc.add_argument("--duration", default="", help="Duration bucket, e.g. 6-8 or 10-12 (videos start at 6 minutes)")
525
726
 
526
727
  vo = sub.add_parser(
527
728
  "voiceover",
@@ -538,7 +739,7 @@ def main(argv: list[str] | None = None) -> None:
538
739
  vo.add_argument("--prompt", default="", help="Topic or brief. Cliptude writes the narration then voices it.")
539
740
  vo.add_argument("--script", default="")
540
741
  vo.add_argument("--script-file", default="")
541
- vo.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 3-4 or 6-8")
742
+ vo.add_argument("--duration", default="", help="Duration bucket, e.g. 6-8 or 10-12 (videos start at 6 minutes)")
542
743
 
543
744
  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
745
  dv.add_argument("job_id")
@@ -590,7 +791,7 @@ def main(argv: list[str] | None = None) -> None:
590
791
  _add_review_args(ps)
591
792
  pr = prod_sub.add_parser("render", help="Produce the video from a ready product script")
592
793
  pr.add_argument("job_id")
593
- pr.add_argument("--aspect-ratio", default="16:9")
794
+ pr.add_argument("--aspect-ratio", default="16:9", choices=["16:9"], help="Cliptude makes 16:9 videos only")
594
795
  _add_thumbnail_args(pr, scope="this video")
595
796
  _add_review_args(pr)
596
797
  pst = prod_sub.add_parser("status", help="Stage, script, preview link and MP4 of a product video")
@@ -610,20 +811,21 @@ def main(argv: list[str] | None = None) -> None:
610
811
  " cliptude plan-report <job-id>"
611
812
  ),
612
813
  )
613
- pj.add_argument("--template", required=True, help="Template name or UUID (Faceless Documentary, Top 10, Avatar Video)")
814
+ 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
815
  pj.add_argument("--title", required=True)
615
- pj.add_argument("--prompt", default="", help="Topic or brief. Cliptude writes the narration.")
816
+ 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
817
  pj.add_argument("--script", default="")
617
818
  pj.add_argument("--script-file", default="")
618
819
  pj.add_argument("--voiceover", default="", help="Local audio to use as the narration (aligned, not re-voiced)")
619
820
  pj.add_argument("--voiceover-url", default="", help="Public https link to the narration audio; Cliptude downloads it")
620
821
  pj.add_argument("--duration", default="", help="Wizard duration bucket, e.g. 6-8")
621
822
  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")
823
+ pj.add_argument("--avatar-engine", default="", choices=["", "iv"], help="Avatar Video: iv (Avatar IV, the only engine). Default: the template's")
623
824
  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
825
  _add_thumbnail_args(pj, scope="this video")
625
826
  _add_pronunciations_arg(pj)
626
827
  pj.add_argument("--vector-motion", default="", choices=["", "none", "video"], help='Vector Explainer: "none" = stills with camera moves, "video" = AI clips. Default: the template\'s')
828
+ _add_captions_arg(pj, scope="this video")
627
829
  pj.add_argument("--vector-character", default="", help='Vector Explainer: character id from `cliptude vector-characters`, or "none". Default: the template\'s')
628
830
 
629
831
  nr = sub.add_parser("narration", help="Numbered sentences and word timings of a plan_ready job")
@@ -762,7 +964,24 @@ def main(argv: list[str] | None = None) -> None:
762
964
  thumbnail = _thumbnail_from_args(args)
763
965
  if thumbnail:
764
966
  settings["thumbnail"] = thumbnail
765
- _print(client.create_template(name=args.name, format=args.format, settings=settings))
967
+ _print(client.create_template(name=args.name, format=args.format, settings=settings,
968
+ brand_kit_id=args.brand_kit, show_logo=args.show_logo, look=args.look or None,
969
+ captions=args.captions))
970
+ elif args.cmd == "template-update":
971
+ if (args.name is None and args.look is None and args.brand_kit is None and args.show_logo is None
972
+ and args.captions is None):
973
+ raise CliptudeApiError("Give --name, --look, --brand-kit, --show-logo / --no-show-logo or --captions / --no-captions.")
974
+ _print(client.update_template(_resolve_template_id(client, args.template), name=args.name,
975
+ brand_kit_id=args.brand_kit, show_logo=args.show_logo, look=args.look,
976
+ captions=args.captions))
977
+ elif args.cmd == "looks":
978
+ _print(client.list_looks())
979
+ elif args.cmd == "look-template":
980
+ _print(client.save_look_as_template(args.slug, name=args.name or None, format=args.format or None))
981
+ elif args.cmd == "brand-kits":
982
+ _print(client.list_brand_kits())
983
+ elif args.cmd == "voice-design":
984
+ _run_voice_design(client, args)
766
985
  elif args.cmd == "template-options":
767
986
  _print(client.template_options(args.format))
768
987
  elif args.cmd == "voices":
@@ -800,6 +1019,7 @@ def main(argv: list[str] | None = None) -> None:
800
1019
  avatar_engine=args.avatar_engine or None,
801
1020
  render_only=args.render_only or None,
802
1021
  vector_reveal_mode=args.vector_motion or None,
1022
+ captions=args.captions,
803
1023
  ))
804
1024
  elif args.cmd == "generate":
805
1025
  script = args.script
@@ -810,19 +1030,20 @@ def main(argv: list[str] | None = None) -> None:
810
1030
  talking_head = (args.talking_head or "").strip()
811
1031
  if talking_head and (voiceover or voiceover_url):
812
1032
  raise CliptudeApiError("Use --talking-head or --voiceover, not both.")
813
- if talking_head and (args.prompt or script):
1033
+ # --prompt may come with any narration as direction for the visuals; two narrations may not.
1034
+ if talking_head and script:
814
1035
  raise CliptudeApiError(
815
- "Use --talking-head or --prompt/--script, not both. "
816
- "An uploaded talking head is transcribed and used as the narration."
1036
+ "Use --talking-head or --script, not both. "
1037
+ "An uploaded talking head is transcribed and used as the narration; --prompt is fine as direction."
817
1038
  )
818
- if voiceover and (args.prompt or script):
1039
+ if (voiceover or voiceover_url) and script:
819
1040
  raise CliptudeApiError(
820
- "Use --voiceover or --prompt/--script, not both. "
821
- "An uploaded file is transcribed and used as the narration."
1041
+ "Use --voiceover or --script, not both. "
1042
+ "An uploaded file is transcribed and used as the narration; --prompt is fine as direction."
822
1043
  )
823
- if not talking_head and not voiceover and not (args.prompt or script):
1044
+ if not talking_head and not voiceover and not voiceover_url and not (args.prompt or script):
824
1045
  raise CliptudeApiError(
825
- "Provide --prompt, --script / --script-file, --voiceover, or --talking-head."
1046
+ "Provide --prompt, --script / --script-file, --voiceover, --voiceover-url, or --talking-head."
826
1047
  )
827
1048
  template_id = _resolve_template_id(client, args.template)
828
1049
  _print(_create_reviewed(client, args,
@@ -849,6 +1070,7 @@ def main(argv: list[str] | None = None) -> None:
849
1070
  vector_character_id=args.vector_character or None,
850
1071
  vector_reveal_mode=args.vector_motion or None,
851
1072
  pronunciations=_pronunciations_from_args(args),
1073
+ captions=args.captions,
852
1074
  ))
853
1075
  elif args.cmd == "script":
854
1076
  if not (args.prompt or "").strip():
@@ -901,6 +1123,7 @@ def main(argv: list[str] | None = None) -> None:
901
1123
  vector_character_id=args.vector_character or None,
902
1124
  vector_reveal_mode=args.vector_motion or None,
903
1125
  pronunciations=_pronunciations_from_args(args),
1126
+ captions=args.captions,
904
1127
  ))
905
1128
  elif args.cmd == "narration":
906
1129
  _print(client.get_narration(args.job_id))