ProMedia

Proyección multimedia para culto y evento. Ventana Control (operador) + ventana Output (pantalla completa en el 2.º monitor / proyector). Todo el código vive en la raíz de este repo.

Referencia del código (arquitectura, API, datos, desarrollo): docs/README.md. Esta página es la guía de arranque y de uso en sala.

Arquitectura

Pieza	Rol
apps/web	SPA Vite + React — rutas /control, /output, /
apps/hub	Hono + WebSocket — sesiones, assets, Biblia, playlists
@promedia/shared	Protocolo, temas, transiciones, tipos de sesión
@promedia/item-types	Registry Preview / En vivo / Output (texto, imagen, vídeo, YouTube, Biblia, presentación)
@promedia/media	Almacenamiento local (disco) + adapter S3 stub
@promedia/i18n	Locales ES · EN · PT · FR · ZH

.
  apps/web/          # Control + Output
  apps/hub/          # API :8787 + WS
  packages/shared/
  packages/item-types/
  packages/media/
  packages/i18n/
  scripts/dev.mjs    # pnpm dev (hub + web)
  portable/          # empaquetado runnable

Servicio	Puerto	URL típica
Hub (API + WS)	8787	http://localhost:8787 (también en la IP LAN)
Web (Vite)	5173+	http://localhost:5173 (o 5174–5178 si 5173 está ocupado)

Abrí siempre /control, no / (la Home es solo un enlace mínimo).

Control remoto por LAN (teléfono)

Con PROMEDIA_MODE=lan (default), hub y Vite escuchan en todas las interfaces (0.0.0.0), no solo localhost.

1. Arrancá ProMedia en la PC del proyector (Abrir-ProMedia.* / pnpm dev). Dejá Output en esa máquina.
2. Teléfono y PC en la misma Wi‑Fi.
3. En la Terminal (o el pie de Control en la PC) aparece algo como
   http://192.168.x.x:5173/control — abrila en el navegador del móvil.
4. En el móvil administrás Guion / En vivo / escenas / temas. La proyección fullscreen sigue en la PC.

Si el firewall bloquea, permití Node en los puertos 5173 y 8787 (entrada LAN). Solo localhost: HUB_HOST=127.0.0.1.

---

Cómo arrancar

Importante: trabajá en la raíz de este repo (ProMedia/).

Mac — doble clic (Finder)

Deps subtítulos (una vez): brew install yt-dlp ffmpeg whisper-cpp — luego reiniciá ProMedia (el hub busca en PATH + /opt/homebrew/bin + /usr/local/bin).

1. Finder → carpeta del repo ProMedia
2. Doble clic en start-mac.command o Abrir-ProMedia.command (mismo arranque; el segundo es atajo con nombre claro)
3. Primera vez en macOS: clic derecho → Abrir
4. Dejá la Terminal abierta; al estar listos hub+web, el script abre Control (/control) en el puerto real de Vite
5. Si copiaste el atajo al Escritorio y ves UI vieja: tras git pull, volvé a copiar Abrir-ProMedia.command desde esta carpeta
6. Enlaces fijos: open-control.html (prueba 5173–5178) o ProMedia-Control.url

Windows — doble clic (Explorador)

1. Explorador → ProMedia
2. Doble clic en start-windows.bat o Abrir-ProMedia.bat (llaman a start-windows.ps1)
3. Requisitos: Node.js 20+ y npm install -g pnpm (una vez). Si falta node_modules, el script corre pnpm install
4. Deps subtítulos (una vez): instalá yt-dlp, ffmpeg y whisper-cli (p. ej. Scoop: scoop install yt-dlp ffmpeg + build/binario whisper.cpp) y asegurate de que estén en el PATH. Alternativa sin Whisper: .srt/.vtt en data/subtitles/sidecars/
5. Abre Control en el puerto real (5173–5178)

Linux — doble clic / terminal

1. En la raíz del repo, la primera vez: chmod +x start-linux.sh Abrir-ProMedia.sh
2. Doble clic o ./start-linux.sh / ./Abrir-ProMedia.sh
3. Atajo: ProMedia.desktop (editá Exec/Path si lo copiás al Escritorio; en GNOME: “Permitir iniciar” / Mark as Trusted)
4. Deps subtítulos (una vez): sudo apt install ffmpeg (o equivalente) + yt-dlp + binario whisper-cli en PATH; el hub también mira /usr/bin y /usr/local/bin
5. Misma lógica: lock, pnpm install si hace falta, pnpm dev, abre /control

Terminal (cualquier SO)

cd /ruta/a/ProMedia
pnpm install   # primera vez (o si falta node_modules)
pnpm dev

Ejemplo (Mac, Escritorio):

cd ~/Desktop/ProMedia && pnpm dev

pnpm dev usa concurrently con logs [hub] / [web]. Espera a que este hub loguee listening y /health responda; imprime la URL real de Vite. Si 5173 está ocupado, puede ser 5174+ — usá esa URL, no asumas 5173.

Una sola instancia

No abras dos pnpm dev / dos launchers a la vez.

Los launchers usan un lock (.promedia-dev.lock):

• Primera instancia: puede liberar puertos ProMedia en 8787 y 5173–5178, luego arranca
• Segunda instancia: no mata puertos (evita SIGTERM 143 sobre Vite) y te avisa que ya hay una corriendo

pnpm dev solo tumba el proceso hermano si hay failure (no si Vite sale 0 tras un SIGTERM externo).

Si ves EADDRINUSE / “puerto ya está en uso”:

# Mac / Linux
lsof -nP -iTCP:8787 -sTCP:LISTEN
lsof -nP -iTCP:5173 -sTCP:LISTEN
kill <PID>

REM Windows (cmd)
netstat -ano -p tcp | findstr :8787
netstat -ano -p tcp | findstr :5173
taskkill /PID <PID> /F

Comprobar el hub:

curl -s http://localhost:8787/health

Fallback: dos terminales

cd /ruta/a/ProMedia

# Terminal A
pnpm dev:hub

# Terminal B
pnpm dev:web

Sin hub, Control muestra que el hub no está corriendo (con reintento).

Solo hub + smoke

pnpm --filter @promedia/hub start   # :8787
node scripts/smoke-hub-ws.mjs

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗