@crievo/omni 0.1.7 → 0.1.9

package/tools/runner.mjs

@@ -67,7 +67,7 @@ async function login() {
     fail(`${e.message}; rode de novo node tools/runner.mjs login`),
   );
   writeEnv({ [KEY]: paired.key });
-  console.log(`Mac pareado como "${paired.name}". A chave ficou no .env (${KEY}).`);
+  console.log(`Máquina pareada como "${paired.name}". A chave ficou no .env (${KEY}).`);
   console.log(
     service().loaded
       ? "O studio (serviço) conecta sozinho em até 30 s."
@@ -119,25 +119,25 @@ async function status() {
   if (!out.url) return console.log("Studio hospedado: não configurado (cloud.studio_url no config).");
   console.log(`Studio hospedado: ${out.url}`);
   console.log(serviceLine());
-  if (!out.hasKey) return console.log("Este Mac: não pareado (node tools/runner.mjs login).");
+  if (!out.hasKey) return console.log("Esta máquina: não pareada (node tools/runner.mjs login).");
   if (!out.paired)
     return console.log(
-      `Este Mac: a chave não vale mais (${out.error}). O studio aberto pareia de novo sozinho (aprove na página que ele abre), ou: node tools/runner.mjs login`,
+      `Esta máquina: a chave não vale mais (${out.error}). O studio aberto pareia de novo sozinho (aprove na página que ele abre), ou: node tools/runner.mjs login`,
     );
   console.log(
-    `Este Mac: pareado como "${out.name}", ${out.online ? "conectado agora" : "desconectado (o studio está aberto? veja o serviço acima)"}.`,
+    `Esta máquina: pareada como "${out.name}", ${out.online ? "conectada agora" : "desconectada (o studio está aberto? veja o serviço acima)"}.`,
   );
 }
 
 async function logout() {
   const url = studioUrl();
   const token = env(KEY);
-  if (!token) return console.log("Este Mac já não está pareado.");
+  if (!token) return console.log("Esta máquina já não está pareada.");
   const r = await call(url, "/runner/logout", { token });
   writeEnv({ [KEY]: "" });
   if (!r.ok && r.status !== 401)
     fail(`a chave saiu do .env, mas o studio não confirmou (${r.status}: ${r.body?.error ?? "?"})`);
-  console.log("Mac desconectado do studio hospedado. Para voltar: node tools/runner.mjs login");
+  console.log("Máquina desconectada do studio hospedado. Para voltar: node tools/runner.mjs login");
 }
 
 const [cmd, sub] = args;

package/tools/setup.mjs

@@ -49,6 +49,13 @@ const readJson = file => {
     return null;
   }
 };
+/* the sound kits: the folders under kit/sfx/ (a kit is a folder with its kit.json) */
+const listKits = dir =>
+  existsSync(dir)
+    ? readdirSync(dir)
+        .filter(k => statSync(join(dir, k)).isDirectory())
+        .sort()
+    : [];
 const toPath = p => resolve(ROOT, String(p).replace(/^~(?=\/|$)/, homedir()));
 const cfg = () => readJson(CONFIG);
 
@@ -279,8 +286,12 @@ function check() {
 
   /* 6. sound: the kit may start empty, but then Claude searches Epidemic through Chrome */
   {
-    const kit = readJson(join(ROOT, "kit", "sfx", "kit.json")) ?? {};
-    const n = Object.keys(kit).length;
+    /* every kit folder under kit/sfx/ (motion-ui, epidemic-sounds…) counts its effects */
+    const kits = listKits(join(ROOT, "kit", "sfx"));
+    const n = kits.reduce(
+      (sum, k) => sum + Object.keys(readJson(join(ROOT, "kit", "sfx", k, "kit.json")) ?? {}).length,
+      0,
+    );
     /* any Claude account that already connected the extension */
     const ext = accountsOf(readJson(CONFIG) ?? {})
       .filter(a => a.provider === "claude")
@@ -393,11 +404,13 @@ function prepare() {
     mkdirSync(library, { recursive: true });
     done.push(`criei a biblioteca de estilos visuais em ${library}`);
   }
-  const kit = join(ROOT, "kit", "sfx");
-  if (!existsSync(join(kit, "kit.json"))) {
+  /* the kits: motion-ui is the default; epidemic-sounds holds the effects captured from Epidemic */
+  for (const name of ["motion-ui", "epidemic-sounds"]) {
+    const kit = join(ROOT, "kit", "sfx", name);
+    if (existsSync(join(kit, "kit.json"))) continue;
     mkdirSync(kit, { recursive: true });
     writeFileSync(join(kit, "kit.json"), "{}\n");
-    done.push("criei o kit de efeitos vazio (kit/sfx/kit.json)");
+    done.push(`criei o kit de efeitos vazio (kit/sfx/${name}/kit.json)`);
   }
   mkdirSync(join(ROOT, "videos"), { recursive: true });
 

package/tools/sound.mjs

@@ -4,29 +4,26 @@
 
      node tools/sound.mjs capture [n]                     prints the capture code (Chrome)
      node tools/sound.mjs download videos/<slug> <url> [name] [--search <term>]
-     node tools/sound.mjs download kit <url> <name> --role <role> [--search <term>]
-     node tools/sound.mjs kit [role|text]                 lists the global kit by role
-     node tools/sound.mjs kit adopt videos/<slug> <name> --role <role> [--as <name-in-kit>]
-                                                          moves an effect captured for the video into the kit
+     node tools/sound.mjs download kit <url> <name> --role <role> [--kit <kit>] [--search <term>]
+     node tools/sound.mjs kit [role|text] [--kit <kit>]   lists the kits (or one) by role
+     node tools/sound.mjs kit adopt videos/<slug> <name> --role <role> [--kit <kit>] [--as <name-in-kit>]
+                                                          moves an effect downloaded for the video into a kit
+     node tools/sound.mjs kit add <kit> <file> --role <role> [--as <name>] [--title <text>]
+                                                          a file the user chose becomes an MP3 of that kit
      node tools/sound.mjs import videos/<slug> <file> [name] [--title <text>]
                                                           a track the user sent (the editor's upload), as an MP3 of the video's sfx/
      node tools/sound.mjs effects videos/<slug> [text]    lists the effects captured for the video
      node tools/sound.mjs videos/<slug>                   prepares the video's sound/
 
-   Every effect comes from Epidemic Sound, through one of two registries: the
-   global kit (sound.kit in the config, kit/sfx/kit.json), curated once and used
-   by every video, each effect with a role (click, pop, tick, typing, confirm,
-   whoosh, transition, riser, impact, glitch, bed, texture); and the video's
-   sfx/ (sfx/sources.json), for what the kit lacks. No other audio saved on the
-   computer gets in, except a track the user sends on purpose through the
-   editor's upload (`import`): it goes to the video's sfx/ as an MP3 with
-   source "upload", only for that video, never into the kit. With a search open in Chrome (sound.source.search in the
-   config), the `capture` code plays the previews and returns each one's URL
-   (audiocdn.epidemicsound.com/lqmp3/<id>.mp3); `download` writes the MP3 to
-   the kit or the video's sfx/ and records the origin. An effect outside both
-   registries is refused. The name is looked up in the video first, then in the
-   kit. From the kit, the effect brings its role's volume (sound.roles in the
-   config, or its own `db` in kit.json), added to the sound's `db`.
+   Kits: one folder each under kit/sfx/ (its kit.json lists the effects, with
+   role and db), curated per sound palette. The default kit (sound.default_kit in
+   the config, motion-ui) is what a sound without `kit` uses; a scene's sound names
+   another with `"kit": "<name>"` (epidemic-sounds, for the effects captured from
+   Epidemic). The video's own sfx/ (sfx/sources.json, captured or sent by the user)
+   always comes first. A sound never falls back to another kit silently: if the
+   name lives only in another kit, the error says which one to name. Any provider's
+   audio can be in a kit; from a kit, the effect brings its role's volume (sound.roles
+   in the config, or its own `db` in kit.json), added to the sound's `db`.
 
    Where sound goes in scenes.json:
      beat.sound               at the beat's instant
@@ -83,7 +80,7 @@
    queue turn (tools/job-queue.mjs).
    ============================================================================ */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, statSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join, resolve, basename, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -124,7 +121,33 @@ const ROLES = {
   texture: { db: 0, stretchable: true },
   ...CFG.sound?.roles,
 };
-const KIT = resolve(ROOT, CFG.sound?.kit ?? "kit/sfx");
+/* the kits: one folder each under KITS (its kit.json lists the effects). The default kit is what a sound
+   without `kit` uses; the video's own sfx/ always comes first (effectFile) */
+const KITS = resolve(ROOT, CFG.sound?.kit ?? "kit/sfx");
+const DEFAULT_KIT = CFG.sound?.default_kit ?? "motion-ui";
+const KIT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+const kitDirOf = kit => join(KITS, kit);
+const kitRegistry = kit => join(kitDirOf(kit), "kit.json");
+/* a sound's file: its name and kit, or the ref the studio shows, "kit/name.mp3" (the kit comes first) */
+const parseRef = (name, kit) => {
+  const i = typeof name === "string" ? name.indexOf("/") : -1;
+  return i < 0 ? { name, kit: kit ?? null } : { name: name.slice(i + 1), kit: name.slice(0, i) };
+};
+/* the kits that exist: each folder under KITS with a valid name */
+const kitNames = () =>
+  existsSync(KITS)
+    ? readdirSync(KITS)
+        .filter(k => KIT_NAME.test(k) && statSync(join(KITS, k)).isDirectory())
+        .sort()
+    : [];
+/* a kit named by a command: valid, and existing unless `create` (kit add makes one) */
+function checkKit(kit, { create = false } = {}) {
+  const k = kit ?? DEFAULT_KIT;
+  if (!KIT_NAME.test(k)) throw new Error(`kit “${k}”: use letras minúsculas, números e hífen (ex.: motion-ui)`);
+  if (!create && !existsSync(kitDirOf(k)))
+    throw new Error(`o kit “${k}” não existe (kits: ${kitNames().join(", ") || "nenhum"})`);
+  return k;
+}
 const CDN = /^https:\/\/audiocdn\.epidemicsound\.com\/lqmp3\/([0-9A-Za-z]+)\.mp3$/;
 const NAME = /^[a-z0-9][a-z0-9._-]*\.mp3$/i;
 const MUSIC_S = 30; /* above this it is a soundtrack, not an effect (the bed may) */
@@ -327,47 +350,60 @@ export function measureEffect(file) {
 }
 
 /* --- where an effect comes from --------------------------------------------------
-   Only from Epidemic, through two registries: the global kit (sound.kit in the
-   config, kit/sfx/ with kit.json), curated once and used by every video, and
-   the video's sfx/ (sfx/sources.json), for sound the kit lacks. The name is
-   looked up in the video first, then in the kit. */
+   Two places: the video's sfx/ (sfx/sources.json: captured for the video, or sent by the user), which
+   always wins, and one kit (kit/sfx/<kit>/kit.json): the sound's `kit`, else the default kit. A sound
+   never falls back to another kit silently: if the name is only in another kit, the error says so. */
 const effectsDir = dir => join(resolve(dir), "sfx");
 const readJson = f => (existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {});
 const sources = dir => readJson(join(effectsDir(dir), "sources.json"));
-const kitSources = () => readJson(join(KIT, "kit.json"));
+const kitSources = kit => readJson(kitRegistry(kit));
 
-export function effectFile(dir, name) {
+/* the file of an effect for a video, and the kit entry (with its kit's name) when it comes from a kit */
+export function effectFile(dir, name, kit) {
+  ({ name, kit } = parseRef(name, kit));
   if (typeof name !== "string" || !NAME.test(name) || basename(name) !== name)
-    return { error: `efeito “${name}”: o nome é um MP3 do sfx/ do vídeo ou do kit (ex.: clique-seco.mp3)` };
-  const [from, source, where] = sources(dir)[name]
-    ? [effectsDir(dir), sources(dir)[name], "sfx/sources.json"]
-    : kitSources()[name]
-      ? [KIT, kitSources()[name], "o kit"]
-      : [];
-  if (!from)
+    return { error: `efeito “${name}”: o nome é um MP3 do sfx/ do vídeo ou de um kit (ex.: clique-seco.mp3)` };
+  const k = kit ?? DEFAULT_KIT;
+  if (!KIT_NAME.test(k)) return { error: `kit “${k}”: use letras minúsculas, números e hífen` };
+  let file,
+    entry = null,
+    where;
+  if (sources(dir)[name]) {
+    file = join(effectsDir(dir), name);
+    where = "sfx/sources.json";
+  } else if (kitSources(k)[name]) {
+    file = join(kitDirOf(k), name);
+    entry = { ...kitSources(k)[name], kitName: k };
+    where = `o kit ${k}`;
+  } else {
+    const elsewhere = kitNames().find(o => o !== k && kitSources(o)[name]);
     return {
-      error: `efeito “${name}” não está no kit nem foi capturado da Epidemic para este vídeo (falta em sfx/sources.json): use um do kit (sound.mjs kit) ou capture com sound.mjs capture e download`,
+      error: elsewhere
+        ? `efeito “${name}” não está no kit ${k}, mas está no kit ${elsewhere}: ponha "kit": "${elsewhere}" no som`
+        : `efeito “${name}” não está no kit ${k} nem no sfx/ deste vídeo (falta em sfx/sources.json): use um do kit (sound.mjs kit --kit ${k}) ou baixe com sound.mjs download`,
     };
-  const file = join(from, name);
+  }
   if (!existsSync(file))
     return { error: `efeito “${name}” está em ${where}, mas o arquivo sumiu: rode sound.mjs download de novo` };
-  return { file, kit: from === KIT ? source : null };
+  return { file, kit: entry };
 }
 
 /* `download` destination: a video dir or the kit ("kit", with --role) */
-function destination(videoDir, role) {
+/* `download` destination: a video dir, or a kit ("kit", with --role and --kit) */
+function destination(videoDir, role, kit) {
   if (videoDir === "kit") {
     if (!ROLES[role]) throw new Error(`no kit, --role é obrigatório: ${Object.keys(ROLES).join(", ")}`);
-    return { dir: KIT, registry: join(KIT, "kit.json"), extra: { role } };
+    const k = checkKit(kit);
+    return { dir: kitDirOf(k), registry: kitRegistry(k), extra: { role }, kit: k };
   }
   const dir = resolve(videoDir ?? "");
   if (!existsSync(join(dir, "scenes.json")))
     throw new Error(`${dir} não é a pasta de um vídeo (falta scenes.json) nem "kit"`);
-  return { dir: effectsDir(dir), registry: join(effectsDir(dir), "sources.json"), extra: {} };
+  return { dir: effectsDir(dir), registry: join(effectsDir(dir), "sources.json"), extra: {}, kit: null };
 }
 
-async function download(videoDir, url, name, search, role) {
-  const { dir, registry, extra } = destination(videoDir, role);
+async function download(videoDir, url, name, search, role, kit) {
+  const { dir, registry, extra, kit: k } = destination(videoDir, role, kit);
   const m = CDN.exec(url ?? "");
   if (!m)
     throw new Error(
@@ -376,14 +412,15 @@ async function download(videoDir, url, name, search, role) {
   name = `${(name ?? m[1]).replace(/\.mp3$/i, "")}.mp3`;
   if (!NAME.test(name)) throw new Error(`nome “${name}”: letras, números, ponto, hífen e sublinhado`);
   const list = readJson(registry);
-  const whereAlready = dir === KIT ? "no kit" : "no vídeo";
+  const whereAlready = k ? `no kit ${k}` : "no vídeo";
   const other = Object.entries(list).find(([n, f]) => f.id === m[1] && n !== name);
   if (other) throw new Error(`esse efeito já está ${whereAlready} como “${other[0]}”`);
   if (list[name] && list[name].id !== m[1])
     throw new Error(
       `já existe “${name}” ${whereAlready} com outro efeito (${list[name].title || list[name].id}): escolha outro nome`,
     );
-  if (dir !== KIT && kitSources()[name]) console.log(`   ⚠ o kit já tem um “${name}”; o do vídeo passa na frente dele`);
+  const clash = !k && kitNames().find(o => kitSources(o)[name]);
+  if (clash) console.log(`   ⚠ o kit ${clash} já tem um “${name}”; o do vídeo passa na frente dele`);
 
   const r = await fetch(url);
   if (!r.ok) throw new Error(`a Epidemic respondeu ${r.status} para ${url}`);
@@ -402,7 +439,7 @@ async function download(videoDir, url, name, search, role) {
     ...extra,
   };
   writeFileSync(registry, JSON.stringify(list, null, 1) + "\n");
-  console.log(`${name} ← ${med.title || m[1]}${extra.role ? ` · kit, papel ${extra.role}` : ""}`);
+  console.log(`${name} ← ${med.title || m[1]}${k ? ` · kit ${k}, papel ${extra.role}` : ""}`);
   console.log(
     med.music
       ? `   ⚠ ${med.duration.toFixed(0)}s: é trilha, não efeito; só serve de música de fundo`
@@ -426,7 +463,9 @@ function importUpload(videoDir, file, wanted, title) {
       .replace(/[^a-z0-9._-]+/g, "-")
       .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "") || "musica";
   const taken = n =>
-    !!sources(dir)[`${n}.mp3`] || !!kitSources()[`${n}.mp3`] || existsSync(join(effectsDir(dir), `${n}.mp3`));
+    !!sources(dir)[`${n}.mp3`] ||
+    kitNames().some(o => !!kitSources(o)[`${n}.mp3`]) ||
+    existsSync(join(effectsDir(dir), `${n}.mp3`));
   let n = slug;
   for (let i = 2; taken(n); i++) n = `${slug}-${i}`;
   const name = `${n}.mp3`;
@@ -491,55 +530,109 @@ function effects(videoDir, filter) {
   }
 }
 
-/* moves an effect already captured from Epidemic for a video into the kit, with its origin */
-function adopt(videoDir, name, role, as) {
+/* moves an effect already downloaded for a video into the kit, with its origin (never a user's upload) */
+/* moves an effect already downloaded for a video into a kit, with its origin (never a user's upload) */
+function adopt(videoDir, name, role, as, kit) {
   const dir = resolve(videoDir ?? "");
   if (!ROLES[role]) throw new Error(`--role é obrigatório: ${Object.keys(ROLES).join(", ")}`);
+  const k = checkKit(kit);
   const source = sources(dir)[name];
   if (!source) throw new Error(`“${name}” não está em ${join(effectsDir(dir), "sources.json")}`);
   if (source.source === "upload")
-    throw new Error(`“${name}” foi enviado pelo usuário para este vídeo: o kit só recebe áudio da Epidemic`);
+    throw new Error(`“${name}” foi enviado pelo usuário para este vídeo: esse áudio não vai para o kit`);
   const newName = `${(as ?? name).replace(/\.mp3$/i, "")}.mp3`;
   if (!NAME.test(newName)) throw new Error(`nome “${newName}”: letras, números, ponto, hífen e sublinhado`);
-  const list = kitSources();
+  const list = kitSources(k);
   const other = Object.entries(list).find(([, e]) => e.id === source.id);
-  if (other) throw new Error(`esse efeito já está no kit como “${other[0]}”`);
+  if (other) throw new Error(`esse efeito já está no kit ${k} como “${other[0]}”`);
   if (list[newName])
-    throw new Error(`o kit já tem “${newName}” (${list[newName].title || list[newName].id}): use --as <outro-nome>`);
-  mkdirSync(KIT, { recursive: true });
-  writeFileSync(join(KIT, newName), readFileSync(join(effectsDir(dir), name)));
+    throw new Error(
+      `o kit ${k} já tem “${newName}” (${list[newName].title || list[newName].id}): use --as <outro-nome>`,
+    );
+  writeFileSync(join(kitDirOf(k), newName), readFileSync(join(effectsDir(dir), name)));
   list[newName] = { ...source, role, adopted_from: basename(dir) };
-  writeFileSync(join(KIT, "kit.json"), JSON.stringify(list, null, 1) + "\n");
-  console.log(`${newName} ← ${source.title || source.id} · kit, papel ${role}`);
+  writeFileSync(kitRegistry(k), JSON.stringify(list, null, 1) + "\n");
+  console.log(`${newName} ← ${source.title || source.id} · kit ${k}, papel ${role}`);
+}
+
+/* a file the user chose (their own pack, a library they point at) becomes an MP3 of a kit, with its role.
+   Nothing is picked on its own: the path comes from the command. A new kit is made here. */
+function addToKit(kit, file, role, as, title) {
+  const k = checkKit(kit, { create: true });
+  if (!ROLES[role]) throw new Error(`--role é obrigatório: ${Object.keys(ROLES).join(", ")}`);
+  if (!file || !existsSync(file)) throw new Error(`o arquivo “${file}” não existe`);
+  const base = (as || basename(file)).replace(/\.[A-Za-z0-9]{1,5}$/, "");
+  const slug =
+    base
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .normalize("NFD")
+      .replace(/[\u0300-\u036f]/g, "")
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, "-")
+      .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "") || "efeito";
+  const list = kitSources(k);
+  let n = slug;
+  for (let i = 2; list[`${n}.mp3`] || existsSync(join(kitDirOf(k), `${n}.mp3`)); i++) n = `${slug}-${i}`;
+  const name = `${n}.mp3`;
+  mkdirSync(kitDirOf(k), { recursive: true });
+  const out = join(kitDirOf(k), name);
+  const isMp3 = /\.mp3$/i.test(file);
+  run("ffmpeg", [
+    "-y",
+    "-v",
+    "error",
+    "-i",
+    file,
+    "-vn",
+    "-map_metadata",
+    "-1",
+    ...(isMp3 ? ["-c:a", "copy"] : ["-c:a", "libmp3lame", "-q:a", "2"]),
+    out,
+  ]);
+  cache.delete(out);
+  list[name] = {
+    title: title || basename(file).replace(/\.[A-Za-z0-9]{1,5}$/, ""),
+    role,
+    added_at: new Date().toISOString().slice(0, 10),
+  };
+  writeFileSync(kitRegistry(k), JSON.stringify(list, null, 1) + "\n");
+  console.log(`${name} ← ${list[name].title} · kit ${k}, papel ${role}`);
+  console.log(`   ${describe(measureEffect(out))}`);
 }
 
 /* the kit grouped by role; `filter` is a role or a piece of the name/title */
-function kit(filter) {
-  const list = Object.entries(kitSources());
-  if (!list.length) {
-    console.log(`o kit está vazio (${KIT}): baixe com sound.mjs download kit <url> <nome> --role <papel>`);
-    return;
-  }
+/* the kits grouped by role; `filter` is a role or a piece of the name/title; `only` names one kit */
+function kit(filter, only) {
+  const names = only ? [checkKit(only)] : kitNames();
   const f = filter?.toLowerCase();
-  for (const role of Object.keys(ROLES)) {
-    const ofRole = list.filter(
-      ([n, e]) => e.role === role && (!f || f === role || `${n} ${e.title}`.toLowerCase().includes(f)),
-    );
-    if (!ofRole.length) continue;
-    const p = ROLES[role];
-    console.log(`${role} (db ${p.db}${p.stretchable ? ", estica" : ""})`);
-    for (const [name, e] of ofRole) {
-      const file = join(KIT, name);
-      if (!existsSync(file)) {
-        console.log(`   ${name}  ⚠ arquivo sumiu`);
-        continue;
-      }
-      const m = measureEffect(file);
-      console.log(
-        `   ${name.padEnd(28)} ${m.music ? `${m.duration.toFixed(0)}s · trilha` : describe(m)}${e.db != null ? ` · db próprio ${e.db}` : ""}`,
+  let any = false;
+  for (const k of names) {
+    const list = Object.entries(kitSources(k));
+    if (!list.length) continue;
+    any = true;
+    console.log(`== kit ${k}${k === DEFAULT_KIT ? " (padrão)" : ""} ==`);
+    for (const role of Object.keys(ROLES)) {
+      const ofRole = list.filter(
+        ([n, e]) => e.role === role && (!f || f === role || `${n} ${e.title}`.toLowerCase().includes(f)),
       );
+      if (!ofRole.length) continue;
+      const p = ROLES[role];
+      console.log(`${role} (db ${p.db}${p.stretchable ? ", estica" : ""})`);
+      for (const [name, e] of ofRole) {
+        const file = join(kitDirOf(k), name);
+        if (!existsSync(file)) {
+          console.log(`   ${name}  ⚠ arquivo sumiu`);
+          continue;
+        }
+        const m = measureEffect(file);
+        console.log(
+          `   ${name.padEnd(28)} ${m.music ? `${m.duration.toFixed(0)}s · trilha` : describe(m)}${e.db != null ? ` · db próprio ${e.db}` : ""}`,
+        );
+      }
     }
   }
+  if (!any)
+    console.log(`os kits estão vazios (${KITS}): adicione com sound.mjs kit add <kit> <arquivo> --role <papel>`);
 }
 
 function capture(n) {
@@ -740,13 +833,15 @@ function pair(v, name, max, nullAtEnd = false) {
 }
 
 export function sanitizeSound(dir, s) {
-  const o = typeof s === "string" ? { name: s } : s;
-  if (!o || typeof o !== "object") throw new Error("som inválido");
-  const { file, error } = effectFile(dir, o.name);
+  const given = typeof s === "string" ? { name: s } : s;
+  if (!given || typeof given !== "object") throw new Error("som inválido");
+  const o = { ...given, ...parseRef(given.name, given.kit) };
+  const { file, error, kit } = effectFile(dir, o.name, o.kit);
   if (error) throw new Error(error);
   const m = measureEffect(file);
   if (m.music) throw new Error(`“${o.name}” tem ${m.duration.toFixed(0)}s: é trilha, só serve de música de fundo`);
   const v = { name: o.name };
+  if (kit) v.kit = kit.kitName;
   if (o.anchor === "start") v.anchor = "start";
   else if (o.anchor != null && o.anchor !== "peak") throw new Error(`âncora: ${o.anchor} (use peak ou start)`);
   for (const k of ["offset", "db", "dur", "speed", "pitch"]) {
@@ -768,10 +863,12 @@ export function sanitizeSound(dir, s) {
 
 export function sanitizeBed(dir, b, total) {
   if (b == null) return null;
-  const o = typeof b === "string" ? { name: b } : b;
-  const { error } = effectFile(dir, o?.name);
+  const given = typeof b === "string" ? { name: b } : b;
+  const o = { ...given, ...parseRef(given.name, given.kit) };
+  const { error, kit } = effectFile(dir, o.name, o.kit);
   if (error) throw new Error(`música de fundo: ${error}`);
   const v = { name: o.name };
+  if (kit) v.kit = kit.kitName;
   if (o.db != null && +o.db !== 0) v.db = number(o.db, [-40, 20], "música de fundo db");
   if (o.from != null && +o.from > 0) v.from = number(o.from, [0, total], "música de fundo from");
   if (o.to != null) v.to = number(o.to, [0, total], "música de fundo to");
@@ -839,13 +936,15 @@ export function sanitizeSpeed(s) {
 
 /* what the studio offers: the kit by role and what was captured for the video, measured */
 export function soundCatalog(dir) {
-  const item = (from, name, e, origin) => {
+  const item = (from, name, e, origin, kit = null) => {
     const file = join(from, name);
     if (!existsSync(file)) return null;
     const m = measureEffect(file);
     return {
-      name,
+      /* a kit's effect is named by its ref, "kit/name.mp3": the studio shows and sends that one */
+      name: kit ? `${kit}/${name}` : name,
       origin,
+      kit,
       role: e.role ?? null,
       title: e.title ?? "",
       music: m.music,
@@ -856,19 +955,21 @@ export function soundCatalog(dir) {
     };
   };
   return {
-    kit: Object.entries(kitSources())
-      .map(([n, e]) => item(KIT, n, e, "kit"))
+    kits: kitNames().map(k => ({ name: k, default: k === DEFAULT_KIT, count: Object.keys(kitSources(k)).length })),
+    kit: kitNames()
+      .flatMap(k => Object.entries(kitSources(k)).map(([n, e]) => item(kitDirOf(k), n, e, "kit", k)))
       .filter(Boolean),
     video: Object.entries(sources(dir))
       .map(([n, e]) => item(effectsDir(dir), n, e, "video"))
       .filter(Boolean),
     roles: ROLES,
+    defaultKit: DEFAULT_KIT,
     level_db: S.level_db,
     ducking: S.ducking,
     bed: S.bed,
   };
 }
-export const kitDir = KIT;
+export { KITS, DEFAULT_KIT, kitDirOf, kitNames };
 
 /* --- the bed's clock -----------------------------------------------------------------
    The bed is isolated: the editor's area cuts and the speed (`cuts` and `speed` at the root of
@@ -914,7 +1015,7 @@ export function planSound(dir, video, { outDir, scenes = null, withBed = true, c
   for (const p of requests(video)) {
     if (scenes && !scenes.has(p.scene)) continue;
     const { s, id } = p;
-    const { file, error, kit } = effectFile(dir, s.name);
+    const { file, error, kit } = effectFile(dir, s.name, s.kit);
     if (error) throw new Error(`${id}: ${error}`);
     const m = measureEffect(file);
     if (m.music)
@@ -1023,7 +1124,7 @@ export function planSound(dir, video, { outDir, scenes = null, withBed = true, c
       layer: e.layer,
       scene: e.scene,
       element: e.element,
-      name: e.name,
+      name: e.kit ? `${e.kit.kitName}/${e.name}` : e.name,
       file: wav,
       wav: relative(dir, wav),
       start: +e.start.toFixed(3),
@@ -1041,6 +1142,7 @@ export function planSound(dir, video, { outDir, scenes = null, withBed = true, c
       cut_start: +e.cut.toFixed(3),
       ...(e.gave_way ? { gave_way: e.gave_way } : {}),
       origin: e.kit ? "kit" : "video",
+      kit: e.kit?.kitName ?? null,
       role: e.kit?.role ?? null,
       kit_db: e.kitDb,
     });
@@ -1120,7 +1222,7 @@ function giveWay(a, b) {
 function makeBed(dir, video, { outDir, voice, ducking, warnings, clock }) {
   const b = typeof video.bed === "string" ? { name: video.bed } : video.bed;
   const total = video.total_duration;
-  const { file, error } = effectFile(dir, b.name);
+  const { file, error } = effectFile(dir, b.name, b.kit);
   if (error) throw new Error(`música de fundo: ${error}`);
   const start = clock.at(Math.max(0, num(b.from, 0))),
     end = clock.at(Math.min(total, num(b.to, total)));
@@ -1358,13 +1460,15 @@ if (isMainModule(import.meta.url)) {
     const option = n => (i => (i < 0 ? undefined : rest.splice(i, 2)[1]))(rest.indexOf(`--${n}`));
     const search = option("search"),
       role = option("role"),
-      title = option("title");
+      title = option("title"),
+      kitOpt = option("kit");
     if (cmd === "capture") capture(+(rest[0] ?? 8));
-    else if (cmd === "download") await download(rest[0], rest[1], rest[2], search, role);
+    else if (cmd === "download") await download(rest[0], rest[1], rest[2], search, role, kitOpt);
     else if (cmd === "import") importUpload(rest[0], rest[1], rest[2], title);
     else if (cmd === "effects") effects(rest[0], rest[1]);
-    else if (cmd === "kit" && rest[0] === "adopt") adopt(rest[1], rest[2], role, option("as") ?? rest[3]);
-    else if (cmd === "kit") kit(rest[0]);
+    else if (cmd === "kit" && rest[0] === "adopt") adopt(rest[1], rest[2], role, option("as") ?? rest[3], kitOpt);
+    else if (cmd === "kit" && rest[0] === "add") addToKit(rest[1], rest[2], role, option("as") ?? rest[3], title);
+    else if (cmd === "kit") kit(rest[0], kitOpt);
     else if (cmd && existsSync(join(resolve(cmd), "scenes.json"))) {
       await turn("sound", cmd);
       prepareSound(cmd);