Capas independientes, projectM en el mapping y catalogo de la galeria

Mapping
- Los clips salian del reves: mapper.js activaba UNPACK_FLIP_Y_WEBGL, pero el
  modelo va con origen arriba-izquierda y texImage2D ya sube la primera fila
  en t=0, asi que el flip la mandaba al final. Comprobado renderizando el
  mapper real en Chromium headless con una fuente mitad roja / mitad azul.
- projectM se puede usar YA en una capa: los .milk de data/presets-projectm se
  traducen a Butterchurn en el navegador al elegirlos (milkdrop-preset-
  converter). La capa MilkDrop gana 'biblioteca' (butter | projectm) sin
  cambiar su firma, para no recrear el contexto WebGL al cambiar de una a otra.
  Medido: 100/100 presets de una muestra convierten, 84/84 de los que llevan
  shaders warp/comp; ~7 ms por preset.
- Cada capa tiene su pestana arriba y su propia vista, y '+ CAPA' crea una y
  entra en ella: con varias capas, ir y volver a MAPPING no era viable.
- Dos capas MilkDrop sin preset ya no salen identicas (cogian el indice 0):
  cada instancia elige uno al azar y lo escribe en el estado.
- Una capa nueva ya no nace en la fuente "motor", que es el lienzo del motor
  activo y hacia que dos capas ensenaran lo mismo.

Galeria de visuales
- scripts/catalogar-visuales.py: ficha de cada clip (pelicula, personajes,
  duracion) y, sobre todo, si es una silueta de verdad y cuanta figura tiene.
  Distingue silueta de corte crudo por el negro puro del fondo: 0,63-0,90
  frente a 0,04-0,06, sin zona gris.
- El panel lista los clips agrupados por pelicula, con nombre legible y aviso
  de los que casi no tienen figura, en vez del nombre del archivo.
- Soporte de siluetas con canal alfa (.webm VP9): transparencia de verdad, sin
  recorte por luminancia. El shader del mapper ya la respeta.

Documentacion
- docs/visuales.md nuevo; pendiente.md al dia con lo hecho y lo que queda.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

data/ayuda.json

@@ -13,9 +13,12 @@
       "title": "Mapping (projection mapping)",
       "body": [
         "Que es: deforma la salida de las visuales para encajarla en superficies fisicas (una pared en angulo, cajas, un objeto). En vez de un rectangulo plano, ajustas la imagen a la forma real.",
-        "Como se usa: marca 'Activar mapping' y 'Modo edicion'. En la ventana de las visuales (el proyector) veras cada superficie con sus cuatro esquinas: arrastralas con el raton para encajarla. Doble clic crea una superficie nueva; la tecla Supr borra la seleccionada.",
-        "Varias superficies: puedes crear varias (con 'Anadir superficie' o doble clic) y mapear la misma imagen en distintas zonas. Cada una se lista en el panel con su boton de borrar.",
-        "Se guarda solo en data/mapping.json y se mantiene al reiniciar. Quita 'Modo edicion' para ocultar los tiradores mientras pinchas.",
+        "Donde esta: en su propia pestana MAPPING, arriba a la derecha del titulo. La pestana MOTORES tiene lo de siempre (encendido, audio, motores y sus controles) y esta lo de encajar la imagen, para que no se mezclen el montaje y el directo. Cuando el mapping esta activado sale un punto verde en la pestana, aunque estes mirando MOTORES.",
+        "Como se usa: marca 'Activar mapping' y pulsa '+ Superficie'. En la previsualizacion del panel arrastra los puntos (con el raton o con el dedo) hasta encajar la forma sobre tu superficie real. Se ve en el proyector al instante.",
+        "Curvar: selecciona una superficie tocando dentro de ella y usa '+ malla' para subdividirla (hasta 6x6). Con la malla subdividida puedes arrastrar cualquier punto, no solo las esquinas, y adaptarla a superficies que no son planas.",
+        "'+ Mascara' anade un recuadro negro que tapa lo que no quieres que se vea (bordes, derrames de luz, huecos entre superficies).",
+        "'Modo edicion' saca ademas los tiradores sobre las propias visuales, por si prefieres ajustar alli con un raton. Quitalo para que no se vean mientras pinchas.",
+        "Se guarda solo en data/mapping.json y se mantiene al reiniciar.",
         "Ojo: no deforma projectM (que va en su propia ventana nativa). Usa Butterchurn, Hydra, Shaders o el Mezclador para tener todo mapeable."
       ]
     },
@@ -68,14 +71,16 @@
     "mixer": {
       "title": "Motor Mezclador VJ",
       "body": [
-        "Que es: el modo de video. Mezcla la imagen de una camara web con clips de video y efectos de color. Es lo mas parecido a un programa de VJ como Resolume.",
-        "Requisitos: una webcam USB que cumpla el estandar UVC. Para los clips, copia tus archivos de video en la carpeta data/videos del proyecto; van bien los .mp4 (H.264) y los .webm.",
-        "Anadir material: con el boton 'Subir video o imagen' del panel puedes mandar clips (mp4, webm...) e imagenes (jpg, png, gif, webp) a la galeria desde el movil o el ordenador, sin tocar carpetas. Tambien puedes generar clips automaticos de tus pelis con DETEKTION (carpeta VISUALES/DETEKTION).",
-        "Como se configura: elige la fuente (camara, video o mezcla de las dos), el modo de mezcla y los efectos de color con los controles deslizantes. La casilla de pulso al ritmo hace que la imagen lata con los graves.",
-        "Personajes sobre visuales: pon Fuente en Mezcla, Fondo en 'Visuales Butter', elige un clip _silueta-negro de la galeria (los de DETEKTION) y modo de mezcla 'Recorte'. El negro del clip se vuelve transparente y el personaje queda delante de MilkDrop latiendo con la musica. El deslizador de mezcla ajusta el umbral del recorte (subelo si queda halo oscuro en los bordes).",
-        "El preset de MilkDrop del fondo es el que estuviera elegido en el motor Butter: escogelo alli antes de entrar al Mezclador. projectM (el nativo) no puede ir de fondo: corre en una ventana aparte, fuera del navegador.",
-        "Si la pantalla se queda en negro, mira el aviso del panel: dice si falta elegir video, si la camara esta apagada o si algo fallo. La camara se reintenta apagando y encendiendo su casilla; un video que no carga se reintenta eligiendolo otra vez en la lista.",
-        "Si tienes mas de una camara, eligela en la lista de camaras del panel. El boton Actualizar lista de videos vuelve a leer la carpeta data/videos por si has copiado clips nuevos."
+        "Que es: el modo de video. Monta DOS CAPAS, una encima de otra, y las combina en directo. Es lo mas parecido a un programa de VJ como Resolume.",
+        "Las dos capas son siempre las mismas. Capa de abajo (el FONDO): la camara web o las visuales Butter (MilkDrop). Capa de encima (el CLIP): un video o una imagen de la galeria. El panel esta numerado en ese orden: 1 que se ve, 2 el fondo, 3 el clip, 4 como se juntan.",
+        "1 - Que se ve. 'Solo el fondo' ensena unicamente la capa de abajo. 'Solo el clip' ensena unicamente el video. 'Los dos' los combina, y es el unico caso en el que aparece el paso 4.",
+        "2 - Fondo. Aqui esta la respuesta a 'como pongo visuales de fondo': cambia el desplegable de Camara a 'Visuales Butter (MilkDrop)'. La camara se apaga sola (con su piloto) y su sitio lo ocupan las visuales. Debajo aparece el preset de MilkDrop que hace de fondo, con Anterior/Siguiente y la casilla de cambio automatico: es el mismo preset del motor Butter, asi que lo que elijas aqui queda elegido tambien alli.",
+        "3 - Clip. Los videos e imagenes de la galeria (carpeta data/videos). Con 'Subir video o imagen' mandas material nuevo desde el movil o el ordenador, sin tocar carpetas. Valen .mp4 (H.264), .webm, .jpg, .png, .gif y .webp. Tambien puedes generar clips de siluetas de tus pelis con DETEKTION (carpeta VISUALES/DETEKTION).",
+        "4 - Como se juntan. 'Recorte' vuelve transparente el negro del clip y deja la figura DELANTE del fondo; ahi el primer deslizador pasa a ser el umbral del recorte (subelo si queda halo oscuro en los bordes). Los demas modos (fundido, diferencia, multiplicar, sumar, capa) mezclan las dos capas enteras.",
+        "Personajes sobre visuales, la receta completa: 'Los dos' + Fondo 'Visuales Butter' + un clip _silueta-negro de la galeria + modo 'Recorte'. El personaje queda delante de MilkDrop latiendo con la musica.",
+        "La linea naranja de debajo del paso 4 dice en una frase lo que va a salir por el proyector con los ajustes que tengas puestos. Si no estas seguro de que estas montando, leela.",
+        "projectM (el nativo) no puede ir de fondo: corre en una ventana aparte, fuera del navegador. El fondo de visuales es siempre Butter.",
+        "Si la pantalla se queda en negro, mira el aviso del panel: dice si falta elegir video, si la camara esta apagada o si algo fallo. La camara se reintenta apagando y encendiendo su casilla; un video que no carga se reintenta eligiendolo otra vez en la lista."
       ]
     },
     "audio": {
@@ -103,6 +108,32 @@
         "Como se configura: elige un ejemplo de la libreria y se carga en el editor, listo para ejecutarse. Puedes modificarlo o pegar codigo tuyo. El boton Ejecutar lanza lo que haya en el editor. El boton Limpiar lo vacia.",
         "Si el codigo tiene un error, FOSFENO lo avisa en la parte de arriba del panel y el detalle tecnico queda en la consola del navegador."
       ]
+    },
+    "capas": {
+      "title": "Capas del mapping",
+      "body": [
+        "Que es: cada capa es una zona de la proyeccion con SU PROPIO visual. Puedes tener MilkDrop a la derecha, otro preset distinto a la izquierda y un video en el centro, cada uno encajado en su sitio.",
+        "Crear: '+ Capa' anade una zona nueva (sale escalonada para que no tape a la anterior). Selecciona la capa y en Propiedades eliges que se proyecta en ella.",
+        "El orden importa: la lista se lee como en cualquier mesa de VJ, la de arriba es la que queda DELANTE en el proyector. Con las flechas la subes o la bajas.",
+        "El circulo de cada fila enciende y apaga la capa sin borrarla: util para probar en directo. La ✕ la borra.",
+        "Sin ninguna capa y con el mapping activado, sale el motor elegido en MOTORES a pantalla completa, como siempre.",
+        "'+ Mascara' no es una capa: es un recuadro negro que se pinta encima de todo para tapar derrames de luz."
+      ]
+    },
+    "fuentes": {
+      "title": "Que se proyecta en una capa",
+      "body": [
+        "Cada capa elige su fuente por separado. Estas son:",
+        "El motor de MOTORES: lo que este puesto en la otra pestana (Butterchurn, Hydra, Shaders o el Mezclador). Si pones esto en varias capas, todas ensenan lo mismo: sirve para repetir el mismo visual en varias paredes.",
+        "Visuales MilkDrop propias: una instancia de Butterchurn SOLO para esta capa, con su preset. Es lo que permite tener dos looks de MilkDrop distintos a la vez, uno en cada zona. Puedes fijar un preset o dejar que vaya cambiando solo cada X segundos.",
+        "Shader GLSL: uno de los shaders de la libreria, reaccionando al audio igual que en el motor de shaders.",
+        "Clip o imagen de la galeria: un archivo de data/videos. Los clips van en bucle y sin sonido. Si dos capas usan el mismo clip, se reproduce una sola vez y se comparte (no cuesta el doble).",
+        "Camara: la webcam. Tambien se comparte entre capas.",
+        "Negro: no pinta nada. Sirve para tapar una zona sin usar mascara.",
+        "Opacidad y mezcla: la opacidad deja ver lo que hay debajo; 'Sumar' apila luz en vez de tapar (las zonas oscuras de la capa dejan pasar la de abajo), que es como se hacen los solapes bonitos.",
+        "projectM no puede ir en una capa: es un programa nativo que corre en su propia ventana, fuera del navegador. Para el mismo tipo de visual, usa 'Visuales MilkDrop propias', que son los mismos presets.",
+        "Ojo con la Raspberry: cada capa de MilkDrop o de shader es un motor de verdad funcionando. Dos o tres van bien; con muchas mas la cosa se arrastra. Los clips y la camara son mucho mas baratos."
+      ]
     }
   }
-}
+}

data/videos/README.txt

@@ -15,3 +15,17 @@ Ejemplo desde linea de comandos para reescalar un video pesado:
   ffmpeg -i original.mp4 -vf scale=-2:720 -c:v libx264 -an clip.mp4
 
 Los videos NO se suben al repositorio (estan en .gitignore).
+
+
+Catalogo
+--------
+
+Cada vez que metas clips nuevos, vuelve a pasar el catalogador: es lo que hace
+que el panel los liste por pelicula y con nombre legible en vez de por nombre
+de archivo, y lo que avisa de los que casi no tienen figura.
+
+  python3 scripts/catalogar-visuales.py            # cataloga
+  python3 scripts/catalogar-visuales.py --limpiar  # + aparta los que no son
+                                                   #   siluetas (ver docs)
+
+Explicado a fondo en docs/visuales.md.