sweety-handdraw-video turns a topic or an article into a hand-drawn narrated video

The agent plans, the local tools draw

The project is best understood as a division of labour, and the README is explicit about where the line falls.

The agent is responsible for understanding the content, writing the narration, designing the storyboard and generating the illustrations. The local tools are responsible for drawing the lines stroke by stroke, filling colour, writing text by hand, aligning the dubbing and exporting the result. What to draw, in which style, and for how long is decided from the content.

The distinction matters because it explains why this is a Skill rather than an application. The README says it is still a production Skill that needs an Agent, image generation and a local runtime environment, and it states plainly that the finished video does not use an external image-to-video model. The current main rendering implementation is Python, Pillow, SciPy and FFmpeg.

The inputs are tabulated in the README, and the differences are worth noting. A single topic means arranging an explanatory route and designing scenes, mechanisms and advice. An article or reference material means keeping the important facts, numbers and qualifications and turning them into something worth listening to. A finished story or finalised text means following the original, and the README says it does not rewrite it when the original must be preserved. And approved images, audio and a script means reusing the material and revising subtitles, hands, visuals or the timeline.

So the tool is aimed at knowledge explanation, fables, opinion pieces, product mechanics and teaching material, and its stated advantage is putting narration, visuals and the drawing process into one production flow.

The voice comes first, and the drawings are budgeted to fit it

Two of the design decisions are unusual enough to be the reason to read the README in full.

The first is the order of operations. The narration is generated per semantic segment, with each segment under roughly 100 characters and split only at sentence ends, and each segment is checked for hum, noise and clipping. Retrying with a different seed is not the answer, and the visuals and subtitles are then scheduled by timestamp.

In practice that means the audio is the spine of the timeline. The visuals follow the words rather than the words being fitted to a fixed picture length.

The second is that the storyboard is costed before anything is drawn. Each frame is budgeted for how many seconds it can occupy and how many strokes it can afford, and the picture is designed to that budget rather than compressing time to fit. The README lists that as 先算预算再出图, and the reasoning is sound: a drawing that has to be rushed is the one that looks rushed.

The drawing itself is described as drawing like a person. The ink-and-flat-fill style draws whole strokes, does outline before detail, moves the pen when lifting, and fills with a marker zigzag; a style with no outline reveals by part as the brush works; and Chinese characters are written in standard stroke order.

That combination of budget, stroke order and per-segment voice is what makes the output repeatable rather than a one-off, and it is why the README talks about keeping scripts, assets, audio, timestamps and check records so that a subtitle fix does not require regenerating the pictures.

Four voice paths, and the endpoints a local service must expose

The README separates the voice catalogue from the voice backend, and the choice is a table with four rows.

The built-in timbres are six, each with real reference audio and a same-text preview, and you can also import your own reference or keep a voice you have already accepted on the machine. What is then chosen is the backend that turns this text into sound.

The VoxCPM2 local adapter needs an Apple Silicon Mac, a separate MLX environment, mlx-audio, mlx and soundfile, a downloaded model and a real path, and the README is clear that the current adapter is not a Windows or NVIDIA deployment option. The VoiceStudio path needs a local service that offers a compatible HTTP API with a configured TTS engine, defaulting to http://127.0.0.1:3900, and it is already wired to mlx-audio with Qwen3-TTS-12Hz-1.7B-Base-bf16. The ready-made narration path takes checked audio with timestamps, which allows offline arrangement and rendering with no voice synthesis at all. The last row, Volcano Doubao or Gemini TTS, is optional, needs your own key in an environment variable, and the README is unusually candid about it: it was implemented from the official documentation and tested with a mock HTTP call only, this repository has not called it for real, it is not the default, and it is not switched to automatically when the local path fails.

The interface a VoiceStudio service must provide is also specified: /engines/tts, /generate, and an optional /transcribe, with the warning that any software with the same name is not necessarily compatible.

Installing the Skill into Codex or Claude Code

Installation is one command, and the README is precise about where the files land.

npx skills add threerocks/sweety-handdraw-video --skill sweety-handdraw-video --agent claude-code codex --global --copy --yes

This round supports macOS and Linux, with Codex and Claude Code as hosts, and Windows is not promised. Where it installs is spelled out: for Claude Code, ~/.claude/skills/sweety-handdraw-video, and for Codex, ~/.agents/skills/sweety-handdraw-video, which is the generic directory that command writes to. Installing for only one host means dropping the other --agent value, and dropping --global installs into the current project instead.

Pinning a version is a separate path. For a fixed build the README points at the v1.4.1 installation package and the list of all versions, and says to download SHA256SUMS.txt from the same page and check it with shasum -a 256 -c SHA256SUMS.txt. It also warns that updating the repository does not update an installed copy, so you replace the whole Skill directory and then read the VERSION file inside it, which should be 1.4.1 for this build.

The manual route is to put the entire sweety-handdraw-video folder from the package into the host's skills directory, with a warning to back up the old directory first, and that copying only SKILL.md will leave you without the scripts, the assets and the built-in dependencies. The hand art, the style previews and the audio previews ship with the package, around 38 MB, so once installed the tool works offline and no longer depends on a first-run download.

In use, you ask for it in plain language, telling the host to turn something into a hand-drawn video, or with the /sweety-handdraw-video command in Claude Code and $sweety-handdraw-video in Codex.

setup.sh builds the runtime, and the doctor command reports what is missing

The runtime preparation is a script, and the README gives both the install and the check-only form:

bash ~/.claude/skills/sweety-handdraw-video/scripts/setup.sh          # 或 Codex 安装目录下的同名脚本
bash ~/.claude/skills/sweety-handdraw-video/scripts/setup.sh --check  # 只检查，不安装

What setup.sh does is worth reading in detail, because it is the difference between a working install and a confusing one. It installs or checks FFmpeg, using Homebrew on macOS and apt on Linux, and on Linux it also installs fonts-noto-cjk and fontconfig and prints the dnf and pacman equivalents. It creates a Python virtual environment outside the Skill directory, at ~/.local/share/sweety-handdraw-video/venv, and installs scripts/requirements.txt into it, which the environment table lists as Pillow, NumPy, SciPy, requests and fontTools. It then verifies the installed package and reports which font was actually selected. It does not download a voice model: that only happens if --voxcpm is passed explicitly, on Apple Silicon, in which case roughly 3.2 GB of VoxCPM2-8bit is downloaded.

The doctor command gives the same information before you start. The README says to run python scripts/handdraw_video.py doctor JOB before making a video, and that it reports separately whether it can render, whether it can generate narration, and a note about image generation capability, giving a fix command for each missing item.

The environment table also records the honest limits of the setup. Complete production has been measured on macOS with Codex, while Claude Code has been verified for installation and the local scripts, with the full pipeline still to be measured. The agent must be able to read the Skill and run local commands. Image generation is available in Codex, and Claude Code needs a tool or MCP connection or must be given the illustrations, with the note that the scripts cannot detect host capability and that without image generation the workflow must stop and say so rather than deliver a text-only video. Python 3.9 or later, FFmpeg with ffprobe, Chinese fonts and one usable voice path are all required, and Node.js and npm are only needed for the install command.

One detail is worth keeping: image privacy cleanup is now pure Python in scripts/clean_image.py, so it no longer needs Bun or ExifTool.

Where sweety-handdraw-video is the wrong tool

The constraints are all consequences of the design, and the README is unusually clear about them.

The hard requirement is an agent that can generate images. The scripts cannot probe the host for that capability, and the environment table says it directly: without image generation you have to stop and explain, and you cannot deliver a video that is only text. That is the right behaviour, but it means the tool is not usable as a standalone command line program.

The second limit is the platform. macOS and Linux are supported with Codex and Claude Code as hosts, and Windows is not committed to. A team on Windows has no supported path, and the local VoxCPM2 adapter is Apple Silicon only, so the self-hosted voice route is narrower still.

The third is the cost of a local voice. The model download is roughly 3.2 GB, and the environment table says the scripts will not download it unless you pass --voxcpm explicitly. That is a sensible default, but it also means a fresh install has no working local voice until you make that decision, and the alternatives are a compatible local VoiceStudio service or pre-recorded narration.

The fourth is about the samples. The two featured videos were made with v1.2, so the continuous narration changes in v1.3 are not in them, and the README notes that the snake sample's original narration carries a continuous 235 Hz hum which a v1.3 gate would reject. The animations are silent excerpts, and the README is direct that you should download the full video to judge the voice and the pacing, because GitHub release attachments can only be downloaded and not played in the page. The samples are also the best available evidence of what the tool produces, and they are deliberately imperfect in ways the documentation names rather than hides.

The fifth is scope. The tool produces narrated explainer video, not a general video editor, and the README's own framing is that the longer samples show narrative range and do not mean a short opinion piece should be made into a long video. The MIT licence and the third party notices file are straightforward, and the last push was on 2026-10-19 with the current version at v1.4.1.

Editorial conclusion

Teams that publish explainer videos from written material and already run Codex or Claude Code should try sweety-handdraw-video, because it keeps the whole pipeline, script, storyboard, voice and drawing, in one repository with per-segment timing so the visuals follow the narration rather than the other way round. It is the wrong tool without an image generation capability in the host, since the scripts cannot detect that and the workflow must stop rather than ship a text-only video, and it is the wrong tool on Windows, which the README does not commit to. Before installing, read the environment table, because a local voice path can pull a model of several gigabytes, and check that the VoiceStudio service you point it at actually implements the endpoints it expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. threerocks/sweety-handdraw-video on GitHub