whale-code 6.4.0

package/dist/server/handlers/voice.js

@@ -0,0 +1,1146 @@
+// server/handlers/voice.ts — ElevenLabs audio suite v2.1
+//
+// Actions: speak, batch, sound_effects, music_plan, music_compose,
+//          music_compose_detailed, speech_to_text, stem_separation,
+//          voice_changer, audio_isolation, voice_design, voice_design_create,
+//          forced_alignment, search_voices, list_voices, get_voice,
+//          clone_voice, usage, list_models,
+//          pvc_create, pvc_upload, pvc_separate_speakers, pvc_status,
+//          pvc_select_speaker, pvc_verify, pvc_train
+//
+// v2.1: music_plan (structured composition plans), auto vocal clarity styles,
+//       composition_plan support on music_compose, 192kbps music output
+// v2: DRY helpers, credential caching, voice name resolution, batch TTS,
+//     retry with backoff, updated models (eleven_v3, scribe_v2)
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const ELEVENLABS_BASE = "https://api.elevenlabs.io/v1";
+const DEFAULT_VOICE_ID = "21m00Tcm4TlvDq8ikWAM"; // Rachel
+const DEFAULT_TTS_MODEL = "eleven_v3";
+const DEFAULT_STS_MODEL = "eleven_english_sts_v2";
+const DEFAULT_MUSIC_MODEL = "music_v1";
+const DEFAULT_SFX_MODEL = "eleven_text_to_sound_v2";
+const DEFAULT_TTV_MODEL = "eleven_ttv_v3";
+const DEFAULT_STT_MODEL = "scribe_v2";
+const MAX_RETRIES = 2;
+const RETRY_DELAY_MS = 1000;
+const VOICE_CACHE_TTL = 600_000; // 10 min
+const KEY_CACHE_TTL = 300_000; // 5 min
+// ============================================================================
+// CREDENTIAL CACHING — 5-min TTL, avoids decrypt RPC on every call
+// ============================================================================
+const keyCache = new Map();
+async function getElevenLabsKey(sb, storeId) {
+    const cached = keyCache.get(storeId);
+    if (cached && Date.now() - cached.fetchedAt < KEY_CACHE_TTL)
+        return cached.key;
+    const { data, error } = await sb.rpc("decrypt_secret", {
+        p_name: "ELEVENLABS_API_KEY",
+        p_store_id: storeId,
+    });
+    if (error || !data)
+        return null;
+    const key = data;
+    keyCache.set(storeId, { key, fetchedAt: Date.now() });
+    if (keyCache.size > 50) {
+        // Evict oldest entry by fetchedAt, not insertion order
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [k, v] of keyCache) {
+            if (v.fetchedAt < oldestTime) {
+                oldestTime = v.fetchedAt;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey)
+            keyCache.delete(oldestKey);
+    }
+    return key;
+}
+// ============================================================================
+// VOICE NAME RESOLUTION — accept name or ID, cache voice list 10 min
+// ============================================================================
+const voiceListCache = new Map();
+/** Popular voice presets for quick lookup without API call */
+const VOICE_PRESETS = {
+    rachel: "21m00Tcm4TlvDq8ikWAM",
+    daniel: "onwK4e9ZLuTAKqWW03F9",
+    roger: "CwhRBWXzGAHq8TQ4Fs17",
+    sarah: "EXAVITQu4vr4xnSDxMaL",
+    adam: "pNInz6obpgDQGcFmaJgB",
+    charlie: "IKne3meq5aSn9XLyUdCD",
+    emily: "LcfcDJNUP1GQjkzn1xUU",
+    josh: "TxGEqnHWrfWFTfGW9XjX",
+};
+async function resolveVoiceId(nameOrId, apiKey, storeId) {
+    // Already a voice ID (UUID-like or 20+ char alphanumeric)?
+    if (/^[a-zA-Z0-9]{20,}$/.test(nameOrId))
+        return nameOrId;
+    // Check presets first (instant, no API call)
+    const preset = VOICE_PRESETS[nameOrId.toLowerCase()];
+    if (preset)
+        return preset;
+    // Fetch and cache voice list from ElevenLabs
+    let voices = voiceListCache.get(storeId);
+    if (!voices || Date.now() - voices.fetchedAt > VOICE_CACHE_TTL) {
+        try {
+            const resp = await fetch(`${ELEVENLABS_BASE}/voices`, {
+                headers: { "xi-api-key": apiKey },
+            });
+            if (resp.ok) {
+                const data = await resp.json();
+                const list = (data.voices || []).map((v) => ({ voice_id: v.voice_id, name: v.name }));
+                voices = { voices: list, fetchedAt: Date.now() };
+                voiceListCache.set(storeId, voices);
+                if (voiceListCache.size > 50) {
+                    let oldestKey;
+                    let oldestTime = Infinity;
+                    for (const [k, v] of voiceListCache) {
+                        if (v.fetchedAt < oldestTime) {
+                            oldestTime = v.fetchedAt;
+                            oldestKey = k;
+                        }
+                    }
+                    if (oldestKey)
+                        voiceListCache.delete(oldestKey);
+                }
+            }
+        }
+        catch { /* fall through to fuzzy match on stale cache */ }
+    }
+    if (voices) {
+        const lower = nameOrId.toLowerCase();
+        // Exact match
+        const exact = voices.voices.find(v => v.name.toLowerCase() === lower);
+        if (exact)
+            return exact.voice_id;
+        // Starts-with match
+        const starts = voices.voices.find(v => v.name.toLowerCase().startsWith(lower));
+        if (starts)
+            return starts.voice_id;
+        // Contains match
+        const contains = voices.voices.find(v => v.name.toLowerCase().includes(lower));
+        if (contains)
+            return contains.voice_id;
+    }
+    // Fall back — treat as voice ID (let ElevenLabs return 404 if invalid)
+    return nameOrId;
+}
+async function uploadAudioAndRecord(sb, storeId, audioBuffer, label, ext, mimeType, aiTags) {
+    const id = crypto.randomUUID();
+    const fileName = `${id}.${ext}`;
+    const storagePath = `ai-generated/${storeId.toUpperCase()}/audio/${fileName}`;
+    const { error: uploadErr } = await sb.storage
+        .from("store-media")
+        .upload(storagePath, audioBuffer, { contentType: mimeType, upsert: true });
+    if (uploadErr)
+        throw new Error(`Storage upload failed: ${uploadErr.message}`);
+    const { data: urlData } = sb.storage.from("store-media").getPublicUrl(storagePath);
+    const fileUrl = urlData.publicUrl;
+    const { data: mediaRow, error: mediaErr } = await sb
+        .from("store_media")
+        .insert({
+        store_id: storeId, file_name: fileName, file_path: storagePath,
+        file_url: fileUrl, file_size: audioBuffer.length, file_type: mimeType,
+        category: "ai_generated", ai_tags: aiTags, ai_description: label, source: "elevenlabs",
+    })
+        .select("id")
+        .single();
+    if (mediaErr)
+        console.error("[voice] store_media insert error:", mediaErr.message);
+    return { file_url: fileUrl, file_name: fileName, file_size: audioBuffer.length, media_id: mediaRow?.id || id };
+}
+// ============================================================================
+// DRY HELPERS — eliminate 90% of code duplication
+// ============================================================================
+function formatInfo(outputFormat) {
+    if (outputFormat.startsWith("pcm"))
+        return { ext: "pcm", mime: "audio/pcm" };
+    if (outputFormat.startsWith("opus"))
+        return { ext: "opus", mime: "audio/opus" };
+    return { ext: "mp3", mime: "audio/mpeg" };
+}
+/** Fetch with retry for ElevenLabs API (handles 429/500/502/503) */
+async function fetchWithRetry(url, init) {
+    let lastErr = null;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const resp = await fetch(url, init);
+            if (resp.ok || (resp.status < 500 && resp.status !== 429))
+                return resp;
+            if (attempt < MAX_RETRIES) {
+                const delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            return resp; // final attempt, return whatever we got
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt < MAX_RETRIES) {
+                await new Promise(r => setTimeout(r, RETRY_DELAY_MS * Math.pow(2, attempt)));
+            }
+        }
+    }
+    throw lastErr || new Error("Fetch failed after retries");
+}
+/** API call → buffer → upload → standard result */
+async function generateAndUpload(sb, storeId, apiKey, url, body, label, tags, ext, mime, extraFields = {}) {
+    try {
+        const resp = await fetchWithRetry(url, {
+            method: "POST",
+            headers: { "xi-api-key": apiKey, "Content-Type": "application/json", Accept: "audio/mpeg" },
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            const errText = await resp.text();
+            return { success: false, error: `ElevenLabs error ${resp.status}: ${errText}` };
+        }
+        const audioBuffer = Buffer.from(await resp.arrayBuffer());
+        const upload = await uploadAudioAndRecord(sb, storeId, audioBuffer, label, ext, mime, tags);
+        return {
+            success: true,
+            data: {
+                file_url: upload.file_url,
+                file_size: upload.file_size,
+                media_id: upload.media_id,
+                format: ext,
+                ...extraFields,
+            },
+        };
+    }
+    catch (err) {
+        return { success: false, error: `${label} failed: ${err}` };
+    }
+}
+/** FormData-based API call → buffer → upload → standard result */
+async function processFormData(sb, storeId, apiKey, url, formData, label, tags, ext, mime, extraFields = {}) {
+    try {
+        const resp = await fetchWithRetry(url, {
+            method: "POST",
+            headers: { "xi-api-key": apiKey },
+            body: formData,
+        });
+        if (!resp.ok) {
+            const errText = await resp.text();
+            return { success: false, error: `ElevenLabs error ${resp.status}: ${errText}` };
+        }
+        const audioBuffer = Buffer.from(await resp.arrayBuffer());
+        const upload = await uploadAudioAndRecord(sb, storeId, audioBuffer, label, ext, mime, tags);
+        return {
+            success: true,
+            data: {
+                file_url: upload.file_url,
+                file_size: upload.file_size,
+                media_id: upload.media_id,
+                format: ext,
+                ...extraFields,
+            },
+        };
+    }
+    catch (err) {
+        return { success: false, error: `${label} failed: ${err}` };
+    }
+}
+/** Build FormData from base64 audio input */
+function audioFormData(audioBase64, fieldName = "file", fileName = "audio.mp3") {
+    const buffer = Buffer.from(audioBase64, "base64");
+    const blob = new Blob([buffer], { type: "audio/mpeg" });
+    const formData = new FormData();
+    formData.append(fieldName, blob, fileName);
+    return formData;
+}
+// ============================================================================
+// MAIN HANDLER
+// ============================================================================
+export async function handleVoice(sb, args, storeId) {
+    const sid = storeId;
+    const action = args.action;
+    const apiKey = await getElevenLabsKey(sb, sid);
+    if (!apiKey) {
+        return { success: false, error: "ELEVENLABS_API_KEY not configured. Add it to user_tool_secrets for this store." };
+    }
+    const outputFormat = args.output_format || "mp3_44100_128";
+    const { ext, mime } = formatInfo(outputFormat);
+    switch (action) {
+        // ── TEXT-TO-SPEECH ─────────────────────────────────────────────────
+        case "speak": {
+            const text = args.text;
+            if (!text)
+                return { success: false, error: "text parameter is required" };
+            if (text.length > 5000)
+                return { success: false, error: "Text too long (max 5000 characters). Split into smaller chunks or use batch action." };
+            // Resolve voice by name or ID
+            const voiceInput = (args.voice_name || args.voice_id || DEFAULT_VOICE_ID);
+            const voiceId = await resolveVoiceId(voiceInput, apiKey, sid);
+            const modelId = args.model_id || DEFAULT_TTS_MODEL;
+            // Smart defaults: cloned/custom voices get higher similarity for accuracy
+            const presetIds = new Set(Object.values(VOICE_PRESETS));
+            const isCloned = !presetIds.has(voiceId) && voiceId !== DEFAULT_VOICE_ID;
+            const defaultStability = isCloned ? 0.35 : 0.5;
+            const defaultSimilarity = isCloned ? 0.9 : 0.75;
+            const defaultStyle = isCloned ? 0.05 : 0;
+            return generateAndUpload(sb, sid, apiKey, `${ELEVENLABS_BASE}/text-to-speech/${voiceId}?output_format=${outputFormat}`, {
+                text,
+                model_id: modelId,
+                voice_settings: {
+                    stability: args.stability ?? defaultStability,
+                    similarity_boost: args.similarity_boost ?? defaultSimilarity,
+                    style: args.style ?? defaultStyle,
+                    use_speaker_boost: args.speaker_boost ?? true,
+                },
+            }, `TTS: ${text.substring(0, 80)}`, ["AI Generated", "Text-to-Speech", "ElevenLabs"], ext, mime, { voice_id: voiceId, model_id: modelId, text_length: text.length, cloned_voice: isCloned });
+        }
+        // ── BATCH TTS ──────────────────────────────────────────────────────
+        case "batch": {
+            const items = args.items;
+            if (!items?.length)
+                return { success: false, error: "items array is required (each with text, optional voice_name/voice_id)" };
+            if (items.length > 10)
+                return { success: false, error: "Maximum 10 items per batch" };
+            const results = await Promise.allSettled(items.map(async (item) => {
+                const voiceInput = item.voice_name || item.voice_id || DEFAULT_VOICE_ID;
+                const voiceId = await resolveVoiceId(voiceInput, apiKey, sid);
+                const modelId = item.model_id || DEFAULT_TTS_MODEL;
+                // Smart defaults: cloned/custom voices get higher similarity for accuracy
+                const presetIds = new Set(Object.values(VOICE_PRESETS));
+                const isCloned = !presetIds.has(voiceId) && voiceId !== DEFAULT_VOICE_ID;
+                const batchStability = isCloned ? 0.35 : 0.5;
+                const batchSimilarity = isCloned ? 0.9 : 0.75;
+                const batchStyle = isCloned ? 0.05 : 0;
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/text-to-speech/${voiceId}?output_format=${outputFormat}`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey, "Content-Type": "application/json", Accept: "audio/mpeg" },
+                    body: JSON.stringify({
+                        text: item.text,
+                        model_id: modelId,
+                        voice_settings: { stability: batchStability, similarity_boost: batchSimilarity, style: batchStyle, use_speaker_boost: true },
+                    }),
+                });
+                if (!resp.ok)
+                    throw new Error(`ElevenLabs error ${resp.status}`);
+                const audioBuffer = Buffer.from(await resp.arrayBuffer());
+                const upload = await uploadAudioAndRecord(sb, sid, audioBuffer, `TTS: ${item.text.substring(0, 80)}`, ext, mime, ["AI Generated", "Text-to-Speech", "ElevenLabs", "Batch"]);
+                return {
+                    text: item.text.substring(0, 80),
+                    voice_id: voiceId,
+                    file_url: upload.file_url,
+                    file_size: upload.file_size,
+                    media_id: upload.media_id,
+                    format: ext,
+                };
+            }));
+            const clips = [];
+            const errors = [];
+            results.forEach((r, i) => {
+                if (r.status === "fulfilled")
+                    clips.push(r.value);
+                else
+                    errors.push({ index: i, text: items[i].text.substring(0, 40), error: r.reason.message });
+            });
+            return {
+                success: true,
+                data: {
+                    generated: clips.length,
+                    failed: errors.length,
+                    total: items.length,
+                    clips,
+                    ...(errors.length > 0 ? { errors } : {}),
+                },
+            };
+        }
+        // ── SPEECH-TO-TEXT ──────────────────────────────────────────────────
+        case "speech_to_text": {
+            const audioBase64 = args.audio_base64;
+            if (!audioBase64)
+                return { success: false, error: "audio_base64 parameter is required" };
+            try {
+                const formData = audioFormData(audioBase64);
+                formData.append("model_id", args.model_id || DEFAULT_STT_MODEL);
+                if (args.language_code)
+                    formData.append("language_code", args.language_code);
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/speech-to-text`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey },
+                    body: formData,
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `ElevenLabs STT error ${resp.status}: ${errText}` };
+                }
+                return { success: true, data: await resp.json() };
+            }
+            catch (err) {
+                return { success: false, error: `STT failed: ${err}` };
+            }
+        }
+        // ── SOUND EFFECTS ──────────────────────────────────────────────────
+        case "sound_effects": {
+            const text = args.text;
+            if (!text)
+                return { success: false, error: "text parameter is required (describe the sound)" };
+            const body = {
+                text,
+                model_id: DEFAULT_SFX_MODEL,
+                prompt_influence: args.prompt_influence ?? 0.3,
+                loop: args.loop ?? false,
+            };
+            if (args.duration_seconds)
+                body.duration_seconds = args.duration_seconds;
+            return generateAndUpload(sb, sid, apiKey, `${ELEVENLABS_BASE}/sound-generation?output_format=${outputFormat}`, body, `SFX: ${text.substring(0, 80)}`, ["AI Generated", "Sound Effect", "ElevenLabs"], ext, mime, { prompt: text, duration_seconds: args.duration_seconds || "auto", loop: body.loop });
+        }
+        // ── MUSIC PLAN ────────────────────────────────────────────────────
+        // FREE endpoint that converts a prompt into a structured composition plan
+        // with proper sections, lyrics per line, timing, and styles.
+        // The plan can then be fed to music_compose for much clearer vocals.
+        case "music_plan": {
+            const prompt = args.prompt;
+            if (!prompt)
+                return { success: false, error: "prompt parameter is required (describe the song)" };
+            const planBody = { prompt, model_id: DEFAULT_MUSIC_MODEL };
+            if (args.music_length_ms)
+                planBody.music_length_ms = args.music_length_ms;
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/music/plan`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+                    body: JSON.stringify(planBody),
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `ElevenLabs plan error ${resp.status}: ${errText}` };
+                }
+                const plan = await resp.json();
+                return {
+                    success: true,
+                    data: {
+                        composition_plan: plan,
+                        hint: "Pass this composition_plan to music_compose to generate the song. You can edit sections, lyrics, or styles before generating.",
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `Music plan failed: ${err}` };
+            }
+        }
+        // ── MUSIC COMPOSE ──────────────────────────────────────────────────
+        case "music_compose": {
+            const prompt = args.prompt;
+            const compositionPlan = args.composition_plan;
+            if (!prompt && !compositionPlan)
+                return { success: false, error: "prompt or composition_plan is required" };
+            const isInstrumental = args.force_instrumental ?? false;
+            // Use higher quality for music (192kbps vs default 128kbps)
+            const musicFormat = outputFormat === "mp3_44100_128" ? "mp3_44100_192" : outputFormat;
+            const musicFmt = formatInfo(musicFormat);
+            // If composition_plan provided, use it (from music_plan or manually built)
+            if (compositionPlan) {
+                // Clone to avoid mutating the caller's object
+                const plan = JSON.parse(JSON.stringify(compositionPlan));
+                // Inject vocal clarity styles when not instrumental
+                if (!isInstrumental) {
+                    if (!plan.positive_global_styles) {
+                        plan.positive_global_styles = ["clear vocals", "crisp pronunciation", "studio quality"];
+                    }
+                    if (!plan.negative_global_styles) {
+                        plan.negative_global_styles = ["distorted vocals", "mumbled lyrics", "lo-fi vocals"];
+                    }
+                }
+                const body = {
+                    composition_plan: plan,
+                    model_id: DEFAULT_MUSIC_MODEL,
+                    force_instrumental: isInstrumental,
+                };
+                return generateAndUpload(sb, sid, apiKey, `${ELEVENLABS_BASE}/music?output_format=${musicFormat}`, body, `Music (plan): ${JSON.stringify(plan).substring(0, 80)}`, ["AI Generated", "Music", "ElevenLabs", "Composition Plan"], musicFmt.ext, musicFmt.mime, { method: "composition_plan", instrumental: isInstrumental });
+            }
+            // Simple prompt mode
+            const body = {
+                prompt: prompt,
+                model_id: DEFAULT_MUSIC_MODEL,
+                force_instrumental: isInstrumental,
+            };
+            if (args.music_length_ms)
+                body.music_length_ms = args.music_length_ms;
+            return generateAndUpload(sb, sid, apiKey, `${ELEVENLABS_BASE}/music?output_format=${musicFormat}`, body, `Music: ${prompt.substring(0, 80)}`, ["AI Generated", "Music", "ElevenLabs"], musicFmt.ext, musicFmt.mime, { prompt, music_length_ms: args.music_length_ms || "auto", instrumental: isInstrumental });
+        }
+        // ── MUSIC COMPOSE DETAILED ─────────────────────────────────────────
+        case "music_compose_detailed": {
+            const prompt = args.prompt;
+            const compositionPlan = args.composition_plan;
+            if (!prompt && !compositionPlan)
+                return { success: false, error: "prompt or composition_plan required" };
+            const isInstrumental = args.force_instrumental ?? false;
+            // Use higher quality for music (192kbps vs default 128kbps)
+            const musicFormat = outputFormat === "mp3_44100_128" ? "mp3_44100_192" : outputFormat;
+            const musicFmt = formatInfo(musicFormat);
+            // Clone to avoid mutating the caller's object, then inject vocal clarity styles
+            let planToUse = compositionPlan;
+            if (compositionPlan && !isInstrumental) {
+                const plan = JSON.parse(JSON.stringify(compositionPlan));
+                if (!plan.positive_global_styles) {
+                    plan.positive_global_styles = ["clear vocals", "crisp pronunciation", "studio quality"];
+                }
+                if (!plan.negative_global_styles) {
+                    plan.negative_global_styles = ["distorted vocals", "mumbled lyrics", "lo-fi vocals"];
+                }
+                planToUse = plan;
+            }
+            const body = {
+                model_id: DEFAULT_MUSIC_MODEL,
+                force_instrumental: isInstrumental,
+                with_timestamps: args.with_timestamps ?? false,
+            };
+            if (prompt)
+                body.prompt = prompt;
+            if (planToUse)
+                body.composition_plan = planToUse;
+            if (args.music_length_ms)
+                body.music_length_ms = args.music_length_ms;
+            return generateAndUpload(sb, sid, apiKey, `${ELEVENLABS_BASE}/music/detailed?output_format=${musicFormat}`, body, `Music (detailed): ${(prompt || "composition plan").substring(0, 80)}`, ["AI Generated", "Music", "ElevenLabs", "Detailed"], musicFmt.ext, musicFmt.mime, { prompt: prompt || "(composition plan)", with_timestamps: body.with_timestamps });
+        }
+        // ── STEM SEPARATION ────────────────────────────────────────────────
+        case "stem_separation": {
+            const audioBase64 = args.audio_base64;
+            if (!audioBase64)
+                return { success: false, error: "audio_base64 parameter is required" };
+            const stemVariation = args.stem_variation || "six_stems_v1";
+            const formData = audioFormData(audioBase64);
+            formData.append("stem_variation_id", stemVariation);
+            return processFormData(sb, sid, apiKey, `${ELEVENLABS_BASE}/music/stem-separation?output_format=${outputFormat}`, formData, `Stem separation (${stemVariation})`, ["AI Generated", "Stem Separation", "ElevenLabs"], "zip", "application/zip", {
+                stem_variation: stemVariation,
+                stems: stemVariation === "two_stems_v1"
+                    ? ["vocals", "accompaniment"]
+                    : ["vocals", "drums", "bass", "piano", "guitar", "other"],
+            });
+        }
+        // ── VOICE CHANGER ──────────────────────────────────────────────────
+        case "voice_changer": {
+            const audioBase64 = args.audio_base64;
+            if (!audioBase64)
+                return { success: false, error: "audio_base64 parameter is required" };
+            const voiceInput = (args.voice_name || args.voice_id);
+            if (!voiceInput)
+                return { success: false, error: "voice_id or voice_name parameter is required" };
+            const voiceId = await resolveVoiceId(voiceInput, apiKey, sid);
+            const modelId = args.model_id || DEFAULT_STS_MODEL;
+            const formData = audioFormData(audioBase64, "audio");
+            formData.append("model_id", modelId);
+            formData.append("remove_background_noise", String(args.remove_background_noise ?? false));
+            if (args.voice_settings)
+                formData.append("voice_settings", JSON.stringify(args.voice_settings));
+            return processFormData(sb, sid, apiKey, `${ELEVENLABS_BASE}/speech-to-speech/${voiceId}?output_format=${outputFormat}`, formData, `Voice change to ${voiceId}`, ["AI Generated", "Voice Changer", "ElevenLabs"], ext, mime, { voice_id: voiceId, model_id: modelId });
+        }
+        // ── AUDIO ISOLATION ────────────────────────────────────────────────
+        case "audio_isolation": {
+            const audioBase64 = args.audio_base64;
+            if (!audioBase64)
+                return { success: false, error: "audio_base64 parameter is required" };
+            const formData = audioFormData(audioBase64, "audio");
+            return processFormData(sb, sid, apiKey, `${ELEVENLABS_BASE}/audio-isolation`, formData, "Audio isolation — vocals isolated", ["AI Generated", "Audio Isolation", "ElevenLabs"], ext, mime, { description: "Isolated vocals with background noise removed" });
+        }
+        // ── VOICE DESIGN ───────────────────────────────────────────────────
+        case "voice_design": {
+            const voiceDescription = args.voice_description;
+            if (!voiceDescription)
+                return { success: false, error: "voice_description parameter is required" };
+            try {
+                const body = {
+                    voice_description: voiceDescription,
+                    text: args.preview_text || "Hello, this is a preview of the designed voice.",
+                    auto_enhance_description: args.auto_enhance ?? true,
+                    model_id: DEFAULT_TTV_MODEL,
+                };
+                if (args.reference_audio_base64) {
+                    body.reference_audio = args.reference_audio_base64;
+                    if (args.reference_weight !== undefined)
+                        body.reference_weight = args.reference_weight;
+                }
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/text-to-voice/design?output_format=${outputFormat}`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `ElevenLabs Voice Design error ${resp.status}: ${errText}` };
+                }
+                const data = await resp.json();
+                const previews = [];
+                for (let i = 0; i < (data.previews || []).length; i++) {
+                    const p = data.previews[i];
+                    const b64 = p.audio_base_64 || p.audio_base64;
+                    if (!b64)
+                        continue;
+                    try {
+                        const buf = Buffer.from(b64, "base64");
+                        const upload = await uploadAudioAndRecord(sb, sid, buf, `Voice design preview ${i + 1}: ${voiceDescription.substring(0, 60)}`, "mp3", "audio/mpeg", ["AI Generated", "Voice Design", "Preview", "ElevenLabs"]);
+                        previews.push({ generated_voice_id: p.generated_voice_id, file_url: upload.file_url, media_id: upload.media_id });
+                    }
+                    catch (uploadErr) {
+                        console.error(`[voice] preview ${i} upload failed:`, uploadErr);
+                        previews.push({ generated_voice_id: p.generated_voice_id, file_url: "(upload failed)", media_id: "" });
+                    }
+                }
+                return { success: true, data: { previews, description: voiceDescription } };
+            }
+            catch (err) {
+                return { success: false, error: `Voice design failed: ${err}` };
+            }
+        }
+        // ── VOICE DESIGN CREATE ────────────────────────────────────────────
+        case "voice_design_create": {
+            const generatedVoiceId = args.generated_voice_id;
+            const voiceName = args.voice_name;
+            if (!generatedVoiceId)
+                return { success: false, error: "generated_voice_id is required (from voice_design)" };
+            if (!voiceName)
+                return { success: false, error: "voice_name is required" };
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/text-to-voice/create`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        generated_voice_id: generatedVoiceId,
+                        voice_name: voiceName,
+                        voice_description: args.voice_description || "",
+                        labels: args.labels || {},
+                    }),
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `ElevenLabs Voice Create error ${resp.status}: ${errText}` };
+                }
+                return { success: true, data: await resp.json() };
+            }
+            catch (err) {
+                return { success: false, error: `Voice create failed: ${err}` };
+            }
+        }
+        // ── CLONE VOICE ────────────────────────────────────────────────────
+        // Accepts single audio_base64 or array of audio_samples for multiple clips.
+        // file_paths support: CLI pre-processor reads files and injects audio_samples.
+        // ElevenLabs recommends 1-2 min clean audio minimum for instant cloning.
+        case "clone_voice": {
+            const voiceName = args.voice_name;
+            if (!voiceName)
+                return { success: false, error: "voice_name is required" };
+            // Accept multiple samples (array) or single audio_base64
+            const samples = [];
+            if (Array.isArray(args.audio_samples)) {
+                for (const s of args.audio_samples) {
+                    if (typeof s === "string" && s.length > 100)
+                        samples.push(s);
+                }
+            }
+            if (typeof args.audio_base64 === "string" && args.audio_base64.length > 100) {
+                samples.push(args.audio_base64);
+            }
+            if (samples.length === 0) {
+                return { success: false, error: "Provide file_paths (array of local audio paths) or audio_samples (array of base64 strings). file_paths is preferred — the CLI encodes automatically." };
+            }
+            try {
+                const formData = new FormData();
+                formData.append("name", voiceName);
+                if (args.voice_description)
+                    formData.append("description", args.voice_description);
+                // Enable noise removal only if samples are long enough (>= 5s ≈ 80KB base64 at 128kbps)
+                // ElevenLabs requires >= 4.6s per sample when noise removal is on
+                const shortestSample = Math.min(...samples.map(s => s.length));
+                const autoNoiseRemoval = shortestSample >= 80_000; // ~5 seconds at 128kbps
+                const removeNoise = args.remove_background_noise ?? autoNoiseRemoval;
+                formData.append("remove_background_noise", String(removeNoise));
+                // Attach each sample as a separate file
+                for (let i = 0; i < samples.length; i++) {
+                    const buffer = Buffer.from(samples[i], "base64");
+                    const blob = new Blob([buffer], { type: "audio/mpeg" });
+                    formData.append("files", blob, `sample-${i}.mp3`);
+                }
+                // Optional: labels for the voice
+                if (args.labels) {
+                    formData.append("labels", JSON.stringify(args.labels));
+                }
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/add`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey },
+                    body: formData,
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `Voice clone error ${resp.status}: ${errText}` };
+                }
+                const data = await resp.json();
+                // Calculate total audio size for quality feedback
+                const totalBytes = samples.reduce((sum, s) => sum + Math.ceil(s.length * 3 / 4), 0);
+                const totalSecs = Math.round(totalBytes / 16000); // rough estimate at 128kbps
+                const qualityNote = totalSecs < 30
+                    ? `Tip: only ~${totalSecs}s of audio provided. For better accuracy, use 1-2 minutes of clean, continuous speech.`
+                    : `Good: ~${totalSecs}s of audio used.`;
+                return {
+                    success: true,
+                    data: {
+                        voice_id: data.voice_id,
+                        name: voiceName,
+                        samples_used: samples.length,
+                        noise_removed: removeNoise,
+                        quality_note: qualityNote,
+                        message: `Voice "${voiceName}" cloned successfully. Use this voice_id with speak action.`,
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `Voice clone failed: ${err}` };
+            }
+        }
+        // ══════════════════════════════════════════════════════════════════
+        // PROFESSIONAL VOICE CLONING (PVC) — near-perfect accuracy
+        // Multi-step: create → upload → separate speakers → verify → train
+        // Requires Creator plan or above on ElevenLabs.
+        // ══════════════════════════════════════════════════════════════════
+        // ── PVC CREATE ─────────────────────────────────────────────────────
+        case "pvc_create": {
+            const voiceName = args.voice_name;
+            const language = args.language || "en";
+            if (!voiceName)
+                return { success: false, error: "voice_name is required" };
+            try {
+                const body = { name: voiceName, language };
+                if (args.voice_description)
+                    body.description = args.voice_description;
+                if (args.labels)
+                    body.labels = args.labels;
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/pvc`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `PVC create error ${resp.status}: ${errText}` };
+                }
+                const data = await resp.json();
+                return {
+                    success: true,
+                    data: {
+                        voice_id: data.voice_id,
+                        name: voiceName,
+                        language,
+                        next_step: "Upload audio samples with pvc_upload action, then use pvc_train to start training.",
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `PVC create failed: ${err}` };
+            }
+        }
+        // ── PVC UPLOAD ─────────────────────────────────────────────────────
+        // Upload audio samples to a PVC voice. Accepts audio_samples or file_paths.
+        case "pvc_upload": {
+            const voiceId = args.voice_id;
+            if (!voiceId)
+                return { success: false, error: "voice_id is required (from pvc_create)" };
+            const samples = [];
+            if (Array.isArray(args.audio_samples)) {
+                for (const s of args.audio_samples) {
+                    if (typeof s === "string" && s.length > 100)
+                        samples.push(s);
+                }
+            }
+            if (typeof args.audio_base64 === "string" && args.audio_base64.length > 100) {
+                samples.push(args.audio_base64);
+            }
+            if (samples.length === 0) {
+                return { success: false, error: "Provide file_paths or audio_samples. The more audio, the better the clone (30+ min recommended)." };
+            }
+            try {
+                const formData = new FormData();
+                for (let i = 0; i < samples.length; i++) {
+                    const buffer = Buffer.from(samples[i], "base64");
+                    const blob = new Blob([buffer], { type: "audio/mpeg" });
+                    formData.append("files", blob, `sample-${i}.mp3`);
+                }
+                const removeNoise = args.remove_background_noise ?? false;
+                formData.append("remove_background_noise", String(removeNoise));
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/pvc/${voiceId}/samples`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey },
+                    body: formData,
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `PVC upload error ${resp.status}: ${errText}` };
+                }
+                const sampleData = await resp.json();
+                const sampleIds = Array.isArray(sampleData) ? sampleData.map((s) => s.sample_id) : [];
+                return {
+                    success: true,
+                    data: {
+                        voice_id: voiceId,
+                        samples_uploaded: samples.length,
+                        sample_ids: sampleIds,
+                        noise_removed: removeNoise,
+                        next_step: "If audio has multiple speakers, use pvc_separate_speakers. Otherwise use pvc_verify to start verification, then pvc_train.",
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `PVC upload failed: ${err}` };
+            }
+        }
+        // ── PVC SEPARATE SPEAKERS ──────────────────────────────────────────
+        case "pvc_separate_speakers": {
+            const voiceId = args.voice_id;
+            const sampleId = args.sample_id;
+            if (!voiceId || !sampleId)
+                return { success: false, error: "voice_id and sample_id are required" };
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/pvc/${voiceId}/samples/${sampleId}/separate-speakers`, { method: "POST", headers: { "xi-api-key": apiKey } });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `Speaker separation error ${resp.status}: ${errText}` };
+                }
+                return {
+                    success: true,
+                    data: {
+                        voice_id: voiceId,
+                        sample_id: sampleId,
+                        status: "started",
+                        next_step: "Use pvc_status to check separation progress. When done, use pvc_select_speaker to pick the right speaker.",
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `Speaker separation failed: ${err}` };
+            }
+        }
+        // ── PVC STATUS ─────────────────────────────────────────────────────
+        // Check speaker separation status or training status
+        case "pvc_status": {
+            const voiceId = args.voice_id;
+            if (!voiceId)
+                return { success: false, error: "voice_id is required" };
+            try {
+                // If sample_id provided, check speaker separation status
+                if (args.sample_id) {
+                    const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/pvc/${voiceId}/samples/${args.sample_id}/speakers`, { headers: { "xi-api-key": apiKey } });
+                    if (!resp.ok) {
+                        const errText = await resp.text();
+                        return { success: false, error: `PVC status error ${resp.status}: ${errText}` };
+                    }
+                    const data = await resp.json();
+                    return { success: true, data };
+                }
+                // Otherwise check overall voice / training status
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/${voiceId}`, {
+                    headers: { "xi-api-key": apiKey },
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `PVC status error ${resp.status}: ${errText}` };
+                }
+                const voice = await resp.json();
+                return {
+                    success: true,
+                    data: {
+                        voice_id: voice.voice_id,
+                        name: voice.name,
+                        category: voice.category,
+                        fine_tuning: voice.fine_tuning,
+                        samples: voice.samples?.length || 0,
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `PVC status failed: ${err}` };
+            }
+        }
+        // ── PVC SELECT SPEAKER ─────────────────────────────────────────────
+        case "pvc_select_speaker": {
+            const voiceId = args.voice_id;
+            const sampleId = args.sample_id;
+            const speakerIds = args.speaker_ids;
+            if (!voiceId || !sampleId)
+                return { success: false, error: "voice_id and sample_id required" };
+            if (!Array.isArray(speakerIds) || speakerIds.length === 0) {
+                return { success: false, error: "speaker_ids array required (from pvc_status separation results)" };
+            }
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/pvc/${voiceId}/samples/${sampleId}`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+                    body: JSON.stringify({ selected_speaker_ids: speakerIds }),
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `Select speaker error ${resp.status}: ${errText}` };
+                }
+                return {
+                    success: true,
+                    data: {
+                        voice_id: voiceId,
+                        sample_id: sampleId,
+                        selected_speakers: speakerIds,
+                        next_step: "Use pvc_verify for verification, then pvc_train to start training.",
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `Select speaker failed: ${err}` };
+            }
+        }
+        // ── PVC VERIFY ─────────────────────────────────────────────────────
+        // Request manual verification (easiest path — ElevenLabs staff reviews)
+        case "pvc_verify": {
+            const voiceId = args.voice_id;
+            if (!voiceId)
+                return { success: false, error: "voice_id is required" };
+            try {
+                const formData = new FormData();
+                // Optional: extra context about why you have permission to use this voice
+                const extraText = args.extra_text || "Voice owner has given consent for cloning.";
+                formData.append("extra_text", extraText);
+                // If verification audio provided (voice owner speaking), attach it
+                if (typeof args.audio_base64 === "string" && args.audio_base64.length > 100) {
+                    const buffer = Buffer.from(args.audio_base64, "base64");
+                    const blob = new Blob([buffer], { type: "audio/mpeg" });
+                    formData.append("files", blob, "verification.mp3");
+                }
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/pvc/${voiceId}/verification`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey },
+                    body: formData,
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `PVC verify error ${resp.status}: ${errText}` };
+                }
+                return {
+                    success: true,
+                    data: {
+                        voice_id: voiceId,
+                        status: "verification_requested",
+                        message: "Manual verification submitted. ElevenLabs will review. Once approved, use pvc_train to start training.",
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `PVC verify failed: ${err}` };
+            }
+        }
+        // ── PVC TRAIN ──────────────────────────────────────────────────────
+        case "pvc_train": {
+            const voiceId = args.voice_id;
+            if (!voiceId)
+                return { success: false, error: "voice_id is required" };
+            // eleven_multilingual_v2 is most stable for PVC training
+            const modelId = args.model_id || "eleven_multilingual_v2";
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/pvc/${voiceId}/train`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey, "Content-Type": "application/json" },
+                    body: JSON.stringify({ model_id: modelId }),
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `PVC train error ${resp.status}: ${errText}` };
+                }
+                return {
+                    success: true,
+                    data: {
+                        voice_id: voiceId,
+                        model_id: modelId,
+                        status: "training_started",
+                        message: "Training started. Use pvc_status to monitor progress. Training typically takes 5-30 minutes depending on audio length.",
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `PVC train failed: ${err}` };
+            }
+        }
+        // ── FORCED ALIGNMENT ───────────────────────────────────────────────
+        case "forced_alignment": {
+            const audioBase64 = args.audio_base64;
+            const transcript = args.transcript;
+            if (!audioBase64)
+                return { success: false, error: "audio_base64 parameter is required" };
+            if (!transcript)
+                return { success: false, error: "transcript parameter is required" };
+            try {
+                const formData = audioFormData(audioBase64);
+                formData.append("text", transcript);
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/forced-alignment`, {
+                    method: "POST",
+                    headers: { "xi-api-key": apiKey },
+                    body: formData,
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `ElevenLabs Forced Alignment error ${resp.status}: ${errText}` };
+                }
+                return { success: true, data: await resp.json() };
+            }
+            catch (err) {
+                return { success: false, error: `Forced alignment failed: ${err}` };
+            }
+        }
+        // ── SEARCH VOICES ──────────────────────────────────────────────────
+        case "search_voices": {
+            const query = args.query || "";
+            try {
+                // Use shared voices endpoint for broader library search
+                const params = new URLSearchParams({ page_size: "25" });
+                if (query)
+                    params.set("search", query);
+                if (args.gender)
+                    params.set("gender", args.gender);
+                if (args.language)
+                    params.set("language", args.language);
+                if (args.accent)
+                    params.set("accent", args.accent);
+                if (args.age)
+                    params.set("age", args.age);
+                if (args.use_case)
+                    params.set("use_case", args.use_case);
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/shared-voices?${params}`, {
+                    headers: { "xi-api-key": apiKey },
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `Voice search error ${resp.status}: ${errText}` };
+                }
+                const data = await resp.json();
+                const voices = (data.voices || []).map((v) => ({
+                    voice_id: v.voice_id,
+                    name: v.name,
+                    category: v.category,
+                    gender: v.gender,
+                    accent: v.accent,
+                    age: v.age,
+                    language: v.language,
+                    use_case: v.use_case,
+                    description: v.description,
+                    preview_url: v.preview_url,
+                }));
+                return { success: true, data: { count: voices.length, voices } };
+            }
+            catch (err) {
+                return { success: false, error: `Voice search failed: ${err}` };
+            }
+        }
+        // ── LIST VOICES ────────────────────────────────────────────────────
+        case "list_voices": {
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices`, {
+                    headers: { "xi-api-key": apiKey },
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `List Voices error ${resp.status}: ${errText}` };
+                }
+                const data = await resp.json();
+                const voices = (data.voices || []).map((v) => ({
+                    voice_id: v.voice_id, name: v.name, category: v.category,
+                    labels: v.labels, description: v.description, preview_url: v.preview_url,
+                }));
+                return { success: true, data: { count: voices.length, voices } };
+            }
+            catch (err) {
+                return { success: false, error: `List voices failed: ${err}` };
+            }
+        }
+        // ── GET VOICE ──────────────────────────────────────────────────────
+        case "get_voice": {
+            const voiceInput = (args.voice_name || args.voice_id);
+            if (!voiceInput)
+                return { success: false, error: "voice_id or voice_name is required" };
+            try {
+                const voiceId = await resolveVoiceId(voiceInput, apiKey, sid);
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/voices/${voiceId}`, {
+                    headers: { "xi-api-key": apiKey },
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `Get Voice error ${resp.status}: ${errText}` };
+                }
+                const voice = await resp.json();
+                return {
+                    success: true,
+                    data: {
+                        voice_id: voice.voice_id, name: voice.name, category: voice.category,
+                        labels: voice.labels, description: voice.description, preview_url: voice.preview_url,
+                        settings: voice.settings, fine_tuning: voice.fine_tuning,
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `Get voice failed: ${err}` };
+            }
+        }
+        // ── USAGE / QUOTA ──────────────────────────────────────────────────
+        case "usage": {
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/user/subscription`, {
+                    headers: { "xi-api-key": apiKey },
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `Usage error ${resp.status}: ${errText}` };
+                }
+                const sub = await resp.json();
+                return {
+                    success: true,
+                    data: {
+                        tier: sub.tier,
+                        character_count: sub.character_count,
+                        character_limit: sub.character_limit,
+                        characters_remaining: (sub.character_limit || 0) - (sub.character_count || 0),
+                        usage_percent: sub.character_limit
+                            ? Math.round(((sub.character_count || 0) / sub.character_limit) * 100)
+                            : 0,
+                        next_reset: sub.next_character_count_reset_unix
+                            ? new Date(sub.next_character_count_reset_unix * 1000).toISOString()
+                            : null,
+                        max_voice_add_edits: sub.max_voice_add_edits,
+                        voice_add_edit_counter: sub.voice_add_edit_counter,
+                        professional_voice_limit: sub.professional_voice_limit,
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: `Usage check failed: ${err}` };
+            }
+        }
+        // ── LIST MODELS ────────────────────────────────────────────────────
+        case "list_models": {
+            try {
+                const resp = await fetchWithRetry(`${ELEVENLABS_BASE}/models`, {
+                    headers: { "xi-api-key": apiKey },
+                });
+                if (!resp.ok) {
+                    const errText = await resp.text();
+                    return { success: false, error: `List Models error ${resp.status}: ${errText}` };
+                }
+                const models = await resp.json();
+                return {
+                    success: true,
+                    data: (models || []).map((m) => ({
+                        model_id: m.model_id, name: m.name, description: m.description,
+                        can_be_finetuned: m.can_be_finetuned,
+                        can_do_text_to_speech: m.can_do_text_to_speech,
+                        can_do_voice_conversion: m.can_do_voice_conversion,
+                        languages: m.languages,
+                    })),
+                };
+            }
+            catch (err) {
+                return { success: false, error: `List models failed: ${err}` };
+            }
+        }
+        default:
+            return {
+                success: false,
+                error: `Unknown voice action: ${action}. Valid: speak, batch, sound_effects, music_plan, music_compose, music_compose_detailed, speech_to_text, stem_separation, voice_changer, audio_isolation, voice_design, voice_design_create, clone_voice, forced_alignment, search_voices, list_voices, get_voice, usage, list_models, pvc_create, pvc_upload, pvc_separate_speakers, pvc_status, pvc_select_speaker, pvc_verify, pvc_train`,
+            };
+    }
+}