morfeo 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,22 @@
+Licencia de uso de Morfeo
+
+Copyright (c) 2026 Uriel Gómez. Todos los derechos reservados.
+
+1. Uso permitido. Puedes instalar y usar Morfeo sin costo para crear videos,
+   incluidos videos con fines comerciales. Los videos que generes son tuyos.
+
+2. Lo que no está permitido sin permiso escrito del autor: copiar, modificar,
+   redistribuir, sublicenciar o vender el código fuente de Morfeo, ni publicar
+   versiones derivadas o paquetes que lo incluyan.
+
+3. Terceros. Morfeo usa software y recursos con sus propias licencias, que
+   también debes cumplir:
+   - Remotion (https://remotion.dev/license): gratis para personas y empresas
+     de hasta 3 personas; empresas más grandes necesitan licencia de Remotion.
+   - Voces Kokoro (Apache 2.0), whisper.cpp (MIT), Three.js (MIT), React (MIT).
+   - Fuentes Anton, Montserrat y JetBrains Mono (SIL Open Font License 1.1).
+   - Si usas servicios externos (ElevenLabs, OpenAI, Anthropic), aplican sus
+     términos y lo que cobren.
+
+4. Sin garantía. Morfeo se entrega "tal cual", sin garantía de ningún tipo. El
+   autor no es responsable de daños derivados de su uso.

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# Morfeo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Documentación: [ureckchan.github.io/morfeo](https://ureckchan.github.io/morfeo/)** · Ejemplos: [github.com/UreckChan/morfeo](https://github.com/UreckChan/morfeo)
+
+Genera videos verticales animados (Shorts, TikTok, Reels) desde código: escribes las escenas y Morfeo agrega
+la voz, la música, los efectos de sonido, los subtítulos, las animaciones y la miniatura.
+
+- **Estilos:** 10 incluidos, y puedes crear los tuyos:
+  - `datos-curiosos`: texto grande con contorno e íconos 3D;
+  - `explicativo`: papel claro, titulares y tarjetas;
+  - `documental`: océano, rayos de luz y datos;
+  - `ilustrado`: escenarios ilustrados y personajes;
+  - `historia`: siluetas, foco de luz y misterio;
+  - `mesa`: objetos 3D y contadores;
+  - `serie`: series con personaje, HUD (días, barras), cartas VS y "comenta";
+  - `infografia`: medidores, barras, globos y rayos X;
+  - `3d`: tus escenas `.glb` con recorrido de cámara;
+  - `minimal`: oscuro y limpio.
+- **Motor de capas:** cada escena se arma con imágenes, texto, contadores, chips, tarjetas, teléfonos, formas,
+  grupos (formaciones, pilas), modelos 3D o tus propios componentes de React. Todo se anima justo en la palabra que dice la voz.
+
+- **Voces:** Kokoro (gratis, en tu computadora, más de 50 voces y mezclas), ElevenLabs, OpenAI, tu propia
+  grabación por escena o cualquier servicio que conectes con una función.
+- **Música:** 7 estilos generados sin derechos de autor, o tu propia pista (mp3, wav, flac, ogg). Baja sola cuando habla la voz.
+- **Guiones:** los escribes tú, o Claude escribe el video completo a partir de un tema o de tu texto.
+- **Subtítulos:** palabra por palabra; con Whisper quedan sincronizados con la voz real.
+
+## Instalar
+
+Necesitas Node.js 18+. Python 3.10–3.13 también, pero el instalador te ayuda a conseguirlo.
+
+```bash
+npx morfeo nuevo mi-canal
+cd mi-canal
+npm install
+npx morfeo instalar
+npx morfeo render
+```
+
+`morfeo instalar` se corre una sola vez por computadora y deja todo en `~/.morfeo`:
+
+- busca Python y, si falta, ofrece instalarlo (Homebrew en Mac, winget en Windows);
+- crea un entorno aislado con las librerías de voz;
+- descarga las voces (~340 MB) y el navegador de render;
+- pregunta si quieres Whisper (~470 MB). En Mac, Whisper necesita `xcode-select --install`.
+
+`npx morfeo doctor` dice qué falta.
+
+## Comandos
+
+| Comando | Qué hace |
+|---|---|
+| `morfeo nuevo <carpeta>` | Crea un proyecto con un video de ejemplo |
+| `morfeo lista` | Videos del proyecto y cuáles ya están hechos |
+| `morfeo render [id...]` | Genera los que faltan (`--todos` para todos, `--gpu` para usar la tarjeta de video) |
+| `morfeo studio` | Abre el editor en el navegador para ver y ajustar en vivo |
+| `morfeo guion "tema"` | Claude escribe un video completo en `guiones/<id>.json` (`--estilo documental`, `--imagenes`) |
+| `morfeo estilos` | Lista los estilos visuales |
+| `morfeo guion --desde guion.txt` | Convierte tu texto en escenas (con IA, o `--sin-ia`: una escena por frase) |
+| `morfeo instalar` / `doctor` | Prepara o revisa la computadora |
+
+## Un video
+
+```js
+// videos.mjs
+import {defineVideos} from 'morfeo';
+
+export default defineVideos({
+	cielo: {
+		title: '¿Por qué el cielo es azul? 🌤️',
+		voice: [['em_alex', 0.6], ['am_michael', 0.4]],
+		music: 'lofi',
+		scenes: [
+			{type: 'title', say: '¿Sabías por qué el cielo es azul?', rows: [['¿POR QUÉ', '#FFF', 150], ['ES AZUL?', '#50DCFF', 230]], icon: 'question'},
+			{type: 'year', say: 'Lord Rayleigh lo explicó en mil ochocientos setenta y uno.', show: 'Lo explicó en 1871.', pre: 'RAYLEIGH', year: 1871, sub: 'DISPERSIÓN'},
+			{type: 'cta'},
+		],
+	},
+});
+```
+
+**Escenas:**
+- `title`: el gancho.
+- `text`: filas grandes de texto.
+- `year`: una fecha.
+- `icon`: ícono grande con etiqueta.
+- `compare`: A vs B, el cambio ocurre en la palabra `at`.
+- `card`: tarjeta tipo código cuyo valor cambia.
+- `dialog`: ventana con un botón que se pulsa en la palabra `click`.
+- `cta`: cierre con tu marca.
+
+`say` es lo que dice la voz. `show` es el subtítulo cuando debe ser distinto, por ejemplo con cifras. Las escenas
+`aliens`, `memory` y `morph` son especiales de los videos de ejemplo.
+
+## Estilos y capas
+
+Cada video elige un `estilo` (o usa el de `morfeo.config.mjs`). `npx morfeo estilos` los lista.
+
+```js
+// guiones/cachalote.mjs
+export default {
+	estilo: 'documental',
+	voice: 'narrador',
+	music: 'ballad',
+	scenes: [
+		{say: '¿Sabías que las orcas le tienen miedo a un solo animal?', capas: [
+			{tipo: 'imagen', src: 'cachalote.png', ancho: 700, entrada: 'deslizar-der', mover: {a: [480, 980]}, flotar: true},
+			{tipo: 'chip', texto: '×5', x: 760, y: 1260, en: 'animal', sonido: 'pop'},
+		]},
+		{type: 'dato', say: 'Baja a más de dos mil metros.', show: 'Baja a más de 2.000 metros.', valor: 2000, sufijo: ' m', camara: {zoom: [1.15, 1]}},
+		{say: 'Y forman un círculo.', capas: [
+			{tipo: 'grupo', repetir: 8, disposicion: 'circulo', radio: 300, orientar: 90, capa: {tipo: 'imagen', src: 'cachalote.png', ancho: 220}},
+		]},
+		{type: 'cta'},
+	],
+};
+```
+
+**Tipos de escena:**
+- `capas`: solo tus capas.
+- `titular`: etiqueta "// paso 1", titular con `*palabra*` resaltada y número.
+- `dato`: número que cuenta.
+- `lista`: tarjeta que se palomea.
+- `telefono`
+- `comparar`
+- `cta`
+
+Todas aceptan `capas`, `fondo`, `camara` (zoom, paneo, temblor), `transicion` (corte, fundido, deslizar, zoom) y `tema`.
+
+**Capas:**
+- `imagen`, `video`, `texto` (con `*resaltado*` y efecto de escribir), `contador` (grande, LCD o chip; lineal o exponencial);
+- `chip`, `etiqueta`, `numero`, `tarjeta`, `telefono`;
+- `forma` (rect, círculo, línea, flecha), `icono`, `emoji`, `marca`, `particulas`;
+- `grupo`: varias capas juntas, o una repetida en círculo, fila, cuadrícula, pila o al azar;
+- `modelo`: tu `.glb`, o formas 3D incluidas como moneda, billete, lingote, cubo y esfera; con `cantidad` y `crecer` forma una pila que crece;
+- `componente`: tu propio React.
+
+**Animación de cada capa:**
+- `en` y `hasta` aceptan segundos o una palabra de la voz;
+- `entrada`: escala, rebote, deslizar-izq, caer, girar…;
+- `mover`, `escalar`, `girar`, `flotar` y `latir`;
+- `sonido`: pop, whoosh, tick, glitch o ding.
+
+Tus imágenes, videos y modelos van en `assets/`. Para que la IA dibuje, usa `{tipo: 'imagen', generar: 'un oso pardo de frente'}`
+con `imagenes: {proveedor: 'openai', estilo: 'ilustración plana, colores cálidos'}` en el config. El `estilo` mantiene la misma
+línea gráfica en todas las imágenes. Cada imagen se genera una sola vez (caché).
+
+**Series y personajes:**
+- `personajes: {neto: {poses: {normal: './neto.png', feliz: './neto-feliz.png'}}}` en el config. Con `referencia: './neto.png'`, una pose escrita como texto (`triste: 'llorando'`) la genera la IA a partir de esa imagen, así sigue siendo el mismo personaje.
+- En la escena: `{tipo: 'personaje', nombre: 'neto', pose: 'normal', poses: [{en: 'enamorado', pose: 'feliz'}], hablar: true}`.
+- `hud: [...]` en el video: capas fijas en todos los cuadros (día, barra "probabilidad 0%", hora). `cambios: [{en: {escena: 3}, valor: 15}]` las actualiza con animación.
+- Escena `eleccion`: cartas VS con "¡COMENTA!", o `formato: 'botones'` (ABRIR / NO ABRIR).
+- Capas de interfaz: `barra`, `medidor`, `votacion`, `estado` (hora, batería, día), `noticia` (cintillo), `chat`, `onda`, `globo` y `seguir`.
+- `imagen` con `cambiarA: {src, en, efecto: 'circulo'}` revela otra imagen, por ejemplo en modo rayos X.
+
+**Escenas 3D:**
+- `{tipo: 'escena3d', src: 'casa.glb', camara: [{en: 0, pos: [12, 7, 16], mirar: [0, 0, 0]}, {en: 'drenaje', pos: [5, 1, 9]}], animacion: true, ocultar: [{nodo: 'Tierra', en: 'tierra'}]}`.
+- La cámara recorre la escena en las palabras que indiques.
+- Las animaciones del archivo van sincronizadas con el video.
+- Las piezas se muestran u ocultan por su nombre de Blender.
+
+**Estilo propio:** `estilos: {'mi-marca': {base: 'minimal', colores: {acento: '#00E0A0'}, fondo: {tipo: 'imagen', src: 'fondo.png'}}}`.
+
+**Componentes propios:** `componentes: {Mapa: './escenas/Mapa.tsx'}`. Reciben `t`, `dur`, `palabras`, `tema` y `cuando('palabra')`.
+
+## Voces
+
+```js
+voice: 'em_alex'                                      // una voz Kokoro
+voice: [['ef_dora', 0.6], ['af_heart', 0.4]]          // mezcla
+voice: './voces/mi-voz.npy'                           // estilo de voz Kokoro propio
+voice: {proveedor: 'elevenlabs', voz: 'VOICE_ID'}     // ELEVENLABS_API_KEY en .env
+voice: {proveedor: 'openai', voz: 'nova'}             // OPENAI_API_KEY en .env
+voice: {proveedor: async (texto) => './audio.wav'}    // tu propio servicio
+```
+
+O graba tú: `{type: 'text', say: 'Hola', audio: './grabaciones/hola.wav', rows: [...]}`.
+
+Lo que se pide a servicios de pago se guarda en caché (`.morfeo/cache`). La misma frase no se vuelve a pedir ni a cobrar.
+
+## Música
+
+`music: 'lofi'` (también `lofi2`, `chillpop`, `synth`, `house`, `ballad`, `trap`), `music: './musica/cancion.mp3'`,
+`music: {archivo: './musica/cancion.mp3', volumen: 0.7, inicio: 12}` o `music: false`.
+
+Para no repetir, define alias en `morfeo.config.mjs` con `voces: {...}` y `musicas: {...}`.
+
+## Claves (.env)
+
+Copia `.env.example` como `.env`. Solo llena lo que uses:
+
+- `ANTHROPIC_API_KEY`: guiones con IA.
+- `ELEVENLABS_API_KEY` u `OPENAI_API_KEY`: voces por servicio.
+
+Nunca subas `.env` a git.
+
+## Desde código
+
+```js
+import {render, guionConIA, guardarVideo} from 'morfeo';
+
+const {id, video} = await guionConIA({tema: 'el origen del café'});
+guardarVideo('./guiones', id, video);
+await render({ids: [id]});
+```
+
+## Licencia
+
+Uso gratuito para crear videos, incluidos los comerciales. El código es de Uriel Gómez; no se permite
+redistribuirlo ni modificarlo. Remotion tiene su propia licencia: gratis para personas y equipos de hasta 3 personas.
+Detalles en [LICENSE](LICENSE).

package/bin/morfeo.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// CLI de Morfeo. `npx morfeo ayuda` para ver los comandos.
+import fs from 'node:fs';
+import path from 'node:path';
+import {ErrorMorfeo} from '../lib/config.mjs';
+import {PAQUETE, VERSION} from '../lib/entorno.mjs';
+
+const AYUDA = `Morfeo ${VERSION} · videos verticales animados con voz, música y subtítulos
+
+Uso: npx morfeo <comando> [opciones]
+
+Primeros pasos
+  instalar              Prepara tu computadora: Python, voces, navegador y (opcional) Whisper
+      --si                responde "sí" a todo        --whisper / --sin-whisper
+  nuevo <carpeta>       Crea un proyecto de ejemplo listo para renderizar
+  doctor                Revisa qué está instalado y qué falta
+
+Videos
+  lista                 Muestra los videos del proyecto y cuáles ya están hechos
+  render [id...]        Genera los videos que faltan (o los que indiques)
+      --todos             regenera todos
+      --gpu               usa la tarjeta de video (más rápido; si falla, quítalo)
+  studio                Abre el editor en el navegador para ver y ajustar en vivo
+  estilos               Lista los estilos visuales disponibles
+
+Guiones
+  guion "tema"          La IA (Claude) escribe un video completo sobre el tema
+  guion --desde f.txt   Convierte tu guion en escenas (con IA; --sin-ia: una escena por frase)
+      --estilo documental   estilo visual (por defecto, el del proyecto)
+      --imagenes            pide ilustraciones con IA (necesita OPENAI_API_KEY)
+      --id nombre  --voz em_alex  --duracion 40  --idioma "inglés"  --tono "humor"
+
+Opciones generales
+  --proyecto <carpeta>  Proyecto a usar (por defecto, la carpeta actual)
+  -v, --version         Versión
+`;
+
+function opciones(argv) {
+	const pos = [];
+	const op = {};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === '-v') op.version = true;
+		else if (a === '-h') op.ayuda = true;
+		else if (a.startsWith('--')) {
+			const [k, v] = a.slice(2).split('=');
+			const clave = k.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+			const sig = argv[i + 1];
+			const conValor = ['proyecto', 'desde', 'id', 'voz', 'duracion', 'idioma', 'estilo', 'tono', 'musica', 'titulo', 'modelo', 'puerto'];
+			if (v != null) op[clave] = v;
+			else if (conValor.includes(clave) && sig != null && !sig.startsWith('--')) op[clave] = argv[++i];
+			else op[clave] = true;
+		} else pos.push(a);
+	}
+	return {pos, op};
+}
+
+async function main() {
+	const [cmd = 'ayuda', ...resto] = process.argv.slice(2);
+	const {pos, op} = opciones(resto);
+	const proyecto = path.resolve(op.proyecto ?? '.');
+	if (cmd === '-v' || cmd === '--version' || op.version) return console.log(VERSION);
+
+	switch (cmd) {
+		case 'instalar':
+		case 'install': {
+			const {instalar} = await import('../lib/instalar.mjs');
+			return instalar({si: !!op.si, whisper: op.whisper ? true : op.sinWhisper ? false : null});
+		}
+		case 'doctor': {
+			const {doctor} = await import('../lib/instalar.mjs');
+			const {cargarEnv} = await import('../lib/render.mjs');
+			cargarEnv(proyecto);
+			const e = await doctor();
+			if (e.some((x) => !x.bien && !x.nombre.includes('opcional'))) process.exitCode = 1;
+			return;
+		}
+		case 'nuevo':
+		case 'new':
+			return nuevo(pos[0], op);
+		case 'lista':
+		case 'ls': {
+			const {lista} = await import('../lib/render.mjs');
+			const l = await lista({proyecto});
+			if (!l.length) return console.log('Este proyecto no tiene videos todavía. Crea uno con:  npx morfeo guion "tu tema"');
+			for (const v of l) console.log(`[${v.hecho ? '✔' : ' '}] ${v.id.padEnd(16)} ${v.titulo}`);
+			console.log(`\n${l.filter((v) => v.hecho).length} de ${l.length} hechos`);
+			return;
+		}
+		case 'render': {
+			if (op.gpu) process.env.MORFEO_GL = 'angle';
+			const {render} = await import('../lib/render.mjs');
+			await render({proyecto, ids: pos, todos: !!op.todos || pos[0] === 'todos'});
+			return;
+		}
+		case 'studio': {
+			const {studio} = await import('../lib/render.mjs');
+			return studio({proyecto, puerto: op.puerto});
+		}
+		case 'estilos': {
+			const {ESTILOS} = await import('../lib/config.mjs');
+			const desc = {
+				'datos-curiosos': 'clásico: morado, texto grande con contorno, íconos pixel 3D (escenas title, year, text...)',
+				explicativo: 'papel claro, titulares negro/rojo, etiquetas "// paso", tarjetas y teléfonos (tutoriales)',
+				documental: 'azul profundo, rayos de luz, burbujas, chips con datos (naturaleza, ciencia)',
+				ilustrado: 'cielo de atardecer o tu escenario ilustrado, personajes y cámara (cuentos, animales)',
+				historia: 'interiores oscuros, foco de luz, siluetas y letreros (misterio, crimen)',
+				mesa: 'mesa de madera con foco, objetos 3D y contadores LCD (dinero, crecimiento)',
+				serie: 'series con personaje y capítulos: HUD (días, barras), cartas VS, "comenta", subtítulos en bloque',
+				infografia: 'infografía plana: medidores, barras, globos, pantalla dividida, rayos X',
+				'3d': 'escenas 3D con recorrido de cámara (tu .glb), una palabra grande a la vez',
+				minimal: 'oscuro y limpio, para lo que sea',
+			};
+			for (const e of ESTILOS) console.log(`  ${e.padEnd(16)} ${desc[e] ?? ''}`);
+			console.log('\nÚsalo con  estilo: "documental"  en el video o en morfeo.config.mjs. Crea los tuyos con  estilos: {...}  en el config.');
+			return;
+		}
+		case 'guion':
+		case 'script':
+			return guion(pos, op, proyecto);
+		case 'ayuda':
+		case 'help':
+		case '--help':
+			return console.log(AYUDA);
+		default:
+			console.error(`Comando desconocido: ${cmd}\n`);
+			console.log(AYUDA);
+			process.exitCode = 1;
+	}
+}
+
+async function guion(pos, op, proyecto) {
+	const {cargarEnv} = await import('../lib/render.mjs');
+	const {guionConIA, guionSinIA, guardarVideo} = await import('../lib/guion.mjs');
+	const {buscarConfig} = await import('../lib/config.mjs');
+	cargarEnv(proyecto);
+	if (!buscarConfig(proyecto)) throw new ErrorMorfeo('Corre esto dentro de un proyecto de Morfeo (npx morfeo nuevo mi-canal).');
+	const texto = op.desde ? fs.readFileSync(path.resolve(op.desde), 'utf8') : null;
+	const tema = pos.join(' ').trim();
+	if (!texto && !tema) throw new ErrorMorfeo('Dime el tema:  npx morfeo guion "por qué el cielo es azul"   o   npx morfeo guion --desde mi-guion.txt');
+	let r;
+	// estilo: el de la opción, o el del proyecto
+	let estilo = op.estilo;
+	if (!estilo) {
+		try {
+			estilo = (await (await import('../lib/config.mjs')).cargarProyecto(proyecto)).estilo;
+		} catch {}
+	}
+	if (texto && op.sinIa) r = guionSinIA(texto, {id: op.id, voz: op.voz, musica: op.musica, titulo: op.titulo, estilo});
+	else {
+		console.log(texto ? 'Claude está convirtiendo tu guion en escenas...' : `Claude está escribiendo un video sobre: ${tema}...`);
+		r = await guionConIA({tema, texto, idioma: op.idioma, duracion: op.duracion ? Number(op.duracion) : undefined, tono: op.tono, estilo, imagenes: !!op.imagenes, voz: op.voz, modelo: op.modelo});
+	}
+	if (op.id) r.id = op.id;
+	const {cargarProyecto} = await import('../lib/config.mjs');
+	let carpeta = path.join(proyecto, 'guiones');
+	try {
+		carpeta = (await cargarProyecto(proyecto)).guiones;
+	} catch {}
+	const {id, archivo} = guardarVideo(carpeta, r.id, r.video);
+	console.log(`\nListo: ${path.relative(proyecto, archivo)}  (${r.video.scenes.length} escenas)`);
+	console.log(`Revísalo y edítalo si quieres; luego:  npx morfeo render ${id}`);
+}
+
+function nuevo(carpeta, op) {
+	if (!carpeta) throw new ErrorMorfeo('Dime el nombre de la carpeta:  npx morfeo nuevo mi-canal');
+	const destino = path.resolve(carpeta);
+	if (fs.existsSync(destino) && fs.readdirSync(destino).length) throw new ErrorMorfeo(`La carpeta ${carpeta} ya existe y no está vacía.`);
+	const plantilla = path.join(PAQUETE, 'plantilla');
+	fs.cpSync(plantilla, destino, {recursive: true});
+	// npm no publica archivos llamados .gitignore: en la plantilla van como "gitignore"
+	for (const [de, a] of [['gitignore', '.gitignore'], ['env.example', '.env.example']])
+		if (fs.existsSync(path.join(destino, de))) fs.renameSync(path.join(destino, de), path.join(destino, a));
+	const nombre = path.basename(destino).toLowerCase().replace(/[^a-z0-9-_]/g, '-');
+	const pkg = path.join(destino, 'package.json');
+	fs.writeFileSync(pkg, fs.readFileSync(pkg, 'utf8').replace('__NOMBRE__', nombre).replace('__VERSION__', `^${VERSION}`));
+	console.log(`Proyecto creado en ${carpeta}/\n\nSiguientes pasos:\n  cd ${carpeta}\n  npm install\n  npx morfeo instalar     (solo la primera vez en esta computadora)\n  npx morfeo render`);
+}
+
+main().catch((e) => {
+	if (e instanceof ErrorMorfeo) console.error(`\n✘ ${e.message}`);
+	else console.error(e);
+	process.exitCode = 1;
+});

package/bin/postinstall.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Aviso corto después de `npm install morfeo`. No descarga nada: lo pesado lo hace `npx morfeo instalar`.
+try {
+	if (process.env.CI || process.env.MORFEO_SILENCIO) process.exit(0);
+	const {venvListo, modelosListos} = await import('../lib/entorno.mjs');
+	if (venvListo() && modelosListos()) process.exit(0);
+	console.log('\n  Morfeo instalado. Falta preparar voces y Python (una sola vez, ~10 min):\n\n    npx morfeo instalar\n');
+} catch {
+	// un aviso nunca debe romper la instalación
+}