O que Fluxo de Trabalho de Renderização de Vídeo faz?
Renderização é o processo de capturar uma composição quadro a quadro e codificá-la em um arquivo de vídeo (por exemplo, MP4). Isso é feito usando o pacote @helios-project/renderer em um ambiente Node.js.
O caminho rápido: um comando
npx -y @helios-project/cli@latest render composition.html -o output.mp4
- A duração, fps e tamanho vêm do
window.heliosda composição. Para defini-los você mesmo, passe--duration,--fps,--widthe--height. - Uma página que se desenha com
window.renderAt(t)precisa de--duration. --audio track.mp3adiciona uma trilha sonora.- Um arquivo HTML simples é renderizado diretamente do disco. Se um empacotador (bundler) precisar construir a composição, execute
npm run deve passe sua URL em vez disso.
Use o script abaixo somente quando precisar de um pipeline personalizado, como propriedades de entrada, várias faixas de áudio ou callbacks de progresso.
1. Pré-requisitos
O renderizador precisa de uma URL para a composição:
- Um arquivo no disco:
file:///path/to/composition.html - Um servidor de desenvolvimento:
npm run dev, por exemplo,http://localhost:3000/composition.html - Qualquer outra URL acessível
2. Criar Script de Renderização
Crie um arquivo chamado render.js (ou render.ts se estiver usando ts-node).
import { Renderer } from '@helios-project/renderer';
import path from 'path';
async function main() {
// 1. Configuração
const compositionUrl = 'http://localhost:3000/composition.html';
const outputPath = path.resolve('output.mp4');
// 2. Inicializar Renderizador
const renderer = new Renderer({
width: 1920,
height: 1080,
fps: 30,
durationInSeconds: 10,
// frameCount: 300, // Opcional: Substitui durationInSeconds por contagem exata de quadros
mode: 'canvas', // Use 'dom' se sua animação usar elementos CSS/HTML
// Configuração de Áudio
audioTracks: [
{ path: 'background.mp3', volume: 0.5 },
{ path: 'voiceover.wav', offset: 2 }
],
audioCodec: 'aac',
// Propriedades de Entrada (Conteúdo Dinâmico)
inputProps: {
title: "Renderização Personalizada",
color: "#00ff00"
}
});
console.log(`Iniciando renderização de ${compositionUrl}...`);
// 3. Executar Renderização
try {
await renderer.render(compositionUrl, outputPath, {
onProgress: (p) => {
const percent = Math.round(p * 100);
process.stdout.write(`\rProgresso: ${percent}%`);
}
});
console.log(`\nConcluído! Salvo em ${outputPath}`);
} catch (err) {
console.error('\nFalha na renderização:', err);
process.exit(1);
}
}
main();
3. Executar Renderização
Execute o script.
# Se estiver usando ts-node
npx ts-node render.ts
# Se estiver usando node (js compilado)
node render.js
Solução de Problemas
"Timeout de página" ou "Conexão recusada"
- Certifique-se de que o servidor local hospedando a composição está em execução.
- Verifique se a URL está correta e acessível em um navegador comum.
"Saída preta" ou "Vídeo vazio"
- Certifique-se de que
window.heliosestá exposto (ou a página definewindow.renderAt(t)). - Se estiver usando
mode: 'canvas', certifique-se de que está desenhando em um elemento<canvas>. - Se estiver usando
mode: 'dom', certifique-se de que os elementos estão visíveis.
"Renderização trava"
- Verifique se a composição tem erros no console do navegador.
- Ative o rastreamento para depurar:
await renderer.render(url, out, { tracePath: 'trace.zip' });
Problemas de Áudio
- Certifique-se de que os caminhos dos arquivos de áudio estão corretos em relação ao local onde o script é executado.
- Se estiver usando
mode: 'dom'e contando com áudio implícito (por exemplo, tags<audio>), certifique-se de que os elementos estão presentes no DOM.