@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 +24 -9
- package/cliptude_mcp/apps.py +6 -2
- package/cliptude_mcp/cli.py +249 -26
- package/cliptude_mcp/client.py +169 -11
- package/cliptude_mcp/creation.py +159 -6
- package/cliptude_mcp/server.py +185 -30
- package/cliptude_mcp/widgets/templates.html +4 -6
- package/cliptude_mcp/widgets/views.js +32 -2
- package/package.json +1 -1
- package/pyproject.toml +1 -1
package/cliptude_mcp/client.py
CHANGED
|
@@ -173,6 +173,13 @@ def _uuid_seg(value: Any, label: str = "job_id") -> str:
|
|
|
173
173
|
return quote(canonical, safe="")
|
|
174
174
|
|
|
175
175
|
|
|
176
|
+
def _voice_provider(provider: str) -> str:
|
|
177
|
+
value = str(provider or "").strip().lower()
|
|
178
|
+
if value not in ("elevenlabs", "minimax", "inworld"):
|
|
179
|
+
raise CliptudeApiError("provider must be elevenlabs, minimax or inworld.")
|
|
180
|
+
return value
|
|
181
|
+
|
|
182
|
+
|
|
176
183
|
def _int_seg(value: Any, label: str = "project_id") -> str:
|
|
177
184
|
"""A positive integer path segment; anything else is refused."""
|
|
178
185
|
text = str(value).strip() if not isinstance(value, bool) else ""
|
|
@@ -298,6 +305,15 @@ def _avatar_job_fields(
|
|
|
298
305
|
return fields
|
|
299
306
|
|
|
300
307
|
|
|
308
|
+
def merge_visual_direction(prompt: str | None, visual_direction: str | None) -> str | None:
|
|
309
|
+
"""The prompt with the deprecated visual_direction appended (the server does the same for direct API calls)."""
|
|
310
|
+
notes = (visual_direction or "").strip()
|
|
311
|
+
text = (prompt or "").strip()
|
|
312
|
+
if notes and notes not in text:
|
|
313
|
+
text = f"{text}\n\n{notes}".strip() if text else notes
|
|
314
|
+
return text or None
|
|
315
|
+
|
|
316
|
+
|
|
301
317
|
def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
|
|
302
318
|
*, as_strings: bool = False) -> dict[str, Any]:
|
|
303
319
|
"""The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
|
|
@@ -475,11 +491,116 @@ class CliptudeClient:
|
|
|
475
491
|
def get_template(self, template_id: str) -> Any:
|
|
476
492
|
return self.request("GET", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}")
|
|
477
493
|
|
|
478
|
-
def create_template(self, *, name: str, format: str, settings: dict[str, Any]
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
)
|
|
494
|
+
def create_template(self, *, name: str, format: str, settings: dict[str, Any],
|
|
495
|
+
brand_kit_id: int | None = None, show_logo: bool | None = None,
|
|
496
|
+
look: str | None = None, captions: bool | None = None) -> Any:
|
|
497
|
+
"""Create a ready-to-use template from settings (no create wizard); optional brand kit, logo, Look and
|
|
498
|
+
whole-video captions (off by default)."""
|
|
499
|
+
settings = dict(settings or {})
|
|
500
|
+
if captions is not None:
|
|
501
|
+
settings["captions_enabled"] = bool(captions)
|
|
502
|
+
body: dict[str, Any] = {"name": name, "format": format, "settings": settings}
|
|
503
|
+
if look:
|
|
504
|
+
body["look"] = look
|
|
505
|
+
if brand_kit_id is not None:
|
|
506
|
+
body["brand_kit_id"] = brand_kit_id or None
|
|
507
|
+
if show_logo is not None:
|
|
508
|
+
body["show_logo"] = bool(show_logo)
|
|
509
|
+
return self.request("POST", "/api/v1/templates", json_body=body)
|
|
510
|
+
|
|
511
|
+
def update_template(self, template_id: str, *, name: str | None = None, brand_kit_id: int | None = None,
|
|
512
|
+
show_logo: bool | None = None, look: str | None = None,
|
|
513
|
+
captions: bool | None = None) -> Any:
|
|
514
|
+
"""Rename a template, set its brand kit (0 = the user's default kit), its logo switch, its Look
|
|
515
|
+
('' removes the Look) or its whole-video captions."""
|
|
516
|
+
body: dict[str, Any] = {}
|
|
517
|
+
if captions is not None:
|
|
518
|
+
body["captions"] = bool(captions)
|
|
519
|
+
if look is not None:
|
|
520
|
+
body["look"] = look
|
|
521
|
+
if name is not None:
|
|
522
|
+
body["name"] = name
|
|
523
|
+
if brand_kit_id is not None:
|
|
524
|
+
body["brand_kit_id"] = brand_kit_id or None
|
|
525
|
+
if show_logo is not None:
|
|
526
|
+
body["show_logo"] = bool(show_logo)
|
|
527
|
+
return self.request("PATCH", f"/api/v1/templates/{_uuid_seg(template_id, 'template_id')}", json_body=body)
|
|
528
|
+
|
|
529
|
+
def list_looks(self) -> Any:
|
|
530
|
+
"""The prebuilt Looks (colours, captions, footage grade, the boards that carry each), with sample reels."""
|
|
531
|
+
return self.request("GET", "/api/v1/looks")
|
|
532
|
+
|
|
533
|
+
def save_look_as_template(self, slug: str, *, name: str | None = None, format: str | None = None) -> Any:
|
|
534
|
+
"""Copy a Look into one of the user's templates (format: any of the Look's formats); returns the template."""
|
|
535
|
+
body: dict[str, Any] = {}
|
|
536
|
+
if name:
|
|
537
|
+
body["name"] = name
|
|
538
|
+
if format:
|
|
539
|
+
body["format"] = format
|
|
540
|
+
from urllib.parse import quote
|
|
541
|
+
|
|
542
|
+
return self.request("POST", f"/api/v1/looks/{quote(slug.strip(), safe='')}/template", json_body=body)
|
|
543
|
+
|
|
544
|
+
def list_brand_kits(self) -> Any:
|
|
545
|
+
"""The user's brand kits (one per channel): logo, colours, fonts; one is the default."""
|
|
546
|
+
return self.request("GET", "/api/v1/brand-kits")
|
|
547
|
+
|
|
548
|
+
def list_media(self, *, folder: str | None = None, kind: str | None = None, limit: int = 50,
|
|
549
|
+
offset: int = 0) -> Any:
|
|
550
|
+
"""The user's media library (images, clips, audio; shared with the editor's uploads)."""
|
|
551
|
+
params: dict[str, Any] = {"limit": limit, "offset": offset}
|
|
552
|
+
if folder is not None:
|
|
553
|
+
params["folder"] = folder
|
|
554
|
+
if kind:
|
|
555
|
+
params["kind"] = kind
|
|
556
|
+
return self.request("GET", "/api/v1/media", params=params)
|
|
557
|
+
|
|
558
|
+
# --- designed voices (ElevenLabs, MiniMax, Inworld; settings, try and remix are ElevenLabs only) -----------
|
|
559
|
+
|
|
560
|
+
def voice_design_options(self) -> Any:
|
|
561
|
+
"""Design models, option ranges and defaults, and the voice settings ranges (the web page's)."""
|
|
562
|
+
return self.request("GET", "/api/v1/voice-designs/options")
|
|
563
|
+
|
|
564
|
+
def design_voice_previews(self, provider: str, description: str, *, language: str | None = None,
|
|
565
|
+
options: dict[str, Any] | None = None) -> Any:
|
|
566
|
+
body = {"description": description, **({"language": language} if language else {}),
|
|
567
|
+
**{k: v for k, v in (options or {}).items() if v is not None}}
|
|
568
|
+
return self.request("POST", f"/api/v1/voice-designs/{_voice_provider(provider)}/previews", json_body=body,
|
|
569
|
+
timeout=max(self.timeout, 180.0))
|
|
570
|
+
|
|
571
|
+
def save_designed_voice(self, provider: str, preview_id: str, voice_name: str, *,
|
|
572
|
+
voice_settings: dict[str, Any] | None = None) -> Any:
|
|
573
|
+
body = {"preview_id": preview_id, "voice_name": voice_name,
|
|
574
|
+
**{k: v for k, v in (voice_settings or {}).items() if v is not None}}
|
|
575
|
+
return self.request("POST", f"/api/v1/voice-designs/{_voice_provider(provider)}", json_body=body,
|
|
576
|
+
timeout=max(self.timeout, 120.0))
|
|
577
|
+
|
|
578
|
+
def update_designed_voice_settings(self, design_id: int | str, voice_settings: dict[str, Any]) -> Any:
|
|
579
|
+
body = {k: v for k, v in (voice_settings or {}).items() if v is not None}
|
|
580
|
+
return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/settings",
|
|
581
|
+
json_body=body)
|
|
582
|
+
|
|
583
|
+
def try_designed_voice(self, design_id: int | str, *, text: str | None = None,
|
|
584
|
+
voice_settings: dict[str, Any] | None = None, **extra: Any) -> Any:
|
|
585
|
+
body = {**({"text": text} if text else {}), **{k: v for k, v in (voice_settings or {}).items() if v is not None},
|
|
586
|
+
**{k: v for k, v in extra.items() if v not in (None, "")}}
|
|
587
|
+
return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/try",
|
|
588
|
+
json_body=body)
|
|
589
|
+
|
|
590
|
+
def remix_designed_voice(self, design_id: int | str, description: str, *,
|
|
591
|
+
options: dict[str, Any] | None = None) -> Any:
|
|
592
|
+
body = {"description": description, **{k: v for k, v in (options or {}).items() if v is not None}}
|
|
593
|
+
return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/remix",
|
|
594
|
+
json_body=body, timeout=max(self.timeout, 180.0))
|
|
595
|
+
|
|
596
|
+
def save_remixed_voice(self, design_id: int | str, preview_id: str, *, voice_name: str | None = None) -> Any:
|
|
597
|
+
body = {"preview_id": preview_id, **({"voice_name": voice_name} if voice_name else {})}
|
|
598
|
+
return self.request("POST", f"/api/v1/voice-designs/elevenlabs/{_int_seg(design_id, 'design_id')}/remix/save",
|
|
599
|
+
json_body=body, timeout=max(self.timeout, 120.0))
|
|
600
|
+
|
|
601
|
+
def delete_designed_voice(self, provider: str, design_id: int | str) -> Any:
|
|
602
|
+
return self.request("DELETE", f"/api/v1/voice-designs/{_voice_provider(provider)}/"
|
|
603
|
+
f"{_int_seg(design_id, 'design_id')}")
|
|
483
604
|
|
|
484
605
|
def template_options(self, format: str) -> Any:
|
|
485
606
|
return self.request("GET", "/api/v1/templates/options", params={"format": format})
|
|
@@ -518,12 +639,18 @@ class CliptudeClient:
|
|
|
518
639
|
vector_character_id: str | None = None,
|
|
519
640
|
vector_reveal_mode: str | None = None,
|
|
520
641
|
pronunciations: list[dict[str, str]] | None = None,
|
|
642
|
+
visual_direction: str | None = None,
|
|
643
|
+
captions: bool | None = None,
|
|
521
644
|
review_token: str | None = None,
|
|
522
645
|
acknowledge: list[str] | None = None,
|
|
523
646
|
review_only: bool | None = None,
|
|
524
647
|
) -> Any:
|
|
525
648
|
if voiceover_path and voiceover_url:
|
|
526
649
|
raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
|
|
650
|
+
# visual_direction is deprecated: the description (prompt) carries the visual direction. Older callers still
|
|
651
|
+
# send it, so it is appended to the prompt here, the same on every path (JSON, voiceover upload, talking head).
|
|
652
|
+
prompt = merge_visual_direction(prompt, visual_direction)
|
|
653
|
+
visual_direction = None
|
|
527
654
|
if render_only and ((output or "").strip().lower() != "plan" or not (voiceover_path or voiceover_url)):
|
|
528
655
|
raise CliptudeApiError(
|
|
529
656
|
"render_only is a plan job with your own narration: pass output=\"plan\" and a voiceover "
|
|
@@ -562,21 +689,23 @@ class CliptudeClient:
|
|
|
562
689
|
)
|
|
563
690
|
if th_path and vo_path:
|
|
564
691
|
raise CliptudeApiError("Upload either a talking head video or a voiceover — not both.")
|
|
565
|
-
|
|
692
|
+
# A prompt may come with any narration as direction for the visuals; two narrations may not.
|
|
693
|
+
if th_path and script:
|
|
566
694
|
raise CliptudeApiError(
|
|
567
|
-
"Upload a talking head video, or send a
|
|
568
|
-
"An uploaded talking head is transcribed and used as the narration."
|
|
695
|
+
"Upload a talking head video, or send a custom script — not both. "
|
|
696
|
+
"An uploaded talking head is transcribed and used as the narration; a prompt is fine as direction."
|
|
569
697
|
)
|
|
570
|
-
if vo_path
|
|
698
|
+
if (vo_path or voiceover_url) and script:
|
|
571
699
|
raise CliptudeApiError(
|
|
572
|
-
"Upload a voiceover, or send a
|
|
573
|
-
"An uploaded file is transcribed and used as the narration."
|
|
700
|
+
"Upload a voiceover, or send a custom script — not both. "
|
|
701
|
+
"An uploaded file is transcribed and used as the narration; a prompt is fine as direction."
|
|
574
702
|
)
|
|
575
703
|
if th_path:
|
|
576
704
|
return self._create_job_talking_head(
|
|
577
705
|
template_id=template_id,
|
|
578
706
|
title=title,
|
|
579
707
|
talking_head_path=th_path,
|
|
708
|
+
prompt=prompt,
|
|
580
709
|
avatar_intro_only=avatar_intro_only,
|
|
581
710
|
avatar_ai_footage=avatar_ai_footage,
|
|
582
711
|
disable_animations=disable_animations,
|
|
@@ -587,6 +716,7 @@ class CliptudeClient:
|
|
|
587
716
|
excluded_animation_types=excluded_animation_types,
|
|
588
717
|
excluded_transition_kinds=excluded_transition_kinds,
|
|
589
718
|
thumbnail=thumbnail,
|
|
719
|
+
captions=captions,
|
|
590
720
|
review=_review_job_fields(review_token, acknowledge, review_only),
|
|
591
721
|
)
|
|
592
722
|
if vo_path:
|
|
@@ -602,6 +732,9 @@ class CliptudeClient:
|
|
|
602
732
|
**({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
|
|
603
733
|
**({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
|
|
604
734
|
**({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
|
|
735
|
+
**({"visual_direction": visual_direction} if visual_direction else {}),
|
|
736
|
+
**({"captions": "true" if captions else "false"} if captions is not None else {}),
|
|
737
|
+
**({"prompt": prompt} if prompt else {}),
|
|
605
738
|
**_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
|
|
606
739
|
}
|
|
607
740
|
return self._create_job_multipart(
|
|
@@ -639,6 +772,10 @@ class CliptudeClient:
|
|
|
639
772
|
body["vector_reveal_mode"] = str(vector_reveal_mode)
|
|
640
773
|
if pronunciations is not None:
|
|
641
774
|
body["pronunciations"] = pronunciations
|
|
775
|
+
if visual_direction:
|
|
776
|
+
body["visual_direction"] = visual_direction
|
|
777
|
+
if captions is not None:
|
|
778
|
+
body["captions"] = bool(captions)
|
|
642
779
|
body.update(_review_job_fields(review_token, acknowledge, review_only))
|
|
643
780
|
return self.request("POST", "/api/v1/jobs", json_body=body)
|
|
644
781
|
|
|
@@ -727,6 +864,7 @@ class CliptudeClient:
|
|
|
727
864
|
template_id: str,
|
|
728
865
|
title: str,
|
|
729
866
|
talking_head_path: str | Path,
|
|
867
|
+
prompt: str | None = None,
|
|
730
868
|
avatar_intro_only: bool | None = None,
|
|
731
869
|
avatar_ai_footage: bool | None = None,
|
|
732
870
|
disable_animations: bool | None = None,
|
|
@@ -737,9 +875,12 @@ class CliptudeClient:
|
|
|
737
875
|
excluded_animation_types: list[str] | None = None,
|
|
738
876
|
excluded_transition_kinds: list[str] | None = None,
|
|
739
877
|
thumbnail: dict[str, str] | None = None,
|
|
878
|
+
captions: bool | None = None,
|
|
740
879
|
review: dict[str, Any] | None = None,
|
|
741
880
|
) -> Any:
|
|
742
881
|
review = review or {}
|
|
882
|
+
captions_field = {"captions": bool(captions)} if captions is not None else {}
|
|
883
|
+
captions_str = {"captions": "true" if captions else "false"} if captions is not None else {}
|
|
743
884
|
review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
|
|
744
885
|
for k, v in review.items()}
|
|
745
886
|
motion_extra = _motion_control_job_fields(
|
|
@@ -776,6 +917,8 @@ class CliptudeClient:
|
|
|
776
917
|
**_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
|
|
777
918
|
**motion_extra,
|
|
778
919
|
**_thumbnail_job_field(thumbnail, as_string=True),
|
|
920
|
+
**({"prompt": prompt} if prompt else {}),
|
|
921
|
+
**captions_str,
|
|
779
922
|
**review_strings,
|
|
780
923
|
}
|
|
781
924
|
return self._create_job_multipart(
|
|
@@ -795,6 +938,8 @@ class CliptudeClient:
|
|
|
795
938
|
**_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
|
|
796
939
|
**motion_extra,
|
|
797
940
|
**_thumbnail_job_field(thumbnail, as_string=True),
|
|
941
|
+
**({"prompt": prompt} if prompt else {}),
|
|
942
|
+
**captions_str,
|
|
798
943
|
**review_strings,
|
|
799
944
|
}
|
|
800
945
|
return self._create_job_multipart(
|
|
@@ -821,9 +966,11 @@ class CliptudeClient:
|
|
|
821
966
|
"title": title,
|
|
822
967
|
"talking_head_r2_key": key,
|
|
823
968
|
"talking_head_duration": str(duration),
|
|
969
|
+
**({"prompt": prompt} if prompt else {}),
|
|
824
970
|
}
|
|
825
971
|
body.update(_avatar_job_fields(avatar_intro_only, avatar_ai_footage))
|
|
826
972
|
body.update(_thumbnail_job_field(thumbnail))
|
|
973
|
+
body.update(captions_field)
|
|
827
974
|
body.update(
|
|
828
975
|
_motion_control_job_fields(
|
|
829
976
|
disable_animations=disable_animations,
|
|
@@ -1075,6 +1222,14 @@ class CliptudeClient:
|
|
|
1075
1222
|
"""What sourcing used for each media request of the locked plan, and every fallback."""
|
|
1076
1223
|
return self.request("GET", f"/api/v1/jobs/{_uuid_seg(job_id)}/plan/report")
|
|
1077
1224
|
|
|
1225
|
+
def get_job_sources(self, job_id: str) -> Any:
|
|
1226
|
+
"""Where every visual in the video came from (time, source, author, license, link) and the description credits."""
|
|
1227
|
+
return self.request("GET", f"/api/v1/jobs/{_uuid_seg(job_id)}/sources")
|
|
1228
|
+
|
|
1229
|
+
def search_media_sources(self, query: str) -> Any:
|
|
1230
|
+
"""Which of the user's videos used a source: a link, YouTube channel or author."""
|
|
1231
|
+
return self.request("GET", "/api/v1/sources/search", params={"q": query})
|
|
1232
|
+
|
|
1078
1233
|
def get_plan_review(self, job_id: str) -> Any:
|
|
1079
1234
|
"""The built design, beat by beat and graphic by graphic, with links to the media (review before render)."""
|
|
1080
1235
|
return self.request("GET", f"/api/v1/jobs/{_uuid_seg(job_id)}/plan/review")
|
|
@@ -1276,9 +1431,12 @@ class CliptudeClient:
|
|
|
1276
1431
|
avatar_engine: str | None = None,
|
|
1277
1432
|
render_only: bool | None = None,
|
|
1278
1433
|
vector_reveal_mode: str | None = None,
|
|
1434
|
+
captions: bool | None = None,
|
|
1279
1435
|
) -> Any:
|
|
1280
1436
|
"""Credits a job would need; creates nothing."""
|
|
1281
1437
|
body: dict[str, Any] = {"template_id": template_id}
|
|
1438
|
+
if captions is not None:
|
|
1439
|
+
body["captions"] = bool(captions)
|
|
1282
1440
|
if render_only:
|
|
1283
1441
|
body["render_only"] = True
|
|
1284
1442
|
for key, value in (
|
package/cliptude_mcp/creation.py
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
"""MCP tools that make the user's own avatar and voices: create_avatar, design_voice_previews, save_designed_voice,
|
|
2
|
-
|
|
2
|
+
voice_design_options, update_designed_voice_settings, try_designed_voice, remix_designed_voice, save_remixed_voice,
|
|
3
|
+
delete_designed_voice, clone_voice. The avatar and voice picker widgets call them with `tools/call`; the model can call them too.
|
|
3
4
|
|
|
4
5
|
Files travel as base64 in the tool call (the widget reads the file the user picked, or a recording), never as a
|
|
5
6
|
path on the hosted server: a local path is accepted only by the stdio server, which runs on the user's computer.
|
|
@@ -18,7 +19,7 @@ from pathlib import Path
|
|
|
18
19
|
from typing import Annotated, Any
|
|
19
20
|
|
|
20
21
|
import httpx
|
|
21
|
-
from mcp.types import CallToolResult, TextContent, ToolAnnotations
|
|
22
|
+
from mcp.types import AudioContent, CallToolResult, TextContent, ToolAnnotations
|
|
22
23
|
from pydantic import Field
|
|
23
24
|
|
|
24
25
|
from cliptude_mcp.client import CliptudeApiError
|
|
@@ -95,6 +96,16 @@ def post_form(client: Any, path: str, data: dict[str, Any], files: dict[str, tup
|
|
|
95
96
|
return payload
|
|
96
97
|
|
|
97
98
|
|
|
99
|
+
def _voice_settings(stability, similarity_boost, style, use_speaker_boost, speed) -> dict[str, Any]:
|
|
100
|
+
values = {"stability": stability, "similarity_boost": similarity_boost, "style": style,
|
|
101
|
+
"use_speaker_boost": use_speaker_boost, "speed": speed}
|
|
102
|
+
return {k: v for k, v in values.items() if v is not None}
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _form_values(values: dict[str, Any]) -> dict[str, Any]:
|
|
106
|
+
return {k: (("true" if v else "false") if isinstance(v, bool) else v) for k, v in values.items()}
|
|
107
|
+
|
|
108
|
+
|
|
98
109
|
def register_creation_tools(
|
|
99
110
|
mcp: Any, client: Callable[[], Any], err: Callable[[Exception], dict[str, Any]], *, local: bool
|
|
100
111
|
) -> None:
|
|
@@ -135,11 +146,24 @@ def register_creation_tools(
|
|
|
135
146
|
provider: Annotated[str, Field(description="elevenlabs, minimax or inworld")],
|
|
136
147
|
description: Annotated[str, Field(min_length=10, max_length=1000, description="The voice to design: age, gender, accent, tone, pace")],
|
|
137
148
|
language: Annotated[str | None, Field(description="Narration language, e.g. English")] = None,
|
|
149
|
+
model_id: Annotated[str | None, Field(description="ElevenLabs only: eleven_multilingual_ttv_v2 (default) or eleven_ttv_v3 (voice_design_options lists them)")] = None,
|
|
150
|
+
should_enhance: Annotated[bool | None, Field(description="ElevenLabs only: let ElevenLabs expand the description")] = None,
|
|
151
|
+
text: Annotated[str | None, Field(description="ElevenLabs only: the preview line, 100-1000 characters")] = None,
|
|
152
|
+
auto_generate_text: Annotated[bool | None, Field(description="ElevenLabs only: ElevenLabs writes the preview line")] = None,
|
|
153
|
+
loudness: Annotated[float | None, Field(description="ElevenLabs only: -1 to 1 (default 0.5)")] = None,
|
|
154
|
+
guidance_scale: Annotated[float | None, Field(description="ElevenLabs only: how closely to follow the description, 0 to 20 (default 5)")] = None,
|
|
155
|
+
quality: Annotated[float | None, Field(description="ElevenLabs v2 only: -1 to 1, higher = better, less variety")] = None,
|
|
156
|
+
seed: Annotated[int | None, Field(description="ElevenLabs only: a whole number for repeatable previews")] = None,
|
|
157
|
+
prompt_strength: Annotated[float | None, Field(description="ElevenLabs v3 with reference audio only: 0 to 1")] = None,
|
|
138
158
|
) -> CallToolResult:
|
|
139
|
-
"""Design a new narration voice from a description: returns a few previews (preview_id) to listen to. Keep one with save_designed_voice. Paid plans; a user keeps one designed voice per provider. The audio goes to the voice picker widget only; the text result lists the preview ids."""
|
|
159
|
+
"""Design a new narration voice from a description: returns a few previews (preview_id) to listen to. Keep one with save_designed_voice. Paid plans; a user keeps one designed voice per provider. ElevenLabs takes the web page's design options (model_id, guidance_scale, loudness, ...; voice_design_options lists ranges and defaults; numbers outside a range are clamped). The audio goes to the voice picker widget only; the text result lists the preview ids."""
|
|
160
|
+
options = {"model_id": model_id, "should_enhance": should_enhance, "text": text,
|
|
161
|
+
"auto_generate_text": auto_generate_text, "loudness": loudness, "guidance_scale": guidance_scale,
|
|
162
|
+
"quality": quality, "seed": seed, "prompt_strength": prompt_strength}
|
|
163
|
+
form = {k: (("true" if v else "false") if isinstance(v, bool) else v) for k, v in options.items() if v is not None}
|
|
140
164
|
try:
|
|
141
165
|
payload = post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}/previews",
|
|
142
|
-
{"description": description, "language": language})
|
|
166
|
+
{"description": description, "language": language, **form})
|
|
143
167
|
except Exception as exc:
|
|
144
168
|
failure = err(exc)
|
|
145
169
|
return CallToolResult(content=[TextContent(type="text", text=json.dumps(failure, default=str))],
|
|
@@ -166,11 +190,140 @@ def register_creation_tools(
|
|
|
166
190
|
provider: Annotated[str, Field(description="Same provider as the previews")],
|
|
167
191
|
preview_id: Annotated[str, Field(min_length=1, description="The preview the user picked")],
|
|
168
192
|
voice_name: Annotated[str, Field(min_length=1, max_length=100, description="Name for the voice")],
|
|
193
|
+
stability: Annotated[float | None, Field(description="ElevenLabs voice setting, 0 to 1 (default 0.5)")] = None,
|
|
194
|
+
similarity_boost: Annotated[float | None, Field(description="ElevenLabs voice setting, 0 to 1 (default 0.75)")] = None,
|
|
195
|
+
style: Annotated[float | None, Field(description="ElevenLabs voice setting, 0 to 1 (default 0)")] = None,
|
|
196
|
+
use_speaker_boost: Annotated[bool | None, Field(description="ElevenLabs voice setting (default true)")] = None,
|
|
197
|
+
speed: Annotated[float | None, Field(description="ElevenLabs voice setting, 0.7 to 1.2 (default 1)")] = None,
|
|
169
198
|
) -> dict[str, Any]:
|
|
170
|
-
"""Keep one designed preview as the user's own private voice. It then appears in list_voices under my_voices and can be used as voice_id (with voice_provider) in create_template."""
|
|
199
|
+
"""Keep one designed preview as the user's own private voice. It then appears in list_voices under my_voices (with design_id and voice_settings) and can be used as voice_id (with voice_provider) in create_template. ElevenLabs voices may get their voice settings now (or later with update_designed_voice_settings); settings left out keep the ElevenLabs default."""
|
|
200
|
+
settings = _voice_settings(stability, similarity_boost, style, use_speaker_boost, speed)
|
|
171
201
|
try:
|
|
172
202
|
return post_form(client(), f"/api/v1/voice-designs/{provider.strip().lower()}",
|
|
173
|
-
{"preview_id": preview_id, "voice_name": voice_name})
|
|
203
|
+
{"preview_id": preview_id, "voice_name": voice_name, **_form_values(settings)})
|
|
204
|
+
except Exception as exc:
|
|
205
|
+
return err(exc)
|
|
206
|
+
|
|
207
|
+
@mcp.tool(
|
|
208
|
+
title="Voice design options",
|
|
209
|
+
annotations=ToolAnnotations(title="Voice design options", read_only_hint=True, open_world_hint=False),
|
|
210
|
+
)
|
|
211
|
+
def voice_design_options() -> dict[str, Any]:
|
|
212
|
+
"""What design_voice_previews, remix_designed_voice and the voice settings accept: ElevenLabs design models, every option's range and default, and the voice settings ranges (the same as the Design a voice page; out-of-range numbers are clamped)."""
|
|
213
|
+
try:
|
|
214
|
+
return client().voice_design_options()
|
|
215
|
+
except Exception as exc:
|
|
216
|
+
return err(exc)
|
|
217
|
+
|
|
218
|
+
@mcp.tool(
|
|
219
|
+
title="Update designed voice settings",
|
|
220
|
+
annotations=ToolAnnotations(title="Update designed voice settings", read_only_hint=False,
|
|
221
|
+
destructive_hint=False, idempotent_hint=True, open_world_hint=True),
|
|
222
|
+
)
|
|
223
|
+
def update_designed_voice_settings(
|
|
224
|
+
design_id: Annotated[int, Field(description="design_id of the user's designed ElevenLabs voice (list_voices my_voices)")],
|
|
225
|
+
stability: Annotated[float | None, Field(description="0 to 1")] = None,
|
|
226
|
+
similarity_boost: Annotated[float | None, Field(description="0 to 1")] = None,
|
|
227
|
+
style: Annotated[float | None, Field(description="0 to 1")] = None,
|
|
228
|
+
use_speaker_boost: Annotated[bool | None, Field(description="true or false")] = None,
|
|
229
|
+
speed: Annotated[float | None, Field(description="0.7 to 1.2")] = None,
|
|
230
|
+
) -> dict[str, Any]:
|
|
231
|
+
"""Change the voice settings of the user's designed ElevenLabs voice; settings left out keep their saved value. Every video voiced with it uses them. Returns voice_settings."""
|
|
232
|
+
try:
|
|
233
|
+
return client().update_designed_voice_settings(
|
|
234
|
+
design_id, _voice_settings(stability, similarity_boost, style, use_speaker_boost, speed))
|
|
235
|
+
except Exception as exc:
|
|
236
|
+
return err(exc)
|
|
237
|
+
|
|
238
|
+
@mcp.tool(
|
|
239
|
+
title="Try designed voice",
|
|
240
|
+
annotations=ToolAnnotations(title="Try designed voice", read_only_hint=True, open_world_hint=True),
|
|
241
|
+
)
|
|
242
|
+
def try_designed_voice(
|
|
243
|
+
design_id: Annotated[int, Field(description="design_id of the user's designed ElevenLabs voice")],
|
|
244
|
+
text: Annotated[str | None, Field(max_length=300, description="A short line to speak (default: a sample line)")] = None,
|
|
245
|
+
stability: Annotated[float | None, Field(description="0 to 1; omit to use the saved setting")] = None,
|
|
246
|
+
similarity_boost: Annotated[float | None, Field(description="0 to 1")] = None,
|
|
247
|
+
style: Annotated[float | None, Field(description="0 to 1")] = None,
|
|
248
|
+
use_speaker_boost: Annotated[bool | None, Field(description="true or false")] = None,
|
|
249
|
+
speed: Annotated[float | None, Field(description="0.7 to 1.2")] = None,
|
|
250
|
+
model_id: Annotated[str | None, Field(description="ElevenLabs TTS model id; omit for the default")] = None,
|
|
251
|
+
language_code: Annotated[str | None, Field(description="Two-letter language code, e.g. en")] = None,
|
|
252
|
+
) -> CallToolResult:
|
|
253
|
+
"""Speak a short test line in the user's designed ElevenLabs voice with these settings (nothing is saved; daily limit). The result carries the audio for the user to play; the text part says how many tries are left."""
|
|
254
|
+
try:
|
|
255
|
+
payload = client().try_designed_voice(
|
|
256
|
+
design_id, text=text,
|
|
257
|
+
voice_settings=_voice_settings(stability, similarity_boost, style, use_speaker_boost, speed),
|
|
258
|
+
model_id=model_id, language_code=language_code)
|
|
259
|
+
except Exception as exc:
|
|
260
|
+
failure = err(exc)
|
|
261
|
+
return CallToolResult(content=[TextContent(type="text", text=json.dumps(failure, default=str))],
|
|
262
|
+
structured_content=failure)
|
|
263
|
+
payload = payload if isinstance(payload, dict) else {}
|
|
264
|
+
audio_url = str(payload.get("audio_url") or "")
|
|
265
|
+
summary = {"tries_left_today": payload.get("tries_left_today"),
|
|
266
|
+
"next": "Let the user listen; when they like the settings, update_designed_voice_settings."}
|
|
267
|
+
content: list[Any] = [TextContent(type="text", text=json.dumps(summary))]
|
|
268
|
+
if audio_url.startswith("data:") and ";base64," in audio_url:
|
|
269
|
+
mime, data = audio_url[5:].split(";base64,", 1)
|
|
270
|
+
content.append(AudioContent(type="audio", data=data, mime_type=mime or "audio/mpeg"))
|
|
271
|
+
return CallToolResult(content=content, structured_content=summary)
|
|
272
|
+
|
|
273
|
+
@mcp.tool(
|
|
274
|
+
title="Remix designed voice",
|
|
275
|
+
annotations=ToolAnnotations(title="Remix designed voice", read_only_hint=False, destructive_hint=False,
|
|
276
|
+
open_world_hint=True),
|
|
277
|
+
)
|
|
278
|
+
def remix_designed_voice(
|
|
279
|
+
design_id: Annotated[int, Field(description="design_id of the user's designed ElevenLabs voice")],
|
|
280
|
+
description: Annotated[str, Field(min_length=5, max_length=1000, description="The change, e.g. 'a little warmer and slower'")],
|
|
281
|
+
guidance_scale: Annotated[float | None, Field(description="0 to 20 (default 2)")] = None,
|
|
282
|
+
loudness: Annotated[float | None, Field(description="-1 to 1 (default 0.5)")] = None,
|
|
283
|
+
text: Annotated[str | None, Field(description="Preview line, 100-1000 characters")] = None,
|
|
284
|
+
seed: Annotated[int | None, Field(description="A whole number for repeatable previews")] = None,
|
|
285
|
+
) -> dict[str, Any]:
|
|
286
|
+
"""Previews of the user's designed ElevenLabs voice with a change. Keep one with save_remixed_voice (it replaces the voice and keeps its settings). Shares the daily design-round limit."""
|
|
287
|
+
try:
|
|
288
|
+
payload = client().remix_designed_voice(design_id, description, options={
|
|
289
|
+
"guidance_scale": guidance_scale, "loudness": loudness, "text": text, "seed": seed})
|
|
290
|
+
except Exception as exc:
|
|
291
|
+
return err(exc)
|
|
292
|
+
if isinstance(payload, dict):
|
|
293
|
+
return {**payload, "previews": [{"preview_id": p.get("preview_id"), "duration_secs": p.get("duration_secs")}
|
|
294
|
+
for p in payload.get("previews") or []],
|
|
295
|
+
"next": "Describe the previews to the user (or let them listen in the voice picker), then "
|
|
296
|
+
"save_remixed_voice with the preview_id they pick."}
|
|
297
|
+
return payload
|
|
298
|
+
|
|
299
|
+
@mcp.tool(
|
|
300
|
+
title="Save remixed voice",
|
|
301
|
+
annotations=ToolAnnotations(title="Save remixed voice", read_only_hint=False, destructive_hint=True,
|
|
302
|
+
open_world_hint=True),
|
|
303
|
+
)
|
|
304
|
+
def save_remixed_voice(
|
|
305
|
+
design_id: Annotated[int, Field(description="design_id of the voice that was remixed")],
|
|
306
|
+
preview_id: Annotated[str, Field(min_length=1, description="The remix preview the user picked")],
|
|
307
|
+
voice_name: Annotated[str | None, Field(max_length=100, description="New name; omit to keep the old one")] = None,
|
|
308
|
+
) -> dict[str, Any]:
|
|
309
|
+
"""Replace the user's designed voice with the remix preview they picked (only after they choose it): the old voice is deleted at ElevenLabs and its voice_id changes; templates that used the old voice_id need the new one."""
|
|
310
|
+
try:
|
|
311
|
+
return client().save_remixed_voice(design_id, preview_id, voice_name=voice_name)
|
|
312
|
+
except Exception as exc:
|
|
313
|
+
return err(exc)
|
|
314
|
+
|
|
315
|
+
@mcp.tool(
|
|
316
|
+
title="Delete designed voice",
|
|
317
|
+
annotations=ToolAnnotations(title="Delete designed voice", read_only_hint=False, destructive_hint=True,
|
|
318
|
+
idempotent_hint=True, open_world_hint=True),
|
|
319
|
+
)
|
|
320
|
+
def delete_designed_voice(
|
|
321
|
+
provider: Annotated[str, Field(description="elevenlabs, minimax or inworld")],
|
|
322
|
+
design_id: Annotated[int, Field(description="design_id from list_voices my_voices")],
|
|
323
|
+
) -> dict[str, Any]:
|
|
324
|
+
"""Delete the user's designed voice here and at the provider (only when the user asks). They can then design another for that provider."""
|
|
325
|
+
try:
|
|
326
|
+
return client().delete_designed_voice(provider, design_id)
|
|
174
327
|
except Exception as exc:
|
|
175
328
|
return err(exc)
|
|
176
329
|
|