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. Source clip audio is not automatically retained; clarify an audio-preservation request before using this visual-frame route.
• 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. Only the Grok client is bundled; 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

• Existing video: inspect it first; keep actual continuous frames when the action is usable. 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.

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.

Export and verify

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.

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; this repo does not yet bundle automatic keyframe selection, a chain runner, or multi-reference/edit/extend CLI modes. 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.