@docyrus/animaguru 0.11.0 → 0.14.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. 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`, `video`, `speech`, `sfx`, `avatars`) returns only that part. Shell completions: `animaguru completion zsh` (also bash and fish).
 
 ## Create an animation video project
 
@@ -162,7 +162,7 @@ animaguru assets download PROJECT_ID ASSET_ID --output welcome.wav
 animaguru files export PROJECT_ID --output adventure-assets.zip
 ```
 
-Use the returned job id with `jobs wait`. For `--reference`, use an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, from the same project. Video duration, resolution and mode must match its provider's profile in `catalog`; omitted video options use five seconds and that model's first supported resolution and mode. Standalone assets use their type's default model when `--model` is omitted; sprite project model defaults continue to apply to sprite commands.
+Use the returned job id with `jobs wait`, or add `--wait` to wait in the same command and `--download PATH` to also save the result (see below). For `--reference`, use an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, from the same project. Video duration, resolution and mode must match its provider's profile in `catalog`; omitted video options use five seconds and that model's first supported resolution and mode. Standalone assets use their type's default model when `--model` is omitted; sprite project model defaults continue to apply to sprite commands.
 
 CLI 0.5.0 adds ElevenLabs speech and SFX:
 
@@ -220,7 +220,71 @@ animaguru assets submit PROJECT_ID --file speech.json --dry-run
 animaguru assets submit PROJECT_ID --file speech.json --model gemini-3.8-flash-tts --yes
 ```
 
-`--model` overrides the file's model. Unrelated type-specific flags are rejected rather than ignored. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's `assets/<id>/` directory and are shared with the web Assets workspace.
+`--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`…). 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 \
+  --prompt "Four channel reports." --voice Kore --download production/audio/vo/ --yes
+```
+
+`assets batch` submits several requests from one file. The file is a JSON list of asset requests, or `{"defaults": {...}, "assets": [...]}` with the defaults merged under each item, so voiceover lines can share their type, model, voice and delivery:
+
+```json
+{"defaults":{"type":"speech","model":"gemini-3.8-flash-tts","voice":"Kore","delivery":"Confident keynote announcer"},
+ "assets":[{"name":"vo-01-hook","prompt":"Four channel reports."},{"name":"vo-02-problem","prompt":"Your data lives apart."}]}
+```
+
+```sh
+animaguru assets batch PROJECT_ID --file vo-lines.json --dry-run
+animaguru assets batch PROJECT_ID --file vo-lines.json --download production/audio/vo --yes
+```
+
+Every item is validated before anything is sent, names must be distinct, and a batch holds up to 50 items. `--dry-run` returns each item's estimate and the total. Items are submitted one at a time; if a submission fails, the batch stops and prints `items` (already queued, with their job ids), `notSubmitted` and `error`, so nothing is resubmitted blindly. With `--wait` or `--download`, every job is waited on under one `--timeout`, and each result is saved into the folder as `NAME.EXT`. The output is `{ "items": [{ "name", "id", "estimatedCredits", "job", "asset", "download" }], "estimatedCredits" }`; an item that failed or timed out carries its own `error`, and the command exits non-zero after printing the list. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's `assets/<id>/` directory and are shared with the web Assets workspace.
+
+## 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.
+
+```sh
+animaguru avatars list PROJECT_ID --limit 10
+animaguru avatars looks PROJECT_ID --avatar-type studio_avatar
+animaguru avatars list PROJECT_ID --ownership private
+
+# A synthetic character from a description.
+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.
+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.
+animaguru avatars create PROJECT_ID --type photo --name "Sam" \
+  --file portrait.jpg --subject-consent --yes
+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:
+
+```sh
+animaguru avatars create PROJECT_ID --type digital_twin --name "Sam" \
+  --file https://example.com/sam-footage.mp4 --subject-consent --yes
+animaguru avatars consent PROJECT_ID GROUP_ID      # a 24-hour link for that person
+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:
+
+```sh
+animaguru avatars templates
+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`.
 
 ## Typed job files
 
@@ -260,6 +324,21 @@ New workspaces offer Explainer, Advertisement and General Video independently of
 
 Twenty original procedural 2.5D studies are bundled. In an untouched project, `npm run example -- risograph-print` installs a runnable study, with starter backups and refusal to replace an authored film. `npm run review` prints a local browser URL and saves text-bound checks, deterministic seek comparisons and frames to `production/review/`. Review moving playback and audio too. Physically rendered 3D is deferred.
 
+## Motion library
+
+CLI 0.14.0 adds `animaguru motion`. Search ready-made motion design examples (PixiJS scenes built on the video film kit) by describing the motion, then install one into a film. Search uses natural language and keywords together; it needs `animaguru auth login` and spends no credits.
+
+```sh
+animaguru motion categories
+animaguru motion search word slam on a beat --category kinetic-typography
+animaguru motion search swipe to delete list --labels mobile --limit 3
+animaguru motion get skeleton-list-swipe                      # beats, options, usage and code
+animaguru motion get skeleton-list-swipe --write src/scenes   # writes the scene and its lib/ modules
+animaguru motion get skeleton-list-swipe --write animations/launch/src/scenes   # workspace: imports runtime/kit
+```
+
+Then call the entry function from `Film.build()`, for example `skeletonListSwipe(this, { at: 4 })`. `--write` refuses to replace an existing scene (pass `--force`) and keeps shared modules that already exist.
+
 ## Submit and share videos
 
 Run `animaguru auth login`, then submit from a finished AnimaGuru video workspace: