@kolbo/mcp 1.42.0 → 1.44.0

package/README.md

@@ -127,11 +127,11 @@ Without the optional skill, the config block alone already exposes every tool
 | `generate_first_last_frame` | First frame + last frame → interpolated video |
 | `generate_lipsync` | Source image/video + audio → lipsynced video (Sync-3 adds active-speaker selection, emotion, model mode, temperature) |
 | `generate_creative_director` | One brief → N coordinated scenes (image or video) |
-| `generate_music` | Text (+ optional lyrics) → song |
-| `generate_speech` | Text + voice → spoken audio |
-| `generate_sound` | Text → sound effect |
+| `generate_music` | Text (+ optional lyrics) → song. Style, title, negative tags, length, and Suno fine-controls (style weight, weirdness, audio weight, persona / singing voice) |
+| `generate_speech` | Text + voice → spoken audio. Full expressive/style control: free-form voice direction (Google/Gemini), preset styles + emotions (DeepDub / MiniMax), speed, and per-provider voice settings (ElevenLabs stability/similarity/style, DeepDub accent/variance/tempo, MiniMax pitch/volume/intensity/timbre) |
+| `generate_sound` | Text → sound effect. Duration, prompt influence, and per-provider controls (Stable Audio guidance, Kie loop/tempo/key, Seed-Audio voice/speed/volume/pitch + reference audio/image) |
 | `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
-| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles |
+| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles. Language, speaker diarization, audio-event tagging, and SRT formatting (words/line, lines/subtitle, caption stretch) |
 
 Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.42.0",
+  "version": "1.44.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/SKILL.md

@@ -103,9 +103,9 @@ Each `references/models/*.md` mirrors the matching skill prompt in `kolbo-api/sr
 | `generate_elements` | Reference-driven video. **Primary route for DNA → video.** |
 | `generate_first_last_frame` | Keyframe interpolation between two frames. |
 | `generate_lipsync` | Lipsync audio to an image or video face. |
-| `generate_music` | Music generation (Suno + variants). |
-| `generate_speech` | TTS. Use `list_voices` to pick a voice. |
-| `generate_sound` | Sound effects. |
+| `generate_music` | Music generation (Suno + variants). Controls: `style`, `title`, `lyrics`, `instrumental`, `vocal_gender`, `negative_tags`, `duration_seconds`, plus Suno fine-controls (`style_weight`, `weirdness`, `audio_weight`, `persona_id`, `singing_dna_id`/`singing_voice_id`). |
+| `generate_speech` | TTS. Use `list_voices` to pick a voice, then steer delivery with per-provider style/emotion controls — see `references/models/voice-tts.md`. |
+| `generate_sound` | Sound effects. Controls: `duration`, `prompt_influence`, plus provider-specific `cfg_strength` (Stable Audio), `sound_loop`/`sound_tempo`/`sound_key` (Kie), and Seed-Audio `seed_*` params. |
 | `generate_3d` | 3D models from text / single image / multi-view. Returns GLB/FBX/OBJ/USDZ. |
 
 ### Discovery, Library, Visual DNA, Moodboards, Chat, App Builder, Publishing
@@ -162,6 +162,7 @@ A user-named tool — in any language — overrides every other rule. Recognized
    - User named one → use it. Model identifiers resolve leniently — shorthand like `"z-image"` or `"nano banana 2"` auto-resolves to the exact identifier, so don't over-engineer exact-id lookups (`list_models` is still authoritative for constraints, caps, and pricing).
    - Auto-select → only from "Auto-selectable" section (models with a `summary`). Cheapest fit. Prefer `[RECOMMENDED]` when cost is similar.
    - Never auto-select from "Named-only" section.
+   - **ALWAYS pass an explicit `model` — never omit it.** Omitting routes to the backend "Smart Select" auto-router, which we deliberately avoid: it hides the model choice and the generation used to show just "Auto" instead of the model that ran. YOU pick the specific model (steps above); only omit `model` when the user explicitly asks for auto-pick, or for chat media analysis (video/audio `media_urls`, which routes to Gemini vision).
 4. **Validate inputs** against model caps — see `references/workflows/cost-and-validation.md`.
 5. **How calls work**: each tool blocks until generation is fully complete. Images: seconds. Video: minutes. Multiple tool calls in one response run concurrently. On hosts with live widgets the tool instead returns `submitted` instantly — the card updates on its own; you only need `get_generation_status` when a follow-up step needs the output URLs.
 6. **Checking status — NEVER poll in a loop**: `get_generation_status` takes `wait=true` (blocks server-side until done, ~3 min) and `generation_ids` (check MANY generations in ONE call — returns `all_done` + which are still running). One `wait=true` call replaces any polling loop. If it comes back with some still processing, call it ONCE more with `wait=true` and the remaining ids.

package/skill/references/models/seedance.md

@@ -1,5 +1,5 @@
 <!-- PARITY: this file mirrors getSeedancePromptSystemPrompt() in
-     kolbo-api/src/config/systemPrompt.js (lines ~775–855).
+     kolbo-api/src/config/systemPrompt.js.
      When that function changes, update this file in the same session.
      See packages/opencode/CLAUDE.md "MCP & Skill Sync Rule". -->
 
@@ -11,7 +11,7 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 
 ## Universal Rules (apply to EVERY Seedance prompt)
 
-- **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too.
+- **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too. For connected narrative sequences the proven phrasing is `N connected cinematic shots, 15 seconds total, 16:9, Multishot ON` — use it and keep `Multishot ON` for any multi-shot story.
 - **Order inside each shot**: Subject → Action → Camera → Style → Constraints → (Audio/SFX if relevant).
 - **Prompt length**: aim for ~120–280 words TOTAL across all shots combined (not per shot). Shorter than ~120 words = random output. Longer risks the 8000-char cap below and makes the model forget the opening. For 6-shot prompts, keep each shot 1–2 tight sentences.
 - **Character lock**: if a character recurs, open with `same character throughout all shots` to stop identity drift.
@@ -60,6 +60,136 @@ Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) v
 - Style anchor: `Cinematic stylized 3D animation, photorealistic <env>, stylized characters`.
 - Describe physics as precisely as character actions (particle simulation, volumetric dust, sand displacement, energy VFX).
 
+### 6. Reference-Anchored Cinematic Sequence (multi-character / named references — highest-fidelity format)
+
+Use whenever the user gives named characters or multiple reference images (`@Image1`, `@Image2`, …) — a tactical unit clearing a bunker, a duel between two referenced characters, a war scene. **This is always an Elements-mode prompt** (route the card to `elements`). Structure:
+
+1. **Labeled scene header FIRST** (grounds the scene before any shot):
+   - `Time of day:` — hour + light quality + atmosphere (dust, haze, heavy silence before action).
+   - `Location:` — the environment in concrete physical detail (materials, wear, light direction, high-contrast blown-out entrance, etc.).
+   - `Characters:` — ONE line per person: `Name @ImageN — wardrobe, position in frame, what they carry`. End with "All must match their character references exactly."
+2. **REFERENCE CONSISTENCY block** — map every reference and pin what must NOT change: `Reference Image 1 is <X>. Preserve exact face, hair, anatomy, wardrobe, colors, props.` Add per-character energy/aura color rules, and any already-established story state (e.g. "the gem is already shattered — no intact gem, no red glow"). End with "Do not redesign, morph, recolor, or swap either character, their clothing, anatomy, weapons, or the environment."
+3. **Shots** — either titled (`Shot 1 — Medium Wide / Tactical Positioning`) or timecoded (`SHOT 1 — 0:00–0:03`); timecodes must sum to the total duration. Under each shot use **Camera → Action → Audio** in that order.
+4. **Continuity** — to chain a series, open with `Begin as a seamless continuation from <the exact last beat of the previous video>.`
+5. Close with whichever **Power Blocks** below actually apply (this format usually warrants all three; a simpler scene may need only AUDIO).
+
+## Power Blocks (CONDITIONAL — add ONLY the ones the shot actually needs; never pad a simple prompt)
+
+These elevate rich cinematic / reference-anchored sequences. For a short, tight, single-idea prompt, skip them — the skill's "short prompts can hit hard, don't pad" rule wins. Apply each only when it earns its place:
+
+- **AUDIO** — Seedance renders sound, so specify it whenever sound matters to the scene (most cinematic/action shots). Default diegetic: `AUDIO: No musical score. Synchronized production sound only:` then a comma list of the exact sounds in narrative order (boots scraping concrete, sling shift, layered breathing, distant sirens, weapon impacts, cloth movement, rushing air). Call for a musical score if the user wants one. Skip the block entirely for a deliberately silent or trivially simple shot.
+- **AVOID** — add when there's real drift risk: referenced characters/DNAs, an established story state, or a specific content tone to enforce. `AVOID:` + the drifts to forbid: character morphing, costume/anatomy changes, missing signature details (a piercing, a scar), camera looking into the lens, glamorous posing, duplicated characters, extra weapons, text / subtitles / logos, plus content-specific negatives (e.g. "intact gemstone, red aura" once it's destroyed). Skip it when there's nothing meaningful to forbid.
+- **PHYSICAL GROUNDING** — only when the shot has a real contact/impact (a boot planted on a chest, a weapon lock, a body thrown): spell out weight transfer, full contact, stable balance, material reaction, and the victim's physical response. Not needed for talking, walking, or ambient shots.
+
+## Dialogue & expression
+
+- Dialogue goes in quotes and may be in ANY language (Hebrew included). For silent tension, deliver it as expression, not speech: `He does not speak. His expression clearly says: "…"`.
+
+## Content tone
+
+- **Brutal war realism** — allow `Hollywood-style blood squib` impacts (visible spray, spreading stain on clothing, violent body reaction, hard collapse) when the user wants gritty combat.
+- **Restrained / no-gore** — when intensity is wanted without gore, state it explicitly (`brutal supernatural strike but no blood, no open wound, no exposed flesh`) AND add the gore terms to the AVOID list.
+- **Rapid-cut montage** (`N cuts / 2 seconds each`) — a valid structure: fixed-length hard cuts, vary the angle every cut (wide / medium / low / side / close handheld), state "Hard cuts. No slow motion," and reserve slow motion for a single named beat if any.
+
+## Universal Craft Layer (apply on top of any format above)
+
+> This is the universal film-direction layer that lifts every prompt above the boilerplate. **Deep-dive reference:** `~/.kolbo/skills/seedance-2-prompting/SKILL.md` (Craft Edition — full block structure, every optical technique, and the pre-flight checklist).
+
+### Core principle
+
+The model reacts to what can be **seen and measured**, not to mood words. Translate abstractions into observables.
+
+- ❌ "tense scene" → ✅ "man freezes, slowly clenches his fist, light only from the side, half his face in shadow"
+- ❌ "cool cinematic shot of a car, epic, fast" → ✅ "low tracking shot alongside the car as it powers through a wet curve, headlights glowing, spray off the tyres, hard buffeting camera shake"
+
+### Style — DISTRIBUTED, not a prefix
+
+Never pile all style tokens at the top of the prompt. Each aspect lives in the block that already governs it:
+
+- Lighting → inside the shot's LIGHTING description
+- Lens / FOV → in OPTICS
+- Color → either an explicit grade (when strong / stylized) or folded into LOCATION + LIGHTING for naturalistic looks
+- Skin / acting → in PERFORMANCE
+- Physics → in PHYSICS
+- Format / resolution / grain → at the END as a suffix stack (before LOCKS)
+
+### Shot sizes
+
+| Abbr | Meaning | In frame |
+|------|---------|----------|
+| ECU | Extreme Close-Up | a detail: eyes, button, headlight, hand |
+| CU | Close-Up | full face / one element large |
+| MCU | Medium Close-Up | head and shoulders |
+| MS | Medium Shot | roughly to the waist |
+| WS | Wide Shot | full figure + surroundings |
+| EWS | Extreme Wide | scale, location |
+
+### FOV anchor table (degrees — what to write in the prompt)
+
+| FOV | mm equiv | Purpose |
+|-----|----------|---------|
+| 180° | Fisheye | spherical distortion |
+| 107° | 14–16mm | architectural ultra-wide |
+| 84° | 20–24mm | wide |
+| 63° | 28–35mm | observational |
+| 47° | 40–50mm | neutral human perspective |
+| 29° | 75–85mm | portrait compression |
+| 18° | 100–135mm | natural portrait |
+| 12° | 180–200mm | tele-detail |
+| 8° | 300–400mm | extreme compression |
+
+Use only the discrete steps. Not "23°" — use 18° or 29°.
+
+### Prompting rules
+
+- **Positive only.** ❌ "does not fall backward" → ✅ "stays upright, feet planted."
+- **Speeds in km/h.** ❌ "fast/slow" → ✅ "moves at 40 km/h", "camera pans at 5 km/h."
+- **Atmosphere in % / meters.** ❌ "light fog" → ✅ "fog density 40%", "haze visible at 15 meters depth."
+- **Atmosphere builds in steps across shots.** Shot 1: 20% → Shot 2: 40% → Shot 3: 60%.
+- **Giant scale via human-height.** ❌ "huge, three meters tall" → ✅ "stands as tall as four humans stacked."
+- **Left/right is from the camera.** "Subject moves left" = left from the camera's view.
+- **Emotion through muscle movement**, not labels. ❌ "she looks sad" → ✅ "her eyes drop to the table, jaw tightens, she swallows once before answering."
+- **WB in Kelvin.** 3200K / 4000K / 5600K / 8500K. Pick ONE for the scene's mood.
+- **Color as material + light + role**, never a flat list. ❌ "she wears red, he wears blue" → ✅ "crimson silk scarf catching the cold tungsten spill from the corridor".
+- **No equipment names**, no director references, no "shot on ARRI / Sigma 85mm / Roger Deakins".
+
+### Cuts and timing
+
+- **Single continuous shot (oner)** → "one continuous shot, the camera does not cut on its own."
+- **Sequential cuts, no timecodes** → "CUT 1 … CUT 2 … CUT 3".
+- **Timed multishot** → explicit HARD CUTs at stated seconds, with timecode blocks `0.0s to 1.0s — [description]`.
+- **Mixed real-time + slow-mo** → hard cuts only between speed modes. Each shot one speed start to finish.
+
+### Special protocols
+
+- **4-mechanism multishot consistency stack** (extreme FOV: 8°, 107°): (1) sequence-wide identity lock, (2) LENS LOCK opener per beat, (3) LENS CHECK closer per beat, (4) color via material + light, not as a list. All four required.
+- **Whip-pan timing:** 0.3s Subject A settled → 0.8s WHIP motion-blur → 1.4s Subject B settled. Whip under 0.8s renders as a hard cut without blur.
+- **Anti-impact lock** (cracks/breaks without impact): "crowd PRESSES, not strikes", "fracture originates from edge stress, not center impact", "no impact point — pressure-based crack."
+
+### Optical techniques
+
+- **Observation pattern (hidden-camera):** foreground occlusion 20–30% + atmospheric haze + 8°–12° super-tele vantage.
+- **Sports broadcast:** 8° super-tele + handheld 1–2cm tremor + "anchored at distance, finding the action".
+- **Tele compressed air column** at 8°–12°: "dust suspended in the long compressed air column between camera and subject".
+
+### Camera placement
+
+Place CAMERA in the **3rd position** of each shot's core layers (Subject → Action → Camera → Style → Constraints). FOV gets ignored at the end, conflicts with identity at the front.
+
+### Pre-flight checklist (before output)
+
+- Distributed style (no top-pile)?
+- One camera movement per time slice?
+- FOV in degrees from the table (not mm, not arbitrary)?
+- WB in Kelvin?
+- Speed in km/h, atmosphere in % or meters?
+- Color via material + light + role?
+- Positive phrasing (no "does not X")?
+- No equipment / director names?
+- Emotion through muscle, not labels?
+- Multishot: FOV per segment + "no drift mid-segment"?
+- 8000-char cap honored?
+
 ## Grid Storyboard Mode (3×3 grid input)
 
 When the user uploads a 3×3 grid image and asks for Seedance prompts, switch to this mode:
@@ -80,11 +210,20 @@ When the user uploads a 3×3 grid image and asks for Seedance prompts, switch to
 
 ## Output Discipline
 
-- Final prompt(s) ALWAYS in a fenced code block ready to paste into the Seedance `prompt` field (or pass as `prompt` on `generate_video` / `generate_elements`).
+- Final prompt(s) ALWAYS in a fenced code block ready to paste into Seedance.
 - After the code block, give a 1-line "why this works" note (camera/escalation/physics choice).
 - If user asked in any language other than English, write your explanation in their language but keep the prompt itself English.
-- **Never exceed 8000 characters TOTAL** for the entire prompt as one string — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 8000 per shot — 8000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
+- **Never exceed 8000 characters TOTAL for the entire prompt as one string** — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 8000 per shot — 8000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
+
+## Where to run in Kolbo
+
+Seedance 2 lives in the **Video** category. Route the prompt card by the INPUTS:
+
+- **First & Last Frame** (`first_last_frame` tag) when the video must begin on one frame and end on another (start + end image, morph A→B). This wins even if Visual DNAs / characters / elements are referenced inside it — First-Last-Frame supports DNAs/elements too.
+- **Elements** (`elements` tag) when the scene is built from reference assets — a Visual DNA / character (`@name`), a moodboard (`#name`), or reference images composed into a NEW scene, with no explicit start+end frame. This is the default for any "@Character does X" / loopable-idle / new-scene-from-my-refs request.
+- **Image-to-Video** (`image_to_video` tag) only when a single existing image is animated as-is.
+- **Text-to-Video** (`text_to_video` tag) only when there is no reference image or character at all.
 
 ## Seedance + Visual DNA / References
 
-When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). Tag the DNA inside the prompt with `@<dna-name>` — see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.
+When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). Tag the DNA inside the prompt with `@<dna-name>` — see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.

package/skill/references/models/voice-tts.md

@@ -0,0 +1,85 @@
+# Voice / Text-to-Speech (`generate_speech`) — full style & option reference
+
+`generate_speech` turns text into spoken audio. Every voice belongs to a
+**provider** (ElevenLabs, DeepDub, MiniMax, Google/Gemini, OpenAI, Zonos). Each
+provider exposes its own expressive controls. You may pass any control on any
+call — **the engine silently ignores controls that don't apply to the chosen
+voice's provider**, so you never need to branch on provider yourself.
+
+## Pick the voice first
+Call `list_voices` (filter by `provider`, `language`, `gender`) and pass the
+returned `voice_id` — or a display name like `"Rachel"`. Cloned/custom voices
+resolve by name too. The voice determines the provider, which determines which
+controls below take effect.
+
+## Core params (all providers)
+| Param | Type | Notes |
+|---|---|---|
+| `text` | string (required) | The words to speak. |
+| `voice` | string | Voice id or display name. Default `"Rachel"`. |
+| `model` | string | From `list_models type="text_to_speech"`. Default `eleven_v3`. Usually inferred from the voice — only needed to force a specific engine. |
+| `language` | string | BCP-47 code, e.g. `"en-US"`, `"he-IL"`, `"es-ES"`. |
+| `speaking_speed` | number | `0.5` (slow) – `2.0` (fast). Default `1.0`. Applies to ElevenLabs / OpenAI / Google. |
+| `project_id` | string | Scope into a project (see Projects rules). |
+
+## Expressive style / emotion (provider-specific)
+| Param | Provider(s) | Values / notes |
+|---|---|---|
+| `style_instructions` | **Google / Gemini** | Free-form natural-language direction, e.g. `"whisper conspiratorially, slightly amused"`, `"excited sports announcer"`. Max 500 chars. |
+| `selected_style` | **DeepDub**, MiniMax | Preset style. DeepDub: `reading`, `conversational`, `angry`, `breathy`, `panic`, `amused`, `sad`, `whisper`, `singing`, `shout`, `scream`, `mumbling`, `excited`. |
+| `emotion` | **MiniMax** | `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `calm`, `fluent`, `whisper`. |
+
+## ElevenLabs voice settings
+| Param | Range | Default | Effect |
+|---|---|---|---|
+| `similarity_boost` | 0–1 | 0.75 | Higher hews closer to the source voice. |
+| `style` | 0–1 | 0.5 | Style exaggeration — higher is more expressive/dramatic. |
+| `use_speaker_boost` | bool | true | Speaker-clarity boost. |
+
+## DeepDub controls
+| Param | Range | Default | Effect |
+|---|---|---|---|
+| `variance` | 0–1 | 0.2 | More variation / takes. |
+| `tempo` | 0–2 | 1.0 | Pacing multiplier. |
+| `promptBoost` | bool | true | Higher fidelity to the text. |
+| `seed` | int | — | Reproducibility (same seed + inputs → same output). Also honored by Zonos. |
+| `accentControl` | object | — | `{ accentBaseLocale, accentLocale, accentRatio }` — blend an accent. Provide BOTH `accentBaseLocale` (e.g. `"en-US"`) and `accentLocale` (e.g. `"en-GB"`); `accentRatio` 0–1 (default 0.5). |
+| `voiceTitle` | string | — | Display title for a custom/cloned voice. |
+
+## MiniMax fine controls
+| Param | Range | Default | Effect |
+|---|---|---|---|
+| `minimax_pitch` | −12 … 12 | 0 | Pitch shift. |
+| `minimax_vol` | 0–10 | 1 | Volume. |
+| `minimax_intensity` | — | — | Voice intensity. |
+| `minimax_timbre` | — | — | Voice timbre. |
+
+## Examples
+Neutral ElevenLabs read:
+```
+generate_speech(text="Welcome to Kolbo.", voice="Rachel")
+```
+Whispered, conspiratorial Gemini delivery:
+```
+generate_speech(text="Meet me at midnight.", voice="Kore",
+                style_instructions="whisper conspiratorially, slow and breathy")
+```
+Angry DeepDub take, faster:
+```
+generate_speech(text="Get out of my house!", voice="<deepdub voice>",
+                selected_style="angry", tempo=1.2)
+```
+Excited MiniMax with pitch/volume tweaks:
+```
+generate_speech(text="We won the championship!", voice="<minimax voice>",
+                emotion="happy", minimax_pitch=3, minimax_vol=6)
+```
+British-accented DeepDub blend:
+```
+generate_speech(text="Good evening.", voice="<deepdub voice>",
+                accentControl={ accentBaseLocale: "en-US", accentLocale: "en-GB", accentRatio: 0.7 })
+```
+
+## Credits
+~5 credits per 100 characters for most TTS models (Zonos ~3; voice design/clone
+~30 flat). Charged only on success. Use `check_credits` once per conversation.

package/src/tools/generate.js

@@ -391,22 +391,36 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_music ────────────────────────────────────────
   server.tool(
     'generate_music',
-    'Generate music from a text description using Kolbo AI. Supports instrumental mode, custom lyrics, style direction, and vocal gender. Default model is Suno. Returns the final audio URL when complete.',
+    'Generate music from a text description using Kolbo AI. Supports instrumental mode, custom lyrics, style direction, vocal gender, negative tags, song length, and Suno fine-controls (style weight, weirdness, audio weight, persona/singing voice). Default model is Suno. Some controls are Suno-only; the engine ignores controls that do not apply to the chosen model. Returns the final audio URL when complete.',
     {
       prompt: z.string().describe('Text description of the music to generate (e.g., "upbeat electronic dance track with synthesizers")'),
       model: z.string().optional().describe('Model identifier. Use list_models type="music_gen" to see options. Omit for Suno (default).'),
       style: z.string().optional().describe('Music style / genre (e.g., "pop", "rock", "lo-fi", "electronic", "jazz")'),
+      title: z.string().optional().describe('Song title. If omitted, one is generated.'),
       instrumental: z.boolean().optional().describe('Generate instrumental only, no vocals. Default: false'),
       lyrics: z.string().optional().describe('Custom lyrics for the song. If omitted, lyrics are generated automatically from the prompt unless instrumental is true.'),
       vocal_gender: z.string().optional().describe('Preferred vocal gender: "male" or "female". Only applies when instrumental is false.'),
+      negative_tags: z.string().optional().describe('Styles / sounds to EXCLUDE, comma-separated (e.g. "heavy metal, screaming, distortion"). Suno.'),
+      duration_seconds: z.number().optional().describe('Target song length in seconds (length-capable models like ElevenLabs Music). Clamped 5–300. Omit for the model default.'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt. Default: true'),
       preset_id: z.string().optional().describe('Preset ID from list_presets type="music" to apply a saved music style preset.'),
+      // ── Suno fine controls ──
+      style_weight: z.number().optional().describe('Suno: how strongly the style/genre is applied, 0–1.'),
+      weirdness: z.number().optional().describe('Suno: creativity / weirdness constraint, 0–1. Higher = more experimental.'),
+      audio_weight: z.number().optional().describe('Suno: influence of an audio/persona reference, 0–1.'),
+      persona_id: z.string().optional().describe('Suno persona id — reuse a saved singing voice/persona.'),
+      use_composition_plan: z.boolean().optional().describe('Suno: enable structured composition planning (verse/chorus structure).'),
+      singing_dna_id: z.string().optional().describe('Visual DNA character id whose singing voice to use (must be owned by the caller).'),
+      singing_voice_id: z.string().optional().describe('Custom cloned singing-voice id (must be owned by the caller).'),
       project_id: projectIdField
     },
-    async ({ prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt, preset_id, project_id }) => {
+    async ({ prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags, duration_seconds, enhance_prompt, preset_id, style_weight, weirdness, audio_weight, persona_id, use_composition_plan, singing_dna_id, singing_voice_id, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/music', {
-        prompt, model, style, instrumental, lyrics, vocal_gender, enhance_prompt, preset_id, project_id
+        prompt, model, style, title, instrumental, lyrics, vocal_gender, negative_tags,
+        duration_seconds, enhance_prompt, preset_id,
+        style_weight, weirdness, audio_weight, persona_id, use_composition_plan,
+        singing_dna_id, singing_voice_id, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -437,23 +451,53 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_speech ───────────────────────────────────────
   server.tool(
     'generate_speech',
-    'Convert text to speech using Kolbo AI. Default provider is ElevenLabs. To pick a specific voice by language/gender, call list_voices first and pass the returned voice_id (or a voice display name — both work). Returns the final audio URL when complete.',
+    'Convert text to speech using Kolbo AI. Default provider is ElevenLabs. To pick a specific voice by language/gender, call list_voices first and pass the returned voice_id (or a voice display name — both work). Every voice belongs to a provider (ElevenLabs, DeepDub, MiniMax, Google/Gemini, OpenAI, Zonos) and each provider exposes its own expressive/style controls below — the engine ignores any control that does not apply to the chosen voice\'s provider, so it is safe to pass only what you need. Returns the final audio URL when complete.',
     {
       text: z.string().describe('The text to convert to speech'),
       voice: z.string().optional().describe('Voice ID (from list_voices) or voice display name (e.g., "Rachel", "Adam"). Default: "Rachel"'),
       model: z.string().optional().describe('Model identifier. Use list_models type="text_to_speech" to see options. Default: eleven_v3'),
       language: z.string().optional().describe('Language code (e.g., "en-US", "he-IL", "es-ES"). Default: "en-US"'),
+      // ── Expressive style / emotion (provider-specific) ──
+      style_instructions: z.string().optional().describe('Google/Gemini voices ONLY. Free-form natural-language voice direction, e.g. "whisper conspiratorially, slightly amused" or "excited sports announcer". Max 500 chars. Ignored by other providers.'),
+      selected_style: z.string().optional().describe('DeepDub & MiniMax voices. Preset expressive style/emotion. DeepDub supports: reading, conversational, angry, breathy, panic, amused, sad, whisper, singing, shout, scream, mumbling, excited. Ignored by other providers.'),
+      emotion: z.string().optional().describe('MiniMax voices. Emotion: happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper.'),
+      speaking_speed: z.number().optional().describe('Speech speed 0.5 (slow) – 2.0 (fast). Default 1.0. Applies to ElevenLabs / OpenAI / Google.'),
+      // ── ElevenLabs voice settings ──
+      similarity_boost: z.number().optional().describe('ElevenLabs voice similarity, 0–1. Default 0.75. Higher hews closer to the original voice.'),
+      style: z.number().optional().describe('ElevenLabs style exaggeration, 0–1. Default 0.5. Higher = more expressive/dramatic.'),
+      use_speaker_boost: z.boolean().optional().describe('ElevenLabs speaker boost. Default true.'),
+      // ── DeepDub controls ──
+      variance: z.number().optional().describe('DeepDub voice variance, 0–1. Default 0.2. Higher = more takes/variation.'),
+      tempo: z.number().optional().describe('DeepDub tempo multiplier, 0–2. Default 1.0.'),
+      promptBoost: z.boolean().optional().describe('DeepDub prompt-fidelity boost. Default true.'),
+      seed: z.number().optional().describe('Reproducibility seed (DeepDub / Zonos). Same seed + inputs → same output.'),
+      accentControl: z.object({
+        accentBaseLocale: z.string().describe('Base accent locale, e.g. "en-US".'),
+        accentLocale: z.string().describe('Target accent locale, e.g. "en-GB".'),
+        accentRatio: z.number().optional().describe('Blend ratio 0–1. Default 0.5.')
+      }).optional().describe('DeepDub accent steering. Provide both base and target locale to blend an accent.'),
+      voiceTitle: z.string().optional().describe('DeepDub display title for a custom/cloned voice.'),
+      // ── MiniMax fine controls ──
+      minimax_pitch: z.number().optional().describe('MiniMax pitch, −12 to 12. Default 0.'),
+      minimax_vol: z.number().optional().describe('MiniMax volume, 0–10. Default 1.'),
+      minimax_intensity: z.number().optional().describe('MiniMax voice intensity.'),
+      minimax_timbre: z.number().optional().describe('MiniMax voice timbre.'),
       project_id: projectIdField
     },
-    async ({ text, voice, model, language, project_id }) => {
+    async ({ text, voice, model, language, style_instructions, selected_style, emotion, speaking_speed, similarity_boost, style, use_speaker_boost, variance, tempo, promptBoost, seed, accentControl, voiceTitle, minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/speech', {
-        text, voice, model, language, project_id
+        text, voice, model, language,
+        style_instructions, selected_style, emotion, speaking_speed,
+        similarity_boost, style, use_speaker_boost,
+        variance, tempo, promptBoost, seed, accentControl, voiceTitle,
+        minimax_pitch, minimax_vol, minimax_intensity, minimax_timbre,
+        project_id
       });
 
       if (ui()) return uiGenerating({
         tool: 'generate_speech', kind: 'audio', gen, client, model, prompt: text,
-        settings: { voice: voice || 'Rachel' }
+        settings: { voice: voice || 'Rachel', style: selected_style || emotion || style_instructions }
       });
 
       const result = await pollUntilDone(client, gen.generation_id, {
@@ -478,18 +522,34 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── generate_sound ────────────────────────────────────────
   server.tool(
     'generate_sound',
-    'Generate sound effects (not music, not speech) from a text description using Kolbo AI. Use this for ambient sounds, foley, impacts, atmospheres, UI sounds, etc. For music use generate_music; for voice use generate_speech. Returns the final audio URL when complete.',
+    'Generate sound effects (not music, not speech) from a text description using Kolbo AI. Use this for ambient sounds, foley, impacts, atmospheres, UI sounds, etc. For music use generate_music; for voice use generate_speech. Beyond the core prompt/duration, per-provider controls are available (Stable Audio guidance, Kie loop/tempo/key, Seed-Audio voice/speed/volume/pitch + reference audio/image); the engine ignores controls that do not apply to the chosen model. Returns the final audio URL when complete.',
     {
       prompt: z.string().describe('Text description of the sound effect (e.g., "thunder clap with rain", "door creaking open", "futuristic UI beep")'),
       model: z.string().optional().describe('Model identifier. Use list_models type="text_to_sound" to see options. Default: elevenlabs-sound-effects-v1'),
       duration: z.number().optional().describe('Duration in seconds. Omit for automatic duration.'),
-      prompt_influence: z.number().optional().describe('How strongly the prompt guides the generation (0–1). Default: 0.5. Lower values give the model more creative freedom; higher values follow the prompt more literally.'),
+      prompt_influence: z.number().optional().describe('ElevenLabs: how strongly the prompt guides the generation (0–1). Default: 0.5. Lower = more creative freedom; higher = more literal.'),
+      // ── FAL Stable Audio / mmaudio ──
+      cfg_strength: z.number().optional().describe('FAL (Stable Audio 3 / mmaudio): classifier-free guidance strength. Higher hews closer to the prompt.'),
+      // ── Kie ──
+      sound_loop: z.boolean().optional().describe('Kie: generate a seamlessly looping sound.'),
+      sound_tempo: z.number().optional().describe('Kie: tempo control.'),
+      sound_key: z.string().optional().describe('Kie: musical key / scale.'),
+      // ── FAL Seed Audio ──
+      seed_voice: z.string().optional().describe('FAL Seed-Audio: voice to use.'),
+      seed_speed: z.number().optional().describe('FAL Seed-Audio: speed multiplier, 0.5–2.0.'),
+      seed_volume: z.number().optional().describe('FAL Seed-Audio: volume, 0–1.'),
+      seed_pitch: z.number().optional().describe('FAL Seed-Audio: pitch shift in semitones.'),
+      seed_reference_audio_urls: z.array(z.string()).optional().describe('FAL Seed-Audio: up to 3 reference audio URLs to condition the sound.'),
+      seed_reference_image_url: z.string().optional().describe('FAL Seed-Audio: a reference image URL to condition the sound.'),
       project_id: projectIdField
     },
-    async ({ prompt, model, duration, prompt_influence, project_id }) => {
+    async ({ prompt, model, duration, prompt_influence, cfg_strength, sound_loop, sound_tempo, sound_key, seed_voice, seed_speed, seed_volume, seed_pitch, seed_reference_audio_urls, seed_reference_image_url, project_id }) => {
       model = await canonicalModelId(client, model); // lenient id resolution ("z-image" → "z-image/turbo")
       const gen = await client.post('/v1/generate/sound', {
-        prompt, model, duration, prompt_influence, project_id
+        prompt, model, duration, prompt_influence,
+        cfg_strength, sound_loop, sound_tempo, sound_key,
+        seed_voice, seed_speed, seed_volume, seed_pitch,
+        seed_reference_audio_urls, seed_reference_image_url, project_id
       });
 
       if (ui()) return uiGenerating({
@@ -963,23 +1023,39 @@ function registerGenerateTools(server, client, options = {}) {
   // ─── transcribe_audio ──────────────────────────────────────
   server.tool(
     'transcribe_audio',
-    'Transcribe audio or video into text + SRT subtitles. Source can be a URL or an absolute local file path. Returns the full text, SRT content, duration, and download URLs for .srt/.txt files. Works on both audio-only files (mp3, wav, m4a) and videos with audio tracks (mp4, mov, webm).',
+    'Transcribe audio or video into text + SRT subtitles. Source can be a URL or an absolute local file path. Returns the full text, SRT content, duration, and download URLs for .srt/.txt files. Works on both audio-only files (mp3, wav, m4a) and videos with audio tracks (mp4, mov, webm). Supports language selection, speaker diarization, audio-event tagging, and SRT subtitle formatting controls.',
     {
       source: z.string().describe('URL or absolute local path to the audio / video file to transcribe'),
+      language: z.string().optional().describe('Language code of the speech (e.g. "en", "he", "es"). Omit to auto-detect.'),
+      diarize: z.boolean().optional().describe('Detect and label distinct speakers. Default: false.'),
+      tag_audio_events: z.boolean().optional().describe('Tag non-speech audio events (laughter, applause, music) in the transcript. Default: false.'),
+      remove_punctuation: z.boolean().optional().describe('Strip punctuation from the transcript. Default: false.'),
+      generate_srt: z.boolean().optional().describe('Produce SRT + word-by-word SRT subtitle files. Default: true.'),
+      words_per_line: z.number().optional().describe('SRT: max words per subtitle line, 1–18. Default: 12.'),
+      lines_per_subtitle: z.number().optional().describe('SRT: max lines per subtitle cue, 1–4. Default: 2.'),
+      stretch_captions: z.boolean().optional().describe('SRT: extend each cue\'s end time to the next cue\'s start (gap-free subtitles). Default: true.'),
       project_id: projectIdField
     },
-    async ({ source, project_id }) => {
+    async ({ source, language, diarize, tag_audio_events, remove_punctuation, generate_srt, words_per_line, lines_per_subtitle, stretch_captions, project_id }) => {
       if (!source) throw new Error('source is required (URL or absolute local path)');
 
+      // Advanced transcription controls forwarded when provided (undefined keys are dropped by the client).
+      const opts = {
+        language, diarize, tag_audio_events, remove_punctuation,
+        generate_srt, words_per_line, lines_per_subtitle, stretch_captions, project_id
+      };
+
       const isUrl = /^https?:\/\//i.test(source);
       let startResponse;
       if (isUrl) {
-        startResponse = await client.post('/v1/transcribe', { audio_url: source, project_id });
+        startResponse = await client.post('/v1/transcribe', { audio_url: source, ...opts });
       } else {
         const resolved = await resolveToBuffer(source, 'audio');
         const form = new FormData();
         form.append('file', resolved.buffer, { filename: resolved.filename, contentType: resolved.contentType });
-        if (project_id) form.append('project_id', project_id);
+        for (const [k, v] of Object.entries(opts)) {
+          if (v !== undefined && v !== null) form.append(k, typeof v === 'boolean' ? String(v) : v);
+        }
         startResponse = await client.postMultipart('/v1/transcribe', form);
       }
 

package/src/tools/visual_dna.js

@@ -20,7 +20,7 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── create_visual_dna ─────────────────────────────────────
   server.tool(
     'create_visual_dna',
-    'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each. For CHARACTER DNAs, a multi-angle character sheet dramatically improves consistency — offer to generate one with `generate_character_sheet` first, then pass its URL as `character_sheet_url` here (see that tool).',
+    'Create a Visual DNA profile from reference media. Each item in images/video/audio can be a public URL or an absolute local file path. Max 4 images, 1 video, 1 audio. Files capped at 25MB each. For EVERY DNA type, a reference sheet dramatically improves consistency (character turnaround / product details / location angles / style board) — offer to generate one with `generate_character_sheet` (matching `sheet_type`) first, then pass its URL as `character_sheet_url` here (see that tool).',
     {
       name: z.string().describe('Name of the Visual DNA profile. **Pick a short, lowercase, no-space single token** (e.g. `maya`, `tokyo_neon`, `brand_red`, `esther_model`) — never names with spaces (`Sarah Johnson` ❌). The user/LLM types this as `@<name>` inside generation prompts, and the @ parser stops at the first space, so `@Sarah Johnson` matches only `Sarah` and the binding silently drops. Multi-word concepts should use underscores or be a single token. Names are case-insensitive on lookup, but **reserved** values rejected on creation: `Image1`, `Image2`, …, `Video1`, …, `Audio1`, … (any-language characters allowed; max 100 chars).'),
       dna_type: z.string().optional().describe('Type: "character", "style", "product", "scene", "environment". Default: "character"'),
@@ -28,7 +28,7 @@ function registerVisualDnaTools(server, client, options = {}) {
       images: z.array(z.string()).optional().describe('Array of image sources (URLs or absolute local paths). Max 4.'),
       video: z.string().optional().describe('Optional video source (URL or absolute local path)'),
       audio: z.string().optional().describe('Optional audio source (URL or absolute local path)'),
-      character_sheet_url: z.string().optional().describe('URL of a multi-angle character sheet (from `generate_character_sheet`) to set as the DNA\'s primary reference. Strongly recommended for character DNAs — it is the single biggest consistency booster. Omit for non-character DNAs or when the user declines.')
+      character_sheet_url: z.string().optional().describe('URL of a reference sheet (from `generate_character_sheet`, any sheet_type) to set as the DNA\'s primary reference. Works for ALL DNA types — character turnaround, product detail sheet, location sheet, or style board — and is the single biggest consistency booster. Omit only when the user declines.')
     },
     async ({ name, dna_type, prompt_helper, images, video, audio, character_sheet_url }) => {
       if (!name || !name.trim()) {
@@ -164,12 +164,13 @@ function registerVisualDnaTools(server, client, options = {}) {
   // ─── generate_character_sheet ──────────────────────────────
   server.tool(
     'generate_character_sheet',
-    'Generate a multi-angle character sheet (turnaround) from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers. The sheet is the single strongest consistency booster for a character DNA. CHARGES CREDITS, so when the user is about to create a character DNA, OFFER this first ("want me to generate a character sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna`.',
+    'Generate a reference sheet for a Visual DNA from 1+ reference image URLs — the same step the in-app Visual DNA wizard offers, for EVERY DNA type via `sheet_type`: character = multi-angle turnaround, product = angles + branding/material/construction close-ups, environment = location angles + one signature detail, style = a style board (the same look applied to six varied subjects). The sheet is the single strongest consistency booster for a DNA, and it always preserves the reference\'s original art style (2D stays 2D, photo stays photo). CHARGES CREDITS, so when the user is about to create a DNA, OFFER this first ("want me to generate a reference sheet for stronger consistency? it costs a few credits") and only run it on a yes. Returns `character_sheet_url` — pass it as `character_sheet_url` to `create_visual_dna` with the matching `dna_type`.',
     {
-      image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the character (front/side/varied angles work best). Use generated-image URLs or upload_media output.')
+      image_urls: z.array(z.string()).min(1).describe('Reference image URLs of the subject (for characters: front/side/varied angles work best). Use generated-image URLs or upload_media output.'),
+      sheet_type: z.enum(['character', 'product', 'environment', 'style']).optional().describe('Which sheet layout to generate — match the DNA type it will be attached to. Defaults to character.')
     },
-    async ({ image_urls }) => {
-      const result = await client.post('/v1/visual-dna/character-sheet', { image_urls });
+    async ({ image_urls, sheet_type }) => {
+      const result = await client.post('/v1/visual-dna/character-sheet', { image_urls, ...(sheet_type ? { sheet_type } : {}) });
       return {
         content: [{
           type: 'text',