video-gif-studio

Video GIF Studio

Deliver an inspectable animation, its source lineage and a reproducible export. Preserve the user's latest motion, appearance and camera preferences. Reference images are optional; an existing video can be sufficient. Do not inherit this skill's founding character, pose, color, duration, or chair constraints into unrelated work.

Match the requested scope

Users may describe only an intended result. Infer a suitable script, motion, timing, camera, effects and output from that goal; briefly state the choices and proceed within existing authorization. Ask only for a necessary missing input, a consequential ambiguity or new spending authority. Do not require a settings questionnaire.

• Script/storyboard only: read planning, deliver the written plan and stop without image or video generation.
• Music analysis only: read music, analyze the supplied audio and return candidate cue timestamps with suggested uses and review status. Do not generate or edit footage unless requested.
• Simple local editing: read timeline and music when relevant. Prepare source frames before composing trims, reordered segments, retiming, holds, loops and an optional soundtrack. For requested source sound, provide a timeline-aligned source_audio and enable --keep-audio; PNG frames alone cannot preserve audio. Video delivery streams at 30 fps by default; use --platform for delivery presets and --proxy for previews (see video delivery). For explicitly requested post-production effects, use scripts/fx_render.py and fx; never invent effects for character actions, substitute effects for physical motion, or conceal bad joins.
• Generate animation/assets: continue below; use the requested format, GIF by default, video for long/music deliverables and PNG/sheets for game use.
• Pixel sprites: use an available sprite skill for intentionally discrete pose-sheet creation, then follow this skill's pixel-native processing and export guidance. Do not require continuous video for every pixel-art request.

Defaults unless the user specifies otherwise

• Motion follows plausible physics and visible cause and effect: support and weight transfer drive the body, the hand drives a held weapon, and cloth/particles follow with appropriate inertia. Effects never substitute for missing physical movement.
• Let the action produce reasonable whole-body travel by default: stepping, lunging, advancing, retreating and returning to balance are allowed when motivated. Show coherent support, push-off, pelvis movement, weight acceptance and recovery. Do not prescribe stationary feet or an immobile lower body merely to simplify alignment or looping; a fixed camera/canvas does not mean a fixed character. Honor an explicitly requested in-place animation or movement limit while retaining plausible weight transfer within it.
• Human characters retain coherent anatomy, limb proportions, joint ranges, muscle and soft-tissue tension, perspective, foreshortening and occlusion throughout the motion. These defaults also apply to pixel art and stylized humans; explicitly requested exaggeration or nonphysical behavior overrides the relevant default.
• When effects are requested, let the selected video generator design and generate them together with motion, using Grok by default. Honor an explicitly selected alternative. When using an accepted fallback, retain the requested effect intent and record the actual generation source. Specify the action, causal timing, readability and background-separation constraints; leave effect shapes, colors and details to that generator unless the user supplies art direction. Do not invent effects for a task that did not request them. Local work defaults to matting, sampling, timing and encoding, not drawing or layering new effects. Record any user-requested exception and actual effect provenance.
• Keep the entire character, weapon and effects visible by default, including trails, expanding particles and their complete dissipation. Frame for the maximum extent over the whole action, not just the starting pose. Do not crop effects at the canvas edge or cut their decay short to fit an export. Respect explicitly requested off-screen action/cropping; otherwise treat lost effect content as an unfinished deliverable.
• A seamless-loop request remains an acceptance requirement through later revisions. Repeated playback is not seamlessness. A preview with a visible boundary mismatch is unfinished, even if encoding checks pass.
• For a loop that returns to its starting location, include a natural recovery and return path. Do not replace that path with per-frame recentering, position snapping or locked feet. Preserve intentional character travel during export.

Requirements

For installation requests, follow references/install.md: have the AI check, download and install missing prerequisites, including Python, rather than return a manual checklist. Preserve working installations; interactive account authorization remains with the user. Use this skill folder's .venv/bin/python (Windows: .venv/Scripts/python.exe) for its scripts; do not assume the current shell Python has the dependencies. scripts/doctor.py reports local readiness without spending generation quota.

Use Grok by default for new motion and effects unless the user selects another route. Grok is an optional dependency, not a prerequisite for GIF generation. Other available and authorized generative video tools can replace Grok, or their outputs can be imported. When no suitable video route is available, use an available image tool for appropriate keyframe GIFs; existing media can also be processed locally. Prefer Grok continuous video when available for more natural articulated motion. The Grok route uses Codex + Grok: Codex runs this skill, directs the motion, uses available image generation when needed, and processes/verifies the output; Grok supplies generated continuous video. Grok must be authenticated and have usable video-generation entitlement/quota. This version includes its own OAuth REST client, using the official Grok CLI for OAuth sign-in and credential refresh, or an explicitly selected direct API key, as described in references/grok.md. Do not imply the repository provides accounts, subscriptions or credits. The installer manages Python packages and missing FFmpeg/ffprobe binaries; read managed dependencies when installing or diagnosing tool availability. Existing video/RGBA conversion can run locally without a new Grok call. Grok and fal.ai MiniMax H3 Max clients are bundled. When fal.ai or H3 Max is selected, read fal connection and modes and use scripts/fal_video.py; never silently switch models or billing providers. Other providers require available tools or explicit integration. Grok website generation/import needs website login, while the bundled client requires its own CLI OAuth session or explicit API key; website login alone does not authenticate the client.

Select the route

Generation providers are interchangeable input routes, not the identity of this skill. fal.ai / MiniMax H3 Max is one supported route, never the sole required provider. Apply the same inspection, repair and final-quality gate to Grok, other available authorized generators, user-supplied footage and existing local videos. Preserve the actual provider provenance; a new route requires its own capability/authentication check and does not silently change billing authority.

• Existing video: inspect it first; keep actual continuous frames when the action is usable. For phone VFR, rotation or HDR, use scripts/intake.py and video delivery before frame preparation. Diagnose before regenerating.
• Reference images: view them and assign roles (identity, costume, proportions, pose, camera, palette). Record exactly which references are actually sent to the provider. A prompt description of a photo is not an uploaded photo.
• No reference: author an original subject and motion brief. When a stable character is useful, generate a start image using the available image-generation tool, inspect it, then animate it. Direct text-to-video is an alternative only if the active provider supports it; do not claim an untested route is verified.
• Natural articulated movement: prefer a continuous video source over independently generated pose sheets. Independent images, crossfades and optical-flow interpolation cannot reliably invent missing joint paths.

For generated raster art, follow the available image-generation tool's instructions; do not replace requested artwork with procedural placeholders. For a chosen video provider, check its live capabilities, authentication, supported inputs and pricing exposure. Read references/grok.md for the bundled Grok client and its limits. If Grok is unavailable, quota-limited or rejected, read fallback routes and check authorized alternative video tools, existing footage, image-generated keyframes and suitable local assets before stopping. Report the failure and actual alternative route; do not hide it behind unrelated static animation or change paid services without authorization.

Direction and generation

Read references/motion.md when designing or revising action. Write a concise visible plan and one executable prompt. Separate:

1. Appearance/camera invariants and reference roles.
2. Ordered action phases, support/contact, anticipation, travel, contact and recovery.
3. Approximate phase durations and playback intention.
4. Secondary motion and motivated camera/prop movement.
5. Background/lighting requirements and intended loop behavior.

Use the user's existing authorization; do not insert a generic approval gate. Ask only for a consequential missing choice, new spending authority, or a required missing input. Generation authorization does not authorize publication or messages to others. Default to one candidate; allow one focused corrective retry within authorized scope, then reassess from pixels rather than blindly resubmitting. Do not retry ambiguous submissions without recovering the existing job ID first.

Preserve source files. Save prompts, ordered input roles and hashes, model/settings, job ID, provider status, actual duration/dimensions and reported usage. Keep auth tokens and signed delivery URLs out of shared artifacts. A provider response saying done proves generation, not correct anatomy or natural motion.

Inspect and refine

For background removal or output selection, read references/transparency.md. Default to Auto, preserving source motion and character pixels; keep graded alpha in RGBA masters and use APNG for soft-alpha animation, with GIF as a compatibility preview. Honor an explicit format request. Users may choose Preserve artwork or AI repair/redraw; these are workflow choices, not CLI flags. Do not automatically redraw every frame with GPT-Image-2.5 or another image model. Verify actual model access and alpha capability, and recheck temporal consistency after any requested repair. A game-use request should lead to PNG frames and an engine-appropriate asset plan, not a GIF-only delivery. The bundled scripts/sprite_export.py packs uniform RGBA frames into multi-page sheets with timing and fixed-pivot metadata; see references/sprites.md.

For dirty contours, fragments or flickering edges, read structure-aware edge repair. For clean chroma or alpha output, use its material-aware alpha and geometry checks: confirmed backdrop is uniform, opaque surfaces stay opaque, fractional coverage/translucency remains graded, and contours follow perspective and motion without halos or jaggies. Identify the actual component and preserve its material, lighting and occlusion before choosing a local repair; pixel size or blur alone cannot classify a defect. Detached-looking detail may be a clipped real strand: use source-guided recovery in a reviewed mask when connection is missing, rather than automatically deleting it.

For hair popping, crawling fractional edges or hair overlapping clothing, read fine-hair occlusion and temporal repair. Verify source continuity, preserve opaque backing surfaces, and test both source-background recomposition and contrasting backgrounds; a successful numeric round trip is not a correct matte. Do not promote an unaccepted local candidate to a library-wide recipe.

For unintended holes beside straps, shoes or narrow limb gaps, use opaque-material loss diagnosis: distinguish material shading from the actual silhouette, repair source RGB as well as alpha when necessary, and validate positive surfaces and negative spaces separately. Never promote one clip’s repair parameters to a whole-library filter.

For reviewed opaque-material boundary recovery, use scripts/repair_material_boundary.py with explicit per-frame source-supported contours and protection masks; see the local boundary tool. It preserves untouched pixels and records review as pending, not accepted. For opaque interior holes already present in an early matte, use scripts/restore_opaque_material.py with reviewed per-frame opaque masks and matched source RGB. Its default preserves valid straight RGB/despill and recovers source color only for erased pixels; use source replacement explicitly for confirmed color damage. Follow coverage and color separation. Preserve real gaps and graded boundaries; mask creation and motion/export acceptance remain separate reviews. When missing opaque material and dirty contact edges occur together, use separate material-hole and contact-boundary diagnosis. Alpha addition and background removal need separate reviewed scopes; a successful local repair is not a whole-library acceptance.

Preserve plausible source motion blur: fast movement need not be sharp in every frame. Judge direction, extent and continuity against neighboring frames and normal-speed playback; follow motion-blur preservation when repairing soft moving edges. Clean output is not uniformly sharpened output.

Watch the complete source at playback speed when a playback surface is available; separately inspect transition frames at useful resolution. Contact sheets cannot establish cadence. State when only frame inspection was available. Check joint paths, limb identity, contact, occlusion, shape continuity, subject detail, camera and prop motion. Use user feedback as evidence: do not "fix" a chair swivel or body counterbalance the user accepts as natural.

When motion is slow, distinguish moving phase from settling pause. "Natural speed" is not automatically 1× generated speed. Apply smooth phase retiming when the path is sound; regenerate when the path is absent or anatomically wrong. Do not mask a bad transition with a cut, ping-pong playback or blended ghost limbs. Read references/export.md for exact CLI input and output behavior.

For transparent output, prefer a separable constant background chosen to avoid subject colors, or source alpha. Magenta is useful, not mandatory. The included keyer is for uniform chroma backgrounds only; for complex scenes the optional bundled background_remove.py entry point can produce local rembg foreground masks from prepared frames. Read managed dependencies. These are framewise masks and require flicker/edge review; they are not a temporal matting model. Preserve interior negative spaces. Do not flood-fill every interior hole or erode the subject as a universal repair. Check masks over both dark and light backgrounds.

Keep a shared canvas. Only stabilize measured unwanted camera drift; never recenter every frame by its bounding box, reshape anatomy, or pin a naturally moving prop without justification. Keep original camera/prop movement unless the brief calls for a change. Loop closure requires compatible pose, velocity and contact; do not label a visible end/start jump seamless.

Read the loop and causal-review guidance in references/motion.md before accepting articulated actions, effects or a requested seamless loop. Review actual weapon paths separately from effect trails. If a bounded corrective retry still fails, retain the unfinished status and explain the specific remaining defect rather than relabeling a preview as complete.

Stylized redraw

When the user asks for a drawn or graphic look a video generator cannot hold (ink, paper cut-out, manga, flat vector), or when accepted motion needs a finish its matte cannot reach, read stylized redraw. The generated or supplied video becomes a motion plate: every delivered pixel is rendered from guides measured on it, and no plate pixel is delivered. Accept the plate for motion first; redrawing keeps bad joint paths. Extract guides with scripts/extract_guides.py (--flow for texture that rides on moving parts), assign effects to their own layer only through reviewed masks (propose_effect_masks.py, review_masks.py, apply_mask_edits.py), render with scripts/render_stylized.py and a bundled or authored Python or JS style plugin, and run scripts/qc_redraw.py. Automatic checks, agent visual notes and human playback review are separate records. A render that fails a check, or shows texture sliding, marbling or shimmer when inspected, is a preview. Do not use this route unrequested or to hide a defective source.

Final quality gate

After export or a timing/visual repair, run python scripts/qa_media.py <delivery> --out <new-qa-dir> on the decoded GIF/APNG/MP4 or PNG sequence (--fps for PNG). Read PASS/WARN/FAIL and each flagged frame/time: FAIL blocks delivery, WARN needs inspection, and PASS only confirms measured thresholds. Numbers cannot prove natural motion, semantic correctness, good matting or music sync. Follow the independent review and completion checklist in quality review; annotate intended holds with --holds or a timeline and use --loop when appropriate.

A requested finished deliverable includes inspection and repair, not just encoding. Perform necessary local cleanup within that request instead of asking separately whether the user wants defects repaired. Inspect source, repaired masters and decoded output for visible contamination, unreasonable contours, lost material/lighting detail, flicker, clipping and broken motion/loop/transition boundaries. Use structure-aware edge repair for local masks and scripts/repair_edges.py for reviewed RGBA sequence repairs. Repeat the relevant inspection after each repair and validate the actual target format/player when available. Do not claim automatic semantic understanding from numeric tests, or that all defects are absent because encoding passed. If a visible defect remains unresolved, continue within the authorized repair scope; when a genuine limitation prevents completion, identify it and label the output a preview, never a repaired final. A whole-library task needs per-clip results, including exceptions.

For library-wide repairs, follow the library acceptance and delivery gate: verify stable placement, plausible motion and actual playback within clips, at loop boundaries and across reachable transitions. Unrequested flicker or position/scale jumps fail acceptance. If the user conditions commit/push on completion, finish that gate before submitting the requested changes; do not substitute a tooling-only commit for finished assets.

Export and verify

After encoding the delivery, run python scripts/qa_media.py <delivery> --out <new-qa-dir>. Review each PASS/WARN/FAIL and its frame/time: FAIL blocks delivery, WARN needs inspection, and numeric PASS cannot establish natural motion, semantic correctness or music sync. Retain the three sheets and reports, then follow quality review for independent visual review. Use --holds for designed pauses and --loop for loop checks; silent assets skip audio checks.

Run scripts/gif_pipeline.py from this skill folder. Dependencies: Python 3, Pillow, NumPy, OpenCV; FFmpeg/ffprobe for VFR video conforming and optional delivery formats. Export into a new run directory, never the skill directory. The helper accepts a CFR video or a numerically named RGBA PNG directory.

Essential GIF invariant: reserve a palette index exclusively for transparency. Quantize visible colors independently and assign transparent pixels from alpha explicitly. Never choose the "nearest magenta" palette color as transparency; this can punch holes in skin shadows. All frames share one palette. Use explicit disposal and verify the decoded GIF, not just source PNGs.

The helper validates every decoded alpha mask against its source threshold, dimensions, frame count and total duration. Inspect skin/fabric color error and edges as well. This proves export integrity, not matting truth, no source flicker, anatomy, natural cadence, or target-app rendering. For a reported defect, compare raw source → RGBA → decoded GIF at the same source index and timing; use references/failure-modes.md.

Deliver the GIF inline, a download link and concise changes/limits. Retain source, masks/frames, timing, contact sheets and provenance. Offer APNG or video when gradients, alpha softness or file size matter. Never rename a lossy GIF limitation as a stylistic success. If the source remains flawed, deliver only a clearly identified preview plus the unresolved issue.

Worked production example

When an actual reference-to-video-to-GIF case or transparency regression example would help, read examples/seated-leg-switch/README.md. It contains the actual uploaded reference, full prompt, source video, final corrected GIF, timing and hashes. These are examples, not default character design, pose, speed or duration settings. Do not load its large media for unrelated tasks.

For a no-user-reference example, see examples/robot-wave-no-reference/README.md: an original start image, a real generation through the bundled Grok client, and a verified transparent GIF. Distinguish zero user references from the generated image used as the video's starting frame.

For a pixel-style running attack with Grok-generated effects and identical pinned endpoints, see examples/chibi-running-dash/README.md. It includes GIF/APNG, source, prompt, timing and verification; playback-speed seamlessness remains unverified.

For a stylized redraw with motion-attached screentone, flow-driven speed lines, a JS style and recorded acceptance, see examples/stylized-redraw-seated/README.md. It also records a preview render that failed a check and why.

Pixel-art defaults

When pixel art is requested, default to pixel-native processing: work on the established logical pixel grid, preserve intentional color clusters, stepped contours and limited palette, and use integer nearest-neighbor presentation scaling. Do not blur, smooth, add antialiasing, use optical-flow inbetweens or regenerate every frame to conceal a bad key. Fractional alpha remains valid for intentionally soft or fading effects; pixel art does not imply globally binary alpha. Pixel-style AI video may lack a consistent native grid: report that limitation instead of claiming nearest-neighbor export creates hand-authored pixel art. Read references/pixel-art.md for edge repair and validation. Honor explicitly requested mixed styles or filtering.

Optional delivery formats

Users may select any combination of GIF, APNG, RGBA PNG frames, Sprite Sheet, MOV, WebM, MP4, or complete asset pack (frames, sheets, metadata and previews). Treat these as output choices, independent of Auto / Preserve artwork / AI repair. Honor explicit selections; do not require a format questionnaire for every task. GIF is the default output when no format is selected. Retain RGBA masters; optionally include APNG for soft-alpha sharing. For explicit game use prioritize PNG frames plus sheets/metadata. A long-video request should use a video container, with GIF only as an optional short preview. See references/video-export.md for MOV/WebM export. Ask about a target engine only when an engine-specific importer/material is required; generic sprites can be prepared immediately.

Read references/sprites.md for sprite export. Keep all frame canvases and the pivot stable, preserve full effects and fractional alpha, and retain intentional displacement. A user may choose page size, padding, native pixel scale and pivot. Infer reasonable defaults and record them. Never claim generic sheets are engine-tested resources, infer hitboxes from glow, or invent gameplay events/root-motion tracks. For looping actions, pinned first/last provider inputs are an available generation technique when supported, but pose/contact/velocity and actual repeated playback still require review.

Optional reference and continuation chain

When the user requests reference extraction, another generation, video editing or continuation, read references/chain.md. Offer three reference modes: suitable keyframes (up to seven), last frame plus consistency references, or last frame only. For requested continuation with no specified reference mode, prefer last frame plus a small set of stable consistency references, subject to verified provider support. Choose frames for their purpose rather than equal time spacing; never pad the set to seven.

Users may choose reference pack only or continue generation. Without authorization for another generation, prepare the reference pack and stop. Existing generation authorization remains valid within its stated scope; do not ask again unnecessarily. A request to update the skill or documentation does not itself authorize a production run. Codex coordinates the chain; automatic keyframe selection and a chain runner are not bundled. The fal client supports multi-reference generation, but not localized video editing, Director streaming or automatic extension. Check the actual provider route before dispatch; do not silently substitute an image-to-video call for requested video editing or extension.

MP4 output uses opaque H.264: explicitly tell the user it does not preserve transparency. Composite onto a user-selected solid background, default black, before encoding. MOV/ProRes 4444 and WebM/VP9 alpha require target-player compatibility checks.

Timed stills and local timeline composition

When the user asks for a picture held for a duration, a freeze-frame or a pause between clips, use references/timeline.md and scripts/compose_timeline.py. Select an explicit image, previous tail frame or a prepared animation's first/last frame and record the added duration. This local operation needs no new Grok generation. Distinguish a completely frozen image (including its effects) from idle motion such as breathing/blinking or continuing particles, which requires animation. Preserve pixel-native scale, shared canvas, alpha and timing; review the transition into/out of a hold. GIF remains the default and APNG, sprite, MOV, WebM and opaque MP4 are optional. Local composition is implemented; automatic multi-generation chain execution remains unbundled.

For “play this loop for N seconds,” use a loop segment in the local timeline. Offer exact duration (default) or complete-cycle ending; complete-cycle mode may exceed the requested time and must report the actual duration. Preserve source cadence, inspect the loop boundary and the next transition, and do not imply repeating a flawed source makes it seamless. A timed loop is distinct from a static hold and from generating new actions. See timeline loop options.

Music input, beat timing and editing

For music-driven animation/PV/MV work, read references/music.md. Use the bundled music_sync.py for waveform and editable BPM/beat candidates, then compose_timeline.py for source trims, ordering, speed/duration fitting, beat cuts, timed stills/loops and a continuous soundtrack. Analyze locally and preserve the original song. Prefer user-specified BPM/offset or reviewed beat timestamps over uncertain automatic estimates; never treat onsets as guaranteed downbeats. Do not require a new generation for a local edit.

Choose salient musical accents and actual visual events, not every beat mechanically. To align an attack/contact event, inspect its source time and fit preparation/recovery around it; a clip-end snap alone does not align internal action. Keep anatomy, weight transfer and pixel-grid rules when retiming. Music requires MOV/WebM/MP4; GIF remains the general default for silent requests, and silent previews may accompany music videos. Review actual audio/video sync and retain estimated/unreviewed status when no listening review is possible. This is a bounded local editing workflow, not a claim of full NLE parity or music-conditioned video generation.

Reusable agent and RTS animation libraries

For controllable characters or reusable action libraries, read animation states. Generate and cache reviewed entry, loop and exit clips, using consistent character/camera/pivot contracts. Drive playback from real agent events; a state machine alone does not make unrelated clips seamless. Transparent PNG frames/sheets are the runtime assets; GIF is a preview.

Character replacement with original motion/audio

For “same video/music, change only the character,” read character-video-edit. Use scripts/assemble_edit.py for reviewed frame selections and time-bounded inset restoration. Reject missing frames, explicitly opt into FPS conform, and stream-copy complete original audio in a separate mux. Check tiny/occluded actors and effect silhouettes as well as faces; technical success leaves semantic and human review pending.

Spatial previs and paired review

For interactive camera blocking, verified control ZIP to MP4, and timestamp-aligned A/B review boards, read spatial-previs-workflow.md.