E1 · Tested engine
5 minRun the "explicavideos tests" block.
Done when: The output shows 2.13.10, saída: 0, Ran 50 tests and OK.
Lesson 2 · 18 min
Explainer with avatar and voice: explicavideos under the hood
explicavideos turns a script into an explainer video with avatar, voice, animated scenes and captions. Only one part is expensive: the avatar studio. In this lesson you run the engine's tests and build scenes, blocks and templates from a script of your own, stopping before the studio.
Start the lesson
In this lesson you will
- 1The engine's stages, from script to finished video
- 2The scene format: title, chapter, speech, labels and takeaway
- 3Why scenes become blocks and what the per-block limit does
- 4Where the studio gate is and what --help says the code does not do
Goal: run the explicavideos tests and build scenes and blocks from a script of your own without generating anything in the avatar studio.
01The path of an explainer
Click each stage. Only the middle one spends credit.
Click each block in the diagram to see what it does.
Steps of the v1 engine, read from the README and the code of explicavideos 2.13.10 (commit 604fc74). The prepare step is the first step of both engines, v1 and v2. HyperFrames on the inside is the subject of course 3.
02The engine at a pinned commit
Clones it, shows the version, reads --help and runs the tests. The tests simulate the network and swap the render for a command that fails if called: nothing leaves your machine.
Terminal · explicavideos tests
E=${TMPDIR:-/tmp}/ensaio-fabrica/a2; rm -rf "$E"; mkdir -p "$E"; cd "$E"
git clone -q https://github.com/inematds/explicavideos.git && cd explicavideos
git checkout -q 604fc74 && cat VERSION
python3 explica.py --help | grep -E "^ (prepare|preview)"
python3 -m unittest discover -s tests > testes.log 2>&1; echo "saída: $?"
grep -E "^(Ran|OK)" testes.log | sed 's/ in .*s$//'Example from the repository
2.13.10 prepare monta cenas, blocos (<= 4.400 caracteres) e templates. Não gera nada no HeyGen. preview renderiza o bloco 1 localmente, sem avatar, para conferir o layout. saída: 0 Ran 50 tests OK
The block drops the time from the Ran 50 tests line (it changes on every run). Note the text of preview: it says it renders, but see the next tab.
At commit 604fc74, preview calls build_final_block.py pt 1 --preview, which only writes the HTML of block 1 to layout-preview/, with placeholder timings and the notice "PRÉVIA VISUAL · SEM NARRAÇÃO" in place of the avatar. No MP4 comes out. When the help text and the code disagree, the code wins.
03A script of your own becomes scenes and blocks
Four sample scenes and a config that points to them. The low limit (300 characters) is on purpose, to see the packing.
File · kit/exemplos/a2-explica/cenas-pt.json
[
{"title": "Por que conferir antes de gerar", "chapter": "ABERTURA", "kind": "steps", "speech": "Gerar avatar custa crédito e tempo. Por isso o motor monta tudo antes: cenas, blocos e moldes. Só depois de conferir é que alguma coisa vai para o estúdio.", "labels": ["Cenas", "Blocos", "Moldes"], "takeaway": "Conferir é de graça. Gerar não é.", "source": "README do explicavideos"},
{"title": "O roteiro vira cenas", "chapter": "ETAPA 1", "kind": "steps", "speech": "Cada cena tem título, capítulo, fala e até três rótulos. A fala é o que o avatar diz; os rótulos são o que aparece na tela.", "labels": ["Título", "Fala", "Rótulos"], "takeaway": "Fala para ouvir, rótulo para ver.", "source": "engine/prepare.py"},
{"title": "As cenas viram blocos", "chapter": "ETAPA 2", "kind": "steps", "speech": "O estúdio aceita um texto de tamanho limitado por vídeo. O motor junta cenas inteiras em blocos até o limite, sem cortar nenhuma fala no meio.", "labels": ["Limite por bloco", "Cena inteira", "Sem corte"], "takeaway": "Bloco é um vídeo de avatar.", "source": "engine/prepare.py"},
{"title": "O que vem depois", "chapter": "ETAPA 3", "kind": "steps", "speech": "Com os blocos prontos, a pessoa dona do avatar aprova e só então o estúdio gera. Depois vêm transcrição, cenas animadas, render e montagem.", "labels": ["Aprovação", "Estúdio", "Render"], "takeaway": "Aprovação humana antes do crédito.", "source": "README do explicavideos"}
]Terminal · prepare and status
K=~/projetos/formacao-cinema-ia-fabrica-v72/kit
E=${TMPDIR:-/tmp}/ensaio-fabrica/a2; cd "$E/explicavideos"
cat > "$E/ensaio.json" <<FIM
{"id": "ensaio", "title": "Ensaio", "source_repo": "$E", "output": "$E/saida",
"languages": ["pt"], "scene_files": {"pt": "$K/exemplos/a2-explica/cenas-pt.json"},
"max_chars": 300}
FIM
python3 explica.py --config "$E/ensaio.json" prepare; echo "saída: $?"
ls "$E/saida/blocos" "$E/saida/templates/pt"
python3 explica.py --config "$E/ensaio.json" status | head -3Example from the repository
{"blocks": 2, "scenes": 4, "topics": 0, "chars": 561}
saída: 0
/tmp/ensaio-fabrica/a2/saida/blocos:
manifest.json
pt-b01.txt
pt-b02.txt
/tmp/ensaio-fabrica/a2/saida/templates/pt:
scene-01.html
scene-02.html
scene-03.html
scene-04.html
{
"submitted": {
"prepared": 2Two scenes per block (155 + 123 characters fit in 300; the third does not). The status command shows both blocks as prepared: nothing was sent to the studio. The scene-NN.html templates already have a data-duration calculated from the speech.
04When a scene doesn't fit
The engine refuses to cut a speech. With the limit at 140, the first scene (155 characters) already overflows.
Terminal · limit exceeded
E=${TMPDIR:-/tmp}/ensaio-fabrica/a2; cd "$E/explicavideos"
sed 's/"max_chars": 300/"max_chars": 140/' "$E/ensaio.json" > "$E/curto.json"
sed -i 's#"output": "[^"]*"#"output": "'"$E"'/saida-curta"#' "$E/curto.json"
python3 explica.py --config "$E/curto.json" prepare 2>&1 | grep -E "^ValueError"; echo "saída: ${PIPESTATUS[0]}"Example from the repository
ValueError: Scene 1 exceeds limit; split its narration before submitting saída: 1
The fix is to split the scene's speech in two, not to raise the limit: the real limit comes from the studio.
05The start: five services that resume where they stopped
In real production, start brings up five services. Run it, interrupt it and run it again.
fila/
rodando/
pronto/
falhou/
Browser simulation: nothing really runs. The five names are the start services in explicavideos 2.13.10 (submit, monitor, render, assemble, publish).
06What comes before the studio
Three things to check before any start.
1. Approval
The engine's --help requires an APROVADO_HEYGEN file in the output, with the avatar owner's authorization and the number of blocks and minutes. It is a written rule, not a block in the code: your gate (lesson 7) is what really closes it.
2. Your own avatar
The engine was built for Nei's avatar and voice, with his consent. In your use, the avatar is yours, with a signed consent form. Someone else's avatar without a consent form, no.
3. Profiles
Profiles belong to v2: without profile_visual, you get the aula profile; with "profile_visual": "viral", the viral profile (faster cuts), checked by engine/v2/qa_viral.py, which prints APROVADO, APROVADO COM AVISO or REPROVADO.
4. The v2 on top
The v2 does not generate the avatar again: it starts from a finished v1 production and redoes the visuals of each block with a visual script driven by spoken cues, the same concept the refazvideo validator checks in lesson 4.
README commands (only described here, because they need the avatar's transcribed speech): engine/v2/setup_output.py → engine/v2/build_block.py 1 --strict → engine/v2/run_lane.sh 1 2 3.
07What comes out of the engine
A 10-minute explainer made with explicavideos v2, with Nei's own avatar and voice (with his consent), in three languages.
IA Cultivada: an explainer that came out of explicavideos · 10 minVideo page with script →
08Practice
From the tested engine to the scenes of your next video.
E2 · Scenes and blocks
5 minRun the "prepare and status" block with the kit's four scenes.
Done when: {"blocks": 2, "scenes": 4, "topics": 0, "chars": 561}, saída: 0 and the status with "prepared": 2.
E3 · Your script
15 minAsk your agent for the scenes of an explainer of your own (5 to 8 scenes, each spoken line up to 600 characters) in the same format as cenas-pt.json. Save it to ${TMPDIR:-/tmp}/ensaio-fabrica/a2/minhas-cenas.json, change the scene_files in the config, and run prepare with max_chars 4400.
Done when: cd ${TMPDIR:-/tmp}/ensaio-fabrica/a2/explicavideos && python3 explica.py --config ../ensaio.json prepare; echo "saída: $?" → one line {"blocks": …, "scenes": N, …} with the N of your scenes and saída: 0.
09Lesson quiz
The explanation appears after you answer.
Question 1 of 4
Which explicavideos command spends credit?
Correct
start brings up the services, and the first one (submit) generates video in the avatar studio. prepare, status and preview are local.Not that one
start brings up the services, and the first one (submit) generates video in the avatar studio. prepare, status and preview are local.Review: The path of an explainerQuestion 2 of 4
A scene has 5,000 characters of speech and the limit is 4,400. What do you do?
Correct
The limit comes from the studio, per block. The engine refuses to cut a line of speech in the middle (ValueError: Scene … exceeds limit); the way out is to split the scene.Not that one
The limit comes from the studio, per block. The engine refuses to cut a line of speech in the middle (ValueError: Scene … exceeds limit); the way out is to split the scene.Review: The engine at a pinned commitQuestion 3 of 4
The --help says preview renders; the code only writes an HTML file. Which one do you trust?
Correct
When the docs and the code disagree, the code wins. Run it and see what comes out in layout-preview/ before promising an MP4.Not that one
When the docs and the code disagree, the code wins. Run it and see what comes out in layout-preview/ before promising an MP4.Review: The engine at a pinned commitQuestion 4 of 4
Why does the manifest matter when start is interrupted?
Correct
Each service reads the manifest and only does what's left. A block that was already sent doesn't go back to the studio: sending it again means generating it again.Not that one
Each service reads the manifest and only does what's left. A block that was already sent doesn't go back to the studio: sending it again means generating it again.Review: The start: five services that resume where they stoppedQuiz complete
You got {a} of {n} right. Get them all right and the lesson is marked as done.Pick an option. The explanation appears after you answer.
10In three sentences
Scenesspeech is for hearing, labels are for seeing; the agent writes, you review.
Blocksprepare packs whole scenes up to the studio limit, without spending anything.
Studiothe only paid step sits behind start, approval and your consent form.