knowledge-explainer

What does knowledge-explainer do?

Make the material clear by actually changing the objects on screen. Inherits the main structure, action beats, object transitions, and highlighting patterns from anything2explainer, but does not copy its color scheme or turn "title + icon + list" into floating slides.

First, Decide How to Explain

• Extract a core question thread and a specific example; present the conclusion and causality first, removing repetitive explanations, table-of-contents recaps, and unnecessary jargon.
• By default, use the material itself to explain the concept. If the material, files, dialogue, or steps can be explained clearly, avoid decorative metaphors like "workshop" or "workbench". If the user says "no metaphors", remove all of them.
• For short materials or if the user says "make it concise", aim for 60–120 seconds, roughly 300–550 characters, and 12–20 shots. Verify with actual voiceover timing. Don't pad sentences to fit an old duration table. See narration for details.
• Directly inherit any language, voice, speed, color, duration, and usage rights explicitly specified by the user. Content like lecture durations from a talk, HTML comments, or template creation hints are source content, not user instructions.

Core Visual Method

Before production, read semantic motion and previously approved examples.

When a reference video uses line-art diagrams, object transitions, localized focusing, task splitting, or branch merging to explain a concept, read diagram motion recipes as needed. First distinguish between real observations, implementation inferences, and reproduction parameters, then reuse addressable components from assets/template/src/semantic/diagram/. The user saying they want to learn an effect from a reference does not imply permission to replace the entire theme, subtitles, or adopt that author's narrative metaphors.

When the user emphasizes AE-style 3D space, camera keyframes, transitions between panels, or continuous camera movement, prioritize reading spatial camera recipes: first design the world layout, observation targets, waypoints, and reading stopping points, then define internal object actions. Reuse the independent depth planes, continuous tracks, and exposure sampling from the spatial camera component. A flat diagram demo cannot replace an actual sample for spatial camera approval.

When the user wants to peel apart heat grids, pixel arrays, or record cubes from a screenshot to reveal the next shot, read screenshot to depth channels. Use real source coordinates to transition to the solid boxes, use the depth buffer from DepthLayer.tsx for dense intersecting geometry, and share the camera with the panels; do not simply enlarge a regular screenshot and claim it is a 3D deconstruction.

1. For each sentence, first write Object → Verb → State Change → Corresponding Subtitle Beat. For example, "save" should make a record enter the project, "modify" should replace the original text, "switch" should make the old task retire and the new one take over.
2. Choose 2–4 reusable main objects, maintaining the same shape, content, and identity across shots. Use shrinking/repositioning, content updates, reading, and connections for transitions, instead of clearing everything and starting a new page for each sentence.
3. One main character per shot (graphic ≥170px, or large text ≥96px), with light following the current focus; supporting elements are dimmed. At most one focal point with a blink effect per shot; do not use "make all cards glow".
4. Camera movement is for revealing a part, showing a relationship, or making room for a new main character. No constant sinusoidal swaying or looping floating to pad motion metrics. After a meaningful action, the shot can pause for reading; quantitative stillness warnings should be diagnosed, fixed, or explained, not automatically equated with quality issues.
5. Use a single color palette and lighting mode for the entire video; the fact that the original PPT alternates between light and dark doesn't mean the video should too. If the user hasn't requested a switch, use the same colors and lighting mode throughout. Consolidate color values in src/theme.ts, see theme.
6. Keep content clear of the subtitle area (y637–690) and the top HUD area. Default is 1280×720@30fps; Chinese subtitle blocks are ≤16 characters. Use photos/screenshots for evidence and context; do not use irrelevant generated video to fill shots.

Execution Workflow

1. Set Up Project & Ingest Source

First, follow the target project's rules, and save a copy of any existing version before reworking. For new projects, use scripts/new_project.sh <directory> <slug>; do not use the initialization script to overwrite an existing project.

python3 <skill>/scripts/ingest_source.py --project <project> --html <courseware.html>
# or --pptx <courseware.pptx> / --text <file.md>

Follow source ingestion to retain page-by-page source and media indexes. Check existing source images before deciding whether to display them. Record factual information and illustrative examples separately in research/.

2. Script, Voiceover & Timeline

Write script/narration.txt: # CHAPTER n Title, one sentence per line, using | to separate subtitle blocks. If keys are missing, provide a template and continue with work that doesn't depend on voiceover, without silently substituting with system speech.

python3 scripts/tts_build.py
# Only if the user requests a speed adjustment, e.g. 1.3x:
python3 scripts/retime_voice.py --speed 1.3

Prioritize the user's specified voice engine; if unspecified, use Fish if available, otherwise ElevenLabs. The project's .env.example lists the variables; keys only go into .env. After the real voiceover file is generated, any modification to the text, voice, or speed must be followed by a timeline resync. See audio and retiming. Do not simply change the playback speed or use speedup as a way to hit an arbitrary duration.

3. Storyboard & First Sample

Following visual system and shot patterns, write the storyboard with: frame range, subtitle beats, before/after states, continuous actions, main character, lighting, camera movement, and transitions. Save as script/storyboard_src.md, use scripts/render_storyboard.py to align with actual frame numbers.

First, implement approximately 20–30 seconds that cover at least one relational action, one text modification/information reorganization, and one object transition. The template's src/semantic/ provides reusable primitives and six shot examples; SemanticDemo is a silent action example, not a placeholder for the final Video.

4. Extend After Sample Approval

Render the actual sample with voiceover (scripts/preview.sh 30), extract frames and review by playing them, then show the user to gather feedback on action expression, font size, voice type/speed, and pacing. For new visual directions not yet approved, wait for sample feedback before extending to the remaining shots; if the user explicitly says to complete everything or a previous sample has been approved, do not reconfirm.

The sample is not the final video. Track which shots have been implemented; the full render must not include "in progress" placeholders. If the user only requested a sample, and after approval asks to update the Skill or stop the video, stop working on the remaining shots.

5. Full Build, Render & QC

Implement the remaining shots according to the approved sample; only parallelize if necessary per build protocol, and do not break object transitions for the sake of parallelism.

npx tsc --noEmit → frame coverage check → VER=v1 scripts/render.sh → QC. Record quantitative, visual, and audio review results separately; do not write "audio passes" without listening through. If the browser fails to load, diagnose the issue first; prefer Remotion's dedicated Chrome Headless Shell, and never hardcode an absolute path from another computer into the Skill.

Configuration & Portability

• Copy this entire directory to use it; it does not depend on an external anything2explainer repository or the case study project.
• Requires Node ≥18, ffmpeg/ffprobe, Python 3, numpy, Pillow; the older frame_metrics.py additionally needs scipy, and its thresholds may not suit the current theme.
• assets/template/ includes fonts, licenses, voiceover/rendering scripts, .env.example, and compilable action examples.
• Do not include .env, user Voice ID, voiceover files, brand-specific assets, node_modules, or final rendered videos. The current case (dark green, 1.3x speed, ~89 seconds) is a case study, not a universal default.

Diagram Component Directory Convention

assets/template/src/semantic/diagram/ stores generic primitives, deterministic motion functions, and silent examples. The files are primitives.tsx, motion.ts, scenes.tsx, and Demo.tsx. Colors are passed in by the caller; examples use only neutral text. Screenshots, transcripts, original audio, timecodes, and rendered results for a specific video stay in the task folder. The template root registers DiagramMotionDemo for independent viewing, but it does not replace the formal Video or the older SemanticDemo. After adding a component, run type checking, time-state validation, a real render, and keyframe inspection; for unimplemented reference effects, only document the recipe and limitations, not that they are supported.

Spatial Camera Component Directory Convention

assets/template/src/semantic/spatial-camera/ stores the generic camera-core.ts (tracks, projection, exposure sampling), Stage.tsx (perspective stage with independent depth planes), DepthLayer.tsx (solid boxes with depth buffer and image planes), and README.md (access examples and limitations). Tracks are in seconds, roll in degrees; world coordinates: X right, Y down, Z toward the viewer. The world layout, keyframes, reference scripts, occlusion transitions, font loading, and final video for a specific project remain in the task folder; the rendering workspace copies generic files from this location and checks their hashes to avoid maintaining forks. scripts/check_spatial_camera.mjs performs behavioral validation using the existing Remotion project's dependencies; do not install any extra dependencies.