v-anim-clip-to-video (CLI)

Small Go CLI that uploads a GTA V .ycd animation clip dictionary to an anim clip → GIF/WebM HTTP API and saves the result. Also supports inspecting a .ycd to list all available clips and their metadata without rendering.

.ycd → GIF:

Limits and API keys

Tier	Daily limit
No key (per IP)	1 conversion per 24 h
API key — basic	3 conversions per 24 h
API key — Pro	100 conversions per 24 h

You can create a free API key at gtax.dev/api-keys.

Set the key with -api-key or the environment variable V_ANIM_CLIP_API_KEY.

API endpoint

The CLI always uses the hosted conversion service at https://public-anim-clip.gtax.dev.

Build

go build -o v-anim-clip-to-video .

Usage

v-anim-clip-to-video -i <file.ycd> [options]

The CLI has two modes:

• Convert — posts multipart/form-data to POST {base}/convert/ycd. Successful responses are image/gif or video/webm (VP9 with alpha channel). Errors are JSON: {"error":"..."}.
• Inspect — posts multipart/form-data to POST {base}/inspect/ycd and prints clip metadata as JSON to stdout. No rendering, no output file written.

Flags

Flag	Default	Description
-i	—	Input .ycd file (required).
-inspect	false	List available clips as JSON and exit (skips all rendering flags).
-o	input basename + .gif/.webm	Output file path.
-output	gif	Output format: gif or mp4 (outputs .webm VP9 with alpha).
-sex	male	Ped skeleton: male or female.
-clip-index	-1 (first clip)	Zero-based index into the sorted clip list. Mutually exclusive with -clip.
-clip	`` (first clip)	Select a clip by its hash key. Mutually exclusive with -clip-index.
-view	front	Camera angle: front, side, or iso.
-fps	15	Frames per second (1–30).
-width	540	Output width in pixels (128–1080).
-height	540	Output height in pixels (128–1080).
-camera-follow	true	Re-center the camera on the ped every frame. Pass -camera-follow=false for a fixed camera so the ped translates across the frame as it moves.
-fixed-zoom	false	Lock the zoom across all frames so the ped does not pulse/breathe in size as limbs extend and contract.
-api-key	$V_ANIM_CLIP_API_KEY	Bearer token for authentication.
-timeout	5m	HTTP client timeout.

Response stats are printed to stderr: duration, frames, clip, clip_count, queue_wait_ms, rate_remaining, rate_limit.

Examples

The example/ folder contains two walk-cycle YCDs ready to use.

Male ped, GIF (default):

./v-anim-clip-to-video -i example/move_m@generic.ycd

Female ped, WebM with alpha, side view:

./v-anim-clip-to-video -i example/move_f@generic.ycd -sex female -output mp4 -view side -o walk_f.webm

Select a specific clip by index (useful when a YCD contains multiple animations):

./v-anim-clip-to-video -i example/move_m@generic.ycd -clip-index 2

Select a clip by hash key:

./v-anim-clip-to-video -i example/move_m@generic.ycd -clip 3065455489 -o walk.gif

Isometric view, higher resolution:

./v-anim-clip-to-video -i example/move_m@generic.ycd -view iso -width 720 -height 720 -fps 24 -o walk_iso.gif

Stable framing (no size pulsing): lock the zoom while keeping the camera centered on the ped:

./v-anim-clip-to-video -i example/move_m@generic.ycd -fixed-zoom -o walk_stable.gif

Fixed camera: disable per-frame follow so the ped translates across the frame as it moves:

./v-anim-clip-to-video -i example/move_m@generic.ycd -camera-follow=false -fixed-zoom -o walk_fixed.gif

With an API key (higher quota):

./v-anim-clip-to-video -api-key "$V_ANIM_CLIP_API_KEY" -i example/move_m@generic.ycd -output mp4 -o walk.webm

Discovering clips in a YCD

Use -inspect to list every animation in a .ycd file before rendering:

./v-anim-clip-to-video -i example/move_m@generic.ycd -inspect

Output (stdout):

{
  "count": 3,
  "clips": [
    {
      "hash": "3065455489",
      "name": "move_m@generic",
      "duration": 1.333,
      "frames": 41,
      "track_count": 24
    }
  ]
}

Then pass -clip-index 0, -clip-index 1, … or -clip <hash> to select a specific clip for conversion.