claude-code-arcane 2.1.0 → 2.3.0

package/skills/spatial-audio/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: spatial-audio
+description: "Audio espacial: HRTF/binaural, Ambisonics, panning, curvas de atenuacion, oclusion y obstruccion, reverb por zona, y presupuesto de CPU por tecnica. Usar para: sonido 3D, audio posicional, VR audio, oclusion, decidir HRTF vs panning."
+category: "audio"
+argument-hint: "[decide | hrtf | ambisonics | occlusion | budget]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# spatial-audio — Audio Posicional
+
+Decide qué técnica de espacialización usar por fuente, y presupuesta el costo. La decisión correcta casi nunca es "la mejor técnica para todo".
+
+## Cuándo usar
+
+- Definir la estrategia de espacialización de un juego o experiencia VR
+- El audio 3D come demasiado CPU
+- Las fuentes no se localizan bien, o suenan "adentro de la cabeza"
+- Implementar oclusión y obstrucción
+- Diseñar reverb por zona
+
+## Input
+
+1. Leer audio bible y el presupuesto de performance del proyecto
+2. Determinar: ¿hay auriculares garantizados (VR) o hay que funcionar en speakers?
+3. Contar las fuentes simultáneas esperadas por categoría
+4. Preguntar al usuario: plataforma target más baja y fps objetivo
+
+---
+
+## Presupuesto — el número que decide todo
+
+| Técnica | Costo |
+|---|---|
+| Convolución HRTF (512 taps) | **~2 ms por fuente** |
+| Encode ambisónico | ~0.1 ms por fuente |
+| Decode ambisónico a binaural | ~1 ms total (una vez, no por fuente) |
+| Panning estéreo / vector-based | despreciable |
+| Atenuación por distancia + filtro | despreciable |
+
+**El audio entero dispone del 5-10% del frame time.** A 60 fps son 16.6 ms de frame, así que el audio tiene ~0.8-1.7 ms.
+
+Ese número mata la idea de HRTF universal de entrada: **50 fuentes × 2 ms = 100 ms de CPU**, seis veces el frame completo. No es "costoso": es imposible.
+
+Presupuesto realista: **3-5 fuentes con HRTF**, el resto por otras técnicas.
+
+---
+
+## Decisión por fuente
+
+| Situación | Técnica | Por qué |
+|---|---|---|
+| 3-5 fuentes críticas, con auriculares | **HRTF** | Localización precisa, incluida elevación |
+| Ambiente, campo difuso | **Ambisonics** | Costo por fuente casi nulo; un solo decode |
+| Fuentes lejanas o poco importantes | **Panning + atenuación** | Gratis, e igual son indistinguibles |
+| Música, UI | **2D, sin espacializar** | No tienen posición en el mundo |
+| Diálogo del jugador / narrador | **2D o pseudo-3D** | Tiene que ser siempre inteligible |
+| Fuentes en speakers (no auriculares) | **Panning / surround** | HRTF en speakers no funciona: asume oídos, no una sala |
+
+**HRTF asume auriculares.** En speakers el crosstalk entre canales destruye las claves binaurales y el resultado es peor que un panning honesto. Si la plataforma no garantiza auriculares, HRTF necesita detección de ruta o queda descartado.
+
+**Estrategia recomendada:** un presupuesto explícito de "slots HRTF" asignado por prioridad dinámica — la fuente más importante y más cercana se lleva el slot, y al alejarse lo devuelve. Todo lo demás, Ambisonics y panning.
+
+---
+
+## Curvas de atenuación
+
+La atenuación es lo que más aporta a la percepción de distancia, y es gratis. Componentes:
+
+| Componente | Qué comunica |
+|---|---|
+| **Volumen por distancia** | Distancia base |
+| **Filtro low-pass creciente** | El aire absorbe agudos: lejano = más opaco |
+| **Reducción de spread** | Cerca es ancho, lejos es puntual |
+| **Aumento de reverb (wet/dry)** | Lejano = más proporción de espacio |
+
+**Los cuatro juntos** venden la distancia mucho mejor que el volumen solo. Un sonido que solo baja de volumen se percibe como "más silencioso", no como "más lejos".
+
+Definir siempre `min distance` (dentro de la cual no atenúa) y `max distance` (fuera de la cual no suena), y la forma de la curva. Log es lo más natural para la mayoría de las fuentes; lineal sirve cuando querés control preciso del rango audible.
+
+## Oclusión y obstrucción
+
+Dos fenómenos distintos que se confunden seguido:
+
+| | Qué es | Efecto |
+|---|---|---|
+| **Obstrucción** | Algo bloquea el camino directo, pero el sonido reflejado llega | Baja el directo, mantiene el reverb. Se oye "alrededor" |
+| **Oclusión** | Directo y reflejado bloqueados: pared sólida | Baja los dos + low-pass fuerte |
+
+Confundirlas produce el bug clásico: un enemigo detrás de una columna se vuelve inaudible (se aplicó oclusión donde correspondía obstrucción).
+
+**Costo:** la parte cara no es el filtro, es el raycast. Con muchas fuentes hay que:
+- Limitar los raycasts por frame y repartirlos entre frames
+- Cachear el resultado y actualizar con menos frecuencia que el frame
+- Interpolar el valor de oclusión hacia el target, nunca aplicarlo de golpe (el salto se escucha)
+
+## Reverb por zona
+
+- Definir zonas con un preset de reverb cada una, y **crossfade en las transiciones** — un cambio instantáneo de reverb es muy audible
+- El envío a reverb depende de la distancia (ver curvas arriba)
+- Las fuentes 2D (música, UI) normalmente **no** van a reverb de zona
+- La cola del reverb tiene que seguir sonando al cambiar de zona, o se corta de forma antinatural
+
+## VR y consideraciones específicas
+
+- **Head tracking obligatorio:** la posición de las fuentes se actualiza con la cabeza. Latencia alta rompe la ilusión y marea
+- **Elevación importa:** es lo que HRTF aporta y el panning no puede
+- **Auriculares garantizados:** es el único contexto donde HRTF es la elección obvia
+- **Presupuesto más ajustado:** 90 fps deja ~11 ms de frame, así que el audio tiene menos margen aún
+
+---
+
+## Proceso
+
+1. **Contar fuentes** simultáneas por categoría
+2. **Presupuestar** contra el 5-10% del frame en la plataforma más baja
+3. **Asignar técnica por categoría**, con slots HRTF explícitos y prioridad dinámica
+4. **Definir curvas** de atenuación con los cuatro componentes
+5. **Definir oclusión vs obstrucción** por tipo de geometría, con presupuesto de raycasts e interpolación
+6. **Definir zonas** de reverb y sus transiciones
+7. **Escribir** — preguntar "¿Escribo la estrategia a `<path>`?" antes de usar Write
+
+---
+
+## Verdict
+
+- **READY** — cada categoría tiene técnica asignada, el presupuesto cierra en la plataforma más baja, y oclusión/obstrucción están diferenciadas
+- **CONCERNS** — la estrategia existe pero el presupuesto no se midió, o HRTF se asume sin verificar que haya auriculares
+- **BLOCKED** — falta el conteo de fuentes simultáneas o el presupuesto de performance del proyecto
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-audit` para medir CPU y voice count reales en runtime
+- `/middleware-integration` para implementar atenuaciones, oclusión y buses de reverb
+- `/procedural-audio` si las fuentes ambiente son muchas y conviene generarlas
+- `/audio-mix` para el reparto de buses y el ducking del diálogo

package/skills/spatial-audio/references/anti-patterns.md

@@ -0,0 +1,53 @@
+# Audio Espacial — Anti-patterns
+
+## HRTF en todas las fuentes
+
+50 fuentes × 2 ms = 100 ms de CPU, contra un frame de 16.6 ms a 60 fps. No es costoso: es seis veces imposible. El presupuesto real es 3-5 fuentes con HRTF y el resto por Ambisonics o panning.
+
+## HRTF en speakers
+
+HRTF asume auriculares. En speakers el crosstalk entre canales destruye las claves binaurales y suena peor que un panning honesto. Si no hay auriculares garantizados, hace falta detección de ruta o se descarta.
+
+## Volumen como única clave de distancia
+
+Un sonido que solo baja de volumen se percibe como "más silencioso", no como "más lejos". Hacen falta los cuatro componentes: volumen, low-pass creciente, spread decreciente y más reverb.
+
+## Confundir oclusión con obstrucción
+
+Aplicar oclusión total donde había obstrucción hace que un enemigo detrás de una columna sea inaudible. Obstrucción baja el directo y mantiene el reflejado; oclusión baja los dos.
+
+## Raycasts sin presupuesto
+
+La parte cara de la oclusión es el raycast, no el filtro. Con 30 fuentes haciendo raycast por frame el costo se dispara. Limitar, repartir entre frames, cachear.
+
+## Oclusión sin interpolar
+
+Aplicar el valor de golpe produce un salto muy audible cada vez que el jugador cruza el borde de una geometría. Interpolar siempre hacia el target.
+
+## Curvas sin min/max distance
+
+Dejar el default del middleware produce sonidos audibles a 200 m o que desaparecen a 3 m. Los dos valores y la forma de la curva son parte del spec.
+
+## Reverb de zona con cambio instantáneo
+
+El salto de preset se escucha como un corte. Crossfade en la transición, y dejar que la cola anterior termine.
+
+## Música y UI espacializadas
+
+No tienen posición en el mundo. Espacializarlas produce paneos raros y costo inútil.
+
+## Diálogo tratado como una fuente 3D más
+
+Si el diálogo importante se ocluye y se atenúa como cualquier SFX, el jugador pierde información. Suele necesitar un tratamiento pseudo-3D: dirección sí, oclusión no.
+
+## Presupuestar contra la plataforma más alta
+
+El modelo entra en PC y no en el target más bajo. El presupuesto se hace contra el piso, no contra el techo.
+
+## Ambisonics para fuentes puntuales importantes
+
+Ambisonics brilla en campo difuso y ambiente. Para la fuente crítica que el jugador tiene que localizar con precisión, no reemplaza a HRTF.
+
+## Ignorar el presupuesto más ajustado de VR
+
+90 fps deja ~11 ms de frame. Un plan de espacialización calculado para 60 fps no entra.

package/skills/ui-sound-design/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: ui-sound-design
+description: "Sonido de interfaz y feedback: duraciones y niveles por tipo de evento, jerarquia de feedback, coordinacion con haptics, respeto del volumen del sistema, accesibilidad. Usar para: sonidos de UI, feedback de menu, notificaciones, sonido de app."
+category: "audio"
+argument-hint: "[set | event-name | review | haptics]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# ui-sound-design — Feedback de Interfaz
+
+Diseña el sonido que confirma acciones. Es el audio que el usuario escucha más veces y el que más rápido se vuelve molesto si está mal calibrado.
+
+## Cuándo usar
+
+- Definir el set de sonidos de UI de un juego o una app
+- El feedback se siente molesto, invasivo o inconsistente
+- Falta jerarquía: todo suena igual de importante
+- Coordinar audio con haptics
+
+## Input
+
+1. Leer audio bible (paleta, frequency allocation, mix hierarchy)
+2. Listar los eventos de UI reales de la interfaz
+3. Preguntar al usuario: plataforma (desktop / consola / móvil), si hay haptics, y si el juego se juega en sesiones largas
+
+---
+
+## Especificaciones por tipo
+
+Estos rangos son el punto de partida calibrado. Salirse de ellos requiere razón.
+
+| Tipo | Duración | Carácter | Nivel |
+|---|---|---|---|
+| **Tap / hover** | 30-80 ms | Click suave, alta frecuencia | −24 dB |
+| **Confirmación** | 80-150 ms | Transiente definido, neutro | −21 dB |
+| **Éxito** | 150-300 ms | Tono ascendente, positivo | −18 dB |
+| **Error** | 200-400 ms | Descendente, menor | −18 dB |
+| **Notificación** | 300-800 ms | Distintivo, llama atención | −18 dB |
+| **Transición / navegación** | 100-250 ms | Movimiento sutil | −24 dB |
+| **Toggle** | 40-100 ms | Dos estados distinguibles | −24 dB |
+
+**El nivel es lo que más se equivoca.** Los sonidos de UI van entre **−18 y −24 dB** relativos al material de gameplay. Un click a −3 dB compite con la acción del juego y agota en minutos.
+
+Regla de proporcionalidad: **el nivel y la duración son proporcionales a la importancia del evento**. Un hover es lo más corto y lo más bajo. Un error de transacción es lo más largo y lo más alto. Si el hover y el error suenan parecido, no hay jerarquía.
+
+## Frecuencia y fatiga
+
+El feedback de UI vive en **2-6 kHz**: es donde el oído es más sensible, así que un sonido bajo se lee claro sin volumen. Es también la banda que **más rápido fatiga**.
+
+Consecuencias de diseño:
+
+- Transientes cortos, no tonos sostenidos: la energía breve informa sin cansar
+- En un juego de sesiones largas, correr el feedback hacia abajo (1-3 kHz) reduce la fatiga a costa de algo de claridad
+- Si el juego tiene mucha percusión brillante o hi-hats, el UI compite: bajar el UI no alcanza, hay que hacerle lugar en el arreglo (ver `/audio-mix`)
+
+## Jerarquía
+
+Tres niveles, y cada evento cae en uno:
+
+| Nivel | Qué entra | Puede interrumpir |
+|---|---|---|
+| **Ambiental** | Hover, navegación, toggle | Nada. Se pierde y no importa |
+| **Confirmatorio** | Tap, confirmación, éxito | Nada, pero no se debe perder |
+| **Crítico** | Error, alerta, timeout | Duckea el resto |
+
+Solo el nivel crítico duckea. Si los tres duckean, la música desaparece cada vez que el usuario navega un menú.
+
+## Haptics
+
+Cuando hay haptics, audio y vibración son **un solo evento percibido**. Reglas:
+
+- **Sincronía dura:** un desfasaje mayor a ~30 ms se percibe como dos eventos separados
+- **No duplicar la información:** si el haptic ya comunica la intensidad, el audio no necesita subir de nivel
+- **Complementariedad de banda:** el haptic cubre lo que el speaker chico no puede dar (el sub). Diseñar el audio sin depender del grave si hay haptic
+- **Respetar el ajuste del usuario:** haptics desactivado no debe dejar el evento sin feedback
+
+## Plataforma
+
+### Móvil — sesiones de audio
+
+Ignorar la sesión de audio es el bug más común de audio en móvil: la app pierde el audio en una llamada y no lo recupera nunca.
+
+| iOS `AVAudioSession` | Comportamiento |
+|---|---|
+| `.ambient` | Se mezcla con otro audio; el switch de silencio lo silencia |
+| `.playback` | Interrumpe otro audio; ignora el switch de silencio |
+| `.playAndRecord` | Para apps con voz |
+| `.soloAmbient` | Default; silencia otro audio |
+
+En Android el equivalente es AudioFocus. En los dos casos hay que manejar **interrupciones** (llamada, alarma) y **cambios de ruta** (auriculares conectados/desconectados).
+
+**Un juego que suena en background o que ignora el switch de silencio es un rechazo de store esperando pasar.** Para un juego, `.ambient` o `.soloAmbient` según si querés dejar que el usuario escuche su música.
+
+### Respetar el volumen del sistema
+
+Nunca normalizar por encima del volumen del sistema ni forzar un mínimo. Si el usuario bajó el volumen, bajó el volumen.
+
+## Accesibilidad
+
+- El sonido de UI **nunca puede ser el único canal** de información crítica: siempre acompañado de señal visual
+- Éxito y error tienen que distinguirse por **contorno melódico** (ascendente vs descendente), no solo por timbre — es lo que sobrevive a pérdida de agudos
+- Ofrecer control de volumen de UI separado de música y SFX
+- Los sonidos repetitivos de navegación tienen que poder desactivarse sin perder el feedback crítico
+
+---
+
+## Proceso
+
+1. **Listar los eventos** de UI reales y asignar cada uno a un nivel de jerarquía
+2. **Especificar** duración, carácter y nivel por evento, contra la tabla de referencia
+3. **Verificar la jerarquía** — hover y crítico tienen que ser inconfundibles
+4. **Definir haptics** si aplica, con sincronía y reparto de banda
+5. **Definir el manejo de sesión** en móvil
+6. **Chequear accesibilidad** — contorno melódico, canal redundante, controles separados
+7. **Escribir** — preguntar "¿Escribo el set a `<path>`?" antes de usar Write
+
+---
+
+## Verdict
+
+- **READY** — cada evento tiene nivel, duración y jerarquía; la accesibilidad está cubierta; en móvil la sesión de audio está definida
+- **CONCERNS** — el set existe pero no hay jerarquía diferenciada, o el nivel está por encima de −18 dB, o falta el manejo de interrupciones
+- **BLOCKED** — no está definida la lista de eventos de UI o falta la dirección del audio bible
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-mix` para el bus de UI y el ducking del nivel crítico
+- `/audio-spec` para formalizar cooldowns (navegación rápida spamea el evento)
+- `/audio-audit` para verificar niveles medidos contra los especificados

package/skills/ui-sound-design/references/anti-patterns.md

@@ -0,0 +1,57 @@
+# UI Sound Design — Anti-patterns
+
+## Sonidos de UI al nivel del gameplay
+
+Un click a −3 dB compite con la acción del juego y agota en minutos. El UI va entre −18 y −24 dB. Es el error más frecuente y el más fácil de arreglar.
+
+## Todo al mismo nivel
+
+Si el hover y el error de transacción suenan igual de importantes, no hay jerarquía y el usuario deja de prestar atención a los dos. Nivel y duración proporcionales a la importancia del evento.
+
+## Todo duckea
+
+Si cada navegación de menú baja la música, la música desaparece. Solo el nivel crítico duckea.
+
+## Sin cooldown en navegación
+
+Recorrer un menú rápido con el stick dispara el mismo tick veinte veces en 300 ms. Suena a glitch. Cooldown mínimo en todo evento de navegación.
+
+## Tonos sostenidos en 2-6 kHz
+
+Es la banda más sensible del oído y la que más fatiga. Un tono sostenido ahí cansa en una sesión. Transientes cortos.
+
+## Ignorar la sesión de audio en móvil
+
+Entra una llamada, la app pierde el audio y no lo recupera. O el juego suena con el switch de silencio activado. Los dos son rechazo de store. Manejar interrupciones y cambios de ruta explícitamente.
+
+## Forzar volumen por encima del sistema
+
+Normalizar hacia arriba o imponer un piso de volumen ignora una decisión explícita del usuario. Nunca.
+
+## Éxito y error que solo se distinguen por timbre
+
+Con pérdida de agudos, en un speaker malo o con el volumen bajo, los dos suenan igual. La diferencia tiene que estar en el contorno: ascendente para éxito, descendente para error.
+
+## Audio como único canal de información crítica
+
+Un usuario con hipoacusia, con el sonido apagado o en un lugar ruidoso pierde la información. Siempre acompañado de señal visual.
+
+## Haptic y audio desfasados
+
+Arriba de ~30 ms se perciben como dos eventos y se siente roto. Y si el haptic está desactivado, el evento no puede quedarse sin ningún feedback.
+
+## Duplicar información entre audio y haptic
+
+Si el haptic ya comunica intensidad, subir el audio para "reforzar" solo agrega molestia.
+
+## Depender del grave en dispositivos chicos
+
+Un sonido de UI cuyo peso vive en 80 Hz no existe en el speaker de un teléfono. Con haptics, el grave es trabajo del haptic; sin haptics, el sonido tiene que leerse en medios.
+
+## Un set sin toggle
+
+Los sonidos de navegación repetitivos tienen que poder apagarse, y apagarlos no debe silenciar los críticos. Controles de volumen separados de música y SFX.
+
+## Diseñar el set sin probar navegación real
+
+Un sonido aprobado clic por clic se vuelve insoportable cuando el usuario recorre seis pantallas en cuatro segundos. Probar con flujos reales, a velocidad real.

package/skills/voice-pipeline/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: voice-pipeline
+description: "Pipeline de voz: script de VO, casting, sesiones de grabacion, naming y batch processing, localizacion, lipsync y barks. Usar para: dialogo grabado, voice over, doblaje, localizacion de voz, gestion de assets de VO."
+category: "audio"
+argument-hint: "[script | casting | naming | loc | barks]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# voice-pipeline — Voz y Localización
+
+Gestiona el ciclo completo de voz grabada: del script al asset integrado y localizado.
+
+La voz es el área de audio donde los errores son **más caros**: rehacer una sesión de grabación cuesta dinero y agenda de actores, y un error de naming multiplicado por 12 idiomas es inmanejable a mano.
+
+## Cuándo usar
+
+- Preparar un script de VO para grabación
+- Definir naming y estructura antes de recibir assets
+- Planificar localización a varios idiomas
+- Gestionar barks (chatter de combate) y su variación
+- El pipeline de VO se desordenó y hay que reorganizarlo
+
+## Input
+
+1. Leer audio bible (dirección de voz si existe) y el guion narrativo
+2. Determinar: cuántos idiomas, cuántos personajes, si hay lipsync
+3. Preguntar al usuario: presupuesto de grabación, si hay actores ya contratados, y plataforma de destino
+
+---
+
+## Naming — la decisión más importante
+
+**El naming se define antes de grabar una sola línea.** Renombrar 4.000 archivos × 12 idiomas después no es una tarea, es un proyecto.
+
+Patrón recomendado:
+
+```
+vo_<personaje>_<contexto>_<id>_<variante>
+vo_kira_combat_taunt_003_a
+vo_kira_story_ch02_017
+```
+
+**Requisitos del patrón:**
+- **ID estable y único** — nunca se reusa, ni si la línea se corta. Los huecos son gratis; renumerar no
+- **Sin espacios ni acentos** — sobrevive a cualquier filesystem y a batch scripts
+- **El idioma NO va en el nombre del archivo** — va en la ruta o en el bank de idioma. Así el mismo nombre resuelve en cualquier locale
+- **Ordenable alfabéticamente** en el orden en que se usa
+- **Longitud acotada** — algunas plataformas tienen límites de path
+
+El ID es la llave que une script, sesión de grabación, asset, subtítulo y traducción. Si cambia en algún punto, el vínculo se rompe.
+
+## Script de VO
+
+Lo que el actor y el director necesitan por línea:
+
+| Campo | Por qué |
+|---|---|
+| **ID** | La llave de todo el pipeline |
+| **Personaje** | |
+| **Texto** | Exacto, es lo que se graba y se subtitula |
+| **Contexto** | Qué pasó antes; sin esto la actuación es a ciegas |
+| **Dirección** | Emoción, intensidad, a quién le habla |
+| **Restricción de duración** | Si tiene que calzar en una animación o un hueco de gameplay |
+| **Tomas pedidas** | Cuántas variantes de intención |
+
+**El contexto es lo que más se omite y lo que más arruina sesiones.** Un actor grabando líneas sueltas en orden alfabético, sin saber a quién le habla ni qué acaba de pasar, entrega material que no sirve y hay que volver a convocarlo.
+
+**Orden de grabación:** por personaje y por escena, no por ID. Agrupar además por intensidad emocional — dejar los gritos para el final de la sesión, porque desgastan la voz y arruinan lo que venga después.
+
+## Casting
+
+- **Rango, no solo timbre** — el personaje que grita en el acto tres necesita un actor que pueda gritar sin perder la voz
+- **Distinguibilidad** — dos personajes que suenan parecido confunden en un juego donde el jugador no siempre ve quién habla. Test: escuchar sin ver
+- **Disponibilidad para pickups** — siempre hay pickups. Un actor imposible de reconvocar es un riesgo de producción
+- **Consistencia entre idiomas** — el casting de localización debería mantener el *rol tímbrico*, no imitar al actor original
+
+## Barks
+
+El chatter de combate tiene reglas propias porque se escucha muchísimo:
+
+- **Muchas variantes por intención** — mínimo 5-8 por tipo. Un bark repetido es lo primero que el jugador nota
+- **Cortos** — 0.5 a 2 s. Un bark largo se pisa con el gameplay
+- **Cooldown global por personaje y por tipo** — dos enemigos gritando lo mismo a la vez suena a bug
+- **Prioridad baja** — un bark nunca debe tapar diálogo narrativo ni feedback del jugador
+- **Bus separado** de `Dialogue` para que no duckeen la música (ver `/audio-mix`)
+- **Interrumpibles** — si el personaje muere a mitad del bark, se corta
+
+## Localización
+
+| Decisión | Recomendación |
+|---|---|
+| Estructura | Un bank o carpeta por idioma, mismos nombres de archivo adentro |
+| Idioma en runtime | Se resuelve cargando el bank del locale, sin lógica en gameplay |
+| Fallback | Idioma base si falta el asset — nunca silencio |
+| Expansión de texto | El alemán y el español crecen 20-35% sobre el inglés: los huecos de tiempo tienen que tolerarlo |
+| Subtítulos | Mismo ID que el audio. Un ID sin subtítulo es un bug de accesibilidad |
+| Sin doblar | Idiomas con subtítulo solo: definir explícitamente cuáles y que la mezcla lo contemple |
+
+**La expansión de texto es el problema práctico más común.** Una línea que calza justo en inglés se pasa 30% en alemán, y si hay una animación fija o un hueco de gameplay, no entra. Presupuestar el hueco contra el idioma más largo del target, no contra el inglés.
+
+## Procesamiento por lotes
+
+El VO llega en crudo y necesita el mismo tratamiento en miles de archivos. Lo que debe ser automatizado, no manual:
+
+1. **Recorte de silencios** con umbral consistente
+2. **Normalización de loudness** a un target común
+3. **De-noise / de-click** si la fuente lo pide
+4. **Fades** de entrada y salida cortos
+5. **Verificación**: sample rate, bit depth, canales, duración vs restricción
+6. **Reporte** de los que no cumplen
+
+El paso 5 y 6 son los que hay que exigir: sin verificación automática, los assets que no cumplen se descubren en integración.
+
+## Lipsync
+
+- **Basado en fonemas** (extraído del audio o del texto) o **basado en amplitud** (más barato, mucho peor)
+- Si hay lipsync, el **texto tiene que coincidir exactamente** con lo grabado — una improvisación del actor rompe la sincronía
+- La localización necesita lipsync regenerado por idioma, o aceptar el desfasaje explícitamente
+- Los pickups tienen que regenerar el lipsync de la línea afectada
+
+---
+
+## Proceso
+
+1. **Definir el naming** y congelarlo. Este paso primero, sin excepción
+2. **Armar el script** con contexto y dirección por línea
+3. **Planificar las sesiones** por personaje/escena, con los gritos al final
+4. **Definir la estructura** de localización y el fallback
+5. **Definir el pipeline** de batch con su paso de verificación
+6. **Definir barks** con variantes, cooldown y bus
+7. **Escribir** — preguntar "¿Escribo el pipeline a `<path>`?" antes de usar Write
+
+---
+
+## Verdict
+
+- **READY** — naming congelado, script con contexto y dirección, estructura de localización con fallback, pipeline de batch con verificación automática
+- **CONCERNS** — el pipeline existe pero el script no tiene contexto por línea, o la expansión de texto no se presupuestó, o los barks no tienen cooldown
+- **BLOCKED** — el naming no está definido: cualquier grabación antes de eso genera trabajo que se va a rehacer
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-mix` para el bus de diálogo y el ducking
+- `/audio-spec` para el contrato de eventos de barks (concurrencia y cooldown)
+- `/audio-audit` para verificar los assets entregados contra el spec
+- `/middleware-integration` para los banks de idioma

package/skills/voice-pipeline/references/anti-patterns.md

@@ -0,0 +1,69 @@
+# Voice Pipeline — Anti-patterns
+
+## Grabar antes de definir el naming
+
+El error más caro del pipeline. Renombrar 4.000 archivos × 12 idiomas, y actualizar script, subtítulos y referencias en el middleware, no es una tarea: es un proyecto. El naming se congela primero.
+
+## Idioma en el nombre del archivo
+
+`vo_kira_line_003_es.wav` obliga a lógica de resolución de nombre en runtime. El idioma va en la ruta o en el bank; el nombre del archivo es idéntico en todos los locales.
+
+## Renumerar IDs
+
+Se corta una línea y se renumeran las siguientes para "que quede ordenado". Se rompe el vínculo con subtítulos, traducciones y assets ya grabados. Los huecos en la numeración son gratis.
+
+## Script sin contexto
+
+El actor graba líneas sueltas en orden alfabético sin saber a quién le habla ni qué acaba de pasar. El material no sirve y hay que reconvocarlo. El contexto por línea es obligatorio.
+
+## Grabar en orden de ID
+
+El orden es por personaje y por escena. Y los gritos al final de la sesión: desgastan la voz y arruinan todo lo que venga después.
+
+## Casting por timbre solamente
+
+El personaje que grita en el acto tres necesita un actor con rango para gritar sin perder la voz. Y si dos personajes suenan parecido, el jugador que no ve quién habla se confunde.
+
+## Actor imposible de reconvocar
+
+Siempre hay pickups. Un actor sin disponibilidad futura es un riesgo de producción, no un detalle de contrato.
+
+## Presupuestar los huecos contra el inglés
+
+El alemán y el español crecen 20-35%. Una línea que calza justo en inglés no entra en alemán, y si hay animación fija, no hay arreglo. Presupuestar contra el idioma más largo del target.
+
+## Fallback a silencio
+
+Falta el asset en un idioma y no suena nada. El fallback es el idioma base, siempre.
+
+## Subtítulo sin el mismo ID
+
+Si el subtítulo no comparte la llave con el audio, mantener los dos sincronizados pasa a ser manual. Y una línea sin subtítulo es un bug de accesibilidad, no un pendiente.
+
+## Barks con pocas variantes
+
+Un bark repetido es lo primero que el jugador nota. Mínimo 5-8 por intención.
+
+## Barks sin cooldown
+
+Tres enemigos gritan la misma frase simultáneamente y suena a bug. Cooldown global por personaje y por tipo.
+
+## Barks en el bus de diálogo
+
+Cada bark de combate duckea la música. Bus separado.
+
+## Barks que no se interrumpen
+
+El personaje muere y su grito sigue sonando desde un cadáver.
+
+## Batch sin verificación
+
+Procesar miles de archivos sin un paso que valide sample rate, canales y duración deja que lo que no cumple se descubra en integración, cuando ya es tarde.
+
+## Lipsync con texto que no coincide
+
+El actor improvisó y el texto de referencia quedó viejo. La sincronía se rompe y nadie sabe por qué. El texto grabado y el de referencia son el mismo o el lipsync miente.
+
+## Localización sin regenerar lipsync
+
+O se regenera por idioma, o se acepta el desfasaje explícitamente como decisión. Lo que no se puede es descubrirlo en certificación.