Turn a Script into a Hand-Drawn Explainer sweety-handdraw-video

Let the picture take shape with the explanation

Narrating an article over a few illustrations does not necessarily show how a process unfolds. sweety-handdraw-video establishes the narration and its actual duration first, then schedules outlines, colors and handwritten points so viewers can watch the explanation take shape.

The catalog’s whiteboard video skill focuses on Excalidraw diagrams and publishing materials. sweety-handdraw-video puts more emphasis on drawing order, the hand or pen, and synchronization with narration, with a local speech-generation option. Use it for an educational topic, a short story or an illustrated adaptation of your article.

The first video is the creator’s portrait explainer. The second is the v1.2/v1.3 drawing comparison included in the creator’s article. The post introduces v1.4; this tutorial follows the repository’s current v1.4.1.

Install the skill and prepare images and narration

Install the complete skill

Run this page’s installation command in a terminal to install for Claude Code and Codex. If you use only one host, remove the other name after --agent. The installer needs Node.js/npm; local drawing and composition use Python 3.9+ and FFmpeg.

The following example uses the Claude Code installation. For Codex, change the first path to $HOME/.agents/skills/sweety-handdraw-video:

# Select the installation directory for your host
SKILL_DIR="$HOME/.claude/skills/sweety-handdraw-video"
bash "$SKILL_DIR/scripts/setup.sh"
bash "$SKILL_DIR/scripts/setup.sh" --check
cat "$SKILL_DIR/VERSION"

setup.sh prepares FFmpeg, a Python virtual environment and rendering dependencies, then checks fonts. --check only checks. Resolve any MISSING entries before continuing; a successful package integrity check prints ok: package integrity. The version checked for this tutorial is 1.4.1.

Confirm where images and speech will come from

The skill guides the agent’s planning and production; local scripts draw and compose the result. Codex can use its built-in image generation. Claude Code needs an image-generation tool or MCP, or illustrations you supply. The style, art direction and directing guides are bundled; no additional installation is needed for them.

Prepare narration separately. Local VoxCPM2 requires an Apple Silicon Mac and a configured model environment. If you already have a compatible local VoiceStudio service, you can use it for speech requests; its configured TTS model generates the audio. Alternatively, provide a complete recording for the AI to align. A normal setup.sh run does not download speech models. Linux supports local rendering, but cannot use the Mac MLX speech route as written. See the official local runtime guide for connection details.

Approve the script, hear a sample and test one scene

Put the learning goal in the brief

Choose a question that fits roughly a minute. This example helps viewers turn a large task, “tidy the room,” into a first step, “clear just the desk tonight.” The picture should show the change in scope rather than repeat the entire narration as text.

The following brief is an editorial exercise that has not been rendered into a film. Send it in Claude Code or Codex after installation, replacing the topic, audience and example for your project:

Use sweety-handdraw-video to make a portrait 9:16 explainer of about one minute. Name the project task-breakdown and keep it outside the skill installation folder.

Topic: how to turn a large task into one step you can do today.
Audience: office workers who keep putting off large tasks.
Example: reduce “tidy the whole room” to “clear just the desk tonight.”
Goal: viewers can write a concrete first action for their own task.

Use clear ink outlines and flat colors, drawing the outlines before coloring.
Show only the pen, without an arm. No music, advertising or watermark.
Provide the narration script and shot plan first, then wait for approval. Do not add research data or statistics that I have not provided.
Let me hear the bundled voice samples. After I choose a voice, generate a short sample using this script for approval.
Once the voice is approved, make one complete scene with outlines, coloring, subtitles and time to view the finished picture.
Wait for approval of that scene before completing the film. Keep the source project and materials for revision.

Approve the voice, then review one drawing sequence

1. Read the narration. Does it explain what makes the task too large, how to reduce its scope and what viewers should do next? If your script is already final, explicitly ask to preserve its meaning and ending.
2. After choosing a voice, listen to a short passage from this script for pronunciation, pauses, noise and pace. Approve it before generating the rest. Bundled samples help select a voice; they do not replace a sample of your own narration.
3. Ask the AI to make one representative illustration, such as the relationship between a cluttered room and the desk to be cleared. Check that the people, objects and change in scope are understandable before animating its drawing process.

For stroke-by-stroke drawing, keep clear contours and flat colors. Some styles without traceable outlines use a brush to reveal a finished image. The project calls this “reveal”; specify the drawing behavior you want when choosing the style.

Build the video around the narration

Once the actual narration is ready, have the AI plan from its timestamps: how long each picture has for outlines and colors, and how long the finished image stays visible. Review the representative sequence before expanding the film so you do not generate many illustrations that are too complex to draw in time.

Play the sample at normal speed. Check whether the pen tip brings out the line, color appears as the pen moves, and the change in scope is visible when the narration explains it. If a picture cannot be drawn in time, remove objects or revise the explanation’s pacing rather than speeding the pen beyond readability.

Make revision requests specific:

When the narration says “clear just the desk tonight,” the desk has not appeared yet.
Keep the current narration and style. Draw the desk earlier and reduce other room details if needed.
Leave time to inspect the completed desk before the next point appears.
Update just this sequence for review; keep the other approved pictures.

The first version has no background music by default. If you want music, supply your own file and ask the AI to lower it during speech, checking the loop transitions and whether the music ends naturally.

Adapt the content, revise locally and export

Change the visual meaning along with the topic

• For your own article, supply the full text and identify numbers, sources and conditions to preserve. Do more than change the title.
• For a work process, redesign the participants, actions and outcomes. An onboarding explanation might show “submit documents → review → feedback” rather than reuse the room illustrations.
• For subtitle or color edits, ask to keep the original pictures and audio, update the relevant layers and render again.
• For changed narration, regenerate affected speech segments and update timing, subtitles and drawing schedules. Editing the script file alone is insufficient.

Use your own recording or a voice you have permission to use. The four bundled synthetic voices are separate from original recordings kept only in the creator’s personal library. The main code is MIT; bundled dependencies and assets retain their own terms. See the third-party notices.

Render and inspect the delivered file

Have the AI finish the project data and asset checks before rendering. For manual operation, use the terminal where you set SKILL_DIR, move to the project’s parent folder and use the Python environment created at the installer’s default location:

# Project and rendering environment; replace custom installation paths as needed
JOB_DIR="$PWD/task-breakdown"
RENDER_PYTHON="$HOME/.local/share/sweety-handdraw-video/venv/bin/python"
"$RENDER_PYTHON" "$SKILL_DIR/scripts/handdraw_video.py" doctor "$JOB_DIR"
"$RENDER_PYTHON" "$SKILL_DIR/scripts/handdraw_video.py" build "$JOB_DIR"
"$RENDER_PYTHON" "$SKILL_DIR/scripts/handdraw_video.py" render "$JOB_DIR"
"$RENDER_PYTHON" "$SKILL_DIR/scripts/handdraw_video.py" verify "$JOB_DIR"

Resolve problems reported by doctor and build before rendering. The full film is written to the project’s outputs/film.mp4. Open that file directly to check sound, duplicate or overlapping subtitles, incomplete drawing and a cut-off ending.

Report your findings to the AI, then send:

Complete delivery using the skill’s finalize workflow, and tell me where to find the film, source project and review records.
In review.json, accurately record which checks were completed and which remain unfinished.

finalize checks that the review records match the current film and writes delivery review records to outputs/verification.json and outputs/verification.txt. It does not render the video again. Any unfinished continuous-playback or listening checks are listed in those records.

For landscape or another aspect ratio, have the AI rearrange the composition and recheck subtitles and illustrations rather than merely resize the portrait film. Keep the scripts, pictures and audio in the project so you can reuse the workflow for your next topic.