Flujo de trabajo de renderizado de video
El renderizado es el proceso de capturar una composición fotograma por fotograma y codificarla en un archivo de video (por ejemplo, MP4). Esto se realiza con el paquete @helios-project/renderer en un entorno Node.js.
El camino rápido: un solo comando
npx -y @helios-project/cli@latest render composition.html -o output.mp4
- La duración, FPS y tamaño provienen de
window.heliosde la composición. Para configurarlos tú mismo, pasa--duration,--fps,--widthy--height. - Una página que se dibuja a sí misma con
window.renderAt(t)necesita--duration. --audio track.mp3añade una banda sonora.- Un archivo HTML simple se renderiza directamente desde el disco. Si un bundler tiene que construir la composición, ejecuta
npm run devy pasa su URL en su lugar.
Usa el script a continuación solo cuando necesites un pipeline personalizado, como props de entrada, varias pistas de audio o callbacks de progreso.
1. Prerrequisitos
El renderizador necesita una URL para la composición:
- Un archivo en disco:
file:///path/to/composition.html - Un servidor de desarrollo:
npm run dev, por ejemplohttp://localhost:3000/composition.html - Cualquier otra URL accesible
2. Crear script de renderizado
Crea un archivo llamado render.js (o render.ts si usas ts-node).
import { Renderer } from '@helios-project/renderer';
import path from 'path';
async function main() {
// 1. Configuración
const compositionUrl = 'http://localhost:3000/composition.html';
const outputPath = path.resolve('output.mp4');
// 2. Inicializar Renderer
const renderer = new Renderer({
width: 1920,
height: 1080,
fps: 30,
durationInSeconds: 10,
// frameCount: 300, // Opcional: Sobrescribe durationInSeconds con un número exacto de fotogramas
mode: 'canvas', // Usa 'dom' si tu animación usa elementos CSS/HTML
// Configuración de audio
audioTracks: [
{ path: 'background.mp3', volume: 0.5 },
{ path: 'voiceover.wav', offset: 2 }
],
audioCodec: 'aac',
// Props de entrada (contenido dinámico)
inputProps: {
title: "Render personalizado",
color: "#00ff00"
}
});
console.log(`Iniciando renderizado de ${compositionUrl}...`);
// 3. Ejecutar renderizado
try {
await renderer.render(compositionUrl, outputPath, {
onProgress: (p) => {
const percent = Math.round(p * 100);
process.stdout.write(`\rProgreso: ${percent}%`);
}
});
console.log(`\n¡Listo! Guardado en ${outputPath}`);
} catch (err) {
console.error('\nRenderizado falló:', err);
process.exit(1);
}
}
main();
3. Ejecutar renderizado
Ejecuta el script.
# Si usas ts-node
npx ts-node render.ts
# Si usas node (js compilado)
node render.js
Solución de problemas
"Tiempo de espera de página" o "Conexión rechazada"
- Asegúrate de que el servidor local que aloja la composición esté funcionando.
- Verifica si la URL es correcta y accesible en un navegador normal.
"Salida negra" o "Video vacío"
- Asegúrate de que
window.heliosesté expuesto (o que la página definawindow.renderAt(t)). - Si usas
mode: 'canvas', asegúrate de estar dibujando en un elemento<canvas>. - Si usas
mode: 'dom', asegúrate de que los elementos sean visibles.
"El renderizado se cuelga"
- Verifica si la composición tiene errores en la consola del navegador.
- Habilita el trazado para depurar:
await renderer.render(url, out, { tracePath: 'trace.zip' });
Problemas de audio
- Asegúrate de que las rutas de los archivos de audio sean correctas en relación al lugar donde se ejecuta el script.
- Si usas
mode: 'dom'y dependes de audio implícito (por ejemplo, etiquetas<audio>), asegúrate de que los elementos estén presentes en el DOM.