@crievo/omni 0.0.0-stage → 0.1.1

package/studio/api/services/clone.ts

@@ -0,0 +1,722 @@
+/* Cloning the voice from the UI: the user records the phrases (or uploads an audio file) and the
+   studio creates the clone on Fish Audio and Cartesia through the API, in one go, and
+   saves the voice profile with both IDs.
+
+   - Fish: POST /model with all samples in `voices` and each one's transcript
+     in `texts` (when we have the text read). train_mode=fast: the voice comes out ready.
+   - Cartesia: POST /voices/clone accepts ONE clip of up to 16 MB. The samples become
+     a single wav, up to ~60 s (Sonic 3.6 uses up to that). A Cartesia clone
+     has one language; the mixed context goes as Portuguese.
+
+   Samples stay in .clones/<id>/ (outside git) to redo the clone later
+   without recording everything again: editing the voice creates or recreates the clone on a single provider
+   (`recreateClone`), when it failed, was never made there, or the user wants to redo it.
+   None of this goes through the queue: it's network and a short ffmpeg. */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ROOT, CONFIG, readJson, run } from "./root";
+import { deleteOldVoice, providerKey, saveProfile, profileNameExists, getProfile } from "./settings";
+import { findCloneContext } from "./clone-phrases";
+
+type Resp =
+  | { ok: true; output: string; id?: string; warnings?: string[]; failed?: string[] }
+  | { ok: false; error: string };
+
+const FFMPEG = Bun.which("ffmpeg") ?? "/opt/homebrew/bin/ffmpeg";
+const FFPROBE = Bun.which("ffprobe") ?? "/opt/homebrew/bin/ffprobe";
+
+const MIN_TOTAL_S = 30; // the minimum the UI asks for
+const MAX_TOTAL_S = 180; // 3 min: beyond that the gain is small and the upload is heavy
+const MIN_SAMPLE_S = 1; // a click with no speech is dropped
+const MAX_SAMPLES = 20; // Fish's `voices` limit
+const CARTESIA_TARGET_S = 60; // Sonic 3.6 uses up to 60 s of the clip
+const CARTESIA_MAX_BYTES = 16 * 1024 ** 2;
+const TIMEOUT_MS = 120_000;
+
+type SampleInput = { text?: unknown; mime?: unknown; data?: unknown };
+type Sample = { file: string; text: string | null; duration: number };
+
+const EXT: Record<string, string> = {
+  "audio/webm": "webm",
+  "video/webm": "webm",
+  "audio/ogg": "ogg",
+  "audio/mp4": "m4a",
+  "audio/x-m4a": "m4a",
+  "audio/mpeg": "mp3",
+  "audio/wav": "wav",
+  "audio/x-wav": "wav",
+  "audio/flac": "flac",
+};
+const extOf = (mime: unknown) => EXT[String(mime).split(";")[0].trim().toLowerCase()] ?? "bin";
+
+async function durationOf(file: string): Promise<number> {
+  const r = await run([FFPROBE, "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file]);
+  const n = parseFloat(r.stdout.trim());
+  return Number.isFinite(n) ? n : 0;
+}
+
+/* any input becomes mono 44.1 kHz wav: the same format for both providers */
+async function normalizeAudio(raw: string, dest: string): Promise<boolean> {
+  const r = await run([
+    FFMPEG,
+    "-y",
+    "-v",
+    "error",
+    "-i",
+    raw,
+    "-vn",
+    "-ac",
+    "1",
+    "-ar",
+    "44100",
+    "-c:a",
+    "pcm_s16le",
+    dest,
+  ]);
+  return r.code === 0;
+}
+
+function httpError(name: string, status: number, text: string) {
+  const body = text.replace(/\s+/g, " ").slice(0, 200);
+  let code = "",
+    detail = "";
+  try {
+    const j = JSON.parse(text);
+    /* Cartesia: { error_code }; ElevenLabs: { detail: { status, message } } */
+    code = String(j?.error_code ?? j?.detail?.status ?? "");
+    detail = typeof j?.detail?.message === "string" ? j.detail.message : "";
+  } catch {
+    /* non-JSON body */
+  }
+  /* Cartesia only clones through the API on a paid plan; on free, only in the playground */
+  if (code === "plan_upgrade_required") {
+    return `${name}: o plano free não deixa clonar pela API (${status}). Assine um plano em play.cartesia.ai/subscription e crie a voz de novo em Editar voz → ${name} → Configurar, ou clone no playground da ${name} e cole ali o Voice ID.`;
+  }
+  /* ElevenLabs: instant clone needs a paid plan (Starter or above), and the key needs Voices: Write */
+  if (code === "can_not_use_instant_voice_cloning")
+    return `${name}: o plano não deixa clonar voz (${status}). Assine o Starter ou acima em elevenlabs.io/subscription, ou cole o Voice ID de uma voz que já existe.`;
+  if (code === "voice_limit_reached")
+    return `${name}: a conta chegou ao limite de vozes (${status}). Apague uma voz em elevenlabs.io → Voices e tente de novo.`;
+  if (code === "missing_permissions")
+    return `${name}: a API key não tem permissão para criar voz (${status}). Gere uma chave com Voices: Write em elevenlabs.io → Developers → API Keys.`;
+  if (detail) return `${name} respondeu ${status}: ${detail}`;
+  if (status === 401 || status === 403)
+    return `${name}: a chave foi recusada (${status}). Confira a API key em Configurações → Voz.`;
+  if (status === 402) return `${name}: sem saldo ou plano que permita clonar (${status}). ${body}`;
+  if (status === 429) return `${name}: limite de uso atingido (${status}). Tente de novo em alguns minutos.`;
+  return `${name} respondeu ${status}: ${body}`;
+}
+
+/* ElevenLabs: POST /v1/voices/add (Instant Voice Cloning) with the samples in `files`; the voice
+   comes out ready. Up to 25 files; the clone learns best from 1 to 2 min of clean speech. */
+async function cloneOnElevenLabs(key: string, name: string, samples: Sample[]): Promise<string> {
+  const form = new FormData();
+  form.set("name", name);
+  form.set("remove_background_noise", "false");
+  for (const a of samples.slice(0, MAX_SAMPLES)) {
+    form.append("files", new File([readFileSync(a.file)], a.file.split("/").pop()!, { type: "audio/wav" }));
+  }
+  const resp = await fetch("https://api.elevenlabs.io/v1/voices/add", {
+    method: "POST",
+    body: form,
+    headers: { "xi-api-key": key },
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(httpError("ElevenLabs", resp.status, text));
+  const id = JSON.parse(text)?.voice_id;
+  if (typeof id !== "string" || !/^[A-Za-z0-9]{20}$/.test(id))
+    throw new Error(`ElevenLabs criou a voz, mas a resposta veio sem voice_id: ${text.slice(0, 160)}`);
+  return id;
+}
+
+async function cloneOnFish(key: string, name: string, samples: Sample[]): Promise<string> {
+  const form = new FormData();
+  form.set("type", "tts");
+  form.set("title", name);
+  form.set("train_mode", "fast");
+  form.set("visibility", "private");
+  form.set("enhance_audio_quality", "true");
+  const withText = samples.every(a => a.text);
+  for (const a of samples.slice(0, MAX_SAMPLES)) {
+    form.append("voices", new File([readFileSync(a.file)], a.file.split("/").pop()!, { type: "audio/wav" }));
+    if (withText) form.append("texts", a.text!);
+  }
+  const resp = await fetch("https://api.fish.audio/model", {
+    method: "POST",
+    body: form,
+    headers: { Authorization: `Bearer ${key}` },
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(httpError("Fish Audio", resp.status, text));
+  const id = JSON.parse(text)?._id;
+  if (typeof id !== "string" || !/^[0-9a-f]{32}$/i.test(id))
+    throw new Error(`Fish Audio criou o modelo, mas a resposta veio sem _id: ${text.slice(0, 160)}`);
+  return id;
+}
+
+/* --- does the plan allow cloning? ----------------------------------------------------------------
+   Cartesia only clones through the API on a paid plan. For the UI to warn before the click, an empty POST
+   /voices/clone: on free it returns 402 plan_upgrade_required before looking at the audio; on
+   paid it returns 400 (missing clip). Nothing is created. Cached for 1 min, and each real
+   clone updates the cache with what Cartesia answered. */
+type Plan = { ok: true } | { ok: false; error: string };
+const PLAN_TTL_MS = 60_000;
+const cartesiaPlan = new Map<string, { at: number; plan: Plan }>();
+const notePlan = (key: string, plan: Plan) => cartesiaPlan.set(key, { at: Date.now(), plan });
+
+export async function getClonePlan(): Promise<{ cartesia: Plan | null }> {
+  const key = providerKey("cartesia");
+  if (!key) return { cartesia: null };
+  const cached = cartesiaPlan.get(key);
+  if (cached && Date.now() - cached.at < PLAN_TTL_MS) return { cartesia: cached.plan };
+  try {
+    const resp = await fetch("https://api.cartesia.ai/voices/clone", {
+      method: "POST",
+      body: new FormData(),
+      signal: AbortSignal.timeout(15_000),
+      headers: { Authorization: `Bearer ${key}`, "Cartesia-Version": CONFIG.voice.cartesia.api_version },
+    });
+    const text = await resp.text();
+    /* only the plan block and a refused key say something; the "missing clip" 400 is the paid one */
+    const plan: Plan =
+      resp.status === 402 || resp.status === 401 || resp.status === 403
+        ? { ok: false, error: httpError("Cartesia", resp.status, text) }
+        : { ok: true };
+    notePlan(key, plan);
+    return { cartesia: plan };
+  } catch {
+    return { cartesia: null }; // offline: the UI warns nothing and the click shows the error
+  }
+}
+
+async function cloneOnCartesia(
+  key: string,
+  name: string,
+  language: string,
+  samples: Sample[],
+  dir: string,
+): Promise<string> {
+  /* whole samples, in order, up to the 60 s target */
+  const used: Sample[] = [];
+  let sum = 0;
+  for (const a of samples) {
+    if (used.length && sum + a.duration > CARTESIA_TARGET_S) break;
+    used.push(a);
+    sum += a.duration;
+  }
+  const list = join(dir, "cartesia.txt");
+  writeFileSync(list, used.map(a => `file '${a.file.replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+  const clip = join(dir, "cartesia.wav");
+  const r = await run([
+    FFMPEG,
+    "-y",
+    "-v",
+    "error",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    list,
+    "-c:a",
+    "pcm_s16le",
+    clip,
+  ]);
+  if (r.code !== 0) throw new Error(`Cartesia: não consegui juntar as amostras (${r.stderr.trim().slice(0, 160)})`);
+  const bytes = readFileSync(clip);
+  if (bytes.length > CARTESIA_MAX_BYTES)
+    throw new Error("Cartesia: o áudio passou de 16 MB; grave menos frases ou frases mais curtas");
+
+  const form = new FormData();
+  form.set("name", name);
+  form.set("language", language);
+  form.set("clip", new File([bytes], "sample.wav", { type: "audio/wav" }));
+  const resp = await fetch("https://api.cartesia.ai/voices/clone", {
+    method: "POST",
+    body: form,
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+    headers: { Authorization: `Bearer ${key}`, "Cartesia-Version": CONFIG.voice.cartesia.api_version },
+  });
+  const text = await resp.text();
+  if (resp.status === 402 || resp.status === 401 || resp.status === 403) {
+    const error = httpError("Cartesia", resp.status, text);
+    notePlan(key, { ok: false, error });
+    throw new Error(error);
+  }
+  if (!resp.ok) throw new Error(httpError("Cartesia", resp.status, text));
+  notePlan(key, { ok: true });
+  const id = JSON.parse(text)?.id;
+  if (typeof id !== "string" || !/^[0-9a-f-]{36}$/i.test(id))
+    throw new Error(`Cartesia criou a voz, mas a resposta veio sem id: ${text.slice(0, 160)}`);
+  return id;
+}
+
+/* The voice the user recorded or imported to clone: the samples of the profile's most recent
+   clone, joined in .clones/<clone>/original.wav (made once). A voice given only by
+   Voice ID has no recording: `ok: false`. */
+export const CLONES_DIR = join(ROOT, ".clones");
+type CloneInfo = {
+  name?: string;
+  context?: string;
+  profile?: string;
+  created_at?: string;
+  ids?: Record<string, string>;
+  samples?: { file: string; duration_s?: number; text?: string | null }[];
+};
+
+/* the profile's most recent clone that still has samples on disk */
+function latestCloneOf(profile: string): { name: string; dir: string; info: CloneInfo; samples: Sample[] } | null {
+  if (!existsSync(CLONES_DIR)) return null;
+  const clones = readdirSync(CLONES_DIR)
+    .map(name => ({
+      name,
+      dir: join(CLONES_DIR, name),
+      info: readJson<CloneInfo>(join(CLONES_DIR, name, "clone.json")),
+    }))
+    .filter((c): c is { name: string; dir: string; info: CloneInfo } => c.info?.profile === profile)
+    .sort((a, b) => String(b.info.created_at).localeCompare(String(a.info.created_at)));
+  for (const c of clones) {
+    const samples = (c.info.samples ?? [])
+      .map(a => ({ file: join(c.dir, a.file), text: a.text ?? null, duration: a.duration_s ?? 0 }))
+      .filter(a => existsSync(a.file));
+    if (samples.length) return { ...c, samples };
+  }
+  return null;
+}
+
+/* for the edit screen: the voice's stored recording, whole (the samples joined), to
+   listen and create the clone on another provider */
+export async function profileRecording(
+  profile: string,
+): Promise<{ ok: true; seconds: number; url: string } | { ok: false }> {
+  const c = latestCloneOf(profile);
+  const o = c ? await originalRecording(profile) : { ok: false as const };
+  if (!c || !o.ok) return { ok: false };
+  return { ok: true, seconds: +c.samples.reduce((s, a) => s + a.duration, 0).toFixed(1), url: o.url };
+}
+
+export async function originalRecording(profile: string): Promise<{ ok: true; url: string } | { ok: false }> {
+  const clone = latestCloneOf(profile);
+  if (!clone) return { ok: false };
+  const dir = clone.dir;
+  const url = `/api/voice-original/${clone.name}`;
+  if (existsSync(join(dir, "original.wav"))) return { ok: true, url };
+  const files = clone.samples.map(a => a.file);
+  if (!files.length) return { ok: false };
+  const list = join(dir, "original.txt");
+  writeFileSync(list, files.map(a => `file '${a.replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+  const r = await run([
+    FFMPEG,
+    "-y",
+    "-v",
+    "error",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    list,
+    "-c:a",
+    "pcm_s16le",
+    join(dir, "original.wav"),
+  ]);
+  rmSync(list, { force: true });
+  return r.code === 0 ? { ok: true, url } : { ok: false };
+}
+
+export type CloneRequest = {
+  name?: unknown;
+  avatar?: unknown;
+  order?: unknown;
+  context?: unknown;
+  providers?: unknown;
+  samples?: unknown;
+  consent?: unknown;
+};
+
+export async function cloneVoice(p: CloneRequest): Promise<Resp> {
+  const name = typeof p.name === "string" ? p.name.trim() : "";
+  if (name.length < 3 || name.length > 20) return { ok: false, error: "o nome da voz tem de 3 a 20 caracteres" };
+  if (p.consent !== true)
+    return { ok: false, error: "confirme que a voz é sua ou que você tem permissão de quem fala" };
+  if (profileNameExists(name)) return { ok: false, error: `já existe um perfil chamado “${name}”` };
+
+  const ctx = findCloneContext(p.context);
+  if (!ctx) return { ok: false, error: "contexto de idioma desconhecido" };
+  const chosen = (Array.isArray(p.providers) ? p.providers : []).filter(
+    (x): x is "fish" | "cartesia" => x === "fish" || x === "cartesia",
+  );
+  if (!chosen.length) return { ok: false, error: "escolha ao menos um provider (Fish Audio ou Cartesia)" };
+  const keys = Object.fromEntries(chosen.map(q => [q, providerKey(q)])) as Record<"fish" | "cartesia", string | null>;
+  const withoutKey = chosen.filter(q => !keys[q]);
+  if (withoutKey.length)
+    return {
+      ok: false,
+      error: `sem API key da ${withoutKey.map(q => (q === "fish" ? "Fish Audio" : "Cartesia")).join(" e da ")}: grave em Configurações → Voz`,
+    };
+
+  const inputs = (Array.isArray(p.samples) ? p.samples : []) as SampleInput[];
+  if (!inputs.length) return { ok: false, error: "nenhuma gravação recebida" };
+  if (inputs.length > MAX_SAMPLES) return { ok: false, error: `no máximo ${MAX_SAMPLES} gravações por clone` };
+
+  const dir = newCloneDir();
+  const warnings: string[] = [];
+  let keep = false; // with no clone created, the samples don't stay behind
+
+  try {
+    const prepared = await prepareSamples(inputs, dir, warnings);
+    if (!prepared.ok) return prepared;
+    const { samples, total } = prepared;
+
+    const ids: { fish?: string; cartesia?: string } = {};
+    const tasks = chosen.map(async q => {
+      try {
+        ids[q] = await cloneOn(q, keys[q]!, name, ctx.language, samples, dir);
+      } catch (err: any) {
+        warnings.push(errorMessage(q, err));
+      }
+    });
+    await Promise.all(tasks);
+    if (!ids.fish && !ids.cartesia)
+      return { ok: false, error: warnings.join(" · ") || "nenhum provider criou o clone" };
+    keep = true;
+
+    const profile = saveProfile({
+      name,
+      avatar: p.avatar,
+      order: p.order,
+      fish: ids.fish ?? "",
+      cartesia: ids.cartesia ?? "",
+    });
+    if (!profile.ok)
+      return {
+        ok: false,
+        error: `o clone foi criado (${JSON.stringify(ids)}) mas o perfil não gravou: ${profile.error}`,
+      };
+
+    writeFileSync(
+      join(dir, "clone.json"),
+      JSON.stringify(
+        {
+          name,
+          context: ctx.id,
+          created_at: new Date().toISOString(),
+          profile: profile.id,
+          ids,
+          samples: samples.map(a => ({
+            file: a.file.split("/").pop(),
+            duration_s: +a.duration.toFixed(2),
+            text: a.text,
+          })),
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+
+    const done = (["fish", "cartesia"] as const).filter(q => ids[q]).map(q => PROVIDER_NAME[q]);
+    const failed = chosen.filter(q => !ids[q]);
+    return {
+      ok: true,
+      id: profile.id,
+      warnings,
+      failed,
+      output: `perfil “${name}” criado com a voz clonada na ${done.join(" e na ")} (${total.toFixed(0)} s de fala)${failed.length ? `. Falhou na ${failed.map(q => PROVIDER_NAME[q]).join(" e na ")}: crie de novo em Editar voz → Configurar` : ""}`,
+    };
+  } finally {
+    rmSync(join(dir, "cartesia.txt"), { force: true });
+    if (!keep) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/* --- create or recreate the clone of an existing voice, on a single provider ---------------------
+   From the edit screen (Fish, Cartesia or ElevenLabs): the clone failed on that provider, was never made there, or the user wants to
+   redo it. Without `samples`, it uses the profile's stored recording in .clones/; with them (the voice
+   has no recording, only a Voice ID), it saves a new clone for the profile. The new Voice ID goes into the
+   profile right away; the old voice stays on the provider's account. */
+export type RecreateRequest = {
+  profile?: unknown;
+  provider?: unknown;
+  samples?: unknown;
+  context?: unknown;
+  consent?: unknown;
+};
+
+export async function recreateClone(p: RecreateRequest): Promise<Resp & { voice_id?: string }> {
+  const profile = getProfile(p.profile);
+  if (!profile) return { ok: false, error: "voz não encontrada" };
+  const q = p.provider;
+  if (q !== "fish" && q !== "cartesia" && q !== "elevenlabs")
+    return { ok: false, error: "só dá para clonar na Fish Audio, na Cartesia ou na ElevenLabs" };
+  const key = providerKey(q);
+  if (!key) return { ok: false, error: `sem API key da ${PROVIDER_NAME[q]}: grave a chave aqui mesmo, acima` };
+
+  const inputs = (Array.isArray(p.samples) ? p.samples : []) as SampleInput[];
+  const warnings: string[] = [];
+  let dir: string,
+    samples: Sample[],
+    ctxId: string,
+    isNew = false,
+    keep = false;
+  if (inputs.length) {
+    if (p.consent !== true)
+      return { ok: false, error: "confirme que a voz é sua ou que você tem permissão de quem fala" };
+    if (inputs.length > MAX_SAMPLES) return { ok: false, error: `no máximo ${MAX_SAMPLES} gravações por clone` };
+    const ctx = findCloneContext(p.context ?? "mixed");
+    if (!ctx) return { ok: false, error: "contexto de idioma desconhecido" };
+    ctxId = ctx.id;
+    dir = newCloneDir();
+    isNew = true;
+    const prepared = await prepareSamples(inputs, dir, warnings);
+    if (!prepared.ok) {
+      rmSync(dir, { recursive: true, force: true });
+      return prepared;
+    }
+    samples = prepared.samples;
+  } else {
+    const c = latestCloneOf(profile.id);
+    if (!c)
+      return {
+        ok: false,
+        error: "esta voz não tem gravação guardada no app: envie um áudio de 30 s a 3 min para criar o clone",
+      };
+    dir = c.dir;
+    samples = c.samples;
+    ctxId = c.info.context ?? "mixed";
+  }
+  const ctx = findCloneContext(ctxId) ?? findCloneContext("mixed")!;
+
+  try {
+    let voiceId: string;
+    try {
+      voiceId = await cloneOn(q, key, profile.name, ctx.language, samples, dir);
+    } catch (err: any) {
+      return { ok: false, error: errorMessage(q, err) };
+    }
+    const order = profile.order.includes(q) ? profile.order : [...profile.order, q];
+    const saved = saveProfile({ ...profile, order, [q]: voiceId });
+    if (!saved.ok)
+      return {
+        ok: false,
+        error: `o clone foi criado na ${PROVIDER_NAME[q]} (${voiceId}) mas a voz não gravou: ${saved.error}`,
+      };
+    keep = true;
+
+    const infoFile = join(dir, "clone.json");
+    const info: CloneInfo = isNew
+      ? {
+          name: profile.name,
+          context: ctx.id,
+          created_at: new Date().toISOString(),
+          profile: profile.id,
+          ids: {},
+          samples: samples.map(a => ({
+            file: a.file.split("/").pop()!,
+            duration_s: +a.duration.toFixed(2),
+            text: a.text,
+          })),
+        }
+      : (readJson<CloneInfo>(infoFile) ?? {});
+    info.ids = { ...(info.ids ?? {}), [q]: voiceId };
+    writeFileSync(infoFile, JSON.stringify(info, null, 2) + "\n");
+    return { ok: true, voice_id: voiceId, warnings, output: `voz “${profile.name}” clonada na ${PROVIDER_NAME[q]}` };
+  } finally {
+    rmSync(join(dir, "cartesia.txt"), { force: true });
+    if (isNew && !keep) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/* --- redo the whole voice, on all its providers --------------------------------------
+   From the edit screen's "Refazer voz": the user sees the same panel as create, with the voice's stored
+   recording attached. They can add more recordings to it (`keep`) or delete it and record everything again.
+   Underneath it's recreate: the new clone comes from all samples (stored and new) on each
+   provider the voice already has, and only after it exists is the old voice deleted on the account. So
+   an error midway never leaves the voice without a clone: the provider that failed keeps the old voice.
+   Name, avatar and order follow the voice (name and avatar can be changed in the same step). */
+export type RedoRequest = {
+  profile?: unknown;
+  name?: unknown;
+  avatar?: unknown;
+  samples?: unknown;
+  keep?: unknown;
+  context?: unknown;
+  consent?: unknown;
+};
+
+export async function redoVoice(p: RedoRequest): Promise<Resp> {
+  const profile = getProfile(p.profile);
+  if (!profile) return { ok: false, error: "voz não encontrada" };
+  const name = typeof p.name === "string" && p.name.trim() ? p.name.trim() : profile.name;
+  if (name.length < 3 || name.length > Math.max(20, profile.name.length))
+    return { ok: false, error: "o nome da voz tem de 3 a 20 caracteres" };
+
+  const chosen = (["fish", "cartesia", "elevenlabs"] as const).filter(q => profile[q]);
+  if (!chosen.length)
+    return { ok: false, error: "esta voz não tem clone na Fish Audio, na Cartesia nem na ElevenLabs para refazer" };
+  const withoutKey = chosen.filter(q => !providerKey(q));
+  if (withoutKey.length)
+    return {
+      ok: false,
+      error: `sem API key da ${withoutKey.map(q => PROVIDER_NAME[q]).join(" e da ")}: grave em Configurações → Voz`,
+    };
+
+  const inputs = (Array.isArray(p.samples) ? p.samples : []) as SampleInput[];
+  if (inputs.length && p.consent !== true)
+    return { ok: false, error: "confirme que a voz é sua ou que você tem permissão de quem fala" };
+  const stored = latestCloneOf(profile.id);
+  const previous = p.keep === false ? null : stored;
+  if (!inputs.length && !previous)
+    return { ok: false, error: "nenhuma gravação: grave ou envie de 30 s a 3 min de fala" };
+
+  const ctx =
+    findCloneContext(
+      inputs.length ? (p.context ?? previous?.info.context ?? "mixed") : (previous?.info.context ?? "mixed"),
+    ) ?? findCloneContext("mixed")!;
+  const dir = newCloneDir();
+  const warnings: string[] = [];
+  let keep = false;
+
+  try {
+    /* the stored ones come to the new dir, first; the new ones go after them */
+    const previousSamples: Sample[] = (previous?.samples ?? []).map((a, i) => {
+      const file = join(dir, `sample-${String(i + 1).padStart(2, "0")}.wav`);
+      copyFileSync(a.file, file);
+      return { ...a, file };
+    });
+    const prepared = await prepareSamples(inputs, dir, warnings, previousSamples);
+    if (!prepared.ok) return prepared;
+    const { samples, total } = prepared;
+    if (samples.length > MAX_SAMPLES)
+      return {
+        ok: false,
+        error: `no máximo ${MAX_SAMPLES} gravações por clone: apague a gravação anterior e grave de novo`,
+      };
+
+    const created: Partial<Record<ClonableProvider, string>> = {};
+    await Promise.all(
+      chosen.map(async q => {
+        try {
+          created[q] = await cloneOn(q, providerKey(q)!, name, ctx.language, samples, dir);
+        } catch (err: any) {
+          warnings.push(`${errorMessage(q, err)} (a voz de antes continua na ${PROVIDER_NAME[q]})`);
+        }
+      }),
+    );
+    const done = chosen.filter(q => created[q]);
+    if (!done.length) return { ok: false, error: warnings.join(" · ") || "nenhum provedor criou o clone" };
+    keep = true;
+
+    const saved = saveProfile({ ...profile, name, avatar: p.avatar ?? profile.avatar, ...created });
+    if (!saved.ok)
+      return {
+        ok: false,
+        error: `o clone foi criado (${JSON.stringify(created)}) mas a voz não gravou: ${saved.error}`,
+      };
+
+    for (const q of done) {
+      const failure = await deleteOldVoice(profile.id, q, profile[q]!);
+      if (failure)
+        warnings.push(
+          `não deu para apagar a voz antiga na ${PROVIDER_NAME[q]} (${profile[q]}): ${failure}. Apague à mão na conta`,
+        );
+    }
+
+    writeFileSync(
+      join(dir, "clone.json"),
+      JSON.stringify(
+        {
+          name,
+          context: ctx.id,
+          created_at: new Date().toISOString(),
+          profile: profile.id,
+          ids: { ...(previous?.info.ids ?? {}), ...created },
+          samples: samples.map(a => ({
+            file: a.file.split("/").pop(),
+            duration_s: +a.duration.toFixed(2),
+            text: a.text,
+          })),
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    /* the old recording is already inside the new dir (or was discarded on purpose) */
+    if (stored) rmSync(stored.dir, { recursive: true, force: true });
+
+    const failed = chosen.filter(q => !created[q]);
+    return {
+      ok: true,
+      id: profile.id,
+      warnings,
+      failed,
+      output: `voz “${name}” refeita na ${done.map(q => PROVIDER_NAME[q]).join(" e na ")} (${total.toFixed(0)} s de fala)${failed.length ? `. Falhou na ${failed.map(q => PROVIDER_NAME[q]).join(" e na ")}: abra Editar voz → Configurar para tentar de novo` : ""}`,
+    };
+  } finally {
+    rmSync(join(dir, "cartesia.txt"), { force: true });
+    if (!keep) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const PROVIDER_NAME = { fish: "Fish Audio", cartesia: "Cartesia", elevenlabs: "ElevenLabs" } as const;
+type ClonableProvider = keyof typeof PROVIDER_NAME;
+
+const newCloneDir = () => {
+  const dir = join(CLONES_DIR, `${new Date().toISOString().slice(0, 10)}-${Math.random().toString(36).slice(2, 8)}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+const cloneOn = (q: ClonableProvider, key: string, name: string, language: string, samples: Sample[], dir: string) =>
+  q === "fish"
+    ? cloneOnFish(key, name, samples)
+    : q === "elevenlabs"
+      ? cloneOnElevenLabs(key, name, samples)
+      : cloneOnCartesia(key, name, language, samples, dir);
+
+const errorMessage = (q: ClonableProvider, err: any) =>
+  err?.name === "TimeoutError"
+    ? `${PROVIDER_NAME[q]}: não respondeu em ${TIMEOUT_MS / 1000} s`
+    : String(err?.message ?? err);
+
+/* the received recordings become normalized wavs in `dir`; checks 30 s to 3 min of speech */
+async function prepareSamples(
+  inputs: SampleInput[],
+  dir: string,
+  warnings: string[],
+  previous: Sample[] = [],
+): Promise<{ ok: true; samples: Sample[]; total: number } | { ok: false; error: string }> {
+  /* `previous` (redo) are already in `dir`, first, and count toward the total */
+  const samples: Sample[] = [...previous];
+  for (const [i, e] of inputs.entries()) {
+    if (typeof e.data !== "string" || !e.data) continue;
+    const n = previous.length + i + 1;
+    const raw = join(dir, `raw-${n}.${extOf(e.mime)}`);
+    writeFileSync(raw, Buffer.from(e.data, "base64"));
+    const file = join(dir, `sample-${String(n).padStart(2, "0")}.wav`);
+    const good = await normalizeAudio(raw, file);
+    rmSync(raw, { force: true });
+    if (!good) {
+      warnings.push(`a gravação ${i + 1} não pôde ser lida e ficou de fora`);
+      continue;
+    }
+    const d = await durationOf(file);
+    if (d < MIN_SAMPLE_S) {
+      warnings.push(`a gravação ${i + 1} ficou curta demais (${d.toFixed(1)} s) e ficou de fora`);
+      continue;
+    }
+    const text = typeof e.text === "string" && e.text.trim() ? e.text.trim() : null;
+    samples.push({ file, text, duration: d });
+  }
+  const total = samples.reduce((s, a) => s + a.duration, 0);
+  if (total < MIN_TOTAL_S)
+    return {
+      ok: false,
+      error: `só ${total.toFixed(0)} s de fala aproveitável: grave pelo menos ${MIN_TOTAL_S} s (o máximo é 3 min)`,
+    };
+  if (total > MAX_TOTAL_S + 1)
+    return { ok: false, error: `${total.toFixed(0)} s de fala: o máximo é 3 min. Tire algum áudio e tente de novo` };
+  return { ok: true, samples, total };
+}