claude-code-arcane 2.1.0 → 2.2.0

package/skills/audio-audit/scripts/check_assets.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Verifica conformidad mecanica de assets WAV contra los standards del proyecto.
+
+Solo stdlib: usa el modulo `wave` para leer cabeceras y frames. Los chequeos que
+necesitarian una herramienta externa se reportan como [SKIP], no rompen la corrida.
+
+Uso:
+    python check_assets.py assets/audio
+    python check_assets.py assets/audio --rate 48000 --bits 16
+    python check_assets.py assets/audio --mono-3d --naming "^(sfx|vo|mus)_"
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import struct
+import sys
+import wave
+
+# Umbrales de deteccion. Explicitos para que se puedan discutir.
+LEADING_SILENCE_MS = 10.0    # silencio inicial que ya se percibe como lag
+SILENCE_FLOOR = 0.002        # ~-54 dBFS: por debajo se considera silencio
+DC_OFFSET_LIMIT = 0.01       # 1% de fondo de escala
+CLIP_SAMPLE_LIMIT = 3        # muestras en fondo de escala para llamarlo clipping
+
+
+class Finding:
+    __slots__ = ("path", "severity", "check", "detail")
+
+    def __init__(self, path: str, severity: str, check: str, detail: str):
+        self.path = path
+        self.severity = severity      # FAIL | WARN | SKIP
+        self.check = check
+        self.detail = detail
+
+
+def read_samples(handle: wave.Wave_read, limit: int | None = None) -> list[int]:
+    """Devuelve las muestras del primer canal, normalizadas a int con signo."""
+    width = handle.getsampwidth()
+    channels = handle.getnchannels()
+    frames = handle.getnframes() if limit is None else min(limit, handle.getnframes())
+    raw = handle.readframes(frames)
+
+    if width == 1:
+        # 8-bit WAV es unsigned; centrar en 0
+        values = [byte - 128 for byte in raw]
+    elif width == 2:
+        values = list(struct.unpack(f"<{len(raw) // 2}h", raw[: len(raw) // 2 * 2]))
+    elif width == 3:
+        values = []
+        for offset in range(0, len(raw) - 2, 3):
+            chunk = raw[offset:offset + 3]
+            value = int.from_bytes(chunk, "little", signed=True)
+            values.append(value)
+    elif width == 4:
+        values = list(struct.unpack(f"<{len(raw) // 4}i", raw[: len(raw) // 4 * 4]))
+    else:
+        return []
+
+    return values[::channels] if channels > 1 else values
+
+
+def full_scale(width: int) -> float:
+    return float(2 ** (8 * width - 1))
+
+
+def check_file(path: str, args: argparse.Namespace) -> list[Finding]:
+    findings: list[Finding] = []
+    name = os.path.basename(path)
+
+    if args.naming and not re.search(args.naming, name):
+        findings.append(Finding(path, "FAIL", "naming",
+                                f"no matchea {args.naming!r}"))
+
+    try:
+        with wave.open(path, "rb") as handle:
+            rate = handle.getframerate()
+            width = handle.getsampwidth()
+            channels = handle.getnchannels()
+            frames = handle.getnframes()
+            duration = frames / rate if rate else 0.0
+
+            if args.rate and rate != args.rate:
+                findings.append(Finding(path, "FAIL", "sample-rate",
+                                        f"{rate} Hz, se esperaba {args.rate} Hz"))
+            if args.bits and width * 8 != args.bits:
+                findings.append(Finding(path, "FAIL", "bit-depth",
+                                        f"{width * 8}-bit, se esperaba {args.bits}-bit"))
+            if args.mono_3d and channels != 1:
+                findings.append(Finding(
+                    path, "FAIL", "channels",
+                    f"{channels} canales; una fuente 3D tiene que ser mono o el "
+                    f"middleware la colapsa y se degrada la localizacion"))
+            if args.rate and rate and rate != args.rate and args.rate % rate and rate % args.rate:
+                findings.append(Finding(path, "WARN", "resample",
+                                        f"{rate} Hz no es multiplo ni divisor de "
+                                        f"{args.rate} Hz: el resampleo es mas costoso"))
+            if frames == 0:
+                findings.append(Finding(path, "FAIL", "empty", "0 frames"))
+                return findings
+            if args.max_duration and duration > args.max_duration:
+                findings.append(Finding(path, "WARN", "duration",
+                                        f"{duration:.2f} s > {args.max_duration:.2f} s"))
+
+            samples = read_samples(handle)
+            if not samples:
+                findings.append(Finding(path, "SKIP", "content",
+                                        f"{width * 8}-bit no soportado por el lector stdlib"))
+                return findings
+
+            scale = full_scale(width)
+            peak = max(abs(value) for value in samples)
+
+            clipped = sum(1 for value in samples if abs(value) >= scale - 1)
+            if clipped >= CLIP_SAMPLE_LIMIT:
+                findings.append(Finding(path, "FAIL", "clipping",
+                                        f"{clipped} muestras en fondo de escala"))
+
+            offset = sum(samples) / len(samples) / scale
+            if abs(offset) > DC_OFFSET_LIMIT:
+                findings.append(Finding(path, "WARN", "dc-offset",
+                                        f"{offset * 100:+.2f}% - produce clicks al concatenar"))
+
+            floor = SILENCE_FLOOR * scale
+            if peak < floor:
+                # Archivo enteramente silencioso: el chequeo de silencio inicial
+                # sobra, seria el mismo hallazgo dos veces.
+                findings.append(Finding(path, "FAIL", "silent", "el archivo es silencio"))
+                return findings
+
+            leading = 0
+            for value in samples:
+                if abs(value) > floor:
+                    break
+                leading += 1
+            leading_ms = leading / rate * 1000
+            if leading_ms > LEADING_SILENCE_MS:
+                findings.append(Finding(
+                    path, "WARN", "leading-silence",
+                    f"{leading_ms:.1f} ms de silencio inicial - se percibe como lag de input"))
+
+    except wave.Error as error:
+        findings.append(Finding(path, "SKIP", "format",
+                                f"no es un WAV PCM legible ({error})"))
+    except OSError as error:
+        findings.append(Finding(path, "FAIL", "io", str(error)))
+
+    return findings
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Verifica conformidad de assets WAV contra los standards del proyecto.")
+    parser.add_argument("root", help="carpeta a auditar (recursivo)")
+    parser.add_argument("--rate", type=int, help="sample rate esperado, ej 48000")
+    parser.add_argument("--bits", type=int, choices=(8, 16, 24, 32),
+                        help="bit depth esperado")
+    parser.add_argument("--mono-3d", action="store_true",
+                        help="exigir mono (assets usados como fuentes 3D)")
+    parser.add_argument("--naming", help="regex que el nombre de archivo debe matchear")
+    parser.add_argument("--max-duration", type=float,
+                        help="duracion maxima en segundos")
+    args = parser.parse_args(argv)
+
+    if not os.path.isdir(args.root):
+        print(f"[FAIL] no es una carpeta: {args.root}", file=sys.stderr)
+        return 1
+
+    paths = []
+    for directory, _subdirs, files in os.walk(args.root):
+        for name in sorted(files):
+            if name.lower().endswith(".wav"):
+                paths.append(os.path.join(directory, name))
+
+    if not paths:
+        print(f"[SKIP] no hay .wav en {args.root}")
+        return 0
+
+    findings: list[Finding] = []
+    for path in paths:
+        findings.extend(check_file(path, args))
+
+    fails = [f for f in findings if f.severity == "FAIL"]
+    warns = [f for f in findings if f.severity == "WARN"]
+    skips = [f for f in findings if f.severity == "SKIP"]
+
+    for group in (fails, warns, skips):
+        for finding in group:
+            relative = os.path.relpath(finding.path, args.root)
+            print(f"[{finding.severity}] {relative}: {finding.check} - {finding.detail}")
+
+    print()
+    print(f"{len(paths)} assets | {len(fails)} FAIL | {len(warns)} WARN | {len(skips)} SKIP")
+
+    if fails:
+        print("NON-COMPLIANT")
+        return 1
+    if warns:
+        print("CONCERNS")
+        return 0
+    print("COMPLIANT")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/audio-bible/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: audio-bible
+description: "Audio Bible authoring: sonic palette, emotional targets per game state, frequency allocation, mix hierarchy, audio standards. Usar para: direccion de audio, paleta sonora, identidad sonora del juego."
+category: "audio"
+argument-hint: "[full|core|standards]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# audio-bible — Sonic Identity Specification
+
+Define la identidad sonora del juego. Toda produccion de audio se gatea contra este documento — es el equivalente auditivo de `/art-bible`.
+
+## Cuándo usar
+
+- Después de tener game concept aprobado, antes de producir un solo sonido
+- Cuando necesitás estandarizar el criterio sonoro entre sound designers y compositores
+- Antes de escribir specs de SFX (`/audio-spec`) o diseñar el sistema de música (`/adaptive-music`)
+
+## Input
+
+1. Leer game concept (elevator pitch, pilares, core fantasy) y art bible si existe
+2. Preguntar al usuario: scope (full bible / core secciones 1-4 / solo standards), plataformas target, y referencias sonoras (juegos, films, discos)
+3. Si ya existe audio bible: detectar secciones completas vs vacías, trabajar solo las incompletas
+
+---
+
+## Secciones del Audio Bible
+
+### Core (secciones 1-4) — definen el lenguaje sonoro
+
+| # | Sección | Qué define | Criterio de calidad |
+|---|---------|-----------|-------------------|
+| 1 | **Sonic Identity Statement** | Regla sonora de 1 línea + 2-3 principios de soporte | Resuelve cualquier ambigüedad sonora. Cada principio ancla en un pilar del juego |
+| 2 | **Emotional Targets por Game State** | Qué debe sentir el jugador en exploración, combate, tensión, victoria, menú | Cada estado auditivamente distinto sin mirar la pantalla |
+| 3 | **Sonic Palette** | Fuentes y texturas: acústico vs sintético, orgánico vs procesado, época/lugar, vocabulario tímbrico | Un sonido nuevo se puede aceptar o rechazar leyendo esto |
+| 4 | **Frequency Allocation** | Qué categoría es dueña de qué banda — evita masking antes de que exista el mix | Diálogo, música, SFX y ambiente no compiten por la misma banda |
+
+### Production (secciones 5-8) — reglas concretas
+
+| # | Sección | Qué define |
+|---|---------|-----------|
+| 5 | **Mix Hierarchy** | Prioridad entre categorías, qué duckea a qué, qué nunca se pisa |
+| 6 | **Music Direction** | Instrumentación, escalas/modos, tempo range, rol del silencio, estrategia adaptativa |
+| 7 | **SFX Direction** | Filosofía de impacto, realismo vs estilización, tratamiento del feedback de UI, uso de variación |
+| 8 | **Audio Standards** | Sample rate, bit depth, formatos, naming, targets de loudness, budgets de memoria y voces por plataforma |
+
+### Reference (sección 9)
+
+| # | Sección | Qué define |
+|---|---------|-----------|
+| 9 | **References & Prohibitions** | 3-5 referencias con qué tomar y qué evitar de cada una. Prohibiciones sonoras explícitas |
+
+---
+
+## Frequency allocation — el punto que más se saltea
+
+La mayoría de los mixes de juego se rompen porque nadie asignó bandas antes de producir. Definir dueño primario por banda evita rehacer assets:
+
+| Banda | Dueño primario | Nota |
+|---|---|---|
+| Sub (20-60 Hz) | Impactos, explosiones | Reservado, no lo llenes de música |
+| Low (60-250 Hz) | Música (bajo, kick), body de impactos | Zona de masking más frecuente |
+| Low-mid (250-500 Hz) | Ambiente, body de props | Acumula barro si no se controla |
+| Mid (500 Hz-2 kHz) | **Diálogo** — intocable | El resto cede acá |
+| High-mid (2-6 kHz) | Feedback de UI, transientes, definición | Fatiga rápido; usar con precisión |
+| High (6-20 kHz) | Aire, detalle, brillo | Primero en irse en compresión lossy |
+
+Cuando un asset nuevo pelea una banda que no le corresponde, la solución es de diseño (cambiar la fuente), no de EQ.
+
+---
+
+## Proceso
+
+Para cada sección:
+1. **Draftar** basándose en game concept, pilares y referencias
+2. **Presentar** al usuario para review
+3. **Escribir** a archivo inmediatamente después de aprobación — preguntar "¿Escribo esta sección a `<path>`?" antes de usar Write
+
+No batchear — escribir cada sección aprobada antes de pasar a la siguiente.
+
+### Conflictos
+
+Si hay tensión entre dirección de audio y constraints técnicos (ej: música en stems para adaptatividad, pero el budget de memoria no da), surfacear el conflicto explícitamente con ambas posiciones. No resolver silenciosamente.
+
+Si la dirección sonora conflictúa con accesibilidad (ej: información crítica solo por audio), surfacear y dejar que el usuario decida.
+
+---
+
+## Principios
+
+- El audio bible es un **documento de restricción**: narrows solution space en favor de coherencia sonora
+- Cada sección debe conectar con los pilares del juego
+- Específico > genérico: "dark and tense" no alcanza — decir la emoción exacta, la fuente tímbrica, el rango de frecuencia, un elemento sonoro que carga el mood
+- Para cada referencia: qué tomar Y qué evitar
+- El silencio es una decisión de diseño, no la ausencia de una — documentarlo
+- Los standards deben ser producibles: un contractor externo debería poder entregar assets válidos sin briefing adicional
+
+---
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md for common mistakes to avoid
+
+## Verdict
+
+Al cerrar el documento, emitir un verdict por sección:
+
+- **READY** — la sección resuelve ambigüedades y es accionable para producción
+- **CONCERNS** — está escrita pero es genérica o no ancla en pilares; listar qué falta
+- **BLOCKED** — falta input upstream (game concept, plataformas, budget) que no se puede inventar
+
+Si alguna sección Core (1-4) queda en BLOCKED, el bible no habilita producción todavía.
+
+## Next steps
+
+- `/audio-spec` para bajar la dirección a spec sheets de SFX y event lists
+- `/adaptive-music` para diseñar el sistema de música contra los emotional targets de la sección 2
+- `/audio-mix` para implementar la mix hierarchy de la sección 5
+- `/audio-audit` para verificar assets producidos contra los standards de la sección 8

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

@@ -0,0 +1,39 @@
+# Audio Bible — Anti-patterns
+
+## Dirección vacía
+
+**Síntoma:** "El juego suena oscuro e inmersivo."
+
+Cualquier sonido pasa ese filtro, así que no filtra nada. Una statement útil excluye: "Todo suena grabado dentro de una habitación de concreto — nada nace limpio, todo tiene el cuarto encima." Eso rechaza el 90% de una library.
+
+## Paleta sin fuentes
+
+Listar adjetivos (cálido, agresivo, etéreo) sin decir de dónde sale el sonido deja la decisión al sound designer, que es exactamente lo que el bible debería resolver. Nombrar fuentes: instrumentos, materiales, técnicas de grabación, cadenas de procesamiento.
+
+## Frequency allocation ausente
+
+Se produce todo, se llega al mix, y diálogo compite con música y SFX en 500 Hz-2 kHz. La solución tardía es EQ quirúrgico que adelgaza todo. La solución temprana es asignar bandas antes de producir.
+
+## Copiar la referencia entera
+
+"Suena como Hollow Knight" sin decir qué se toma produce pastiche. Para cada referencia: qué tomar y qué evitar explícitamente.
+
+## Emotional targets que no se distinguen
+
+Si exploración y tensión comparten instrumentación, tempo y densidad, el jugador no lee el estado por audio. Test: describir los estados sin nombrarlos y ver si son distinguibles.
+
+## Standards no producibles
+
+"Audio de alta calidad, sin artefactos" no es un standard. Sample rate, bit depth, formato por plataforma, naming pattern, target de loudness con tolerancia, headroom y budget de voces sí lo son.
+
+## El silencio sin documentar
+
+Los juegos con mejor audio usan silencio deliberadamente. Si el bible no dice dónde y por qué, alguien va a llenar cada segundo con ambiente.
+
+## Ignorar la plataforma
+
+Un bible que asume monitores de estudio falla en el speaker de un handheld o en earbuds bluetooth. Los targets de loudness y la allocation de frecuencias cambian por plataforma — documentar cuáles importan.
+
+## Bible que nadie gatea
+
+Si no hay un paso de review que compare assets contra el bible, es decoración. Conectarlo con `/audio-audit` y hacerlo condición de entrega.

package/skills/audio-mix/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: audio-mix
+description: "Mezcla de juego: jerarquia de buses, ducking y sidechain, mix states/snapshots, frequency masking, headroom y targets de loudness. Usar para: estructura de buses, ducking de dialogo, mix dinamico, resolver que el mix suena barroso."
+category: "audio"
+argument-hint: "[buses | ducking | states | loudness | review]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# audio-mix — Mezcla Dinámica
+
+Diseña la estructura de buses y las reglas que deciden **qué se escucha cuando todo suena a la vez**.
+
+El mix de un juego no es un mix estático: es un sistema de reglas, porque no se sabe de antemano qué va a sonar simultáneamente.
+
+## Cuándo usar
+
+- Definir la arquitectura de buses del proyecto
+- El mix suena barroso, o el diálogo no se entiende
+- Falta control dinámico: momentos importantes no destacan
+- Cumplir targets de loudness de plataforma
+
+## Input
+
+1. Leer audio bible, sección 4 (frequency allocation) y 5 (mix hierarchy)
+2. Listar las categorías de audio del proyecto
+3. Preguntar al usuario: plataformas target, si hay diálogo, y si existe algún requisito de certificación
+
+---
+
+## Jerarquía de buses
+
+Estructura base que sirve para casi cualquier juego:
+
+```
+Master
+├── Music
+├── SFX
+│   ├── Player          (feedback de la acción del jugador)
+│   ├── World           (enemigos, props, entorno)
+│   └── Ambience
+├── Voice
+│   ├── Dialogue        (narrativa, crítico)
+│   └── Barks           (chatter de combate)
+└── UI
+```
+
+**Por qué esta forma:**
+- `Player` separado de `World` permite proteger el feedback de la acción del jugador cuando hay 40 enemigos
+- `Dialogue` separado de `Barks` permite duckear por diálogo importante sin que cada bark baje la música
+- `UI` afuera de `SFX` porque tiene su propio nivel (−18 a −24 dB) y su propio control de usuario
+- `Ambience` separado porque es lo primero que se sacrifica cuando el mix se llena
+
+**Cada bus necesita:** volumen base, control de usuario expuesto o no, y si va a reverb de zona.
+
+## Ducking
+
+Bajar una categoría cuando otra suena. Los casos reales:
+
+| Trigger | Qué duckea | Cuánto | Attack / Release |
+|---|---|---|---|
+| Diálogo | Music, Ambience | −6 a −9 dB | 50 ms / 400 ms |
+| UI crítico | Music, SFX | −3 a −6 dB | 20 ms / 200 ms |
+| Momento narrativo | Todo menos Voice | −12 dB | 200 ms / 800 ms |
+| Barks | nada, o −2 dB | mínimo | rápido |
+
+**El release siempre más largo que el attack.** Un release corto produce bombeo audible: la música sube y baja a cada palabra. 300-500 ms de release para diálogo es lo que suena natural.
+
+**El ducking no reemplaza al arreglo.** Si la música vive en 500 Hz-2 kHz y el diálogo también, hay que duckear tanto que se escucha. La solución es dejar ese rango libre en el arreglo (ver `/music-composition`, orquestación production-aware). El ducking es el ajuste fino, no la solución estructural.
+
+**Sidechain vs ducking por evento:** el ducking por evento (el middleware baja el bus cuando el evento está activo) es más predecible y más barato. El sidechain real (detectar la señal) responde mejor a diálogo de duración variable. Para VO grabado, ducking por evento alcanza.
+
+## Frequency masking
+
+Dos sonidos que ocupan la misma banda compiten, y el más fuerte gana. El EQ correctivo adelgaza todo; la solución es la **asignación de bandas** del audio bible.
+
+Cuando ya está producido y hay que arreglarlo:
+
+| Problema | Arreglo de mezcla |
+|---|---|
+| Diálogo tapado por música | EQ dinámico en Music: hueco en 1-3 kHz solo cuando hay VO |
+| Impactos sin peso | High-pass en Music y Ambience por debajo de 80 Hz |
+| Mix barroso | High-pass en todo lo que no necesita graves; casi nada necesita por debajo de 60 Hz |
+| UI perdido | Reducir el brillo de la percusión, no subir el UI |
+| Todo suena chico | Demasiadas fuentes; el problema es voice count, no EQ |
+
+## Mix states
+
+Snapshots de la mezcla que se activan por contexto. El mix dinámico es lo que hace que un juego suene "bien mezclado" en situaciones que nadie mezcló a mano.
+
+| Estado | Qué cambia |
+|---|---|
+| Exploration | Base |
+| Combat | Player y World arriba, Ambience abajo |
+| Cutscene | Voice arriba, todo lo demás abajo, sin UI |
+| Menu (pausa) | Todo salvo UI y Music muy abajo o silenciado |
+| Low health | Filtro en Music, tinnitus, resto atenuado |
+| Death | Corte o filtro extremo |
+
+**Interpolar entre estados**, nunca saltar. 200-500 ms según qué tan dramático sea el cambio. Y definir qué pasa si dos estados quieren activarse a la vez: prioridad explícita.
+
+## Headroom y loudness
+
+**Headroom:** dejar margen en el master para que los picos simultáneos no clippeen. El mix se hace apuntando a que el caso peor (explosión + música + diálogo) tenga espacio, no el caso promedio.
+
+**Targets de loudness.** La referencia de industria en juegos es **ASWG-R001** (Sony), que es la única especificación de una plataforma mayor:
+
+| Contexto | Loudness promedio | True peak máximo |
+|---|---|---|
+| Consola / home | **−23 LUFS** (±2) | **−1 dBTP** |
+| Portable / handheld | **−18 LUFS** | −1 dBTP |
+
+El target portable es más alto porque se juega en ambientes ruidosos y con speakers chicos.
+
+Notas de aplicación:
+- La medición es del **programa completo en gameplay representativo**, no de un asset aislado
+- Verificar los targets vigentes de cada plataforma antes de certificación: las recomendaciones se revisan (el promedio de ASWG estuvo también citado como −24 LKFS)
+- El true peak de −1 dBTP deja margen para la codificación lossy, que puede generar picos por encima del valor medido en PCM
+
+---
+
+## Proceso
+
+1. **Definir la jerarquía de buses** con sus volúmenes base y controles de usuario
+2. **Definir reglas de ducking** con attack/release y cuánto
+3. **Definir mix states** con sus transiciones y prioridades
+4. **Verificar masking** contra la frequency allocation del bible
+5. **Definir targets de loudness** por plataforma y cómo se van a medir
+6. **Escribir** — preguntar "¿Escribo el diseño de mezcla a `<path>`?" antes de usar Write
+
+### Verificación
+
+El mix se valida **jugando**, en el caso peor: máxima densidad de enemigos, con diálogo, con música de combate, en el dispositivo más chico del target. Si ahí se entiende el diálogo y se lee el feedback del jugador, el mix funciona.
+
+---
+
+## Verdict
+
+- **COMPLIANT** — buses definidos, ducking con release más largo que attack, mix states interpolados con prioridad, y loudness medido dentro del target de cada plataforma
+- **CONCERNS** — la estructura existe pero el loudness no se midió en gameplay real, o el ducking está tapando un problema de arreglo
+- **NON-COMPLIANT** — el loudness está fuera del target de plataforma, o hay clipping en el caso peor
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md
+
+## Next steps
+
+- `/audio-audit` para medir loudness, picos y voice count en gameplay real
+- `/middleware-integration` para implementar buses, ducking y states
+- `/ui-sound-design` para el nivel del bus UI
+- `/music-composition` si el masking se tiene que resolver en el arreglo y no en la mezcla

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

@@ -0,0 +1,65 @@
+# Audio Mix — Anti-patterns
+
+## Mezclar en aislamiento
+
+Aprobar cada categoría por separado y esperar que el conjunto funcione. El mix se valida jugando el caso peor: máxima densidad, con diálogo, con música de combate, en el dispositivo más chico.
+
+## Release de ducking demasiado corto
+
+La música sube y baja a cada palabra y se escucha el bombeo. El release siempre más largo que el attack: 300-500 ms para diálogo.
+
+## Ducking como solución al masking
+
+Si la música y el diálogo viven los dos en 500 Hz-2 kHz, hay que duckear tanto que el efecto es audible. Eso se resuelve en el arreglo, dejando el rango libre. El ducking es ajuste fino.
+
+## Todo duckea a todo
+
+Barks duckeando música, UI duckeando SFX, ambiente duckeando barks. El resultado es un mix que respira todo el tiempo y nunca está quieto. Definir qué duckea a qué, y que sea poco.
+
+## Un solo bus de SFX
+
+Con 40 enemigos, el feedback de la acción del jugador se pierde entre el resto. Separar `Player` de `World` es lo que permite protegerlo.
+
+## Diálogo y barks en el mismo bus
+
+Cada bark de combate duckea la música. Separarlos permite duckear por diálogo importante nada más.
+
+## UI dentro de SFX
+
+El UI tiene otro nivel (−18 a −24 dB) y suele necesitar control de usuario propio. Metido en SFX, hereda un volumen que no le corresponde.
+
+## Mix states que saltan
+
+Cambiar de snapshot instantáneamente se escucha como un corte. Interpolar 200-500 ms según el cambio.
+
+## Estados sin prioridad
+
+Combat y Low health quieren activarse a la vez y el resultado depende del orden de evaluación. Prioridad explícita.
+
+## EQ correctivo en todo
+
+Adelgazar cada fuente con EQ hasta que dejen de pelear produce un mix delgado y sin peso. El problema de raíz es la asignación de bandas, o hay demasiadas fuentes sonando.
+
+## Confundir "suena chico" con problema de EQ
+
+Cuando todo suena chico, casi siempre hay demasiadas voces activas y ninguna tiene lugar. Es un problema de voice count, y el EQ no lo arregla.
+
+## Nada de headroom
+
+Mezclar apuntando al caso promedio y clippear cuando coinciden explosión, música y diálogo. El margen se calcula contra el peor caso.
+
+## Medir loudness en un asset aislado
+
+Los targets de LUFS son del programa completo en gameplay representativo. Medir un archivo no dice nada del cumplimiento.
+
+## Asumir un target sin verificar
+
+Los targets de plataforma se revisan. Confirmar el vigente antes de certificación en vez de confiar en un número memorizado.
+
+## Ignorar el true peak
+
+Un mix que llega a 0 dBFS en PCM puede generar picos por encima al codificarse en lossy. −1 dBTP existe por eso.
+
+## Mezclar solo con auriculares buenos
+
+El mix suena perfecto en los monitores del sound designer y se cae en el speaker de un handheld. Validar en el dispositivo más chico del target.