gooseworks-ai/goose-skills / skills/video/render-3d-character-explainer
render-3d-character-explainer
VerifiedAssemble an animated character-explainer video ad (~77s, 9:16, any art style: Pixar-style 3D, claymation, anime, paper-cut, felt) on an "N types of X" listicle spine: one recurring human protagonist plus one persona character per list item. Given per-scene clips, a scene timing table and narration, it trims, normalises, concatenates and mixes them, reusing the source ad's audio (restyle) or fresh per-scene voiceover over a music bed (original), loops a scene's keyframe when its clip failed, and burns captions last. Free, deterministic assembly (Python and ffmpeg, no paid calls); the recipe supplies the clips, keyframes, audio and captions. Use for the 3d-character-explainer format.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.8 KB |
| scripts/compose.py | script | 11.7 KB |
| scripts/config.example.json | config | 4.4 KB |
| scripts/make_captions.py | script | 3.2 KB |
| skill.meta.json | config | 239 B |
| tests/smoke-test.md | markdown | 4.2 KB |
tests/smoke-test.md
View on GitHub# Smoke test — render-3d-character-explainer
Verifies the free ffmpeg assembly end-to-end. No paid calls. Needs: Python 3 and
ffmpeg/ffprobe. You supply per-scene clips + a narration track (restyle mode) or per-scene
VO mp3s (original mode). Any 1080×1920 mp4s and any audio track work for a smoke run; a
scene with no clip must have a `keyframe` PNG so the static-still fallback fires.
## Setup
```bash
cd scripts
mkdir -p /tmp/3dchar-smoke/clips /tmp/3dchar-smoke/keyframes /tmp/3dchar-smoke/audio
# synthetic color clips + a still keyframe + a silent narration track:
ffmpeg -y -f lavfi -i color=c=red:s=1080x1920:d=3 -r 30 /tmp/3dchar-smoke/clips/clip-01.mp4
ffmpeg -y -f lavfi -i color=c=green:s=1080x1920:d=3 -r 30 /tmp/3dchar-smoke/clips/clip-02.mp4
# scene 03 has NO clip -> exercises the static-still fallback from its keyframe
ffmpeg -y -f lavfi -i color=c=blue:s=1080x1920:d=1 -frames:v 1 /tmp/3dchar-smoke/keyframes/scene-03.png
# total audio = sum of the three windows (2.0 + 2.5 + 1.5 = 6.0s)
ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t 6.0 /tmp/3dchar-smoke/audio/source-audio.mp3
```
Write `/tmp/3dchar-smoke/config.json`:
```json
{
"audio_mode": "restyle",
"source_audio": "/tmp/3dchar-smoke/audio/source-audio.mp3",
"captions_ass": "/tmp/3dchar-smoke/captions.ass",
"scenes": [
{ "id": "01", "clip": "/tmp/3dchar-smoke/clips/clip-01.mp4", "keyframe": "/tmp/3dchar-smoke/keyframes/scene-03.png", "target_sec": 2.0, "caption": "Six types." },
{ "id": "02", "clip": "/tmp/3dchar-smoke/clips/clip-02.mp4", "keyframe": "/tmp/3dchar-smoke/keyframes/scene-03.png", "target_sec": 2.5, "caption": "One per persona." },
{ "id": "03", "clip": "/tmp/3dchar-smoke/clips/missing.mp4", "keyframe": "/tmp/3dchar-smoke/keyframes/scene-03.png", "target_sec": 1.5, "caption": null }
]
}
```
## Run
```bash
# 1) per-scene captions (libass) — run BEFORE compose
python3 make_captions.py --config /tmp/3dchar-smoke/config.json \
--out /tmp/3dchar-smoke/captions.ass
# 2) assemble the master
python3 compose.py --config /tmp/3dchar-smoke/config.json \
--work-dir /tmp/3dchar-smoke \
--out /tmp/3dchar-smoke/master.mp4
# 3) confirm 9:16, 30fps, duration == sum of the windows (6.00s)
ffprobe -v error -select_streams v:0 \
-show_entries stream=width,height,r_frame_rate \
-show_entries format=duration -of default=nw=1 /tmp/3dchar-smoke/master.mp4
```
## Expect
- `make_captions.py` writes `captions.ass` — one cue per scene WITH a caption (scene 03
suppressed), `start = scene_start + 0.08s`.
- `compose.py` prints per-scene retime lines, a `scene-03 STATIC-STILL fallback` line, the
total runtime, a final `WROTE ... (expected ~6.00s, delta ±...)`, and
`STATIC-STILL FALLBACK SCENES: 03`.
- `master.mp4` is `width=1080`, `height=1920`, `r_frame_rate=30/1`, and its duration is
within ±0.1s of `sum(scenes[].target_sec)` (6.00s here).
- Run the `watch` skill on `master.mp4` for a real (non-synthetic) run: the human protagonist
holds across scenes, each persona is on-model, the cast-reveal matches the N list items, the
product beat shows the REAL box (blank label in the plate, real box composited), narration
lands beat-for-beat, and captions don't collide with on-screen text.
## Fail signals
- Concat drops frames / audio desyncs → a segment wasn't re-encoded to 30fps (all segments
MUST be `libx264 -r 30` before the concat demuxer). compose.py always re-encodes, so this
means a source clip fed the wrong stream — check the ffprobe output.
- Duration far off the summed windows → a `target_sec` wasn't the source-inherited window
(restyle) or the measured VO duration (original); the trims must sum to the audio length.
- Master has letterbox bars from a mismatched-aspect clip → expected: decrease+pad pads to the
canvas colour rather than cropping. If the bars are the WRONG colour, set `pad_color`.
- `scene-NN: no usable clip AND no keyframe fallback` → a scene has neither a valid `clip` nor
a `keyframe`; every scene needs a keyframe so the static-still fallback can fire.
- Original mode loudness off (not ~-14 LUFS) → the VO/music busses were bypassed; confirm the
`loudnorm` filters ran and `amix normalize=0`.
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |