aguspranyoto/2d-animation-hyperframes

---

name: 2d-animation-hyperframes description: Turn a user-supplied emotion-tagged narration script (script.txt with tags like [excited], [curious]) and its voiceover into a consistent 2D educational animation in HyperFrames, using the project's visual references. Style: 2D flat, dominant white background with faded sketch lines, only the main subject and text in full color. Do not draft narration unless explicitly asked. Also covers sound effects: where they go, how to retrieve or synthesize them, and how to wire cues into the timeline.

2D Animation HyperFrames

Use this skill to make an animated video from the user's approved narration script and timing source. The normal input is vo.mp3 plus script.txt (emotion-tagged narration), with visual references in references/visual-style/overall/.

Example trigger:

/2d-animation-hyperframes Create a 2D animated video using vo.mp3 and script.txt. Follow the visual references in references/visual-style/overall/.

The user's script and audio are the source of truth. Do not spend tokens drafting a new script, rewriting narration, or generating a replacement voiceover unless the user explicitly asks. Emotion tags are delivery instructions, not spoken words: keep them verbatim and never read or caption them. If the requested files are missing or ambiguous, ask for their location; do not substitute a newly written script.

Default audience is Indonesian children from TK through SD. Keep visual storytelling clear, warm, and age-appropriate. Keep all animation 2D.

Inputs, script format, and timing

Find the files attached to the request or in the active project. Use the provided paths when specified. If files are not in the project, ask where to find them before starting production. Sources live in the workspace layout described in references/multi-video.md: the narration and voiceover are in inputs/<slug>/, the HyperFrames project is generated under videos/<slug>/, and the shared visual references sit at the workspace root (references/visual-style/overall/).

script.txt format: a line containing only an emotion tag in square brackets (for example [excited], [ curious ], [playfully]) sets the delivery for the narration block that follows, until the next tag. Blank lines separate blocks for readability only; they do not imply pauses. Example:

[excited]
Adik-adik, pernah nggak sih kalian melihat jerapah?

[curious]
Wah, lehernya panjang sekali, ya!

Rules for the tags:

• A tag applies to the whole narration block after it. Use it to drive the scene beat, character expression, pacing, and visual emphasis.
• Never speak, caption, or render the tags. Strip them before producing on-screen text.
• Keep tags exactly as written. If the voiceover was generated by ElevenLabs, the same tags were the delivery instructions; do not normalize or invent new ones.
• Unrecognized tags are still delivery hints; pass them through rather than dropping them.

Timing source, in priority order:

1. If the user also provides a word/segment timestamp export (ElevenLabs JSON) for the same audio, use it; it is optional, not required.
2. Otherwise derive word-level timing from vo.mp3: transcribe/align the supplied audio against script.txt text (for example ElevenLabs Scribe word timestamps, or the timestamp payload returned when the TTS produced the audio).
3. If vo.mp3 is missing, ask for it. Do not synthesize a substitute voiceover unless the user asks.

Before animating:

1. Check that every script block maps to a span in the audio and that the timing source covers the full vo.mp3 duration, including any initial offset or pauses.
2. Confirm the script text corresponds to the supplied audio. Do not edit the narration. If text, audio, and timings conflict, explain the mismatch and ask for corrected files.
3. Use emotion-tag blocks (and segment boundaries if a timestamp export is supplied) for story beats and scene changes. Use word timestamps for captions, emphasis, and small visual cues. Group words into meaningful phrases instead of making every word a separate scene.

Build the 2D visual style

Default style keyword for every scene:

2D flat, Dominant white background with faded sketch lines. Only the main subject and text are in full color.

Inspect all usable images in references/visual-style/overall/ together before designing scenes. Treat them as the source of truth for this project's visual identity. Extract a compact style guide covering:

• palette, saturation, contrast, lighting, and glow;
• shape language, line weight, texture, and detail density;
• character proportions, expressions, and recurring design features;
• composition and how flat 2D artwork suggests depth;
• typography, text animation, pacing, transitions, and visual motifs.

Apply one consistent style guide to every scene and new asset. If references conflict, follow the most repeated or most recently approved direction; ask only if the conflict would materially change the result. Keep the result 2D: use layers, parallax, overlap, scale, shadows, and gradients for depth. Do not turn it into 3D models or a 3D-rendered look unless the user asks.

HyperFrames production workflow

1. Use HyperFrames as the animation and rendering framework. Work in the user's active video project folder and preserve its assets and references.
2. Plan scenes around the approved narration, emotion-tag blocks, and word timings. Keep the narration unchanged; align visual actions and captions to the audio timeline. Put music and sound effects in pauses or at levels that do not mask speech.
3. Build a short 2D test scene using the actual vo.mp3, script.txt, and visual references. Preview it and check style consistency, readability, and synchronization at speech onset, pauses, transitions, and ending.
4. Make targeted revisions based on the preview, then extend the approved visual language across the full video. Do not create the full animation before the test scene is reviewed.
5. Run the HyperFrames preview from the project folder (npx hyperframes preview). It opens the browser-based HyperFrames Studio and hot reloads file changes. The separate desktop Studio app is optional for this CLI workflow.
6. Render the approved project to MP4 with the current HyperFrames CLI workflow. Report the output path and any production limitations. Do not claim a preview is a rendered final video.

Use the installed HyperFrames authoring instructions if available. If setup or dependencies are missing, explain the exact missing step. Do not install software or change global settings without the user's authorization.

Starting a new video

Generate the HyperFrames project from the workspace root instead of scaffolding by hand; one project per video.

python tools/new-video.py <slug>                    # scaffold + transcribe + block map
python tools/new-video.py <slug> --force            # rebuild an existing videos/<slug>
python tools/new-video.py <slug> --no-transcribe    # scaffold only

It reads inputs/<slug>/ (vo.mp3 + script.txt) and writes videos/<slug>/, then prints one line per tagged block with absolute and local start/durations. Full layout, outputs, and post-generation steps are in references/multi-video.md.

Sound effects

SFX sit under narration, never over it. Put one accent on each visual hit (element appear, cut, punchline, reveal) — not on every caption. Leave silence between cues.

• Default route: retrieve CC0/CC BY effects via the media-use skill (Openverse, or its bundled 21-file library in that skill's audio/assets/sfx/). Never generate when a stock effect matches.
• Custom route: synthesize a consistent family with Python (numpy + stdlib wave, 44.1 kHz mono 16-bit, peak-normalised 0.7, seeded noise). Recipes for pop, boing, whoosh, chime, stamp and sparkle are in references/sfx.md.
• Wire each cue as a timed <audio> on the root composition: unique id, data-start in absolute seconds, data-duration equal to the file length, data-volume 0.22–0.38, and a data-track-index that does not overlap another audible clip.
• npm run check must report 0 errors and no clip_ends_past_root_duration or duplicate_audio_track warnings before rendering.

Scope

This skill creates the animation from supplied media; it does not normally create or revise narration. If the user only asks for a storyboard or visual plan, provide that based on the same audio and script.txt without drafting a script. If the user explicitly asks for scriptwriting, handle that separate request and get approval before generating a new voiceover or replacing the existing audio.