@docyrus/animaguru 0.35.1 → 0.38.0

package/README.md

@@ -29,7 +29,7 @@ The npm package requires Node.js 24+. Its default registry is https://registry.n
 
 From this repository, `npm ci && npm run cli:build` builds the CLI and `npm run cli -- --help` runs it. `npm run cli:release` prepares the npm tarball and public Mac downloads. `npm run cli:publish` publishes that reviewed release under the Docyrus organization; publishing requires a logged-in npm account with organization access and any required 2FA. Each release needs a new version in `cli/package.json`; the CLI version is read from that file. `npm run deploy` builds release downloads before uploading the site.
 
-The command `animaguru schema` returns the Crust command schema, and `animaguru catalog` lists supported art styles, actions, asset types, models, video profiles and speech voices; `catalog --type music` (or `sprites`, `image`, `vector`, `video`, `speech`, `sfx`, `model`, `avatars`) returns only that part. Shell completions: `animaguru completion zsh` (also bash and fish).
+The command `animaguru schema` returns the Crust command schema, and `animaguru catalog` lists supported art styles, actions, asset types, models, video profiles and speech voices; `catalog --type music` (or `sprites`, `image`, `vector`, `gif`, `video`, `speech`, `sfx`, `model`, `avatars`) returns only that part. Shell completions: `animaguru completion zsh` (also bash and fish).
 
 ## Required updates
 
@@ -63,6 +63,10 @@ CLI 0.34.0 adds `"thumbnail"` to `film.config.json` for a designed cover. It nam
 
 CLI 0.35.0 adds photoreal Gaussian splats: `assets generate --type model --model idol --reference SHA` turns the object in a saved image into splats with Sperid Labs' Idol on fal (`--photo` for a camera photo, `--splats` 32,768–1,048,576, `--seed`), saved as `.spz`, upright and facing +Z. New video workspaces include Spark, and the kit's `stage.splat()` draws splats in a three.js shot, sorted for each frame's camera, with `photoView()` to open on the reference image's exact view and `softShadow()` to ground them. See the `animaguru-3d-models` skill. CLI 0.35.1 fixes `photoView()` for product images Idol reads as near-orthographic (a field of view under 0.1°): it widens the view to 6° and moves the camera in, so the shot still opens on the product.
 
+CLI 0.36.0 adds Mureka 9.5 music on fal, HeyGen Voice speech and Seedance video on BytePlus (`--model byteplus/seedance-2.5`, `-2.0`, `-2.0-fast` or `-2.0-mini`). `--type music --model fal/mureka-9.5-song` sings `--lyrics` with `--vocals female|male` or writes a song from the prompt in `--styles`, for `--seconds` 120–300 or a length of its own; `fal/mureka-9.5-instrumental` writes from the prompt; `fal/mureka-9.5-soundtrack --source SHA` scores a saved video, image or sprite art. `--type speech --model heygen-voice-1` or `heygen-voice-1-turbo` speaks a HeyGen public voice ID given as `--voice` (Nadine by default). `catalog` lists `musicOptions` and `heygenVoices`. See [image, video, music and speech generation](#image-video-music-and-speech-generation).
+
+CLI 0.38.0 adds animated GIFs and GPT Image 2.6 vectors, both drawn by GPT Image 2.6 on fal. `--type gif` draws a short looping animation, such as a sprite's walk cycle, an icon that moves or a sticker, with `--frames` (2–16), `--frame-ms`, `--quality`, `--aspect-ratio`, `--transparent` and up to four `--references` to animate; it downloads as `.gif`, and its SHA works as a video frame or reference, through its first frame. `--type vector --model fal/gpt-image-2.6-vector` draws an SVG from the prompt alone and `--transparent` leaves out its background. `catalog --type gif` lists the models, limits and each frame's size. See [GIFs](#gifs) and [Vectors](#vectors).
+
 CLI 0.16.2 also installs `animaguru-art-motion` for Codex and Claude Code: one skill with 36 English art-treatment references and nine explainer motion grammars, plus AnimaGuru generation, timing, camera and review guidance. Request it explicitly for a custom film treatment; its references are separate from the gallery presets. Source coverage and the upstream MIT notice are included in the skill.
 
 CLI 0.5.2 includes a complete local PixiJS video workspace, now with 60 visual styles:
@@ -248,6 +252,22 @@ animaguru assets generate PROJECT_ID --type sfx --name "Magic spell" \
   --prompt-influence 0.6 --dry-run
 ```
 
+CLI 0.36.0 adds Mureka 9.5 music on fal and HeyGen Voice speech. A Mureka song sings `--lyrics` (with `--vocals female` or `male`, the prompt setting the style) or writes its own from the prompt in optional `--styles`; `--seconds` asks for 120–300 seconds. A soundtrack scores a saved video, image or sprite art given as `--source`, and runs as long as the video. HeyGen Voice speaks a public voice ID (Nadine is the default; `catalog --type speech` lists `heygenVoices`) and reads the transcript as written, so it takes no `--delivery`:
+
+```sh
+animaguru assets generate PROJECT_ID --type music --model fal/mureka-9.5-song \
+  --name "Studio song" --prompt "Upbeat synth-pop" --vocals female \
+  --lyrics $'[Verse]\nTiny robots in the studio light\n[Chorus]\nAnimate, animate' --dry-run
+animaguru assets generate PROJECT_ID --type music --model fal/mureka-9.5-song \
+  --name "Summer song" --prompt "A bright summer love song" --styles pop,r&b --dry-run
+animaguru assets generate PROJECT_ID --type music --model fal/mureka-9.5-instrumental \
+  --name "Menu loop" --prompt "Calm lo-fi piano for a cozy game menu" --dry-run
+animaguru assets generate PROJECT_ID --type music --model fal/mureka-9.5-soundtrack \
+  --name "Trailer score" --source VIDEO_BLOB_SHA --prompt "Tense, then hopeful" --dry-run
+animaguru assets generate PROJECT_ID --type speech --model heygen-voice-1-turbo \
+  --name "Host" --prompt "Welcome to AnimaGuru." --dry-run
+```
+
 Replace `--dry-run` with `--yes` to generate within your authorized credit budget. ElevenLabs accepts a voice ID in `--voice` and defaults to George when omitted. Use audio tags in the transcript; `--delivery` is only for Gemini and is rejected for ElevenLabs. SFX has a single model, `eleven_text_to_sound_v2`; `--seconds` accepts 0.5–30 (default 5), `--loop` requests a seamless loop, and `--prompt-influence` accepts 0–1 (default 0.3). Both return MP3. `catalog` includes `sfxModels` and `elevenLabsVoices`. The server needs `AI_PROVIDER_KEY_ELEVENLABS`; provider keys never belong in CLI credentials.
 
 CLI 0.8.0 adds MiniMax H3 Max Turbo and the H3 workflows. MiniMax H3 Max and H3 Max Turbo on fal.ai (`fal/minimax-h3-max`, `fal/minimax-h3-max-turbo`) also write videos from text and extend saved videos. Choose with `--workflow`:
@@ -334,9 +354,22 @@ animaguru assets generate PROJECT_ID --type video --model heygen/heygen-video-1
 
 From an image or text, HeyGen's clips run to 30 seconds while it rewrites the prompt: `--prompt-expansion balanced` asks for its fastest rewriting and `quality` its fuller one. Every second of a clip over 15 seconds costs its long-clip rate. At 1080p and 2K, text-to-video and reference-to-video are 16:9 or 9:16; from an image, the clip keeps the image's shape. `reference-to-video` takes up to nine `--references` images, three `--reference-videos` (HeyGen reads the first 5 seconds of each) and three `--audio-references`, twelve files in all, named Image 1, Video 1, Audio 1 in the prompt. It takes no `--reference`, `--end-reference` or `--middle-reference`, and `--aspect-ratio auto` (default) follows the first image or clip. HeyGen takes images of up to 5 MB, and clips and audio of up to 16 MB. Up to 5 seconds of each reference clip, and each reference image after the second, add to the cost; audio references are free.
 
+CLI 0.36.0 adds ByteDance's Seedance on BytePlus: `byteplus/seedance-2.5`, `byteplus/seedance-2.0`, `byteplus/seedance-2.0-fast` and `byteplus/seedance-2.0-mini`. Each films from an image (`--reference`, optionally ending on `--end-reference`; the clip keeps the image's shape), from text (`--workflow text-to-video`, with `--aspect-ratio`), or from saved images and audio (`--workflow reference-to-video`: up to nine `--references` and three `--audio-references`, named Image 1 and Audio 1 in the prompt; 2.0, fast and mini need an image beside audio). Clips are 4–15 whole seconds (2.5 up to 30), at 480p or 720p (2.0 also 1080p), with sound of their own and no `--soundtrack`, `--seed` or `--prompt-expansion`. Seedance takes no reference videos or extensions here, and refuses images of real people's faces. A clip is charged the tokens BytePlus counts, at most the estimate: a 5-second 720p clip is about 118 credits on 2.5, 77 on 2.0, 62 on fast and 39 on mini.
+
+```sh
+# A sprite's wave, from its art to its art.
+animaguru assets generate PROJECT_ID --type video --model byteplus/seedance-2.0-mini \
+  --name "Wave" --reference ART_SHA --end-reference ART_SHA \
+  --prompt "The robot waves its right hand, then stands still again" --seconds 5 --resolution 720p --dry-run
+# A 20-second scene from text on Seedance 2.5.
+animaguru assets generate PROJECT_ID --type video --model byteplus/seedance-2.5 \
+  --workflow text-to-video --name "Harbor" --aspect-ratio 21:9 \
+  --prompt "Fishing boats leave a foggy harbor at dawn, gulls calling, one slow continuous shot" --seconds 20 --dry-run
+```
+
 ### Vectors
 
-CLI 0.27.0 adds vectors: editable SVG files drawn by Ideogram on fal.ai (`fal/ideogram-vector`), for logos, icons, mascots and flat illustrations that stay sharp at any size and can be animated shape by shape.
+CLI 0.27.0 adds vectors: editable SVG files drawn by Ideogram on fal.ai (`fal/ideogram-vector`), for logos, icons, mascots and flat illustrations that stay sharp at any size and can be animated shape by shape. CLI 0.38.0 adds a second model, GPT Image 2.6 on fal (`fal/gpt-image-2.6-vector`).
 
 ```sh
 # Draw from a prompt; --references guide the look, the first one leading.
@@ -347,9 +380,44 @@ animaguru assets generate PROJECT_ID --type vector --name "Fox mascot" \
 # Trace a saved image or sprite into shapes; it takes no prompt.
 animaguru assets generate PROJECT_ID --type vector --name "Logo" \
   --workflow image-to-vector --source IMAGE_SHA --shapes simple --dry-run
+
+# GPT Image 2.6 draws from the prompt alone; --transparent leaves out the background.
+animaguru assets generate PROJECT_ID --type vector --model fal/gpt-image-2.6-vector \
+  --name "Coffee badge" --prompt "A round coffee shop badge, two flat colors, bold outlines" \
+  --quality medium --aspect-ratio 1:1 --transparent --dry-run
+```
+
+With Ideogram, `--workflow` is `text-to-vector` (default) or `image-to-vector`. From text, `--quality` is `low` (13 credits), `medium` (default, 16) or `high` (20, or 32 with references); `--aspect-ratio` is `auto` (default, the model's choice) or a ratio from 1:4 to 4:1 (`catalog --type vector` lists them); `--references` takes up to five of this project's images or sprite art of up to 10 MB each, named Image 1, Image 2… in the prompt; `--seed` repeats a result. `image-to-vector` traces `--source`, one of this project's images or sprite art of up to 50 MB, for 10 credits: `--shapes detailed` (default) keeps fine detail and `simple` uses fewer, simpler shapes. The result is saved as `image/svg+xml` and downloads as `NAME.svg`.
+
+GPT Image 2.6 Vector (`--model fal/gpt-image-2.6-vector`) draws a picture from `--prompt` at `--quality low|medium|high` and converts it to paths. It only draws from text: it takes no `--references`, `--seed`, `--workflow image-to-vector`, `--source` or `--shapes`, and `--aspect-ratio` is `auto` (default) or a ratio from 1:3 to 3:1 (`gptAspectRatios` in `catalog --type vector`). `--transparent` leaves out the background; Ideogram always draws one and refuses the flag. fal publishes no price per SVG, so the dry run holds 8, 12 or 22 credits by quality, and the job is charged the tokens fal meters for the picture and its paths. Choose Ideogram to follow reference images or to trace one.
+
+Vectors can't be used as image or video references; trace or draw one from an image instead. GIFs can, through their first frame (see [GIFs](#gifs)).
+
+### GIFs
+
+CLI 0.38.0 adds animated GIFs drawn by GPT Image 2.6 on fal.ai: short loops such as a sprite's walk or idle cycle, an icon that moves, or a sticker. `fal/gpt-image-2.6-gif` (Flare, the default) is faster; `fal/gpt-image-2.6-sunburst-gif` (Sunburst) draws finer detail more slowly, at the same token prices.
+
+```sh
+# Nine square frames at 120 ms each: a loop of just over a second.
+animaguru assets generate PROJECT_ID --type gif --name "Fox walk" \
+  --prompt "A cartoon fox walk cycle, side view, flat colors, the same fox in every frame" \
+  --frames 9 --frame-ms 120 --transparent --dry-run
+
+# Animate a saved character: Image 1 leads, as in an image edit.
+animaguru assets generate PROJECT_ID --type gif --model fal/gpt-image-2.6-sunburst-gif \
+  --name "Fox wave" --prompt "The fox from Image 1 waves its paw and smiles, then holds still" \
+  --references CHARACTER_SHA --frames 6 --quality high --download loops/ --yes
+
+# Start a video on the GIF's first frame.
+animaguru assets generate PROJECT_ID --type video --name "Fox walks off" \
+  --prompt "The fox walks out of the frame to the right" --reference GIF_SHA --dry-run
 ```
 
-`--workflow` is `text-to-vector` (default) or `image-to-vector`. From text, `--quality` is `low` (13 credits), `medium` (default, 16) or `high` (20, or 32 with references); `--aspect-ratio` is `auto` (default, the model's choice) or a ratio from 1:4 to 4:1 (`catalog --type vector` lists them); `--references` takes up to five of this project's images or sprite art of up to 10 MB each, named Image 1, Image 2… in the prompt; `--seed` repeats a result. `image-to-vector` traces `--source`, one of this project's images or sprite art of up to 50 MB, for 10 credits: `--shapes detailed` (default) keeps fine detail and `simple` uses fewer, simpler shapes. The result is saved as `image/svg+xml` and downloads as `NAME.svg`. Vectors can't be used as image or video references; trace or draw one from an image instead.
+`--prompt` is required (3–4,000 characters). `--frames` is 2–16 (default 9), and `--frame-ms` is how long each frame shows, 20–2,000 ms (default 200), rounded to 10 ms. `--aspect-ratio` is 1:1 (default), 3:2, 2:3, 16:9 or 9:16, and `--quality` low, medium (default) or high. `--transparent` draws the frames without a background, for a sprite over a scene. `--references` takes up to four of this project's images, GIF stills or sprite art to animate or follow, named Image 1, Image 2… in the prompt.
+
+All frames share the pixels of one picture, 3,840 × 2,160, so the more frames, the smaller each one: nine square frames are 960 × 960 and sixteen are 720 × 720. `catalog --type gif` lists `gifOptions.frameSizes` for every shape and frame count. The dry run holds credits at GPT Image 2.5's still prices for those frames, plus a little for each reference (about 31 credits for nine square frames at medium); fal meters the tokens actually used and that is what the job is charged.
+
+A saved GIF is `image/gif` and downloads as `NAME.gif`. `assets list` gives its `result.gif` (`width`, `height`, `frames`, `durationMs`) and `preview`, the SHA of a PNG still of its first frame. Either SHA works wherever a saved image does: a video's `--reference`, `--end-reference`, `--middle-reference`, `--references`, `--keyframes` or `--lighting`, an image's or a vector's `--references`, the image a vector traces (`--source`), a 3D model's `--reference`, and the picture a Mureka soundtrack scores. Each uses the first frame. In a film workspace, play the GIF itself with the kit's `gifClip()`; the `animaguru-video` skill shows how.
 
 Images have a full background by default; `--transparent` requests a cutout. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 shapes. `--aspect-ratio` is 1:1 (default, 1024×1024), 3:2 (1536×1024), 2:3 (1024×1536), 16:9 (1536×864) or 9:16 (864×1536). `--references` takes up to four comma-separated blob SHAs of this project's images (including attached uploads) or sprite art, and the new image follows them: generate a character sheet once, then reference it in every scene to keep the character consistent. Refer to them in the prompt as Image 1, Image 2 and so on, and say what to take from each. Each reference adds a little to the estimate. `--mask` edits only part of Image 1, the first reference: give up to eight rectangles as `x,y,width,height` fractions of its size from the top left, separated by semicolons (`0,0,1,0.4` is the top 40%). The rest of the image is kept, and the result keeps Image 1's shape, which must be one of the five above. Gemini speech's `--prompt` is the verbatim transcript, and `--delivery` controls how it sounds without being spoken. Gemini speech supports both `gemini-3.8-flash-tts` and `gemini-3.8-flash-lite-tts`. Music uses Lyria. Google audio requires the server's `AI_PROVIDER_KEY_GOOGLE` secret; no provider keys are stored in the CLI.
 
@@ -373,7 +441,7 @@ animaguru assets submit PROJECT_ID --file speech.json --model gemini-3.8-flash-t
 
 `--model` overrides the file's model. Unrelated type-specific flags are rejected rather than ignored, and the error lists the flags that type accepts.
 
-`assets generate` and `assets submit` accept `--wait` to block until the job finishes (failing if generation fails) and `--download PATH` to wait and then save the result; `--timeout` sets the wait in seconds (default 600). A `PATH` that is an existing folder or ends in `/` receives `NAME.EXT`, named after the asset and its type (`.wav`, `.mp3`, `.png`, `.svg`…). The JSON output adds `job`, `asset` (`id`, `name`, `type`, `mimeType`) and `download` (`path`, `size`) to the submission receipt.
+`assets generate` and `assets submit` accept `--wait` to block until the job finishes (failing if generation fails) and `--download PATH` to wait and then save the result; `--timeout` sets the wait in seconds (default 600). A `PATH` that is an existing folder or ends in `/` receives `NAME.EXT`, named after the asset and its type (`.wav`, `.mp3`, `.png`, `.svg`, `.gif`…). The JSON output adds `job`, `asset` (`id`, `name`, `type`, `mimeType`) and `download` (`path`, `size`) to the submission receipt.
 
 ```sh
 animaguru assets generate PROJECT_ID --type speech --name vo-01-hook \
@@ -396,7 +464,7 @@ Every item is validated before anything is sent, names must be distinct, and a b
 
 ## HeyGen avatars
 
-CLI 0.13.0 adds `avatars` for HeyGen's avatar API. A group is a character; its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. Any project can browse HeyGen's public catalog. An avatar you create belongs to the project that created it: only that project lists, changes or deletes it.
+CLI 0.13.0 adds `avatars` for HeyGen's avatar API. A group is a character; its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. Any project can browse HeyGen's public catalog. An avatar you create belongs to its project's workspace: every project there lists, uses and changes it, and no other workspace can see, change or render it. The voice HeyGen clones for a digital twin belongs to the workspace the same way.
 
 ```sh
 animaguru avatars list PROJECT_ID --limit 10
@@ -407,7 +475,7 @@ animaguru avatars list PROJECT_ID --ownership private
 animaguru avatars create PROJECT_ID --type prompt --name "Ada" \
   --prompt "Woman in her early 30s, warm smile, navy blazer, bright studio, soft key light" \
   --aspect-ratio 16:9 --dry-run
-# A new outfit or setting for one of the project's avatars.
+# A new outfit or setting for one of the workspace's avatars.
 animaguru avatars create PROJECT_ID --type prompt --name "Ada, keynote" \
   --look LOOK_ID --prompt "On a conference stage under a spotlight" --yes
 # A photo avatar from a saved image, an HTTPS URL or a local file.
@@ -418,7 +486,7 @@ animaguru avatars wait PROJECT_ID LOOK_ID
 
 `create` and `add-looks` return the new look IDs. Looks start `processing`; `avatars wait` polls until HeyGen finishes (`completed`) or fails. `--file` and `--reference-images` take a project image's SHA (from `assets list`, or a character's `art`), an HTTPS URL HeyGen downloads (up to 32 MB), or a local file sent inline (up to 8 MB). Photos and footage show a real person: pass `--subject-consent` only when that person agreed to become an avatar.
 
-A digital twin trains on footage of a real person (about two minutes of natural talking: a project video SHA, a URL or a local file) and clones their voice. It renders only after that person records consent on camera:
+A digital twin trains on footage of a real person (about two minutes of natural talking: a project video SHA, a URL or a local file) and clones their voice, which only this workspace can use. It renders only after that person records consent on camera:
 
 ```sh
 animaguru avatars create PROJECT_ID --type digital_twin --name "Sam" \
@@ -427,7 +495,7 @@ animaguru avatars consent PROJECT_ID GROUP_ID      # a 24-hour link for that per
 animaguru avatars get PROJECT_ID --group GROUP_ID  # consentStatus: pending, accepted or rejected
 ```
 
-Look Packs dress one of the project's looks in a themed set of five looks; a single template makes two. `avatars templates` lists their IDs, each in a female and a male variant:
+Look Packs dress one of the workspace's looks in a themed set of five looks; a single template makes two. `avatars templates` lists their IDs, each in a female and a male variant:
 
 ```sh
 animaguru avatars templates
@@ -435,7 +503,19 @@ animaguru avatars add-looks PROJECT_ID --look LOOK_ID \
   --template 5a8e6be843ee4321a014946bf62aa322 --aspect-ratio 9:16 --yes
 ```
 
-Credits are charged once HeyGen accepts a request: 132 for a photo or prompt avatar, 213 for a digital twin, and 132 for each generated look (a Look Pack makes five). `--dry-run` validates and estimates offline; the server checks files, avatar ownership and credits before calling HeyGen. Paid requests carry a retry key, so a retried request is not charged twice. `avatars rename PROJECT_ID LOOK_ID --name NAME` and `avatars voice PROJECT_ID GROUP_ID --voice VOICE_ID` change the project's own avatars. `avatars delete PROJECT_ID --group GROUP_ID --yes` (or `--look LOOK_ID`) deletes for good; deleting an avatar's last look deletes the avatar. The server needs `AI_PROVIDER_KEY_HEYGEN`.
+Credits are charged once HeyGen accepts a request: 132 for a photo or prompt avatar, 213 for a digital twin, and 132 for each generated look (a Look Pack makes five). `--dry-run` validates and estimates offline; the server checks files, avatar ownership and credits before calling HeyGen. Paid requests carry a retry key, so a retried request is not charged twice. `avatars rename PROJECT_ID LOOK_ID --name NAME` and `avatars voice PROJECT_ID GROUP_ID --voice VOICE_ID` change the workspace's own avatars; a default voice must be public or one of the workspace's cloned voices. `avatars delete PROJECT_ID --group GROUP_ID --yes` (or `--look LOOK_ID`) deletes for good, the voice cloned for a digital twin included; deleting an avatar's last look deletes the avatar. The server needs `AI_PROVIDER_KEY_HEYGEN`.
+
+CLI 0.37.0 adds avatar videos. `avatars video` films one completed look speaking a script (up to 1,500 characters) or lip-syncing saved speech or music (`--audio SHA`, up to 120 seconds), and saves the clip to the project as a video asset. A script speaks in the look's own voice unless `--voice` picks a public voice or one of the workspace's cloned voices; `avatars voices` lists both. `--model` is the engine and must be one the look's `supportedEngines` list.
+
+```sh
+animaguru avatars voices PROJECT_ID --language English --gender female
+animaguru avatars video PROJECT_ID --look LOOK_ID --name "Welcome" \
+  --script "Hi, I'm Ada. Here is what we shipped this week." --aspect-ratio 9:16 --dry-run
+animaguru avatars video PROJECT_ID --look LOOK_ID --name "Voice-over cut" --audio SPEECH_SHA --model heygen/avatar-v --yes
+animaguru jobs wait PROJECT_ID JOB_ID
+```
+
+The dry run asks the server, which checks the look, voice and audio and measures the audio. A video is charged for the seconds HeyGen makes: about 6.7 credits a second on Avatar IV and V (5 for photo avatars on Avatar IV) and 1.7 for digital twins and studio avatars on Avatar III, so a 30-second clip on Avatar IV costs about 200 credits.
 
 ## Typed job files