Mapping in-browser (Fase 1) + trabajo en curso

Projection mapping editable desde el navegador, sin herramientas externas:
- web/stage/mapper.js (nuevo): compositor WebGL que texturiza el motor activo
  sobre superficies deformables (homografia por vertice: keystone correcto).
- Editor con raton en el escenario (crear, arrastrar esquinas, mover, borrar)
  y previsualizacion arrastrable en el panel (raton/tactil) para editar desde
  el movil sin tocar la ventana de visuales.
- Backend: estado "mapping" + evento set_mapping, persistido en data/mapping.json
  (ignorado en git). Seccion "Mapping" en el panel + texto de ayuda.
- Solo motores web (butterchurn/hydra/shaders/mixer); projectM no se mapea.
- .gitignore: excluye config de runtime (mapping.json, pm-favoritos.json).

Incluye ademas trabajo en curso previo sin commitear (server.py, stage.js,
panel.js/css, ayuda.json, hydra-sketches.json, problemas.md,
start-projectm.sh), subido junto a peticion del autor.

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

data/ayuda.json

@@ -9,6 +9,16 @@
         "Para apagar la Raspberry de verdad, usa los botones de Reiniciar y Apagar del final del panel."
       ]
     },
+    "mapping": {
+      "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.",
+        "Ojo: no deforma projectM (que va en su propia ventana nativa). Usa Butterchurn, Hydra, Shaders o el Mezclador para tener todo mapeable."
+      ]
+    },
     "engines": {
       "title": "Motor de visuales",
       "body": [
@@ -20,9 +30,15 @@
     "projectm": {
       "title": "Motor projectM",
       "body": [
-        "Que es: el visualizador clasico de MilkDrop, compilado dentro de la Raspberry. Reacciona al audio por si solo y va rotando entre miles de presets.",
-        "Requisitos: se compila durante la instalacion. Si la compilacion fallo, este motor sale como no disponible y hay que volver a compilarlo. Los otros cuatro motores funcionan sin el.",
-        "Como se configura: projectM es un programa nativo, su ventana se pone por encima de las demas visuales. Los botones Anterior y Siguiente cambian de preset, pero eso solo funciona en sesion X11; en Wayland projectM rota presets automaticamente."
+        "Que es: el visualizador clasico MilkDrop en version nativa. Corre fuera del navegador, en su propia ventana, y reacciona a la musica igual que el resto de motores.",
+        "Probar y elegir: los botones Anterior/Siguiente saltan a mano y la linea 'En pantalla' dice como se llama lo que se esta viendo. Cuando aparezca uno que te guste, pulsa Congelar visual: se queda clavado al instante, sin cortes (vuelve a pulsar para soltarlo).",
+        "Fijar este estilo apunta en las listas la categoria y el visual que se ven ahora: projectM rotara solo entre las variantes de ese mismo look. Tambien puedes elegirlos a mano en las listas.",
+        "Elegir a dedo: cada visual es una carpeta con varias variantes .milk. Con categoria y visual elegidos, la tercera lista muestra las variantes: elige una y projectM se queda con esa exacta (y sobrevive a reinicios, al contrario que Congelar).",
+        "Favoritos: cuando aparezca un visual que te guste, pulsa 'Guardar el de pantalla' y se apunta en la lista de favoritos (se guardan en data/pm-favoritos.json, sobreviven a reinicios). En directo, cada favorito es un boton: tocalo y se lanza esa variante exacta. La X lo quita de la lista.",
+        "Ritmo de cambio: el deslizador de segundos por visual controla cada cuanto rota en automatico (de 5 segundos a 10 minutos), y la casilla de orden aleatorio decide si va en orden o barajado.",
+        "Pantalla: elige en que monitor se abre projectM. En Auto se abre siempre donde este el escenario (el proyector). Si conectas o quitas pantallas, pulsa Buscar dispositivos en el apartado Audio para refrescar la lista.",
+        "Cada cambio de listas o del deslizador relanza projectM y la pantalla queda en negro un segundo: es normal (Congelar y Anterior/Siguiente no relanzan). Al relanzar, el visual congelado se suelta.",
+        "El audio lo coge de la fuente elegida en el apartado Audio (microfono o audio del navegador), como los demas motores."
       ]
     },
     "butterchurn": {
@@ -53,8 +69,12 @@
       "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, conectada antes de encender la Raspberry. Para los clips, copia tus archivos de video en la carpeta data/videos del proyecto.",
+        "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."
       ]
     },
@@ -62,9 +82,11 @@
       "title": "Audio y BPM",
       "body": [
         "Que es: aqui se elige por que entrada escucha FOSFENO la musica, y se ve el BPM que detecta.",
-        "Requisitos: un microfono USB o una tarjeta de sonido USB con entrada. La Raspberry no tiene entrada de audio propia.",
-        "Como se configura: por defecto FOSFENO coge el microfono USB automaticamente. Si tienes varias entradas, eligela en la lista. El BPM se calcula solo a partir del sonido y tarda unos segundos en estabilizarse.",
-        "Si conectas el microfono o la camara con la Raspberry ya encendida, pulsa el boton Buscar dispositivos de nuevo y apareceran en sus listas sin tener que reiniciar."
+        "Dos fuentes: 'Microfono (sala)' escucha el ambiente con un micro; 'Audio del navegador' capta directamente lo que suena en el propio equipo (Spotify, YouTube, lo que reproduzcas) aunque lo oigas por los cascos, sin necesidad de micro.",
+        "Audio del navegador: al elegirlo, FOSFENO mueve solo la captura al 'monitor' del sistema (PulseAudio/PipeWire) con pactl. Vale para todos los motores, projectM incluido. Si cambias de salida (por ejemplo conectas o quitas unos cascos bluetooth), pulsa 'Aplicar entrada' para que se recoloque.",
+        "Si sale un aviso de que no se pudo mover la captura, comprueba que algo esta sonando y vuelve a pulsar 'Aplicar entrada'. Como ultimo recurso, revisa 'pactl list sources short' en una terminal.",
+        "Como se configura: por defecto FOSFENO coge el microfono. Si tienes varias entradas, eligela en la lista. El BPM se calcula solo a partir del sonido y tarda unos segundos en estabilizarse.",
+        "Si conectas el microfono o la camara con el equipo ya encendido, pulsa el boton Buscar dispositivos de nuevo y apareceran en sus listas sin tener que reiniciar."
       ]
     },
     "sensibilidad": {
@@ -83,4 +105,4 @@
       ]
     }
   }
-}
+}

data/hydra-sketches.json

@@ -18,5 +18,9 @@
   "estrellas": {
     "name": "Estrellas",
     "code": "noise(() => 3 + a.fft[1]*6, 0.15).thresh(() => 0.62 - a.fft[0]*0.45).color(0.7,0.9,1.0).modulateRotate(osc(2), 0.2).out(o0)"
+  },
+  "piratas-recorte": {
+    "name": "PIRATAS: personaje sobre visuales",
+    "code": "/* personaje recortado (clip _silueta-negro) con visuales detras. Cambia el nombre del clip por cualquier otro _silueta-negro de la galeria. */ s1.initVideo(\"/data/videos/p3-duelo_silueta-negro.mp4\"); osc(8, 0.06, () => 1 + a.fft[0]*2).color(1.0, 0.45, 0.1).kaleid(3).modulate(noise(2), () => a.fft[1]*0.5).out(o1); src(o1).layer(src(s1).luma(0.12, 0.18)).out(o0)"
   }
-}
+}