claude-code-arcane 2.1.0 → 2.3.0

package/skills/midi-compose/scripts/compose_midi.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""Escribe un Standard MIDI File (formato 1) desde un spec JSON.
+
+Solo stdlib: el SMF es un formato binario documentado y no hace falta
+ninguna dependencia para emitirlo. Ver references/smf-format.md.
+
+Uso:
+    python compose_midi.py spec.json -o salida.mid
+    python compose_midi.py spec.json --validate      # solo valida, no escribe
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import struct
+import sys
+
+# ---------------------------------------------------------------- constantes
+
+DRUM_CHANNEL = 9          # canal 10 en base 1; reservado a percusion por GM
+MAX_CHANNELS = 16         # el limite duro: 15 tracks melodicos + percusion
+DEFAULT_PPQ = 480
+
+NOTE_OFFSETS = {
+    "C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11,
+}
+
+# sf para el meta de tonalidad: sostenidos positivos, bemoles negativos
+KEY_SIGNATURES = {
+    "C": 0, "G": 1, "D": 2, "A": 3, "E": 4, "B": 5, "F#": 6, "C#": 7,
+    "F": -1, "Bb": -2, "Eb": -3, "Ab": -4, "Db": -5, "Gb": -6, "Cb": -7,
+}
+
+
+class SpecError(ValueError):
+    """El spec JSON es invalido. El mensaje explica que arreglar."""
+
+
+# ------------------------------------------------------------------ helpers
+
+def vlq(value: int) -> bytes:
+    """Variable-length quantity: el encoding de delta-times del SMF.
+
+    Siete bits por byte, MSB=1 en todos menos el ultimo.
+    """
+    if value < 0:
+        raise SpecError(f"delta-time negativo: {value}")
+    out = [value & 0x7F]
+    value >>= 7
+    while value:
+        out.append((value & 0x7F) | 0x80)
+        value >>= 7
+    return bytes(reversed(out))
+
+
+def parse_pitch(pitch: object) -> int:
+    """Acepta 60, "C4", "F#3", "Bb5". Devuelve numero de nota MIDI (C4 = 60)."""
+    if isinstance(pitch, bool):
+        raise SpecError(f"pitch invalido: {pitch!r}")
+    if isinstance(pitch, int):
+        if not 0 <= pitch <= 127:
+            raise SpecError(f"pitch fuera de rango 0-127: {pitch}")
+        return pitch
+    if not isinstance(pitch, str) or not pitch:
+        raise SpecError(f"pitch invalido: {pitch!r}")
+
+    text = pitch.strip()
+    letter = text[0].upper()
+    if letter not in NOTE_OFFSETS:
+        raise SpecError(f"nota desconocida en pitch {pitch!r}")
+
+    index = 1
+    accidental = 0
+    while index < len(text) and text[index] in "#b":
+        accidental += 1 if text[index] == "#" else -1
+        index += 1
+
+    octave_text = text[index:]
+    if not octave_text.lstrip("-").isdigit():
+        raise SpecError(f"falta la octava en pitch {pitch!r} (ej: C4, F#3, Bb5)")
+
+    # C4 = 60 => la octava -1 arranca en 0
+    value = (int(octave_text) + 1) * 12 + NOTE_OFFSETS[letter] + accidental
+    if not 0 <= value <= 127:
+        raise SpecError(f"pitch {pitch!r} cae fuera del rango MIDI 0-127")
+    return value
+
+
+def meta(kind: int, payload: bytes) -> bytes:
+    return b"\xff" + bytes([kind]) + vlq(len(payload)) + payload
+
+
+def text_meta(kind: int, text: str) -> bytes:
+    return meta(kind, text.encode("utf-8", errors="replace"))
+
+
+# ------------------------------------------------------------------ validate
+
+def validate(spec: dict) -> dict:
+    """Normaliza y valida el spec. Devuelve el spec normalizado."""
+    if not isinstance(spec, dict):
+        raise SpecError("el spec raiz tiene que ser un objeto JSON")
+
+    tempo = spec.get("tempo", 120)
+    if not isinstance(tempo, (int, float)) or not 1 <= tempo <= 600:
+        raise SpecError(f"tempo tiene que ser un numero entre 1 y 600, no {tempo!r}")
+
+    ppq = spec.get("ppq", DEFAULT_PPQ)
+    if not isinstance(ppq, int) or not 24 <= ppq <= 32767:
+        raise SpecError(f"ppq tiene que ser un entero entre 24 y 32767, no {ppq!r}")
+
+    signature = spec.get("time_signature", [4, 4])
+    if (not isinstance(signature, (list, tuple)) or len(signature) != 2
+            or not all(isinstance(n, int) for n in signature)):
+        raise SpecError('time_signature tiene que ser [numerador, denominador], ej [4, 4]')
+    numerator, denominator = signature
+    if not 1 <= numerator <= 255:
+        raise SpecError(f"numerador de compas invalido: {numerator}")
+    if denominator not in (1, 2, 4, 8, 16, 32, 64):
+        raise SpecError(f"denominador de compas invalido: {denominator}")
+
+    key = spec.get("key", "C")
+    mode = spec.get("mode", "major")
+    if key not in KEY_SIGNATURES:
+        raise SpecError(
+            f"tonalidad {key!r} desconocida. Validas: {', '.join(sorted(KEY_SIGNATURES))}"
+        )
+    if mode not in ("major", "minor"):
+        raise SpecError(f'mode tiene que ser "major" o "minor", no {mode!r}')
+
+    tracks = spec.get("tracks")
+    if not isinstance(tracks, list) or not tracks:
+        raise SpecError("el spec necesita al menos un track en 'tracks'")
+
+    melodic = 0
+    used_channels: set[int] = set()
+    normalized_tracks = []
+    warnings: list[str] = []
+
+    for position, track in enumerate(tracks):
+        label = track.get("name") if isinstance(track, dict) else None
+        where = f"track {position}" + (f" ({label})" if label else "")
+
+        if not isinstance(track, dict):
+            raise SpecError(f"{where}: cada track tiene que ser un objeto")
+
+        channel = track.get("channel", DRUM_CHANNEL if track.get("drums") else position)
+        if not isinstance(channel, int) or not 0 <= channel < MAX_CHANNELS:
+            raise SpecError(f"{where}: channel tiene que estar entre 0 y 15, no {channel!r}")
+        if channel in used_channels:
+            raise SpecError(f"{where}: el canal {channel} ya lo usa otro track")
+        used_channels.add(channel)
+
+        if channel == DRUM_CHANNEL:
+            if not track.get("drums"):
+                warnings.append(
+                    f"{where}: usa el canal {DRUM_CHANNEL}, reservado a percusion por GM. "
+                    f'Si es intencional agregale "drums": true; si no, movelo a otro canal.'
+                )
+        else:
+            melodic += 1
+
+        program = track.get("program", 0)
+        if not isinstance(program, int) or not 0 <= program <= 127:
+            raise SpecError(f"{where}: program tiene que estar entre 0 y 127, no {program!r}")
+
+        notes = track.get("notes")
+        if not isinstance(notes, list):
+            raise SpecError(f"{where}: 'notes' tiene que ser una lista")
+
+        normalized_notes = []
+        for note_position, note in enumerate(notes):
+            note_where = f"{where}, nota {note_position}"
+            if not isinstance(note, dict):
+                raise SpecError(f"{note_where}: cada nota tiene que ser un objeto")
+
+            pitch = parse_pitch(note.get("pitch"))
+
+            start = note.get("start", 0)
+            if not isinstance(start, (int, float)) or start < 0:
+                raise SpecError(f"{note_where}: 'start' tiene que ser >= 0, no {start!r}")
+
+            duration = note.get("duration", 1)
+            if not isinstance(duration, (int, float)) or duration <= 0:
+                raise SpecError(f"{note_where}: 'duration' tiene que ser > 0, no {duration!r}")
+
+            velocity = note.get("velocity", 90)
+            if not isinstance(velocity, int) or not 1 <= velocity <= 127:
+                raise SpecError(
+                    f"{note_where}: 'velocity' tiene que estar entre 1 y 127, no {velocity!r}"
+                )
+
+            normalized_notes.append(
+                {"pitch": pitch, "start": float(start),
+                 "duration": float(duration), "velocity": velocity}
+            )
+
+        normalized_tracks.append({
+            "name": track.get("name", f"Track {position}"),
+            "channel": channel,
+            "program": program,
+            "notes": normalized_notes,
+        })
+
+    return {
+        "name": spec.get("name", "untitled"),
+        "tempo": float(tempo),
+        "ppq": ppq,
+        "time_signature": [numerator, denominator],
+        "key": key,
+        "mode": mode,
+        "tracks": normalized_tracks,
+        "melodic_tracks": melodic,
+        "warnings": warnings,
+    }
+
+
+# --------------------------------------------------------------------- build
+
+def build_chunk(name: bytes, body: bytes) -> bytes:
+    return name + struct.pack(">I", len(body)) + body
+
+
+def conductor_track(spec: dict) -> bytes:
+    """Track 0 del formato 1: tempo, compas, tonalidad. Sin notas."""
+    events = [b"\x00" + text_meta(0x03, spec["name"])]
+
+    microseconds = int(round(60_000_000 / spec["tempo"]))
+    events.append(b"\x00" + meta(0x51, struct.pack(">I", microseconds)[1:]))
+
+    numerator, denominator = spec["time_signature"]
+    events.append(
+        b"\x00" + meta(0x58, bytes([numerator, denominator.bit_length() - 1, 24, 8]))
+    )
+
+    sharps = KEY_SIGNATURES[spec["key"]]
+    events.append(
+        b"\x00" + meta(0x59, struct.pack(">bB", sharps, 1 if spec["mode"] == "minor" else 0))
+    )
+
+    events.append(b"\x00" + meta(0x2F, b""))
+    return build_chunk(b"MTrk", b"".join(events))
+
+
+def music_track(track: dict, ppq: int) -> bytes:
+    channel = track["channel"]
+    events = [
+        b"\x00" + text_meta(0x03, track["name"]),
+        b"\x00" + bytes([0xC0 | channel, track["program"]]),
+    ]
+
+    # (tick, orden, bytes). orden 0 = note-off primero, para que una nota
+    # reatacada en el mismo tick no se corte a si misma.
+    timeline: list[tuple[int, int, bytes]] = []
+    for note in track["notes"]:
+        start = int(round(note["start"] * ppq))
+        end = start + max(1, int(round(note["duration"] * ppq)))
+        timeline.append((start, 1, bytes([0x90 | channel, note["pitch"], note["velocity"]])))
+        timeline.append((end, 0, bytes([0x80 | channel, note["pitch"], 0])))
+
+    timeline.sort(key=lambda item: (item[0], item[1]))
+
+    previous = 0
+    for tick, _order, payload in timeline:
+        events.append(vlq(tick - previous) + payload)
+        previous = tick
+
+    events.append(b"\x00" + meta(0x2F, b""))
+    return build_chunk(b"MTrk", b"".join(events))
+
+
+def build_midi(spec: dict) -> bytes:
+    ppq = spec["ppq"]
+    tracks = [conductor_track(spec)] + [music_track(t, ppq) for t in spec["tracks"]]
+    header = build_chunk(b"MThd", struct.pack(">HHH", 1, len(tracks), ppq))
+    return header + b"".join(tracks)
+
+
+# ----------------------------------------------------------------------- cli
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Escribe un .mid desde un spec JSON.")
+    parser.add_argument("spec", help="ruta al spec JSON")
+    parser.add_argument("-o", "--output", help="ruta del .mid de salida")
+    parser.add_argument("--validate", action="store_true",
+                        help="solo valida el spec, no escribe nada")
+    args = parser.parse_args(argv)
+
+    try:
+        with open(args.spec, "r", encoding="utf-8") as handle:
+            raw = json.load(handle)
+    except FileNotFoundError:
+        print(f"[FAIL] no existe el spec: {args.spec}", file=sys.stderr)
+        return 1
+    except json.JSONDecodeError as error:
+        print(f"[FAIL] JSON invalido en {args.spec}: {error}", file=sys.stderr)
+        return 1
+
+    try:
+        spec = validate(raw)
+    except SpecError as error:
+        print(f"[FAIL] {error}", file=sys.stderr)
+        return 1
+
+    note_count = sum(len(t["notes"]) for t in spec["tracks"])
+    print(f"[PASS] spec valido: {len(spec['tracks'])} tracks "
+          f"({spec['melodic_tracks']} melodicos de 15 posibles), {note_count} notas, "
+          f"{spec['tempo']:g} BPM, {spec['key']} {spec['mode']}")
+    for warning in spec["warnings"]:
+        print(f"[WARN] {warning}")
+
+    if args.validate:
+        return 0
+
+    output = args.output or (args.spec.rsplit(".", 1)[0] + ".mid")
+    data = build_midi(spec)
+    with open(output, "wb") as handle:
+        handle.write(data)
+
+    print(f"[COMPLETE] {output} ({len(data)} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/midi-compose/templates/example-composition.json

@@ -0,0 +1,69 @@
+{
+  "name": "Explore Calm — bed + pulse",
+  "tempo": 84,
+  "ppq": 480,
+  "time_signature": [4, 4],
+  "key": "D",
+  "mode": "minor",
+  "tracks": [
+    {
+      "name": "Bed (strings)",
+      "channel": 0,
+      "program": 48,
+      "notes": [
+        { "pitch": "D3", "start": 0, "duration": 4, "velocity": 62 },
+        { "pitch": "A3", "start": 0, "duration": 4, "velocity": 58 },
+        { "pitch": "F4", "start": 0, "duration": 4, "velocity": 54 },
+
+        { "pitch": "Bb2", "start": 4, "duration": 4, "velocity": 62 },
+        { "pitch": "F3", "start": 4, "duration": 4, "velocity": 58 },
+        { "pitch": "D4", "start": 4, "duration": 4, "velocity": 54 },
+
+        { "pitch": "C3", "start": 8, "duration": 4, "velocity": 62 },
+        { "pitch": "G3", "start": 8, "duration": 4, "velocity": 58 },
+        { "pitch": "E4", "start": 8, "duration": 4, "velocity": 54 },
+
+        { "pitch": "A2", "start": 12, "duration": 4, "velocity": 60 },
+        { "pitch": "E3", "start": 12, "duration": 4, "velocity": 56 },
+        { "pitch": "C4", "start": 12, "duration": 4, "velocity": 52 }
+      ]
+    },
+    {
+      "name": "Melody (clarinet)",
+      "channel": 1,
+      "program": 71,
+      "notes": [
+        { "pitch": "A4", "start": 0.0, "duration": 2.0, "velocity": 78 },
+        { "pitch": "F4", "start": 2.0, "duration": 1.0, "velocity": 72 },
+        { "pitch": "E4", "start": 3.0, "duration": 1.0, "velocity": 72 },
+        { "pitch": "D4", "start": 4.0, "duration": 3.0, "velocity": 80 },
+        { "pitch": "F4", "start": 7.0, "duration": 1.0, "velocity": 70 },
+        { "pitch": "G4", "start": 8.0, "duration": 2.0, "velocity": 76 },
+        { "pitch": "E4", "start": 10.0, "duration": 2.0, "velocity": 72 },
+        { "pitch": "D4", "start": 12.0, "duration": 4.0, "velocity": 74 }
+      ]
+    },
+    {
+      "name": "Pulse (percussion)",
+      "channel": 9,
+      "drums": true,
+      "program": 0,
+      "notes": [
+        { "pitch": 42, "start": 0.0, "duration": 0.25, "velocity": 54 },
+        { "pitch": 42, "start": 1.0, "duration": 0.25, "velocity": 44 },
+        { "pitch": 42, "start": 2.0, "duration": 0.25, "velocity": 54 },
+        { "pitch": 42, "start": 3.0, "duration": 0.25, "velocity": 44 },
+        { "pitch": 42, "start": 4.0, "duration": 0.25, "velocity": 54 },
+        { "pitch": 42, "start": 5.0, "duration": 0.25, "velocity": 44 },
+        { "pitch": 42, "start": 6.0, "duration": 0.25, "velocity": 54 },
+        { "pitch": 42, "start": 7.0, "duration": 0.25, "velocity": 44 },
+        { "pitch": 36, "start": 8.0, "duration": 0.5, "velocity": 66 },
+        { "pitch": 42, "start": 9.0, "duration": 0.25, "velocity": 44 },
+        { "pitch": 42, "start": 10.0, "duration": 0.25, "velocity": 54 },
+        { "pitch": 42, "start": 11.0, "duration": 0.25, "velocity": 44 },
+        { "pitch": 36, "start": 12.0, "duration": 0.5, "velocity": 66 },
+        { "pitch": 42, "start": 14.0, "duration": 0.25, "velocity": 50 }
+      ]
+    }
+  ]
+}

package/skills/music-composition/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: music-composition
+description: "Composicion musical: armonia, melodia, forma, groove, orquestacion. Traduce problemas creativos vagos en movimientos compositivos concretos con cifrados, grados de escala y voicings. Usar para: progresiones, melodias, modulacion, arreglo, analisis musical. NO genera audio ni MIDI ni opera DAW."
+category: "audio"
+argument-hint: "[harmony|melody|form|groove|orchestration|analyze]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Edit
+---
+# music-composition — Decisiones Musicales
+
+Resuelve problemas de composición con salida accionable: cifrados concretos, melodías en grados de escala, bocetos de groove, voicings específicos.
+
+**La teoría es un mapa de efectos posibles, no una lista de mandamientos.** Cada técnica se presenta con *qué efecto produce* y *por qué*, para que la elección sea informada y no obediente.
+
+## Alcance
+
+**Sí:** armonía, melodía, contrapunto, ritmo/groove, forma, orquestación, idioma instrumental, análisis, songwriting.
+
+**No:** generar archivos MIDI (→ `/midi-compose`), generar audio, operar DAW, mixing/mastering (→ `/audio-mix`), sound design (→ `/sfx-design`), notación en Sibelius/Dorico.
+
+## Cuándo usar
+
+- Problemas técnicos: "qué escala va sobre Cm7", "cómo modulo de C a Eb"
+- Problemas de craft: "esta melodía no se pega", "el estribillo se siente flojo"
+- Problemas vagos: "la transición es incómoda", "suena genérico" — traducirlos a movimientos compositivos es exactamente el trabajo de esta skill
+- Música de juego: temas, variaciones, material que después se vuelve adaptativo
+
+---
+
+## Método
+
+### 1. Traducir el problema
+
+El usuario casi nunca llega con vocabulario técnico. Antes de proponer nada, convertir la queja en un diagnóstico:
+
+| Queja | Diagnóstico probable | Dónde mirar |
+|---|---|---|
+| "El estribillo se siente flojo" | No hay contraste de registro/densidad/ritmo armónico con la estrofa | `references/form.md` |
+| "Suena genérico" | Progresión y ritmo armónico predecibles, melodía sin perfil | `references/harmony.md`, `references/melody.md` |
+| "No se me pega" | Falta un gesto repetible: motivo corto, salto identificable, ritmo asimétrico | `references/melody.md` |
+| "La transición es incómoda" | Salto de tonalidad/textura sin preparación ni pivote | `references/harmony.md` |
+| "Se cansa rápido" | Loop sin variación de material ni cambio de densidad | `references/game-music.md` |
+| "Se siente barroso" | Voicings apilados en el mismo registro, doblajes innecesarios | `references/orchestration.md` |
+
+### 2. Ofrecer opciones con trade-off
+
+Nunca una sola respuesta. Dos o tres movimientos, cada uno con el efecto que produce y su costo:
+
+> Para levantar el estribillo tenés tres palancas:
+> - **Subir el ritmo armónico** (un acorde por compás → dos): más urgencia, pero pierde espacio para la melodía
+> - **Abrir el registro** (melodía una 6ª arriba): más brillo y esfuerzo vocal percibido, pero quema el recurso si ya lo usaste
+> - **Cambiar el bajo a inversiones** (I → I/3 → IV): más movimiento sin tocar la melodía, efecto sutil
+
+### 3. Ser concreto
+
+Salida útil, no descriptiva:
+
+- **Armonía:** cifrado real — `| Cmaj7 | Am7 | Dm7 | G7sus4 G7 |`, no "una progresión menor melancólica"
+- **Melodía:** grados de escala con ritmo — `5 - 3 - 2 - 1` (blanca, negra, negra, redonda), portable a cualquier tonalidad
+- **Groove:** boceto en grilla de subdivisión, con dónde cae el acento y dónde se corre
+- **Voicing:** notas exactas por registro — `bajo: C2 / piano: E3-G3-B3-D4 / cuerdas: G4-C5`
+
+### 4. Validar
+
+Antes de cerrar: ¿la propuesta resuelve el problema original o lo esquiva? ¿Es tocable por el instrumento/voz target? ¿Respeta las convenciones del género sin ser esclava de ellas?
+
+---
+
+## Referencias
+
+Cargar solo la que aplica al problema:
+
+| Área | Archivo |
+|---|---|
+| Armonía funcional, modal, cromática, modulación, voice leading, reharmonización | `references/harmony.md` |
+| Construcción melódica, desarrollo motívico, estructura de frase | `references/melody.md` |
+| Formas populares y clásicas, transiciones, narrativa formal | `references/form.md` |
+| Groove, feel, métricas impares, polirritmia, recursos rítmicos | `references/rhythm-groove.md` |
+| Rangos y carácter instrumental, densidad de arreglo, voicing y textura | `references/orchestration.md` |
+| Música de juego: loops, variación, temas y transformación, escalas y modos por mood | `references/game-music.md` |
+
+---
+
+## Principios
+
+- Explicar **por qué** una técnica produce su efecto, no solo que existe
+- Respetar convenciones de género sin esclavizarse a ellas — nombrar la convención y la opción de romperla
+- El silencio y la reducción de densidad son movimientos compositivos, no falta de material
+- Si el usuario describe el objetivo en términos no técnicos, traducir primero y confirmar el diagnóstico antes de proponer
+- Cuando escribas material a archivo, preguntar "¿Escribo esto a `<path>`?" antes de usar Write
+
+---
+
+## Verdict
+
+Al cerrar una consulta:
+
+- **COMPLETE** — el problema está diagnosticado y hay al menos dos movimientos concretos con trade-off explícito
+- **CONCERNS** — hay propuesta pero el diagnóstico no se confirmó con el usuario, o la salida quedó descriptiva en vez de concreta
+- **BLOCKED** — falta información que no se puede inferir: tonalidad, instrumentación target, género, o el material existente
+
+## Next steps
+
+- `/midi-compose` para bajar el material a un `.mid` real
+- `/adaptive-music` para convertir un tema en un sistema que responde al gameplay
+- `/audio-bible` si las decisiones musicales no tienen dirección de la cual colgarse

package/skills/music-composition/references/form.md

@@ -0,0 +1,57 @@
+# Forma
+
+## El principio
+
+La forma administra **atención**. Cada sección existe para contrastar con la anterior. Si dos secciones consecutivas tienen la misma densidad, registro y ritmo armónico, funcionalmente son una sola.
+
+## Palancas de contraste
+
+Para diferenciar secciones, en orden de eficacia:
+
+1. **Densidad** — cuántos elementos suenan a la vez
+2. **Registro** — dónde vive la melodía
+3. **Ritmo armónico** — velocidad de cambio de acorde
+4. **Textura** — homofónica, polifónica, monofónica
+5. **Instrumentación** — quién toca
+6. **Dinámica** — la más obvia y la más débil por sí sola
+
+Un estribillo que solo es "más fuerte" no es un estribillo. Uno que sube el registro, dobla el ritmo armónico y agrega dos capas, sí.
+
+## Formas populares
+
+| Forma | Esquema | Nota |
+|---|---|---|
+| Estrofa-estribillo | A B A B (C) B | Estándar; el puente C aporta el contraste que evita la fatiga |
+| AABA | A A B A | Estándar de jazz/musical; el B es el "bridge" |
+| Verso-pre-estribillo-estribillo | A A' B A B | El pre-estribillo hace el trabajo de tensión |
+| Through-composed | sin repetición | Narrativo; costoso de escuchar dos veces |
+| Loop con capas | un solo material, capas entrando/saliendo | La forma nativa de música de juego |
+
+## Formas clásicas
+
+- **Binaria / ternaria** — AB, ABA. Base de todo
+- **Sonata** — exposición (dos temas en tonalidades distintas), desarrollo (fragmentación y modulación), reexposición (los dos temas en la tónica). El motor es el conflicto tonal
+- **Tema y variaciones** — un material, N transformaciones. La forma más directamente aplicable a juegos
+- **Rondó** — ABACA. El retorno del A da estabilidad, los episodios dan variedad
+- **Passacaglia / chacona** — bajo obstinado con variación arriba. Loop infinito que no aburre
+
+## Transiciones
+
+Lo que hace que dos secciones se peguen o se choquen:
+
+| Recurso | Efecto |
+|---|---|
+| **Anacrusa** | Anticipar la sección con una figura antes del downbeat |
+| **Turnaround** | 1-2 compases de armonía que devuelven a la tónica |
+| **Fill / break** | Silencio o solo percusión antes de la entrada |
+| **Pedal** | Sostener una nota mientras cambia todo arriba |
+| **Corte seco** | Sin preparación. Efectivo una vez por pieza |
+| **Riser / crescendo de densidad** | Sumar capas hacia el punto de cambio |
+
+La transición incómoda casi siempre es un cambio de tonalidad o textura sin ninguno de estos.
+
+## Narrativa formal
+
+Una pieza tiene un arco, y el arco tiene un punto de máxima información. Ubicarlo entre el 60% y el 75% de la duración: suficientemente tarde para haber construido, suficientemente temprano para tener resolución.
+
+La **reducción** funciona mejor que la adición para señalizar un momento importante. Sacar todo y dejar una voz llama más atención que sumar la décima capa.

package/skills/music-composition/references/game-music.md

@@ -0,0 +1,82 @@
+# Música de Juego
+
+## La restricción central
+
+La música de juego se escucha **muchas más veces que la música lineal, en duración desconocida, y compitiendo con SFX y diálogo**. Eso cambia las decisiones compositivas, no solo la implementación.
+
+Consecuencias directas:
+
+1. **Lo que en música lineal es "interesante" acá es "fatigante".** Un gesto llamativo cada 8 compases se vuelve insoportable a la vigésima repetición
+2. **La duración es indefinida.** No hay clímax garantizado; el arco tiene que funcionar cortado en cualquier punto
+3. **El registro medio no es tuyo.** Diálogo y feedback de UI viven ahí
+4. **El silencio es barato y potente.** Es el único recurso que no se gasta con la repetición
+
+## Escribir para repetición
+
+- **Loops largos con material corto** — un loop de 2 minutos construido con 4 células es menos fatigante que uno de 30 segundos con 12 ideas
+- **Evitar el gesto firma dentro del loop** — guardar los eventos distintivos para stingers o para capas que entran ocasionalmente
+- **Ritmo armónico lento** — la progresión que se puede escuchar 50 veces es la que no llama la atención sobre sí misma
+- **Ambigüedad de fin** — si el loop cierra con cadencia auténtica, cada repetición suena a arranque forzado. Cerrar con semicadencia, pedal o cadencia plagal
+- **Priorizar textura sobre melodía en gameplay sostenido** — la melodía fuerte es para momentos, no para fondo
+
+## Composición por capas
+
+La forma nativa. Escribir un mismo material en estratos que pueden entrar y salir sin romper nada:
+
+| Capa | Rol | Entra cuando |
+|---|---|---|
+| **Bed** | Pad/textura sostenida, define tonalidad | Siempre |
+| **Pulse** | Pulso rítmico mínimo | Hay actividad |
+| **Harmony** | Movimiento armónico explícito | Sube la tensión |
+| **Melody** | Tema identificable | Momento narrativo |
+| **Intensity** | Percusión densa, metales, disonancia | Combate/clímax |
+
+**Regla de composición:** cada capa tiene que sonar bien sola y en cualquier combinación con las de abajo. Eso se logra escribiéndolas todas contra la misma armonía y el mismo grid, y no dejando que ninguna dependa de otra para tener sentido.
+
+## Temas y transformación
+
+Un tema, N estados de juego. Las transformaciones más rentables:
+
+| Transformación | Estado que representa |
+|---|---|
+| Aumentación + reducción de densidad | Memoria, calma, safe zone |
+| Modo menor / ♭6 | Amenaza, pérdida |
+| Fragmentación + aumento de tempo | Persecución, urgencia |
+| Reorquestación a solo | Intimidad, muerte de personaje |
+| Sobre pedal disonante | Corrupción, algo está mal |
+| Métrica cambiada | Extrañeza, otro plano |
+
+Esto le da coherencia a una banda de sonido entera con una sola idea musical, y hace que el jugador "reconozca" sin saber por qué.
+
+## Modos por mood
+
+| Mood buscado | Recurso |
+|---|---|
+| Aventura, optimismo | Mixolidio, ♭7; cuartas y quintas abiertas |
+| Melancolía sin tragedia | Dórico, ♮6 |
+| Asombro, escala | Lidio, ♯4; acordes mayores por movimiento de terceras |
+| Amenaza | Frigio, ♭2; tritono; cluster |
+| Misterio | Escala de tonos enteros; armonía cuartal; ambigüedad de centro |
+| Tensión sostenida | Pedal + disonancia que no resuelve |
+| Vacío, desolación | Intervalos abiertos, silencio, un solo timbre |
+
+## Enfoques generativos
+
+Cuando el contenido tiene que exceder lo que se puede escribir a mano:
+
+- **Cadenas de Markov** — melodía estocástica entrenada sobre material propio. Preserva el idioma; no genera estructura
+- **L-systems / gramáticas recursivas** — generan *estructura* jerárquica (frases, secciones) por reescritura de reglas. Complemento natural de Markov, que no tiene forma
+- **Restricciones de armonía** — capa de validación: el generador propone, las reglas de voice leading y función filtran
+- **Selección estocástica de capas** — la variación viene de qué combinación suena, no de generar notas nuevas. Mucho más barato y más controlable
+
+**Recomendación práctica:** la selección estocástica de capas resuelve el 90% de la necesidad real de variación en un juego, sin ninguno de los riesgos de calidad de la generación de notas. Ir a Markov/L-systems solo cuando la variación de capas ya no alcanza.
+
+## Anti-patterns
+
+- **Loop de 30 segundos con melodía fuerte** — el camino más rápido a que el jugador baje la música
+- **Cadencia auténtica al final del loop** — cada vuelta suena a error
+- **Melodía en 500 Hz-2 kHz durante diálogo** — pelea con VO y pierde
+- **Todas las capas dependientes entre sí** — al quitar una, el resto suena incompleto
+- **Un tema por zona sin relación entre ellos** — la banda de sonido no acumula significado
+- **Componer a duración fija** — el gameplay no dura lo que dura tu pieza
+- **Sub saturado de música** — se come el espacio de los impactos