English Learning Animation

English Learning Animation

Create a coherent, original short-form English lesson. Prioritize a watchable scene over a slide deck with narration.

Workflow

1. Define one communicative outcome and write an English-only script with 3–5 usable phrases, a natural dialogue, and a brief repeat-after-me close. Do not choose a target runtime first. Let the generated speech, necessary pauses, cover, and recap determine the final duration. Many lessons will naturally land near 25–45 seconds, but this is not a quota.
2. Build a shot list before generating visuals. Add a semantic_contract to script.json: topic, setting, visual brief, required scene tags, and stale terms that must never appear. Every scene needs semantic_tags. Give every voice segment a stable semantic owner such as customer, barista, or narrator; do not use gender as the long-term character identity.
3. Use Qwen3-TTS VoiceDesign when no reference audio exists. Create a short audition for every recurring role first; do not reuse one voice for multiple characters. Lock each approved role's voice_profile and add line-specific performance direction.
4. Generate an empty background plate and separate transparent character/prop cutouts that visibly match the current setting. A hotel lobby cannot stand in for a subway station, restaurant, or attraction. Use a layered animation system such as paper-collage-remotion; never animate a single flattened illustration as the whole video.
5. Place audio using actual generated durations, then make visual changes at segment starts, phrase beats, and turn changes. Never add dead air or extend scenes merely to reach a round-number runtime. During dialogue, keep the speaker visually primary; during narration, use an English phrase card or semantic graphic rather than pretending a character is speaking.
6. Render only after passing the quality gates below.

Production Starter

Initialize a new project from the approved layered-animation baseline:

python /scripts/init_project.py 

Add the empty background plates and transparent cutouts at the asset paths declared in script.json; do not copy generated user content into the skill. Each speaking cutout should declare a speaker field matching the narration role id.

Generate role-separated audio with the bundled script:

python /scripts/generate_qwen3_voices.py voice-manifest.json \
  --model 

Use voice-manifest.json as the editable voice contract. Every row needs a semantic role id, English line, stable voice_profile, and line-specific performance instruction. The generator remains compatible with the older combined voice_instruction field. Keep the manifest's generation seed for reproducible auditions. Device selection is automatic (CUDA → MPS → CPU); override it only when necessary.

If the Qwen3 path is unknown, discover it first:

python /scripts/find_qwen3_voicedesign.py

The model finder respects HF_HOME; pass --cache-dir for a nonstandard cache.

Visual and Language Rules

• Start with a 2–3 second cover that says the learning promise in English. Default to a topic or benefit subtitle such as Travel English · Speak Naturally; do not put the total runtime on the cover unless the user explicitly requests it. Any runtime claim must come from the final measured render.
• Keep on-video language English-only for immersion. Put Chinese explanations in post copy or a separate study sheet only if requested.
• Keep all character layers opaque. Do not use opacity to de-emphasize a non-speaker; use mild saturation/scale contrast instead.
• Use low-frequency micro-motion only: roughly 1 px vertical travel and <= 1% scale change. Never use rapid sinusoidal shaking as a speaking cue.
• Treat subtitle/phrase-card timing as audio-driven. Show whole dialogue lines for comprehension; use short phrase progression only for deliberate practice beats.
• Keep phrase cards in script.json under phrase_cards, keyed by narrator segment id. The renderer must read this data; never leave topic-specific cards hard-coded in video.tsx.
• Preserve a repeatable visual system: original characters, no copied logos/layouts/assets, warm editorial illustration, strong hierarchy, readable English type.

Quality Gates

Before delivery, verify the current render against references/quality-gates.md.

Run all pre-render gates with one command:

python /scripts/validate_project.py 

This preflight also rejects missing topic/scene tags, stale prohibited terms, and hard-coded phrase-card logic. After rendering, inspect the generated cover and one review frame per segment against the semantic_contract; mechanical validation cannot decide whether an illustration truly depicts the requested setting.

After rendering, run the same acceptance pipeline with the final video. This also extracts the cover and one representative frame per spoken segment:

python /scripts/validate_project.py  \
  --video  \
  --review-dir 

Use the individual gates below when diagnosing a failure.

Validate the lesson and voice contract:

python /scripts/validate_lesson.py voice-manifest.json
python /scripts/validate_contract.py voice-manifest.json script.json

Before rendering, validate that every declared character asset is a real opaque cutout rather than a flattened or ghosted plate:

python /scripts/validate_layers.py script.json public

After generating audio, check actual durations, declared scene windows, overlap, English-only captions, and speaker-to-layer ownership:

python /scripts/validate_timeline.py script.json public

After rendering, validate the stream and extract the cover plus one representative frame per spoken segment. Inspect all review frames before delivery:

python /scripts/validate_render.py out/final.mp4 --cover-frame work/cover-check.png
python /scripts/extract_review_frames.py \
  out/final.mp4 script.json work/review-frames

Tool Routing

• Read and use paper-collage-remotion for cutout-layer animation and Remotion rendering.
• Use imagegen to create new bitmap background plates or cutouts.
• Use local Qwen3-TTS VoiceDesign for no-reference character voice generation. Keep its model path, role instructions, and audio assets local to the project.
• Use ffprobe to read actual audio/video duration and validate the final file.